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 requestiong 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 = xmlNodeGetDouble(xid, "/configuration/x-pos");
  20    ypos = xmlNodeGetDouble(xid, "/configuration/y-pos");
  21    zpos = xmlNodeGetDouble(xid, "/configuration/z-pos");
  22    xmlClose(xid);
  23 }
  24
  25 While it is certainly possible to access every node directly by calling the
  26 xmlNodeGet(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 = xmlNodeGet(id, "/configuration/setup/");
  35    version = xmlNodeGetDouble(xnid, "version");
  36    s = xmlNodeGetString(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 *filename);
  51 void *xmlInitBuffer(const char *buffer, size_t size);
  52 void xmlClose(void *xid);
  53
  54 #
  55 # Get the Id of a node at the specified path
  56 # e.g.
  57 #    xnid = xmlNodeGet(id, "/path/to/specified/node");
  58 #
  59 void *xmlNodeGet(const void *xid, const char *path);
  60 void *xmlNodeCopy(const void *xid, const char *path);
  61
  62 #
  63 # Functions to walk the node tree and process them one by one.
  64 # e.g.
  65 #   xmid = xmlMarkId(id);
  66 #   num = xmlNodeGetNum(xmid, "node");
  67 #   for (i=0; i<num; i++) {
  68 #      if (xmlNodeGetPos(id, xmid, "element", i) != 0) {
  69 #         if ((s = xmlGetString(xmid)) != 0) {
  70 #            printf("%s\n", s);
  71 #            free(s);
  72 #         }
  73 #      }
  74 #   }
  75 #   free(xmid);
  76 #
  77 void *xmlMarkId(const void *xid);
  78 unsigned int xmlNodeGetNum(const void *xid, const char *path);
  79 void *xmlNodeGetPos(const void *pid, void *xid, const char *element, int pos);
  80
  81 #
  82 # Get the name of the current node
  83 #
  84 char *xmlNodeGetName(const void *xid);
  85 size_t xmlNodeCopyName(const void *xid, const char *buffer, size_t size);
  86
  87 #
  88 # These functions work on the current node.
  89 # e.g.
  90 #    xnid = xmlNodeGet(id, "/path/to/last/node");
  91 #    i = xmlGetInt(xnid);
  92 # or
  93 #    xnid = xmlNodeGet(id, "/path/to/specified/node");
  94 #    if (xmlCompareString(xnid, "value") == 0) printf("We have a match!\n");
  95 #
  96 long int xmlGetInt(const void *xid);
  97 double xmlGetDouble(const void *xid);
  98 char *xmlGetString(const void *xid);
  99 size_t xmlCopyString(const void *xid, char *buffer, const size_t size);
 100 int xmlCompareString(const void *xid, const char *str);
 101
 102 #
 103 # These functions work on a specified node path
 104 # e.g.
 105 #    d = xmlNodeGetDouble(id, "/path/to/node");
 106 # or
 107 #    xnid = xmlNodeGet(id, "/path/to");
 108 #    i = xmlNodeGetInt(xnid, "node");
 109 #
 110 long int xmlNodeGetInt(const void *xid, const char *path);
 111 double xmlNodeGetDouble(const void *xid, const char *path);
 112 char *xmlNodeGetString(const void *xid, const char *path);
 113 size_t xmlNodeCopyString(const void *xid, const char *path,
 114                             char *buffer, const size_t size);
 115 int xmlNodeCompareString(const void *xid, const char *path, const char *str);
 116
 117 #
 118 # These functions work on a specified atribute
 119 # e.g.
 120 #    i = xmlAttributeGetInt(id, "n");
 121 #
 122 # or
 123 #    s = xmlAttributeGetString(id, "type");
 124 #    if (s) printf("node is of type '%s'\n", s);
 125 #    free(s);
 126 #
 127 long int xmlAttributeGetInt(const void *xid, const char *attr);
 128 double xmlAttributeGetDouble(const void *xid, const char *attr);
 129 char *xmlAttributeGetString(const void *xid, const char *attr);
 130 size_t xmlAttributeCopyString(const void *xid, const char *attr,
 131                                  const char *buffer, size_t size);
 132 int xmlAttributeCompareString(const void *xid, const char *attr,
 133                                  const char *str);
 134
 135 #
 136 # Error detection and reporting functions
 137 #
 138 # char *err_str = xmlErrorGetString(id, 0);
 139 # size_t err_lineno = xmlErrorGetLineNo(id, 0);
 140 # int err = xmlErrorGetNo(id, 1); /* clear last error */
 141 # if (err) printf("Error #%i at line %u: '%s'\n", err, err_lineno, err_str);
 142 #
 143 int xmlErrorGetNo(const void *xid, int clear);
 144 size_t xmlErrorGetLineNo(const void *xid, int clear);
 145 size_t xmlErrorGetColumnNo(const void *xid, int clear);
 146 const char *xmlErrorGetString(const void *xid, int clear);