flightgear/utils/xmlgrep/README

This library is specially designed for reading xml configuration files and
to be as low on memory management as possible. Modifying or writing xml files
is not planned for the future. In most situations being able to gather data
by reading an xml file is more than enough and the read-only decision
provides a number of advantages over a one-size fits all approach. For isntance
the memory footprint can be kept low and the library can be kept simple.

To achieve these goals the mmap function is used to map the configuration file
to a memory region. The only places where memory is allocated is when creating
a new XML-id, when requesting a string from a node, when requesting the node
name or when a request is made to copy a node into a new memory region.

Using this library should be pretty simple for most tasks; just open a file,
read every parameter one by one and close the id again.
{
   void *xid;

   xid = xmlOpen("/tmp/file.xml");
   xpos = xmlGetNodeDouble(xid, "/configuration/x-pos");
   ypos = xmlGetNodeDouble(xid, "/configuration/y-pos");
   zpos = xmlGetNodeDouble(xid, "/configuration/z-pos");
   xmlClose(xid);
}

While it is certainly possible to access every node directly by calling the
xmlGetNode(Int/Double/String) functions, when more than one node need to be
gathered from a parent node it is advised to get the id of the parent node
and work from there since the XML-id holds the boundaries of the (parent)node
which limits the searching area resulting in improved searching speed.
{
   void *xnid;
   char *s;

   xnid = xmlGetNode(id, "/configuration/setup/");
   version = xmlGetNodeDouble(xnid, "version");
   s = xmlGetNodeString(xnid, "author");
   if (s) author = s;
   free(s);
   free(xnid);
}

Overview of the available functions:
 ----------------------------------------------------------------------------- 
#
# Functions to Open and Close the XML file
# e.g.
#   id = xmlOpen("/tmp/file.xml");
#   xmlClose(id);
#
void *xmlOpen(const char *);
void xmlClose(const void *);

#
# Get the Id of a node at the specified path
# e.g.
#    xnid = xmlGetNode(id, "/path/to/specified/node");
#
void *xmlGetNode(const void *, const char *);
void *xmlCopyNode(void *, const char *);

#
# Functions to walk the node tree and process them one by one.
# e.g.
#   xmid = xmlMarkId(id);
#   num = xmlGetNumNodes(xmid);
#   for (i=0; i<num; i++) {
#      if (xmlGetNodeNum(id, xmid, "element", i) != 0) {
#         if ((s = xmlGetString(xmid)) != 0) {
#            printf("%s\n", s);
#            free(s);
#         }
#      }
#   }
#   free(xmid);
#
void *xmlMarkId(void *);
unsigned int xmlGetNumNodes(void *, const char *);
void *xmlGetNodeNum(const void *, void *, const char *, int);

#
# Get the name of the current node
#
char *xmlGetNodeName(void *);
size_t xmlCopyNodeName(void *, const char *, size_t);

#
# These functions work on the current node.
# e.g.
#    xnid = xmlGetNode(id, "/path/to/last/node");
#    i = xmlGetInt(xnid);
# or
#    xnid = xmlGetNode(id, "/path/to/specified/node");
#    if (xmlCompareString(xnid, "value") == 0) printf("We have a match!\n");
#
long int xmlGetInt(void *);
double xmlGetDouble(void *);
char *xmlGetString(void *);
size_t xmlCopyString(void *, char *, const size_t);
int xmlCompareString(const void *, const char *);

#
# These functions work on a specified node path
# e.g.
#    d = xmlGetNodeDouble(id, "/path/to/node");
# or
#    xnid = xmlGetNode(id, "/path/to");
#    i = xmlGetNodeInt(xnid, "node");
#
long int xmlGetNodeInt(void *, const char *);
double xmlGetNodeDouble(void *, const char *);
char *xmlGetNodeString(void *, const char *);
size_t xmlCopyNodeString(void *, const char *, char *, const size_t);
int xmlCompareNodeString(const void *, const char *, const char *);