![]() |
![]() |
![]() |
JSON-GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
JsonPath; JsonPathClass; JsonPath * json_path_new (void
); #define JSON_PATH_ERROR enum JsonPathError; gboolean json_path_compile (JsonPath *path
,const char *expression
,GError **error
); JsonNode * json_path_match (JsonPath *path
,JsonNode *root
); JsonNode * json_path_query (const char *expression
,JsonNode *root
,GError **error
);
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.
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.:
1 2 3 4 |
/* dot notation */ $.store.book[0].title /* bracket notation */ $['store']['book'][0]['title'] |
The available operators are:
Table 1. 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 1. 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:
{ "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 (); 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:
[ "Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien" ]
JsonPath is available since JSON-GLib 0.14
typedef struct _JsonPath JsonPath;
The JsonPath structure is an opaque object whose members cannot be directly accessed except through the provided API.
Since 0.14
typedef struct _JsonPathClass JsonPathClass;
The JsonPathClass structure is an opaque object class whose members cannot be directly accessed.
Since 0.14
JsonPath * json_path_new (void
);
Creates a new JsonPath instance.
Once created, the JsonPath object should be used with json_path_compile()
and json_path_match()
.
Returns : |
the newly created JsonPath instance. Use
g_object_unref() to free the allocated resources when done. [transfer full]
|
Since 0.14
#define JSON_PATH_ERROR (json_path_error_quark ())
Error domain for JsonPath errors
Since 0.14
typedef enum { JSON_PATH_ERROR_INVALID_QUERY } JsonPathError;
Error code enumeration for the JSON_PATH_ERROR
domain.
Since 0.14
gboolean json_path_compile (JsonPath *path
,const char *expression
,GError **error
);
Validates and decomposes expression
.
A JSONPath expression must be compiled before calling json_path_match()
.
|
a JsonPath |
|
a JSONPath expression |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success; on error, error will be set with
the JSON_PATH_ERROR domain and a code from the JsonPathError
enumeration, and FALSE will be returned |
Since 0.14
JsonNode * json_path_match (JsonPath *path
,JsonNode *root
);
Matches the JSON tree pointed by root
using the expression compiled
into the JsonPath.
The matching JsonNodes will be copied into a JsonArray and returned wrapped in a JsonNode.
|
a compiled JsonPath |
|
a JsonNode |
Returns : |
a newly-created JsonNode of type
JSON_NODE_ARRAY containing an array of matching JsonNodes.
Use json_node_free() when done. [transfer full]
|
Since 0.14
JsonNode * json_path_query (const char *expression
,JsonNode *root
,GError **error
);
Queries a JSON tree using a JSONPath expression.
This function is a simple wrapper around json_path_new()
,
json_path_compile()
and json_path_match()
. It implicitly
creates a JsonPath instance, compiles expression
and
matches it against the JSON tree pointed by root
.
|
a JSONPath expression |
|
the root of a JSON tree |
|
return location for a GError, or NULL
|
Returns : |
a newly-created JsonNode of type
JSON_NODE_ARRAY containing an array of matching JsonNodes.
Use json_node_free() when done. [transfer full]
|
Since 0.14