[glib/wip/doc-fixes: 1200/1200] docs: Add simple GMarkup parser example

[David King <davidk src gnome org>]

commit ae88f4054969af74efccfefa9e2017ee044b297d
Author: David King <amigadave amigadave com>
Date:   Fri Nov 23 18:47:03 2012 +0000

    docs: Add simple GMarkup parser example
    
    Based on an initial parser by Luc Pionchon.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=442929

 glib/gmarkup.c              |    2 +
 glib/tests/.gitignore       |    1 +
 glib/tests/Makefile.am      |    3 +
 glib/tests/markup-example.c |  150 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 156 insertions(+), 0 deletions(-)
---
diff --git a/glib/gmarkup.c b/glib/gmarkup.c
index f424026..799f401 100644
--- a/glib/gmarkup.c
+++ b/glib/gmarkup.c
@@ -81,6 +81,8 @@
  * <listitem>Character references</listitem>
  * <listitem>Sections marked as CDATA</listitem>
  * </itemizedlist>
+ *
+ * <example id="gmarkup-example"><title>Example GMarkup parser</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../glib/tests/markup-example.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
  */
 
 G_DEFINE_QUARK (g-markup-error-quark, g_markup_error)
diff --git a/glib/tests/.gitignore b/glib/tests/.gitignore
index 1bc83c5..80069c5 100644
--- a/glib/tests/.gitignore
+++ b/glib/tests/.gitignore
@@ -36,6 +36,7 @@ mainloop
 mappedfile
 markup-collect
 markup-escape
+markup-example
 markup-parse
 markup-subparser
 mem-overflow
diff --git a/glib/tests/Makefile.am b/glib/tests/Makefile.am
index 983259b..62b7e68 100644
--- a/glib/tests/Makefile.am
+++ b/glib/tests/Makefile.am
@@ -62,6 +62,9 @@ markup_collect_LDADD = $(progs_ldadd)
 TEST_PROGS         += markup-escape
 markup_escape_LDADD = $(progs_ldadd)
 
+TEST_PROGS               += markup-example
+markup_example_LDADD      = $(progs_ldadd)
+
 TEST_PROGS               += markup-subparser
 markup_subparser_LDADD    = $(progs_ldadd)
 
diff --git a/glib/tests/markup-example.c b/glib/tests/markup-example.c
new file mode 100644
index 0000000..dd34695
--- /dev/null
+++ b/glib/tests/markup-example.c
@@ -0,0 +1,150 @@
+#include <glib.h>
+
+/*
+ * Example XML for the parser.
+ */
+static const gchar foo_xml_example[] =
+"<foo bar='baz' bir='boz'>"
+"   <bar>bar text 1</bar> "
+"   <bar>bar text 2</bar> "
+"   foo text              "
+"<!-- nothing -->         "
+"</foo>                   ";
+
+static void foo_parser_start_element (GMarkupParseContext  *context,
+                                      const gchar          *element_name,
+                                      const gchar         **attribute_names,
+                                      const gchar         **attribute_values,
+                                      gpointer              user_data,
+                                      GError              **error);
+static void foo_parser_end_element   (GMarkupParseContext  *context,
+                                      const gchar          *element_name,
+                                      gpointer              user_data,
+                                      GError              **error);
+static void foo_parser_characters    (GMarkupParseContext  *context,
+                                      const gchar          *text,
+                                      gsize                 text_len,
+                                      gpointer              user_data,
+                                      GError              **error);
+static void foo_parser_passthrough   (GMarkupParseContext  *context,
+                                      const gchar          *passthrough_text,
+                                      gsize                 text_len,
+                                      gpointer              user_data,
+                                      GError              **error);
+static void foo_parser_error         (GMarkupParseContext  *context,
+                                      GError               *error,
+                                      gpointer              user_data);
+
+/*
+ * Parser
+ */
+static const GMarkupParser foo_xml_parser = {
+  foo_parser_start_element,
+  foo_parser_end_element,
+  foo_parser_characters,
+  foo_parser_passthrough,
+  foo_parser_error
+};
+
+/*
+ * Called for opening tags like <foo bar="baz">
+ */
+static void
+foo_parser_start_element (GMarkupParseContext *context,
+                          const gchar         *element_name,
+                          const gchar        **attribute_names,
+                          const gchar        **attribute_values,
+                          gpointer             user_data,
+                          GError             **error)
+{
+  gsize i;
+
+  g_print ("element: <%s>\n", element_name);
+
+  for (i = 0; attribute_names[i]; i++)
+    {
+      g_print ("attribute: %s = \"%s\"\n", attribute_names[i],
+                                           attribute_values[i]);
+    }
+}
+
+/*
+ * Called for closing tags like </foo>
+ */
+static void
+foo_parser_end_element (GMarkupParseContext *context,
+                        const gchar         *element_name,
+                        gpointer             user_data,
+                        GError             **error)
+{
+  g_print ("attribute: </%s>\n", element_name);
+}
+
+/*
+ * Called for character data. Text is not nul-terminated
+ */
+static void
+foo_parser_characters (GMarkupParseContext *context,
+                       const gchar         *text,
+                       gsize                text_len,
+                       gpointer             user_data,
+                       GError             **error)
+{
+  g_print ("text: [%s]\n", text);
+}
+
+/*
+ * Called for strings that should be re-saved verbatim in this same
+ * position, but are not otherwise interpretable. At the moment this
+ * includes comments and processing instructions. Text is not
+ * nul-terminated.
+ */
+static void
+foo_parser_passthrough    (GMarkupParseContext  *context,
+                           const gchar          *passthrough_text,
+                           gsize                 text_len,
+                           gpointer              user_data,
+                           GError              **error)
+{
+  g_print ("passthrough: %s\n", passthrough_text);
+}
+
+/*
+ * Called when any parsing method encounters an error. The GError should not be
+ * freed.
+ */
+static void
+foo_parser_error          (GMarkupParseContext  *context,
+                           GError               *error,
+                           gpointer              user_data)
+{
+  g_printerr ("ERROR: %s\n", error->message);
+}
+
+int main ()
+{
+  GMarkupParseContext *context;
+  gboolean success = FALSE;
+  glong len;
+
+  len = g_utf8_strlen (foo_xml_example, -1);
+  g_print ("Parsing: %s\n", foo_xml_example);
+  g_print ("(%ld UTF8 characters)\n", len);
+
+  context = g_markup_parse_context_new (&foo_xml_parser, 0, NULL, NULL);
+
+  success = g_markup_parse_context_parse (context, foo_xml_example, len, NULL);
+
+  g_markup_parse_context_free (context);
+
+  if (success)
+    {
+      g_print ("DONE\n");
+      return 0;
+    }
+  else
+    {
+      g_printerr ("ERROR\n");
+      return 1;
+    }
+}