JsonPath

JsonPath — JSONPath implementation

Synopsis

#include <json-glib/json-glib.h>

                    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);

Object Hierarchy

  GObject
   +----JsonPath

Description

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.:

1
2
3
4
5
// 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 `[i,j,...]`. For instance, `$.store.book[0,2]` matches the elements 0 and 2 (the first and third) 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "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:

1
2
JsonParser *parser = json_parser_new ();
json_parser_load_from_data (parser, json_data, -1, NULL);

If we run the following code:

1
2
3
4
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:

1
2
3
4
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:

1
["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]

JsonPath is available since JSON-GLib 0.14

Details

JsonPath

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


JsonPathClass

typedef struct _JsonPathClass JsonPathClass;

The `JsonPathClass` structure is an opaque object class whose members cannot be directly accessed.

Since 0.14


json_path_new ()

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


JSON_PATH_ERROR

#define JSON_PATH_ERROR         (json_path_error_quark ())

Error domain for JsonPath errors

Since 0.14


enum JsonPathError

typedef enum {
  JSON_PATH_ERROR_INVALID_QUERY
} JsonPathError;

Error code enumeration for the JSON_PATH_ERROR domain.

JSON_PATH_ERROR_INVALID_QUERY

Invalid query

Since 0.14


json_path_compile ()

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().

path :

a JsonPath

expression :

a JSONPath expression

error :

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


json_path_match ()

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.

path :

a compiled JsonPath

root :

a JsonNode

Returns :

a newly-created JsonNode of type JSON_NODE_ARRAY containing an array of matching JsonNodes. Use json_node_unref() when done. [transfer full]

Since 0.14


json_path_query ()

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.

expression :

a JSONPath expression

root :

the root of a JSON tree

error :

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_unref() when done. [transfer full]

Since 0.14