From 20c861f02f8e41cde2dec92f9d63d8266383c26b Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 6 Mar 2014 13:58:15 +0000 Subject: docs: Port to MarkDown Drop the DocBook documentation, and move everything to the MarkDown format used by modern gtk-doc. --- json-glib/json-path.c | 268 +++++++++++++++++++++----------------------------- 1 file changed, 110 insertions(+), 158 deletions(-) (limited to 'json-glib/json-path.c') diff --git a/json-glib/json-path.c b/json-glib/json-path.c index f829433..e212f87 100644 --- a/json-glib/json-path.c +++ b/json-glib/json-path.c @@ -40,162 +40,114 @@ * 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. - * + * ## Syntax of the JSONPath expressions ## * - * - * 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: - * - * + * 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: + * + * * Root node + * The '$' character represents the root node of the JSON tree, and + * matches the entire document. + * + * * Child nodes can either be matched using '.' or '[]'. For instance, + * both `$.store.book` and `$['store']['book'] match the contents of + * the book member of the store object. + * + * * Child nodes can be reached without specifying the whole tree structure + * through the recursive descent operator, or '..'. For instance, + * `$..author` matches all author member in every object. + * + * * Child nodes can grouped through the wildcard operator, or '*'. For + * instance, `$.store.book[*].author` matches all author members of any + * object element contained in the book array of the store object. + * + * * Element nodes can be accessed using their index (starting from zero) + * in the subscript operator '[]'. For instance, `$.store.book[0]` matches + * the first element of the book array of the store object. + * + * * Subsets of element nodes can be accessed using the set notation + * operator '[start,end]'. For instance, `$.store.book[0,2]` matches the + * first, second, and third elements of the book array of the store + * object. + * + * * Slices of element nodes can be accessed using the slice notation + * operation '[start:end:step]'. If start is omitted, the starting index + * of the slice is implied to be zero; if end is omitted, the ending index + * of the slice is implied to be the length of the array; if step is + * omitted, the step of the slice is implied to be 1. For instance, + * `$.store.book[:2]` matches the first two elements of the book array + * of the store object. + * + * More information about JSONPath is available on Stefan Gössner's + * [JSONPath website](http://goessner.net/articles/JsonPath/). + * + * ## Example of JSONPath matches + * The following example shows some of the results of using #JsonPath + * on a JSON tree. We use the following JSON description of a bookstore: + * |[ + * { "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" } + * } + * } + * ]| + * + * 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 (); + * json_generator_set_root (generator, result); + * char *str = json_generator_to_data (generator, NULL); + * g_print ("Results: %s\n", str); + * ]| + * + * The output will be: + * + * |[ + * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"] + * ]| * * #JsonPath is available since JSON-GLib 0.14 */ @@ -981,11 +933,11 @@ walk_path_node (GList *path, * Matches the JSON tree pointed by @root using the expression compiled * into the #JsonPath. * - * The matching #JsonNodes will be copied into a #JsonArray and + * The matching #JsonNodes will be copied into a #JsonArray and * returned wrapped in a #JsonNode. * * Return value: (transfer full): a newly-created #JsonNode of type - * %JSON_NODE_ARRAY containing an array of matching #JsonNodes. + * %JSON_NODE_ARRAY containing an array of matching #JsonNodes. * Use json_node_free() when done * * Since: 0.14 @@ -1025,7 +977,7 @@ json_path_match (JsonPath *path, * matches it against the JSON tree pointed by @root. * * Return value: (transfer full): a newly-created #JsonNode of type - * %JSON_NODE_ARRAY containing an array of matching #JsonNodes. + * %JSON_NODE_ARRAY containing an array of matching #JsonNodes. * Use json_node_free() when done * * Since: 0.14 -- cgit v1.2.1