utils/xmlgrep/README

   1 This library is specially designed for reading xml configuration files and
   2 to be as low on memory management as possible. Modifying or writing xml files
   3 is not planned for the future. In most situations being able to gather data
   4 by reading an xml file is more than enough and the read-only decision
   5 provides a number of advantages over a one-size fits all approach. For isntance
   6 the memory footprint can be kept low and the library can be kept simple.
   7
   8 To achieve these goals the mmap function is used to map the configuration file
   9 to a memory region. The only places where memory is allocated is when creating
  10 a new XML-id, when requesting a string from a node, when requesting the node
  11 name or when a request is made to copy a node into a new memory region.
  12
  13 Using this library should be pretty simple for most tasks; just open a file,
  14 read every parameter one by one and close the id again.
  15 {
  16    void *xid;
  17
  18    xid = xmlOpen("/tmp/file.xml");
  19    xpos = xmlGetNodeDouble(xid, "/configuration/x-pos");
  20    ypos = xmlGetNodeDouble(xid, "/configuration/y-pos");
  21    zpos = xmlGetNodeDouble(xid, "/configuration/z-pos");
  22    xmlClose(xid);
  23 }
  24
  25 While it is certainly possible to access every node directly by calling the
  26 xmlGetNode(Int/Double/String) functions, when more than one node need to be
  27 gathered from a parent node it is advised to get the id of the parent node
  28 and work from there since the XML-id holds the boundaries of the (parent)node
  29 which limits the searching area resulting in improved searching speed.
  30 {
  31    void *xnid;
  32    char *s;
  33
  34    xnid = xmlGetNode(id, "/configuration/setup/");
  35    version = xmlGetNodeDouble(xnid, "version");
  36    s = xmlGetNodeString(xnid, "author");
  37    if (s) author = s;
  38    free(s);
  39    free(xnid);
  40 }
  41
  42 Overview of the available functions:
  43  -----------------------------------------------------------------------------
  44 #
  45 # Functions to Open and Close the XML file
  46 # e.g.
  47 #   id = xmlOpen("/tmp/file.xml");
  48 #   xmlClose(id);
  49 #
  50 void *xmlOpen(const char *);
  51 void xmlClose(const void *);
  52
  53 #
  54 # Get the Id of a node at the specified path
  55 # e.g.
  56 #    xnid = xmlGetNode(id, "/path/to/specified/node");
  57 #
  58 void *xmlGetNode(const void *, const char *);
  59 void *xmlCopyNode(void *, const char *);
  60
  61 #
  62 # Functions to walk the node tree and process them one by one.
  63 # e.g.
  64 #   xmid = xmlMarkId(id);
  65 #   num = xmlGetNumNodes(xmid);
  66 #   for (i=0; i<num; i++) {
  67 #      if (xmlGetNodeNum(id, xmid, "element", i) != 0) {
  68 #         if ((s = xmlGetString(xmid)) != 0) {
  69 #            printf("%s\n", s);
  70 #            free(s);
  71 #         }
  72 #      }
  73 #   }
  74 #   free(xmid);
  75 #
  76 void *xmlMarkId(void *);
  77 unsigned int xmlGetNumNodes(void *, const char *);
  78 void *xmlGetNodeNum(const void *, void *, const char *, int);
  79
  80 #
  81 # Get the name of the current node
  82 #
  83 char *xmlGetNodeName(void *);
  84 size_t xmlCopyNodeName(void *, const char *, size_t);
  85
  86 #
  87 # These functions work on the current node.
  88 # e.g.
  89 #    xnid = xmlGetNode(id, "/path/to/last/node");
  90 #    i = xmlGetInt(xnid);
  91 # or
  92 #    xnid = xmlGetNode(id, "/path/to/specified/node");
  93 #    if (xmlCompareString(xnid, "value") == 0) printf("We have a match!\n");
  94 #
  95 long int xmlGetInt(void *);
  96 double xmlGetDouble(void *);
  97 char *xmlGetString(void *);
  98 size_t xmlCopyString(void *, char *, const size_t);
  99 int xmlCompareString(const void *, const char *);
 100
 101 #
 102 # These functions work on a specified node path
 103 # e.g.
 104 #    d = xmlGetNodeDouble(id, "/path/to/node");
 105 # or
 106 #    xnid = xmlGetNode(id, "/path/to");
 107 #    i = xmlGetNodeInt(xnid, "node");
 108 #
 109 long int xmlGetNodeInt(void *, const char *);
 110 double xmlGetNodeDouble(void *, const char *);
 111 char *xmlGetNodeString(void *, const char *);
 112 size_t xmlCopyNodeString(void *, const char *, char *, const size_t);
 113 int xmlCompareNodeString(const void *, const char *, const char *);