From 23f628ee4f4feef09e32bd0215cd066f0cddede1 Mon Sep 17 00:00:00 2001
From: ooxi <85fcd0ef4ec8@f977375cdcd6.anonbox.net>
Date: Wed, 31 Oct 2012 21:01:27 +0100
Subject: [PATCH] Include updated example in README

---
 README.md      | 83 +++++++++++++++++++++++++++++++++++++++++++++++++-
 test/example.c | 21 ++++++++++++-
 2 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1f35f55..6089ccf 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,88 @@ into other projects without the need for big external dependencies.
 Usage
 -----
 
-Usage examples can be found in the [unit cases](https://github.com/ooxi/xml.c/blob/master/test/test-xml.c).
+This example is also [included in the repository](https://github.com/ooxi/xml.c/blob/master/test/example.c)
+and will be build by default. Most of the code is C boilerplate, the important
+functions are `xml_parse_document`, `xml_document_root`, `xml_node_name`,
+`xml_node_content` and `xml_node_child` / `xml_node_children`.
+
+```c
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <xml.h>
+
+
+
+int main(int argc, char** argv) {
+
+	/* XML source, could be read from disk
+	 */
+	uint8_t* source = ""
+		"<Root>"
+			"<Hello>World</Hello>"
+			"<This>"
+				"<Is>:-)</Is>"
+				"<An>:-O</An>"
+				"<Example>:-D</Example>"
+			"</This>"
+		"</Root>"
+	;
+
+
+	/* Parse the document
+	 *
+	 * Watch out: Remember not to free the source until you have freed the
+	 *     document itself. If you have to free the source before, supply a
+	 *     copy to xml_parse_document which can be freed together with the
+	 *     document (`free_buffer' argument to `xml_document_free')
+	 */
+	struct xml_document* document = xml_parse_document(source, strlen(source));
+
+	/* You _have_ to check the result of `xml_parse_document', if it's 0
+	 * then the source could not be parsed. If you think this is a bug in
+	 * xml.c, than use a debug build (cmake -DCMAKE_BUILD_TYPE=Debug) which
+	 * will verbosely tell you about the parsing process
+	 */
+	if (!document) {
+		printf("Could parse document\n");
+		exit(EXIT_FAILURE);
+	}
+	struct xml_node* root = xml_document_root(document);
+
+
+	/* Say Hello World :-)
+	 */
+	struct xml_node* root_hello = xml_node_child(root, 0);
+	struct xml_string* hello = xml_node_name(root_hello);
+	struct xml_string* world = xml_node_content(root_hello);
+
+	/* Watch out: `xml_string_copy' will not 0-terminate your buffers! (but
+	 *     `calloc' will :-)
+	 */
+	uint8_t* hello_0 = calloc(xml_string_length(hello) + 1, sizeof(uint8_t));
+	uint8_t* world_0 = calloc(xml_string_length(world) + 1, sizeof(uint8_t));
+	xml_string_copy(hello, hello_0, xml_string_length(hello));
+	xml_string_copy(world, world_0, xml_string_length(world));
+
+	printf("%s %s\n", hello_0, world_0);
+	free(hello_0);
+	free(world_0);
+
+
+	/* Extract amount of Root/This children
+	 */
+	struct xml_node* root_this = xml_node_child(root, 1);
+	printf("Root/This has %lu children\n", (unsigned long)xml_node_children(root_this));
+
+
+	/* Remember to free the document or you'll risk a memory leak
+	 */
+	xml_document_free(document, false);
+}
+```
+
+Another usage example can be found in the [unit case](https://github.com/ooxi/xml.c/blob/master/test/test-xml.c).
 
 
 License
diff --git a/test/example.c b/test/example.c
index 05980ea..ebf605c 100644
--- a/test/example.c
+++ b/test/example.c
@@ -45,7 +45,7 @@ int main(int argc, char** argv) {
 
 	/* Parse the document
 	 *
-	 * @warning Remember not to free the source until you have freed the
+	 * Watch out: Remember not to free the source until you have freed the
 	 *     document itself. If you have to free the source before, supply a
 	 *     copy to xml_parse_document which can be freed together with the
 	 *     document (`free_buffer' argument to `xml_document_free')
@@ -64,6 +64,25 @@ int main(int argc, char** argv) {
 	struct xml_node* root = xml_document_root(document);
 
 
+	/* Say Hello World :-)
+	 */
+	struct xml_node* root_hello = xml_node_child(root, 0);
+	struct xml_string* hello = xml_node_name(root_hello);
+	struct xml_string* world = xml_node_content(root_hello);
+
+	/* Watch out: `xml_string_copy' will not 0-terminate your buffers! (but
+	 *     `calloc' will :-)
+	 */
+	uint8_t* hello_0 = calloc(xml_string_length(hello) + 1, sizeof(uint8_t));
+	uint8_t* world_0 = calloc(xml_string_length(world) + 1, sizeof(uint8_t));
+	xml_string_copy(hello, hello_0, xml_string_length(hello));
+	xml_string_copy(world, world_0, xml_string_length(world));
+
+	printf("%s %s\n", hello_0, world_0);
+	free(hello_0);
+	free(world_0);
+
+
 	/* Extract amount of Root/This children
 	 */
 	struct xml_node* root_this = xml_node_child(root, 1);