|  |  |  | 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 : | TRUEon success; on error,errorwill be set with
theJSON_PATH_ERRORdomain and a code from the JsonPathError
enumeration, andFALSEwill 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_ARRAYcontaining an array of matching JsonNodes.
Usejson_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_ARRAYcontaining an array of matching JsonNodes.
Usejson_node_free()when done. [transfer full] | 
Since 0.14