packages/services/ezxml/v2_0/doc/ezxml.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <head><title>ezXML</title></head>
   5   <body>
   6     <h1>ezXML - XML Parsing C Library</h1>
   7     <h3>version 0.8</h3>
   8     <p>
   9       ezXML is a C library for parsing XML documents inspired by
  10       <a href="http://www.php.net/SimpleXML">simpleXML</a> for
  11       PHP. As the name implies, it's easy to use. It's ideal for parsing xml
  12       configuration files or REST web service responses. It's also fast and
  13       lightweight (11k compiled). The latest version is available here:
  14       <a href="http://prdownloads.sf.net/ezxml/ezxml-0.8.tar.gz?download"
  15          >ezxml-0.8.tar.gz</a>
  16     </p>
  17
  18     <b>Example Usage</b>
  19     <p>
  20       Given the following example xml document:
  21     </p>
  22     <code>
  23       &lt;?xml version="1.0"?&gt;<br />
  24       &lt;formula1&gt;<br />
  25       &nbsp;&nbsp;&lt;team name="McLaren"&gt;<br />
  26       &nbsp;&nbsp;&nbsp;&nbsp;&lt;driver&gt;<br />
  27       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;Kimi
  28       Raikkonen&lt;/name&gt;<br />
  29       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;points&gt;45&lt;/points&gt;<br />
  30       &nbsp;&nbsp;&nbsp;&nbsp;&lt;/driver&gt;<br />
  31       &nbsp;&nbsp;&nbsp;&nbsp;&lt;driver&gt;<br />
  32       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;David
  33       Coultard&lt;/name&gt;<br />
  34       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;points&gt;24&lt;/points&gt;<br />
  35       &nbsp;&nbsp;&nbsp;&nbsp;&lt;/driver&gt;<br />
  36       &nbsp;&nbsp;&lt;/team&gt;<br />
  37       &lt;/formula1&gt;
  38     </code>
  39     <p>
  40       This code snipped prints out a list of drivers, which team they drive for,
  41       and how many championship points they have:
  42     </p>
  43     <code>
  44       ezxml_t f1 = ezxml_parse_file("formula1.xml"), team, driver;<br />
  45       const char *teamname;<br />
  46       &nbsp;<br />
  47       for (team = ezxml_child(f1, "team"); team; team = team->next) {<br />
  48       &nbsp;&nbsp;&nbsp;&nbsp;teamname = ezxml_attr(team, "name");<br />
  49       &nbsp;&nbsp;&nbsp;&nbsp;for (driver = ezxml_child(team, "driver"); driver;
  50       driver = driver->next) {<br />
  51       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("%s, %s: %s\n",
  52       ezxml_child(driver, "name")->txt, teamname,<br />
  53       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  54       &nbsp;&nbsp;ezxml_child(driver, "points")->txt);<br />
  55       &nbsp;&nbsp;&nbsp;&nbsp;}<br />
  56       }<br />
  57       ezxml_free(f1);
  58     </code>
  59     <p>
  60       Alternately, the following would print out the name of the second driver
  61       of the first team:
  62     </p>
  63     <code>
  64       ezxml_t f1 = ezxml_parse_file("formula1.xml");<br />
  65       &nbsp;<br />
  66       printf("%s\n", ezxml_get(f1, "team", 0, "driver", 1, "name", -1)->txt);
  67       <br />ezxml_free(f1);
  68     </code>
  69     <p>
  70       The -1 indicates the end of the argument list. That's pretty much all
  71       there is to it. Complete API documentation can be found in ezxml.h.
  72     </p>
  73
  74     <b>Known Limitations</b>
  75     <ul>
  76       <li>
  77         No support for UTF-16, however UTF-8 is handled correctly. UTF-16
  78         support is required for XML 1.0 conformity and will be implimented for
  79         the 1.0 release.
  80         <br />&nbsp;
  81       </li>
  82       <li>
  83         Loads the entire xml document into memory at once and does not allow for
  84         documents to be passed in a chunk at a time. Large xml files can still
  85         be handled though through <code>ezxml_parse_file()</code> and
  86         <code>ezxml_parse_fd()</code>, which use mmap to map the file to a
  87         virtual address space and rely on the virtual memory system to page in
  88         data as needed.
  89         <br />&nbsp;
  90       </li>
  91       <li>
  92         Ignores DTDs. Parsing of the internal DTD subset is required for XML 1.0
  93         conformity and will be implimented for the 1.0 release. ezXML is not,
  94         and is not likely to become, a validating parser.
  95         <br />&nbsp;
  96       </li>
  97       <li>
  98         In making the character content of tags easy to access, there is no
  99         way provided to keep track of the location of sub tags relative to the
 100         character data. Example:
 101         <p>
 102           <code>&lt;doc&gt;line one&lt;br/&gt;<br />line two&lt;/doc&gt;</code>
 103         </p>
 104         <p>
 105           The character content of the doc tag is reported as
 106           <code>"line one\nline two"</code>, and <code>&lt;br/&gt;</code> is
 107           reported as a sub tag, but the location of <code>&lt;br/&gt;</code>
 108           within the character data is not. The function
 109           <code>ezxml_toxml()</code> will convert an ezXML structure back to xml
 110           with sub tag locations intact.
 111         </p>
 112       </li>
 113     </ul>
 114
 115     <b>Licensing</b>
 116     <p>
 117       ezXML was written by Aaron Voisine and is distributed under the terms of
 118       the <a href="license.txt">MIT license</a>.
 119     </p>
 120   </body>
 121 </html>