packages/services/ezxml/v2_0/doc/ezxml.txt

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