libxml2/doc/library.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5 <link rel="SHORTCUT ICON" href="/favicon.ico">
   6 <style type="text/css"><!--
   7 TD {font-family: Verdana,Arial,Helvetica}
   8 BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
   9 H1 {font-family: Verdana,Arial,Helvetica}
  10 H2 {font-family: Verdana,Arial,Helvetica}
  11 H3 {font-family: Verdana,Arial,Helvetica}
  12 A:link, A:visited, A:active { text-decoration: underline }
  13 --></style>
  14 <title>The parser interfaces</title>
  15 </head>
  16 <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
  17 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
  18 <td width="180">
  19 <a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo"></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo"></a></div>
  20 </td>
  21 <td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
  22 <h1>The XML C library for Gnome</h1>
  23 <h2>The parser interfaces</h2>
  24 </td></tr></table></td></tr></table></td>
  25 </tr></table>
  26 <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
  27 <td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
  28 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  29 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
  30 <tr><td bgcolor="#fffacd">
  31 <form action="search.php" enctype="application/x-www-form-urlencoded" method="GET">
  32 <input name="query" type="TEXT" size="20" value=""><input name="submit" type="submit" value="Search ...">
  33 </form>
  34 <ul>
  35 <li><a href="index.html">Home</a></li>
  36 <li><a href="intro.html">Introduction</a></li>
  37 <li><a href="FAQ.html">FAQ</a></li>
  38 <li><a href="docs.html">Documentation</a></li>
  39 <li><a href="bugs.html">Reporting bugs and getting help</a></li>
  40 <li><a href="help.html">How to help</a></li>
  41 <li><a href="downloads.html">Downloads</a></li>
  42 <li><a href="news.html">News</a></li>
  43 <li><a href="XMLinfo.html">XML</a></li>
  44 <li><a href="XSLT.html">XSLT</a></li>
  45 <li><a href="python.html">Python and bindings</a></li>
  46 <li><a href="architecture.html">libxml architecture</a></li>
  47 <li><a href="tree.html">The tree output</a></li>
  48 <li><a href="interface.html">The SAX interface</a></li>
  49 <li><a href="xmldtd.html">Validation &amp; DTDs</a></li>
  50 <li><a href="xmlmem.html">Memory Management</a></li>
  51 <li><a href="encoding.html">Encodings support</a></li>
  52 <li><a href="xmlio.html">I/O Interfaces</a></li>
  53 <li><a href="catalog.html">Catalog support</a></li>
  54 <li><a href="library.html">The parser interfaces</a></li>
  55 <li><a href="entities.html">Entities or no entities</a></li>
  56 <li><a href="namespaces.html">Namespaces</a></li>
  57 <li><a href="upgrade.html">Upgrading 1.x code</a></li>
  58 <li><a href="threads.html">Thread safety</a></li>
  59 <li><a href="DOM.html">DOM Principles</a></li>
  60 <li><a href="example.html">A real example</a></li>
  61 <li><a href="contribs.html">Contributions</a></li>
  62 <li><a href="xmlreader.html">The Reader Interface</a></li>
  63 <li><a href="tutorial/index.html">Tutorial</a></li>
  64 <li><a href="guidelines.html">XML Guidelines</a></li>
  65 <li>
  66 <a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
  67 </li>
  68 </ul>
  69 </td></tr>
  70 </table>
  71 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  72 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
  73 <tr><td bgcolor="#fffacd"><ul>
  74 <li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li>
  75 <li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li>
  76 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
  77 <li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
  78 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
  79 <li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li>
  80 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
  81 <li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li>
  82 <li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
  83 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&amp;product=libxml2">Bug Tracker</a></li>
  84 </ul></td></tr>
  85 </table>
  86 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  87 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
  88 <tr><td bgcolor="#fffacd"><ul>
  89 <li><a href="APIchunk0.html">Alphabetic</a></li>
  90 <li><a href="APIconstructors.html">Constructors</a></li>
  91 <li><a href="APIfunctions.html">Functions/Types</a></li>
  92 <li><a href="APIfiles.html">Modules</a></li>
  93 <li><a href="APIsymbols.html">Symbols</a></li>
  94 </ul></td></tr>
  95 </table>
  96 </td></tr></table></td>
  97 <td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
  98 <p>This section is directly intended to help programmers getting bootstrapped
  99 using the XML library from the C language. It is not intended to be
 100 extensive. I hope the automatically generated documents will provide the
 101 completeness required, but as a separate set of documents. The interfaces of
 102 the XML library are by principle low level, there is nearly zero abstraction.
 103 Those interested in a higher level API should <a href="#DOM">look at
 104 DOM</a>.</p>
 105 <p>The <a href="html/libxml-parser.html">parser interfaces for XML</a> are
 106 separated from the <a href="html/libxml-htmlparser.html">HTML parser
 107 interfaces</a>.  Let's have a look at how the XML parser can be called:</p>
 108 <h3><a name="Invoking">Invoking the parser : the pull method</a></h3>
 109 <p>Usually, the first thing to do is to read an XML input. The parser accepts
 110 documents either from in-memory strings or from files.  The functions are
 111 defined in &quot;parser.h&quot;:</p>
 112 <dl>
 113 <dt><code>xmlDocPtr xmlParseMemory(char *buffer, int size);</code></dt>
 114     <dd>
 115 <p>Parse a null-terminated string containing the document.</p>
 116     </dd>
 117 </dl>
 118 <dl>
 119 <dt><code>xmlDocPtr xmlParseFile(const char *filename);</code></dt>
 120     <dd>
 121 <p>Parse an XML document contained in a (possibly compressed)
 122       file.</p>
 123     </dd>
 124 </dl>
 125 <p>The parser returns a pointer to the document structure (or NULL in case of
 126 failure).</p>
 127 <h3 id="Invoking1">Invoking the parser: the push method</h3>
 128 <p>In order for the application to keep the control when the document is
 129 being fetched (which is common for GUI based programs) libxml provides a push
 130 interface, too, as of version 1.8.3. Here are the interface functions:</p>
 131 <pre>xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
 132                                          void *user_data,
 133                                          const char *chunk,
 134                                          int size,
 135                                          const char *filename);
 136 int              xmlParseChunk          (xmlParserCtxtPtr ctxt,
 137                                          const char *chunk,
 138                                          int size,
 139                                          int terminate);</pre>
 140 <p>and here is a simple example showing how to use the interface:</p>
 141 <pre>            FILE *f;
 142
 143             f = fopen(filename, &quot;r&quot;);
 144             if (f != NULL) {
 145                 int res, size = 1024;
 146                 char chars[1024];
 147                 xmlParserCtxtPtr ctxt;
 148
 149                 res = fread(chars, 1, 4, f);
 150                 if (res &gt; 0) {
 151                     ctxt = xmlCreatePushParserCtxt(NULL, NULL,
 152                                 chars, res, filename);
 153                     while ((res = fread(chars, 1, size, f)) &gt; 0) {
 154                         xmlParseChunk(ctxt, chars, res, 0);
 155                     }
 156                     xmlParseChunk(ctxt, chars, 0, 1);
 157                     doc = ctxt-&gt;myDoc;
 158                     xmlFreeParserCtxt(ctxt);
 159                 }
 160             }</pre>
 161 <p>The HTML parser embedded into libxml also has a push interface; the
 162 functions are just prefixed by &quot;html&quot; rather than &quot;xml&quot;.</p>
 163 <h3 id="Invoking2">Invoking the parser: the SAX interface</h3>
 164 <p>The tree-building interface makes the parser memory-hungry, first loading
 165 the document in memory and then building the tree itself. Reading a document
 166 without building the tree is possible using the SAX interfaces (see SAX.h and
 167 <a href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">James
 168 Henstridge's documentation</a>). Note also that the push interface can be
 169 limited to SAX: just use the two first arguments of
 170 <code>xmlCreatePushParserCtxt()</code>.</p>
 171 <h3><a name="Building">Building a tree from scratch</a></h3>
 172 <p>The other way to get an XML tree in memory is by building it. Basically
 173 there is a set of functions dedicated to building new elements. (These are
 174 also described in &lt;libxml/tree.h&gt;.) For example, here is a piece of
 175 code that produces the XML document used in the previous examples:</p>
 176 <pre>    #include &lt;libxml/tree.h&gt;
 177     xmlDocPtr doc;
 178     xmlNodePtr tree, subtree;
 179
 180     doc = xmlNewDoc(&quot;1.0&quot;);
 181     doc-&gt;children = xmlNewDocNode(doc, NULL, &quot;EXAMPLE&quot;, NULL);
 182     xmlSetProp(doc-&gt;children, &quot;prop1&quot;, &quot;gnome is great&quot;);
 183     xmlSetProp(doc-&gt;children, &quot;prop2&quot;, &quot;&amp; linux too&quot;);
 184     tree = xmlNewChild(doc-&gt;children, NULL, &quot;head&quot;, NULL);
 185     subtree = xmlNewChild(tree, NULL, &quot;title&quot;, &quot;Welcome to Gnome&quot;);
 186     tree = xmlNewChild(doc-&gt;children, NULL, &quot;chapter&quot;, NULL);
 187     subtree = xmlNewChild(tree, NULL, &quot;title&quot;, &quot;The Linux adventure&quot;);
 188     subtree = xmlNewChild(tree, NULL, &quot;p&quot;, &quot;bla bla bla ...&quot;);
 189     subtree = xmlNewChild(tree, NULL, &quot;image&quot;, NULL);
 190     xmlSetProp(subtree, &quot;href&quot;, &quot;linus.gif&quot;);</pre>
 191 <p>Not really rocket science ...</p>
 192 <h3><a name="Traversing">Traversing the tree</a></h3>
 193 <p>Basically by <a href="html/libxml-tree.html">including &quot;tree.h&quot;</a> your
 194 code has access to the internal structure of all the elements of the tree.
 195 The names should be somewhat simple like <strong>parent</strong>,
 196 <strong>children</strong>, <strong>next</strong>, <strong>prev</strong>,
 197 <strong>properties</strong>, etc... For example, still with the previous
 198 example:</p>
 199 <pre><code>doc-&gt;children-&gt;children-&gt;children</code></pre>
 200 <p>points to the title element,</p>
 201 <pre>doc-&gt;children-&gt;children-&gt;next-&gt;children-&gt;children</pre>
 202 <p>points to the text node containing the chapter title &quot;The Linux
 203 adventure&quot;.</p>
 204 <p>
 205 <strong>NOTE</strong>: XML allows <em>PI</em>s and <em>comments</em> to be
 206 present before the document root, so <code>doc-&gt;children</code> may point
 207 to an element which is not the document Root Element; a function
 208 <code>xmlDocGetRootElement()</code> was added for this purpose.</p>
 209 <h3><a name="Modifying">Modifying the tree</a></h3>
 210 <p>Functions are provided for reading and writing the document content. Here
 211 is an excerpt from the <a href="html/libxml-tree.html">tree API</a>:</p>
 212 <dl>
 213 <dt><code>xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const
 214   xmlChar *value);</code></dt>
 215     <dd>
 216 <p>This sets (or changes) an attribute carried by an ELEMENT node.
 217       The value can be NULL.</p>
 218     </dd>
 219 </dl>
 220 <dl>
 221 <dt><code>const xmlChar *xmlGetProp(xmlNodePtr node, const xmlChar
 222   *name);</code></dt>
 223     <dd>
 224 <p>This function returns a pointer to new copy of the property
 225       content. Note that the user must deallocate the result.</p>
 226     </dd>
 227 </dl>
 228 <p>Two functions are provided for reading and writing the text associated
 229 with elements:</p>
 230 <dl>
 231 <dt><code>xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc, const xmlChar
 232   *value);</code></dt>
 233     <dd>
 234 <p>This function takes an &quot;external&quot; string and converts it to one
 235       text node or possibly to a list of entity and text nodes. All
 236       non-predefined entity references like &amp;Gnome; will be stored
 237       internally as entity nodes, hence the result of the function may not be
 238       a single node.</p>
 239     </dd>
 240 </dl>
 241 <dl>
 242 <dt><code>xmlChar *xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int
 243   inLine);</code></dt>
 244     <dd>
 245 <p>This function is the inverse of
 246       <code>xmlStringGetNodeList()</code>. It generates a new string
 247       containing the content of the text and entity nodes. Note the extra
 248       argument inLine. If this argument is set to 1, the function will expand
 249       entity references.  For example, instead of returning the &amp;Gnome;
 250       XML encoding in the string, it will substitute it with its value (say,
 251       &quot;GNU Network Object Model Environment&quot;).</p>
 252     </dd>
 253 </dl>
 254 <h3><a name="Saving">Saving a tree</a></h3>
 255 <p>Basically 3 options are possible:</p>
 256 <dl>
 257 <dt><code>void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int
 258   *size);</code></dt>
 259     <dd>
 260 <p>Returns a buffer into which the document has been saved.</p>
 261     </dd>
 262 </dl>
 263 <dl>
 264 <dt><code>extern void xmlDocDump(FILE *f, xmlDocPtr doc);</code></dt>
 265     <dd>
 266 <p>Dumps a document to an open file descriptor.</p>
 267     </dd>
 268 </dl>
 269 <dl>
 270 <dt><code>int xmlSaveFile(const char *filename, xmlDocPtr cur);</code></dt>
 271     <dd>
 272 <p>Saves the document to a file. In this case, the compression
 273       interface is triggered if it has been turned on.</p>
 274     </dd>
 275 </dl>
 276 <h3><a name="Compressio">Compression</a></h3>
 277 <p>The library transparently handles compression when doing file-based
 278 accesses. The level of compression on saves can be turned on either globally
 279 or individually for one file:</p>
 280 <dl>
 281 <dt><code>int  xmlGetDocCompressMode (xmlDocPtr doc);</code></dt>
 282     <dd>
 283 <p>Gets the document compression ratio (0-9).</p>
 284     </dd>
 285 </dl>
 286 <dl>
 287 <dt><code>void xmlSetDocCompressMode (xmlDocPtr doc, int mode);</code></dt>
 288     <dd>
 289 <p>Sets the document compression ratio.</p>
 290     </dd>
 291 </dl>
 292 <dl>
 293 <dt><code>int  xmlGetCompressMode(void);</code></dt>
 294     <dd>
 295 <p>Gets the default compression ratio.</p>
 296     </dd>
 297 </dl>
 298 <dl>
 299 <dt><code>void xmlSetCompressMode(int mode);</code></dt>
 300     <dd>
 301 <p>Sets the default compression ratio.</p>
 302     </dd>
 303 </dl>
 304 <p><a href="bugs.html">Daniel Veillard</a></p>
 305 </td></tr></table></td></tr></table></td></tr></table></td>
 306 </tr></table></td></tr></table>
 307 </body>
 308 </html>