From dd77cd25f604c0a106e14db333c098bbe5db6320 Mon Sep 17 00:00:00 2001
From: ehofman <ehofman>
Date: Mon, 30 Jun 2008 07:30:02 +0000
Subject: [PATCH] Some small updates; fix typo's and fix a small memory leak
 Improve the documentation in README

---
 utils/xmlgrep/README    | 46 ++++++++++++++++++++++++++++++++++++++++-
 utils/xmlgrep/xml.c     |  4 ++--
 utils/xmlgrep/xmlgrep.c | 11 +++++-----
 3 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/utils/xmlgrep/README b/utils/xmlgrep/README
index 29be06bb3..81757de9d 100644
--- a/utils/xmlgrep/README
+++ b/utils/xmlgrep/README
@@ -1,3 +1,46 @@
+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 or when a request is made to
+copy a node.
+
+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. This is because the XML-id holds the boundaries of the
+(parent)node which limits the searching area causing 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.
@@ -16,7 +59,7 @@ void *xmlGetNode(const void *, const char *);
 void *xmlCopyNode(void *, const char *);
 
 #
-# Functions to walk the node tree an process them one by one.
+# Functions to walk the node tree and process them one by one.
 # e.g.
 #   xmid = xmlMarkId(id);
 #   num = xmlGetNumElements(xmid);
@@ -28,6 +71,7 @@ void *xmlCopyNode(void *, const char *);
 #         }
 #      }
 #   }
+#   free(xmid);
 #
 void *xmlMarkId(void *);
 unsigned int xmlGetNumElements(void *, const char *);
diff --git a/utils/xmlgrep/xml.c b/utils/xmlgrep/xml.c
index b464724e0..ccc1ccf82 100644
--- a/utils/xmlgrep/xml.c
+++ b/utils/xmlgrep/xml.c
@@ -1,5 +1,5 @@
-/* Copyright (c) 2007,2008 by Adalin B.V.
- * Copyright (c) 2007,2008 by Erik Hofman
+/* Copyright (c) 2007, 2008 by Adalin B.V.
+ * Copyright (c) 2007, 2008 by Erik Hofman
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
diff --git a/utils/xmlgrep/xmlgrep.c b/utils/xmlgrep/xmlgrep.c
index 5f8e92cd0..139f1ae8d 100644
--- a/utils/xmlgrep/xmlgrep.c
+++ b/utils/xmlgrep/xmlgrep.c
@@ -249,22 +249,21 @@ void walk_the_tree(size_t num, void *xid, char *tree)
 
 void grep_file(unsigned num)
 {
-    void *xrid;
+    void *xid;
 
-    xrid = xmlOpen(_filenames[num]);
-    if (xrid)
+    xid = xmlOpen(_filenames[num]);
+    if (xid)
     {
-       void *xid = xmlMarkId(xrid);
+       void *xrid = xmlMarkId(xid);
        walk_the_tree(num, xrid, _root);
        free(xrid);
-       xrid = xid;
     }
     else
     {
         fprintf(stderr, "Error reading file '%s'\n", _filenames[num]);
     }
 
-    xmlClose(xrid);
+    xmlClose(xid);
 }
 
 int