[json-glib] docs: Document JsonPath and add it to the API reference

[Emmanuele Bassi <ebassi src gnome org>]

commit 257209ab47ebcbf36006dd3aa3fcee5545381c6f
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Wed Jun 1 07:54:26 2011 +0100

    docs: Document JsonPath and add it to the API reference

 doc/reference/json-glib-docs.xml     |    3 +-
 doc/reference/json-glib-sections.txt |   20 ++++
 doc/reference/json-glib.types        |    1 +
 json-glib/json-path.c                |  174 +++++++++++++++++++++++++++++++++-
 4 files changed, 195 insertions(+), 3 deletions(-)
---
diff --git a/doc/reference/json-glib-docs.xml b/doc/reference/json-glib-docs.xml
index 92bf7d9..3247ff8 100644
--- a/doc/reference/json-glib-docs.xml
+++ b/doc/reference/json-glib-docs.xml
@@ -15,7 +15,7 @@
     </copyright>
 
     <copyright>
-      <year>2009, 2010</year>
+      <year>2009, 2010, 2011</year>
       <holder>Intel Corporation</holder>
     </copyright>
 
@@ -103,6 +103,7 @@
       <title>Parser</title>
       <xi:include href="xml/json-parser.xml"/>
       <xi:include href="xml/json-reader.xml"/>
+      <xi:include href="xml/json-path.xml"/>
     </chapter>
 
     <chapter>
diff --git a/doc/reference/json-glib-sections.txt b/doc/reference/json-glib-sections.txt
index de2b990..293cd26 100644
--- a/doc/reference/json-glib-sections.txt
+++ b/doc/reference/json-glib-sections.txt
@@ -355,3 +355,23 @@ JsonReaderPrivate
 json_reader_get_type
 json_reader_error_quark
 </SECTION>
+
+<SECTION>
+<FILE>json-path</FILE>
+JsonPath
+JsonPathClass
+json_path_new
+JSON_PATH_ERROR
+JsonPathError
+json_path_compile
+json_path_match
+<SUBSECTION>
+json_path_query
+<SUBSECTION Standard>
+JSON_TYPE_PATH
+JSON_PATH
+JSON_IS_PATH
+<SUBSECTION Private>
+json_path_get_type
+json_path_error_quark
+</SECTION>
diff --git a/doc/reference/json-glib.types b/doc/reference/json-glib.types
index 01cb215..d937207 100644
--- a/doc/reference/json-glib.types
+++ b/doc/reference/json-glib.types
@@ -2,5 +2,6 @@
 json_builder_get_type
 json_generator_get_type
 json_parser_get_type
+json_path_get_type
 json_reader_get_type
 json_serializable_get_type
diff --git a/json-glib/json-path.c b/json-glib/json-path.c
index 5d00710..0857e05 100644
--- a/json-glib/json-path.c
+++ b/json-glib/json-path.c
@@ -23,9 +23,179 @@
 /**
  * SECTION:json-path
  * @Title: JsonPath
- * @Short_Desc: JSONPath implementation
+ * @short_description: JSONPath implementation
  *
- * JSONPath is FIXME
+ * #JsonPath is a simple class implementing the JSONPath syntax for extracting
+ * data out of a JSON tree. While the semantics of the JSONPath expressions are
+ * heavily borrowed by the XPath specification for XML, the syntax follows the
+ * ECMAScript origins of JSON.
+ *
+ * Once a #JsonPath instance has been created, it has to compile a JSONPath
+ * expression using json_path_compile() before being able to match it to a
+ * JSON tree; the same #JsonPath instance can be used to match multiple JSON
+ * trees. It it also possible to compile a new JSONPath expression using the
+ * same #JsonPath instance; the previous expression will be discarded only if
+ * the compilation of the new expression is successful.
+ *
+ * The simple convenience function json_path_query() can be used for one-off
+ * matching.
+ *
+ * <refsect2 id="json-path-syntax">
+ *   <title>Syntax of the JSONPath expressions</title>
+ *   <para>A JSONPath expression is composed by path indices and operators.
+ *   Each path index can either be a member name or an element index inside
+ *   a JSON tree. A JSONPath expression must start with the '$' operator; each
+ *   path index is separated using either the dot notation or the bracket
+ *   notation, e.g.:</para>
+ *   |[
+ *     /&ast; dot notation &ast;/
+ *     $.store.book[0].title
+ *     /&ast; bracket notation &ast;/
+ *     $['store']['book'][0]['title']
+ *   ]|
+ *   <para>The available operators are:</para>
+ *   <table frame='all' id="json-path-operators">
+ *     <title>Operators</title>
+ *     <tgroup cols='4'>
+ *       <colspec name='operator'/>
+ *       <colspec name='description'/>
+ *       <colspec name='example'/>
+ *       <colspec name='results'/>
+ *       <thead>
+ *         <row>
+ *           <entry>Operator</entry>
+ *           <entry>Description</entry>
+ *           <entry>Example</entry>
+ *           <entry>Results</entry>
+ *         </row>
+ *       </thead>
+ *       <tbody>
+ *         <row>
+ *           <entry>$</entry>
+ *           <entry>The root node</entry>
+ *           <entry>$</entry>
+ *           <entry>The whole document</entry>
+ *         </row>
+ *         <row>
+ *           <entry>. or []</entry>
+ *           <entry>The child member or element</entry>
+ *           <entry>$.store.book</entry>
+ *           <entry>The contents of the book member of the store object</entry>
+ *         </row>
+ *         <row>
+ *           <entry>..</entry>
+ *           <entry>Recursive descent</entry>
+ *           <entry>$..author</entry>
+ *           <entry>The content of the author member in every object</entry>
+ *         </row>
+ *         <row>
+ *           <entry>*</entry>
+ *           <entry>Wildcard</entry>
+ *           <entry>$.store.book[*].author</entry>
+ *           <entry>The content of the author member of any object of the
+ *           array contained in the book member of the store object</entry>
+ *         </row>
+ *         <row>
+ *           <entry>[]</entry>
+ *           <entry>Subscript</entry>
+ *           <entry>$.store.book[0]</entry>
+ *           <entry>The first element of the array contained in the book
+ *           member of the store object</entry>
+ *         </row>
+ *         <row>
+ *           <entry>[,]</entry>
+ *           <entry>Set</entry>
+ *           <entry>$.store.book[0,1]</entry>
+ *           <entry>The first two elements of the array contained in the
+ *           book member of the store object</entry>
+ *         </row>
+ *         <row>
+ *           <entry>[start:end:step]</entry>
+ *           <entry>Slice</entry>
+ *           <entry>$.store.book[:2]</entry>
+ *           <entry>The first two elements of the array contained in the
+ *           book member of the store object; the start and step are omitted
+ *           and implied to be 0 and 1, respectively</entry>
+ *         </row>
+ *       </tbody>
+ *     </tgroup>
+ *   </table>
+ *   <para>More information about JSONPath is available on Stefan Gössner's
+ *   <ulink url="http://goessner.net/articles/JsonPath/";>website</ulink>.</para>
+ * </refsect2>
+ *
+ * <example id="json-path-example">
+ *   <title>Example of JsonPath usage</title>
+ *   <para>The following example shows some of the results of using #JsonPath
+ *   on a JSON tree. We use the following JSON description of a
+ *   bookstore:</para>
+ * <programlisting><![CDATA[
+{ "store": {
+    "book": [
+      { "category": "reference",
+        "author": "Nigel Rees",
+        "title": "Sayings of the Century",
+        "price": "8.95"
+      },
+      { "category": "fiction",
+        "author": "Evelyn Waugh",
+        "title": "Sword of Honour",
+        "price": "12.99"
+      },
+      { "category": "fiction",
+        "author": "Herman Melville",
+        "title": "Moby Dick",
+        "isbn": "0-553-21311-3",
+        "price": "8.99"
+      },
+      { "category": "fiction",
+        "author": "J. R. R. Tolkien",
+        "title": "The Lord of the Rings",
+        "isbn": "0-395-19395-8",
+        "price": "22.99"
+      }
+    ],
+    "bicycle": {
+      "color": "red",
+      "price": "19.95"
+    }
+  }
+}
+]]></programlisting>
+ *   <para>We can parse the JSON using #JsonParser:</para>
+ *   <programlisting>
+ * JsonParser *parser = json_parser_new ();
+ * json_parser_load_from_data (parser, json_data, -1, NULL);
+ *   </programlisting>
+ *   <para>If we run the following code:</para>
+ *   <programlisting>
+ * JsonNode *result;
+ * JsonPath *path = json_path_new ();
+ * json_path_compile (path, "$.store..author", NULL);
+ * result = json_path_match (path, json_parser_get_root (parser));
+ *   </programlisting>
+ *   <para>The <emphasis>result</emphasis> #JsonNode will contain an array
+ *   with all values of the <emphasis>author</emphasis> member of the objects
+ *   in the JSON tree. If we use a #JsonGenerator to convert the #JsonNode
+ *   to a string and print it:</para>
+ *   <programlisting>
+ * JsonGenerator *generator = json_generator_new ();
+ * char *str;
+ * json_generator_set_pretty (generator, TRUE);
+ * json_generator_set_root (generator, result);
+ * str = json_generator_to_data (generator, NULL);
+ * g_print ("Results: %s\n", str);
+ *   </programlisting>
+ *   <para>The output will be:</para>
+ *   <programlisting><![CDATA[
+[
+  "Nigel Rees",
+  "Evelyn Waugh",
+  "Herman Melville",
+  "J. R. R. Tolkien"
+]
+]]></programlisting>
+ * </example>
  *
  * #JsonPath is available since JSON-GLib 0.14
  */