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.5</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 (less than 20k compiled). The latest version is available
  14       here:
  15       <a href="http://prdownloads.sf.net/ezxml/ezxml-0.8.5.tar.gz?download"
  16          >ezxml-0.8.5.tar.gz</a>
  17     </p>
  18
  19     <b>Example Usage</b>
  20     <p>
  21       Given the following example XML document:
  22     </p>
  23     <code>
  24       &lt;?xml version="1.0"?&gt;<br />
  25       &lt;formula1&gt;<br />
  26       &nbsp;&nbsp;&lt;team name="McLaren"&gt;<br />
  27       &nbsp;&nbsp;&nbsp;&nbsp;&lt;driver&gt;<br />
  28       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;Kimi
  29       Raikkonen&lt;/name&gt;<br />
  30       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;points&gt;45&lt;/points&gt;<br />
  31       &nbsp;&nbsp;&nbsp;&nbsp;&lt;/driver&gt;<br />
  32       &nbsp;&nbsp;&nbsp;&nbsp;&lt;driver&gt;<br />
  33       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;David
  34       Coultard&lt;/name&gt;<br />
  35       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;points&gt;24&lt;/points&gt;<br />
  36       &nbsp;&nbsp;&nbsp;&nbsp;&lt;/driver&gt;<br />
  37       &nbsp;&nbsp;&lt;/team&gt;<br />
  38       &lt;/formula1&gt;
  39     </code>
  40     <p>
  41       This code snippet prints out a list of drivers, which team they drive for,
  42       and how many championship points they have:
  43     </p>
  44     <code>
  45       ezxml_t f1 = ezxml_parse_file("formula1.xml"), team, driver;<br />
  46       const char *teamname;<br />
  47       &nbsp;<br />
  48       for (team = ezxml_child(f1, "team"); team; team = team->next) {<br />
  49       &nbsp;&nbsp;&nbsp;&nbsp;teamname = ezxml_attr(team, "name");<br />
  50       &nbsp;&nbsp;&nbsp;&nbsp;for (driver = ezxml_child(team, "driver"); driver;
  51       driver = driver->next) {<br />
  52       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("%s, %s: %s\n",
  53       ezxml_child(driver, "name")->txt, teamname,<br />
  54       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  55       &nbsp;&nbsp;ezxml_child(driver, "points")->txt);<br />
  56       &nbsp;&nbsp;&nbsp;&nbsp;}<br />
  57       }<br />
  58       ezxml_free(f1);
  59     </code>
  60     <p>
  61       Alternately, the following would print out the name of the second driver
  62       on the first team:
  63     </p>
  64     <code>
  65       ezxml_t f1 = ezxml_parse_file("formula1.xml");<br />
  66       &nbsp;<br />
  67       printf("%s\n", ezxml_get(f1, "team", 0, "driver", 1, "name", -1)->txt);
  68       <br />ezxml_free(f1);
  69     </code>
  70     <p>
  71       The -1 indicates the end of the argument list. That's pretty much all
  72       there is to it. Complete API documentation can be found in ezxml.h.
  73     </p>
  74
  75     <b>Known Limitations</b>
  76     <ul>
  77       <li>
  78         ezXML is not a validating parser.
  79         <br />&nbsp;
  80       </li>
  81       <li>
  82         Loads the entire XML document into memory at once and does not allow for
  83         documents to be passed in a chunk at a time. Large XML files can still
  84         be handled though through <code>ezxml_parse_file()</code> and
  85         <code>ezxml_parse_fd()</code>, which use mmap to map the file to a
  86         virtual address space and rely on the virtual memory system to page in
  87         data as needed.
  88         <br />&nbsp;
  89       </li>
  90       <li>
  91         Does not currently recognize all possible well-formedness errors. It
  92         should correctly handle all well-formed XML documents and will either
  93         ignore or halt XML processing on well-formedness errors. More
  94         well-formedness checking will be added in subsiquent releases.
  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>