From 257209ab47ebcbf36006dd3aa3fcee5545381c6f Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 1 Jun 2011 07:54:26 +0100 Subject: docs: Document JsonPath and add it to the API reference --- json-glib/json-path.c | 174 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 172 insertions(+), 2 deletions(-) (limited to 'json-glib/json-path.c') 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. + * + * + * Syntax of the JSONPath expressions + * 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.: + * |[ + * /* dot notation */ + * $.store.book[0].title + * /* bracket notation */ + * $['store']['book'][0]['title'] + * ]| + * The available operators are: + * + * Operators + * + * + * + * + * + * + * + * Operator + * Description + * Example + * Results + * + * + * + * + * $ + * The root node + * $ + * The whole document + * + * + * . or [] + * The child member or element + * $.store.book + * The contents of the book member of the store object + * + * + * .. + * Recursive descent + * $..author + * The content of the author member in every object + * + * + * * + * Wildcard + * $.store.book[*].author + * The content of the author member of any object of the + * array contained in the book member of the store object + * + * + * [] + * Subscript + * $.store.book[0] + * The first element of the array contained in the book + * member of the store object + * + * + * [,] + * Set + * $.store.book[0,1] + * The first two elements of the array contained in the + * book member of the store object + * + * + * [start:end:step] + * Slice + * $.store.book[:2] + * 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 + * + * + * + *
+ * More information about JSONPath is available on Stefan Gössner's + * website. + * + * + * + * Example of JsonPath usage + * The following example shows some of the results of using #JsonPath + * on a JSON tree. We use the following JSON description of a + * bookstore: + * + * We can parse the JSON using #JsonParser: + * + * JsonParser *parser = json_parser_new (); + * json_parser_load_from_data (parser, json_data, -1, NULL); + * + * If we run the following code: + * + * JsonNode *result; + * JsonPath *path = json_path_new (); + * json_path_compile (path, "$.store..author", NULL); + * result = json_path_match (path, json_parser_get_root (parser)); + * + * The result #JsonNode will contain an array + * with all values of the author member of the objects + * in the JSON tree. If we use a #JsonGenerator to convert the #JsonNode + * to a string and print it: + * + * 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); + * + * The output will be: + * + * * * #JsonPath is available since JSON-GLib 0.14 */ -- cgit v1.2.1