json.c.types

Indicates the content of a node.

Error codes for JSON_PARSER_ERROR.

This enumeration can be extended at later date

Error codes for JSON_PATH_ERROR.

This enumeration can be extended at later date

Error codes for JSON_READER_ERROR.

This enumeration can be extended at later date

json.array.Array is the representation of the array type inside JSON.

A json.array.Array contains json.node.Node elements, which may contain fundamental types, other arrays or objects.

Since arrays can be arbitrarily big, copying them can be expensive; for this reason, they are reference counted. You can control the lifetime of a json.array.Array using json.array.Array.ref_ and json.array.Array.unref.

To append an element, use json.array.Array.addElement.

To extract an element at a given index, use json.array.Array.getElement.

To retrieve the entire array in list form, use json.array.Array.getElements.

To retrieve the length of the array, use json.array.Array.getLength.

json.builder.Builder provides an object for generating a JSON tree.

The root of the JSON tree can be either a json.object.ObjectWrap or a json.array.Array. Thus the first call must necessarily be either json.builder.Builder.beginObject or json.builder.Builder.beginArray.

For convenience to language bindings, most json.builder.Builder method return the instance, making it easy to chain function calls.

Using json.builder.Builder

g_autoptr(JsonBuilder) builder = json_builder_new ();

json_builder_begin_object (builder);

json_builder_set_member_name (builder, "url");
json_builder_add_string_value (builder, "http://www.gnome.org/img/flash/two-thirty.png");

json_builder_set_member_name (builder, "size");
json_builder_begin_array (builder);
json_builder_add_int_value (builder, 652);
json_builder_add_int_value (builder, 242);
json_builder_end_array (builder);

json_builder_end_object (builder);

g_autoptr(JsonNode) root = json_builder_get_root (builder);

g_autoptr(JsonGenerator) gen = json_generator_new ();
json_generator_set_root (gen, root);
g_autofree char *str = json_generator_to_data (gen, NULL);

// str now contains the following JSON data
// { "url" : "http://www.gnome.org/img/flash/two-thirty.png", "size" : [ 652, 242 ] }

json.generator.Generator provides an object for generating a JSON data stream from a tree of json.node.Node instances, and put it into a buffer or a file.

A generic container of JSON data types.

json.node.Node can contain fundamental types (integers, booleans, floating point numbers, strings) and complex types (arrays and objects).

When parsing a JSON data stream you extract the root node and walk the node tree by retrieving the type of data contained inside the node with the JSON_NODE_TYPE macro. If the node contains a fundamental type you can retrieve a copy of the gobject.value.Value holding it with the json.node.Node.getValue function, and then use the gobject.value.Value API to extract the data; if the node contains a complex type you can retrieve the json.object.ObjectWrap or the json.array.Array using json.node.Node.getObject or json.node.Node.getArray respectively, and then retrieve the nodes they contain.

A json.node.Node may be marked as immutable using json.node.Node.seal. This marks the node and all its descendents as read-only, and means that subsequent calls to setter functions (such as json.node.Node.setArray) on them will abort as a programmer error. By marking a node tree as immutable, it may be referenced in multiple places and its hash value cached for fast lookups, without the possibility of a value deep within the tree changing and affecting hash values. Immutable nodes may be passed to functions which retain a reference to them without needing to take a copy.

A json.node.Node supports two types of memory management: malloc/free semantics, and reference counting semantics. The two may be mixed to a limited extent: nodes may be allocated (which gives them a reference count of 1), referenced one or more times, unreferenced exactly that number of times (using json.node.Node.unref), then either unreferenced exactly once more or freed (using json.node.Node.free) to destroy them. The json.node.Node.free function must not be used when a node might have a reference count not equal to 1. To this end, JSON-GLib uses json.node.Node.copy and json.node.Node.unref internally.

An iterator object used to iterate over the members of a JSON object.

json.object_iter.ObjectIter must be allocated on the stack and initialised using json.object_iter.ObjectIter.init_ or json.object_iter.ObjectIter.initOrdered.

The iterator is invalidated if the object is modified during iteration.

All the fields in the json.object_iter.ObjectIter structure are private and should never be accessed directly.

json.object.ObjectWrap is the representation of the object type inside JSON.

A json.object.ObjectWrap contains json.node.Node "members", which may contain fundamental types, arrays or other objects; each member of an object is accessed using a unique string, or "name".

Since objects can be arbitrarily big, copying them can be expensive; for this reason they are reference counted. You can control the lifetime of a json.object.ObjectWrap using json.object.ObjectWrap.ref_ and json.object.ObjectWrap.unref.

To add or overwrite a member with a given name, use json.object.ObjectWrap.setMember.

To extract a member with a given name, use json.object.ObjectWrap.getMember.

To retrieve the list of members, use json.object.ObjectWrap.getMembers.

To retrieve the size of the object (that is, the number of members it has), use json.object.ObjectWrap.getSize.

json.parser.Parser provides an object for parsing a JSON data stream, either inside a file or inside a static buffer.

Using json.parser.Parser

The json.parser.Parser API is fairly simple:

gboolean
parse_json (const char *filename)
{
  g_autoptr(JsonParser) parser = json_parser_new ();
  g_autoptr(GError) error = NULL

  json_parser_load_from_file (parser, filename, &error);
  if (error != NULL)
    {
      g_critical ("Unable to parse '%s': %s", filename, error->message);
      return FALSE;
    }

  g_autoptr(JsonNode) root = json_parser_get_root (parser);

  // manipulate the object tree from the root node

  return TRUE
}

By default, the entire process of loading the data and parsing it is synchronous; the json.parser.Parser.loadFromStreamAsync API will load the data asynchronously, but parse it in the main context as the signals of the parser must be emitted in the same thread. If you do not use signals, and you wish to also parse the JSON data without blocking, you should use a gio.task.Task and the synchronous json.parser.Parser API inside the task itself.

The class structure for the JsonParser type.

json.path.Path 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 json.path.Path instance has been created, it has to compile a JSONPath expression using json.path.Path.compile before being able to match it to a JSON tree; the same json.path.Path instance can be used to match multiple JSON trees. It it also possible to compile a new JSONPath expression using the same json.path.Path instance; the previous expression will be discarded only if the compilation of the new expression is successful.

The simple convenience function json.path.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:

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

Example of JSONPath matches

The following example shows some of the results of using json.path.Path 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 json.parser.Parser:

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 node will contain an array with all values of the author member of the objects in the JSON tree. If we use a json.generator.Generator to convert the result node 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"]

json.reader.Reader provides a simple, cursor-based API for parsing a JSON DOM.

It is similar, in spirit, to the XML Reader API.

Using json.reader.Reader

g_autoptr(JsonParser) parser = json_parser_new ();

// str is defined elsewhere
json_parser_load_from_data (parser, str, -1, NULL);

g_autoptr(JsonReader) reader = json_reader_new (json_parser_get_root (parser));

json_reader_read_member (reader, "url");
  const char *url = json_reader_get_string_value (reader);
  json_reader_end_member (reader);

json_reader_read_member (reader, "size");
  json_reader_read_element (reader, 0);
    int width = json_reader_get_int_value (reader);
    json_reader_end_element (reader);
  json_reader_read_element (reader, 1);
    int height = json_reader_get_int_value (reader);
    json_reader_end_element (reader);
  json_reader_end_member (reader);

Error handling

In case of error, json.reader.Reader will be set in an error state; all subsequent calls will simply be ignored until a function that resets the error state is called, e.g.:

// ask for the 7th element; if the element does not exist, the
// reader will be put in an error state
json_reader_read_element (reader, 6);

// in case of error, this will return NULL, otherwise it will
// return the value of the element
str = json_reader_get_string_value (value);

// this function resets the error state if any was set
json_reader_end_element (reader);

If you want to detect the error state as soon as possible, you can use json.reader.Reader.getError:

// like the example above, but in this case we print out the
// error immediately
if (!json_reader_read_element (reader, 6))
  {
    const GError *error = json_reader_get_error (reader);
    g_print ("Unable to read the element: %s", error->message);
  }

json.serializable.Serializable is an interface for controlling the serialization and deserialization of gobject.object.ObjectWrap classes.

Implementing this interface allows controlling how the class is going to be serialized or deserialized by func@Json.construct_gobject and func@Json.serialize_gobject, respectively.

Interface that allows serializing and deserializing object instances with properties storing complex data types.

The func@Json.gobject_from_data and func@Json.gobject_to_data functions will check if the passed object type implements this interface, so it can also be used to override the default property serialization sequence.