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 requestiong 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 = xmlNodeGetDouble(xid, "/configuration/x-pos");
   ypos = xmlNodeGetDouble(xid, "/configuration/y-pos");
   zpos = xmlNodeGetDouble(xid, "/configuration/z-pos");
   xmlClose(xid);
}

While it is certainly possible to access every node directly by calling the
xmlNodeGet(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 = xmlNodeGet(id, "/configuration/setup/");
   version = xmlNodeGetDouble(xnid, "version");
   s = xmlNodeGetString(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 = xmlNodeGet(id, "/path/to/specified/node");
#
void *xmlNodeGet(const void *, const char *);
void *xmlNodeCopy(void *, const char *);

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

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

#
# These functions work on the current node.
# e.g.
#    xnid = xmlNodeGet(id, "/path/to/last/node");
#    i = xmlGetInt(xnid);
# or
#    xnid = xmlNodeGet(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 = xmlNodeGetDouble(id, "/path/to/node");
# or
#    xnid = xmlNodeGet(id, "/path/to");
#    i = xmlNodeGetInt(xnid, "node");
#
long int xmlNodeGetInt(void *, const char *);
double xmlNodeGetDouble(void *, const char *);
char *xmlNodeGetString(void *, const char *);
size_t xmlNodeCopyString(void *, const char *, char *, const size_t);
int xmlNodeCompareString(const void *, const char *, const char *);

#
# These functions work on a specified atribute
# e.g.
#    i = xmlAttributeGetInt(id, "n");
#
# or
#    s = xmlNodeGetString(id, "type");
#    if (s) printf("node is of type '%s'\n", s);
#    free(s);
#
long int xmlAttributeGetInt(const void *, const char *);
double xmlAttributeGetDouble(const void *, const char *);
char *xmlAttributeGetString(const void *, const char *);
size_t xmlAttributeCopyString(const void *, const char *, const char *, size_t);
int xmlAttributeCompareString(const void *, const char *, const char *);

#
# Error detection and reporting functions
#
# char *err_str = xmlErrorGetString(id, 0);
# size_t err_lineno = xmlErrorGetLineNo(id, 0);
# int err = xmlErrorGetNo(id, 1); /* clear last error */
# if (err) printf("Error #%i at line %u: '%s'\n", err, err_lineno, err_str);
#
int xmlErrorGetNo(const void *, int);
size_t xmlErrorGetLineNo(const void *, int);
const char *xmlErrorGetString(const void *, int);