*** v4.3.0 - Added Github#9: "Support for XMLNode_add_sibling()".

	- Documentation update.
	- Rudimentary unit testing.

Author: Matthieu Labas

CHANGELOG

@@ -1,3 +1,7 @@
+*** v4.3.0 - Added Github#9: "Support for XMLNode_add_sibling()".
+	- Documentation update.
+	- Rudimentary unit testing.
+
 *** v4.2.7 - Fixed #20 by Richard Minner (SXMLC_VERSION not updated), #21, #22 by George Makarov (sx_f* consistency).
 
 *** v4.2.6 - Fixed #17, #18, #19 by Andreas Neustifter (infinite loop and compilation messages).

doc/datastruct.html

@@ -192,7 +192,7 @@ <h4>XML node</h4>
 <li>
 	<code>TAG_TEXT</code> (since v4.1.0) is a special node which <code>text</code> field contains the text of its father node.
 	It is particularly useful when you want to DOM-parse a document and want to keep the text position in the
-	childrend, instead of merging all text pieces (default behavior before v4.1.0).<br/>
+	children, instead of merging all text pieces (default behavior before v4.1.0).<br/>
 	Thanks go to Olgierd Stankiewicz for that improvement! :)
 </li>
 </ul>
@@ -207,6 +207,17 @@ <h4>XML node</h4>
 in between can lead to memory leak.
 </p>
 
+<h5>Inactive Nodes</h5>
+<p>
+Nodes can be <em>inactive</em>: they are still in the list of their father node's children, but will <em>not</em> be
+displayed by <code>XMLDoc_print()</code> or taken into account by any <code>XMLNode_*()</code> functions!
+</p>
+<p>
+Marking a node "invalid" is equivalent to send it to the trash bin: it will be invisible to every accessor functions.<br/>
+If there is a need to access them, it should be done by manipulating the father's children list directly (see more at
+<a href="howto.html#INACTIVE">Inactive nodes HOW TO</a>).
+</p>
+
 </div>
 
 <div id="ft">

doc/howto.html

@@ -125,6 +125,7 @@ <h2>How to</h2>
 	</ul>
 </li>
 <li><a href="#CUSTOM">Handle new tags</a>
+<li><a href="#INACTIVE">Handle inactive nodes</a>
 </ul>
 
 <hr/>
@@ -174,9 +175,9 @@ <h5>SAX parser</h5>
 There are only 6 callbacks that can be called when using the SAX parser (plus an additional one if needed):
 <ul>
 <li><code>start_doc</code> is called when document parsing starts, before parsing the first node.</li>
-<li><code>start_node</code> is called when a new node has been found (e.g. "<code>&lt;newNode param="val"&gt;</code>")</li>
+<li><code>start_node</code> is called when a new node has been found (e.g. "<code>&lt;newNode param="val"&gt;</code>"). <em>All node attributes are already read</em>.</li>
 <li><code>end_node</code> is called when a node is being closed. (e.g. "<code>&lt;/newNode&gt;</code>")</li>
-<li><code>new_text</code> is called when text has been read from a node(e.g. "<code>&lt;newNode&gt;My text&lt;/newNode&gt;</code>")</li>
+<li><code>new_text</code> is called when text has been read from a node(e.g. "<code>&lt;newNode&gt;My text&lt;/newNode&gt;</code>" or "<code>&lt;newNode&gt;My text&lt;OtherNode&gt;...</code>")</li>
 <li><code>end_doc</code> is called when document parsing ends. No other callbacks will be called after.</li>
 <li><code>on_error</code> is called when an error occurs during parsing. Parsing stops after.</li>
 <li><code>all_event</code> is given for those who prefer to handle all such events in a single function instead of three
@@ -297,9 +298,15 @@ <h6>DOM text handling</h6>
 <ul>
 <li><code>node1.text</code> is <code>NULL</code></li>
 <li><code>node1.n_children</code> is 3</li>
-<li><code>node1.children[0]->tag_type</code> is <code>TAG_FATHER</code></li>
-<li><code>node1.children[0]->text</code> is <code>text1</code></li>
-<li><code>node1.children[2]->text</code> is <code>text3</code></li>
+<li><code>node1.children[0]</code>:<ul>
+	<li><code>.tag_type</code> is <code>TAG_TEXT</code></li>
+	<li><code>.text</code> is <code>text1</code></li></ul></li>
+<li><code>node1.children[1]</code>:<ul>
+	<li><code>.tag_type</code> is <code>TAG_FATHER</code></li>
+	<li><code>.text</code> is <code>NULL</code></li></ul></li>
+<li><code>node1.children[2]</code>:<ul>
+	<li><code>.tag_type</code> is <code>TAG_TEXT</code></li>
+	<li><code>.text</code> is <code>text3</code></li></ul></li>
 </ul>
 The previous behavior is kept if <code>DOM_through_SAX.text_as_nodes</code> is 0 (text concatenation).
 </p>
@@ -318,38 +325,22 @@ <h4>Create an XML document</h4>
 
 XMLDoc_init(&doc);
 
-node = XMLNode_alloc();
-XMLNode_set_tag(node, "xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"");
-XMLNode_set_type(node, TAG_INSTR);
+node = XMLNode_new(TAG_INSTR, "xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"", NULL);
 XMLDoc_add_node(&doc, node);
 
-node = XMLNode_alloc();
-XMLNode_set_tag(node, " Pre-comment ");
-XMLNode_set_type(node, TAG_COMMENT);
-// Or since v4.3.0: node = XMLNode_new_node_comment(" Pre-comment ");
+node = XMLNode_new_node_comment(" Pre-comment ");
 XMLDoc_add_node(&doc, node);
 
-node = XMLNode_alloc();
-XMLNode_set_tag(node, "\nAnother one\nMulti-line...\n");
-XMLNode_set_type(node, TAG_COMMENT);
-// Or since v4.3.0: node = XMLNode_new_node_comment("\nAnother one\nMulti-line...\n");
+node = XMLNode_new_node_comment("\nAnother one\nMulti-line...\n");
 XMLDoc_add_node(&doc, node);
 
-node = XMLNode_alloc();
-XMLNode_set_tag(node, "properties");
-XMLNode_set_type(node, TAG_FATHER);
+node = XMLNode_new(TAG_FATHER, "properties", NULL);
 XMLDoc_add_node(&doc, node); // Becomes root node because of 'TAG_FATHER'
 
-node = XMLNode_alloc();
-XMLNode_set_type(node, TAG_COMMENT);
-XMLNode_set_tag(node, "Hello World!");
-// Or since v4.3.0: node = XMLNode_new_node_comment("Hello World!");
+node = XMLNode_new_node_comment("Hello World!");
 XMLDoc_add_child_root(&doc, node);
 
-node = XMLNode_alloc();
-XMLNode_set_tag(node, "info");
-XMLNode_set_text(node, "This is my name");
-// Or since v4.3.0: node = XMLNode_new_node_text("info", "This is my name");
+node = XMLNode_new_node_text("info", "This is my name");
 XMLNode_set_attribute(node, "type", "Name");
 XMLDoc_add_child_root(&doc, node);
 </pre>
@@ -543,6 +534,55 @@ <h4>Handle new tags</h4>
 </pre>
 </p>
 
+<a name="INACTIVE"/>
+<p>
+<h4>Handle inactive nodes</h4>
+<p>
+Nodes marked "inactive" are made invisible by <code>XMLNode_*()</code> accessor functions. So
+once a node retrieved by <code>XMLNode_get_child()</code> is marked as inactive, <em>you can no longer
+get a reference to it</em>! Instead, you have to manually access their father's children list directly
+(which <code>sxmlc</code> lets you do simply, hence its name ;-)).
+</p>
+<p>
+Consider the following XML:
+<pre class="code">
+&lt;root&gt;
+    &lt;child0&gt;
+    &lt;child1&gt;
+    &lt;child2&gt;
+&lt;/root&gt;
+</pre>
+The following code:
+<pre class="code">
+XMLNode* node;
+
+node = XMLNode_get_child(father, 0); // Get first ACTIVE child (real index: 0)
+XMLNode_print_header(node, stdout, 0, 4);
+node->active = false;
+
+node = XMLNode_get_child(father, 0); // Get first ACTIVE child (real index: 1)
+XMLNode_print_header(node, stdout, 0, 4);
+node->active = false;
+
+node = XMLNode_get_child(father, 0); // Get first ACTIVE child (real index: 2)
+XMLNode_print_header(node, stdout, 0, 4);
+node->active = false;
+
+father->children[1]->active = true; // Re-activate node [1] by direct access to children list
+
+node = XMLNode_get_child(father, 0); // Get first ACTIVE child (real index: 1)
+printf("\n");
+XMLNode_print_header(node, stdout, 0, 4);
+</pre>
+Will print the following:
+<pre class="code">
+&lt;child0&gt;
+&lt;child1&gt;
+&lt;child2&gt;
+
+&lt;child1&gt;
+</pre>
+</p>
 </div>
 
 <div id="ft">

src/examples/test.c

@@ -810,7 +810,7 @@ int _allin1(XMLEvent event, const XMLNode* node, SXML_CHAR* text, const int n, S
 	}
 }
 
-#if 1
+#if 0
 int main()
 {
 	int ret;