added Dodji's example, added output handling Daniel

* doc/examples/*: added Dodji's example, added output handling
Daniel

ChangeLog

@@ -1,3 +1,7 @@
+Thu Nov 13 12:44:14 CET 2003 Daniel Veillard <daniel@veillard.com>
+
+	* doc/examples/*: added Dodji's example, added output handling
+
 Thu Nov 13 11:35:35 CET 2003 Daniel Veillard <daniel@veillard.com>
 
 	* doc/examples/*: added Aleksey XPath example, fixed bugs

doc/examples/.cvsignore

@@ -4,3 +4,4 @@ Makefile
 xpath1
 parse1
 parse2
+tree1

doc/examples/Makefile.am

@@ -11,9 +11,9 @@ examples.xml: index.py *.c
 index.html: examples.xml examples.xsl
 	-@(xsltproc examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html)
 
-EXTRA_DIST=examples.xsl index.py test1.xml examples.xml test2.xml 
+EXTRA_DIST=examples.xsl index.py test1.xml examples.xml test2.xml tree1.out 
 
-noinst_PROGRAMS=xpath1 parse1 parse2 
+noinst_PROGRAMS=xpath1 parse1 parse2 tree1 
 
 xpath1_SOURCES=xpath1.c
 xpath1_LDFLAGS=
@@ -30,8 +30,14 @@ parse2_LDFLAGS=
 parse2_DEPENDENCIES= $(DEPS)
 parse2_LDADD= @RDL_LIBS@ $(LDADDS)
 
+tree1_SOURCES=tree1.c
+tree1_LDFLAGS=
+tree1_DEPENDENCIES= $(DEPS)
+tree1_LDADD= @RDL_LIBS@ $(LDADDS)
+
 tests: $(noinst_PROGRAMS)
 	parse1 test1.xml
 	parse2 test2.xml
+	tree1 test2.xml > tree1.tmp ; diff tree1.tmp tree1.out ; rm tree1.tmp
 
 

doc/examples/examples.xml

@@ -78,14 +78,37 @@
       <typedef line='26' file='tree' name='xmlDocPtr'/>
     </uses>
   </example>
+  <example filename='tree1.c'>
+    <synopsis>Navigates a tree to print element names</synopsis>
+    <purpose>Parse a file to a tree, use xmlDocGetRootElement() to get the root element, then walk the document and print all the element name in document order.</purpose>
+    <usage>tree1 filename_or_URL</usage>
+    <test>tree1 test2.xml &gt; tree1.tmp ; diff tree1.tmp tree1.out ; rm tree1.tmp</test>
+    <author>Dodji Seketeli</author>
+    <copy>see Copyright for the status of this software. </copy>
+    <section>Tree</section>
+    <includes>
+      <include>&lt;libxml/tree.h&gt;</include>
+      <include>&lt;libxml/parser.h&gt;</include>
+    </includes>
+    <uses>
+      <function line='83' file='parser' name='xmlCleanupParser'/>
+      <macro line='65' file='xmlversion' name='LIBXML_TEST_VERSION'/>
+      <enum line='34' file='tree' name='XML_ELEMENT_NODE'/>
+      <function line='77' file='tree' name='xmlFreeDoc'/>
+      <function line='65' file='parser' name='xmlParseFile'/>
+      <function line='72' file='tree' name='xmlDocGetRootElement'/>
+    </uses>
+  </example>
   <symbols>
     <symbol name='LIBXML_TEST_VERSION'>
       <ref filename='xpath1.c'/>
       <ref filename='parse1.c'/>
       <ref filename='parse2.c'/>
+      <ref filename='tree1.c'/>
     </symbol>
     <symbol name='XML_ELEMENT_NODE'>
       <ref filename='xpath1.c'/>
+      <ref filename='tree1.c'/>
     </symbol>
     <symbol name='XML_NAMESPACE_DECL'>
       <ref filename='xpath1.c'/>
@@ -97,10 +120,14 @@
       <ref filename='xpath1.c'/>
       <ref filename='parse1.c'/>
       <ref filename='parse2.c'/>
+      <ref filename='tree1.c'/>
     </symbol>
     <symbol name='xmlCtxtReadFile'>
       <ref filename='parse2.c'/>
     </symbol>
+    <symbol name='xmlDocGetRootElement'>
+      <ref filename='tree1.c'/>
+    </symbol>
     <symbol name='xmlDocPtr'>
       <ref filename='xpath1.c'/>
       <ref filename='parse1.c'/>
@@ -110,6 +137,7 @@
       <ref filename='xpath1.c'/>
       <ref filename='parse1.c'/>
       <ref filename='parse2.c'/>
+      <ref filename='tree1.c'/>
     </symbol>
     <symbol name='xmlFreeParserCtxt'>
       <ref filename='parse2.c'/>
@@ -128,6 +156,7 @@
     </symbol>
     <symbol name='xmlParseFile'>
       <ref filename='xpath1.c'/>
+      <ref filename='tree1.c'/>
     </symbol>
     <symbol name='xmlParserCtxtPtr'>
       <ref filename='parse2.c'/>
@@ -168,6 +197,9 @@
       <example filename='parse1.c'/>
       <example filename='parse2.c'/>
     </section>
+    <section name='Tree'>
+      <example filename='tree1.c'/>
+    </section>
     <section name='XPath'>
       <example filename='xpath1.c'/>
     </section>

doc/examples/index.py

@@ -216,6 +216,8 @@ def dump_sections(output):
 def dump_Makefile():
     for file in glob.glob('*.xml'):
         extras.append(file)
+    for file in glob.glob('*.out'):
+        extras.append(file)
     Makefile="""# Beware this is autogenerated by config.py
 INCLUDES = -I$(top_builddir)/include -I@srcdir@/include @THREAD_CFLAGS@ @Z_CFLAGS@
 DEPS = $(top_builddir)/libxml2.la

doc/examples/tree1.c

@@ -0,0 +1,86 @@
+/**
+ * section: Tree
+ * synopsis: Navigates a tree to print element names
+ * purpose: Parse a file to a tree, use xmlDocGetRootElement() to
+ *          get the root element, then walk the document and print
+ *          all the element name in document order.
+ * usage: tree1 filename_or_URL
+ * test: tree1 test2.xml > tree1.tmp ; diff tree1.tmp tree1.out ; rm tree1.tmp
+ * author: Dodji Seketeli
+ * copy: see Copyright for the status of this software.
+ */
+#include <stdio.h>
+#include <libxml/parser.h>
+#include <libxml/tree.h>
+
+/*
+ *To compile this file using gcc you can type
+ *gcc `xml2-config --cflags --libs` -o xmlexample libxml2-example.c
+ */
+
+/**
+ * print_element_names:
+ * @a_node: the initial xml node to consider.
+ *
+ * Prints the names of the all the xml elements
+ * that are siblings or children of a given xml node.
+ */
+void
+print_element_names(xmlNode * a_node)
+{
+    xmlNode *cur_node = NULL;
+
+    for (cur_node = a_node; cur_node; cur_node = cur_node->next) {
+        if (cur_node->type == XML_ELEMENT_NODE) {
+            printf("node type: Element, name: %s\n", cur_node->name);
+        }
+
+        print_element_names(cur_node->children);
+    }
+}
+
+
+/**
+ * Simple example to parse a file called "file.xml", 
+ * walk down the DOM, and print the name of the 
+ * xml elements nodes.
+ */
+int
+main(int argc, char **argv)
+{
+    xmlDoc *doc = NULL;
+    xmlNode *root_element = NULL;
+
+    if (argc != 2)
+        return(1);
+
+    /*
+     * this initialize the library and check potential ABI mismatches
+     * between the version it was compiled for and the actual shared
+     * library used.
+     */
+    LIBXML_TEST_VERSION
+
+    /*parse the file and get the DOM */
+    doc = xmlParseFile(argv[1]);
+
+    if (doc == NULL) {
+        printf("error: could not parse file file.xml\n");
+    }
+
+    /*Get the root element node */
+    root_element = xmlDocGetRootElement(doc);
+
+    print_element_names(root_element);
+
+    /*free the document */
+    xmlFreeDoc(doc);
+
+    /*
+     *Free the global variables that may
+     *have been allocated by the parser.
+     */
+    xmlCleanupParser();
+
+    return 0;
+}

doc/examples/tree1.out

@@ -0,0 +1,4 @@
+node type: Element, name: doc
+node type: Element, name: src
+node type: Element, name: dest
+node type: Element, name: src