unified MX27, MX25, MX37 trees
[karo-tx-redboot.git] / 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>