JsonReader

## JsonReader JsonReader — A cursor-based parser |

## Synopsis

    struct              JsonReader;
    struct              JsonReaderClass;
    JsonReader *        json_reader_new                     (JsonNode *node);
    void                json_reader_set_root                (JsonReader *reader,
                                                             JsonNode *root);

    gboolean            json_reader_read_element            (JsonReader *reader,
                                                             guint index_);
    void                json_reader_end_element             (JsonReader *reader);
    gboolean            json_reader_is_array                (JsonReader *reader);
    gint                json_reader_count_elements          (JsonReader *reader);

    gboolean            json_reader_read_member             (JsonReader *reader,
                                                             const gchar *member_name);
    void                json_reader_end_member              (JsonReader *reader);
    gboolean            json_reader_is_object               (JsonReader *reader);
    gint                json_reader_count_members           (JsonReader *reader);
    gchar **            json_reader_list_members            (JsonReader *reader);
    const gchar *       json_reader_get_member_name         (JsonReader *reader);

    gboolean            json_reader_is_value                (JsonReader *reader);
    JsonNode *          json_reader_get_value               (JsonReader *reader);
    gint64              json_reader_get_int_value           (JsonReader *reader);
    gdouble             json_reader_get_double_value        (JsonReader *reader);
    const gchar *       json_reader_get_string_value        (JsonReader *reader);
    gboolean            json_reader_get_boolean_value       (JsonReader *reader);
    gboolean            json_reader_get_null_value          (JsonReader *reader);

    enum                JsonReaderError;
    #define             JSON_READER_ERROR
    const GError *      json_reader_get_error               (JsonReader *reader);

## Object Hierarchy

      GObject
       +----JsonReader

## Properties

      "root"                     JsonNode*             : Read / Write / Construct

## Description

JsonReader provides a simple, cursor-based API for parsing a JSON DOM. It is similar, in spirit, to the XML Reader API.

In case of error, JsonReader 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.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    /* 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_get_error()`:

    1
    2
    3
    4
    5
    6
    7
    8
    /* 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);
      }

JsonReader is available since JSON-GLib 0.12.

## Details

### struct JsonReader

    struct JsonReader;

The JsonReader structure contains only private data and should only be accessed using the provided API

Since 0.12

### struct JsonReaderClass

    struct JsonReaderClass {
    };

The JsonReaderClass structure contains only private data

Since 0.12

### json_reader_new ()

    JsonReader *        json_reader_new                     (JsonNode *node);

Creates a new JsonReader. You can use this object to read the contents of the JSON tree starting from `node`

`node` : | a JsonNode, or `NULL`. [allow-none]
Returns : | the newly created JsonReader. Use `g_object_unref()` to release the allocated resources when done

Since 0.12

### json_reader_set_root ()

    void                json_reader_set_root                (JsonReader *reader,
                                                             JsonNode *root);

Sets the root JsonNode to be read by `reader`. The `reader` will take a copy of `root`

If another JsonNode is currently set as root, it will be replaced.

`reader` : | a JsonReader
`root` : | a JsonNode. [allow-none]

Since 0.12

### json_reader_read_element ()

    gboolean            json_reader_read_element            (JsonReader *reader,
                                                             guint index_);

Advances the cursor of `reader` to the element `index_` of the array or the object at the current position.

You can use the json_reader_get_value* family of functions to retrieve the value of the element; for instance:

    1
    2
    json_reader_read_element (reader, 0);
    int_value = json_reader_get_int_value (reader);

After reading the value, `json_reader_end_element()` should be called to reposition the cursor inside the JsonReader, e.g.:

    1
    2
    3
    4
    5
    6
    7
    json_reader_read_element (reader, 1);
    str_value = json_reader_get_string_value (reader);
    json_reader_end_element (reader);

    json_reader_read_element (reader, 2);
    str_value = json_reader_get_string_value (reader);
    json_reader_end_element (reader);

If `reader` is not currently on an array or an object, or if the `index_` is bigger than the size of the array or the object, the JsonReader will be put in an error state until `json_reader_end_element()` is called.

`reader` : | a JsonReader
`index_` : | the index of the element
Returns : | `TRUE` on success, and `FALSE` otherwise

Since 0.12

### json_reader_end_element ()

    void                json_reader_end_element             (JsonReader *reader);

Moves the cursor back to the previous node after being positioned inside an array

This function resets the error state of `reader`, if any was set

`reader` : | a JsonReader

Since 0.12

### json_reader_is_array ()

    gboolean            json_reader_is_array                (JsonReader *reader);

Checks whether the `reader` is currently on an array

`reader` : | a JsonReader
Returns : | `TRUE` if the JsonReader is on an array, and `FALSE` otherwise

Since 0.12

### json_reader_count_elements ()

    gint                json_reader_count_elements          (JsonReader *reader);

Counts the elements of the current position, if `reader` is positioned on an array

`reader` : | a JsonReader
Returns : | the number of elements, or -1. In case of failure the JsonReader is set in an error state

Since 0.12

### json_reader_read_member ()

    gboolean            json_reader_read_member             (JsonReader *reader,
                                                             const gchar *member_name);

Advances the cursor of `reader` to the `member_name` of the object at the current position.

You can use the json_reader_get_value* family of functions to retrieve the value of the member; for instance:

    1
    2
    json_reader_read_member (reader, "width");
    width = json_reader_get_int_value (reader);

After reading the value, `json_reader_end_member()` should be called to reposition the cursor inside the JsonReader, e.g.:

    1
    2
    3
    4
    5
    6
    7
    json_reader_read_member (reader, "author");
    author = json_reader_get_string_value (reader);
    json_reader_end_element (reader);

    json_reader_read_element (reader, "title");
    title = json_reader_get_string_value (reader);
    json_reader_end_element (reader);

If `reader` is not currently on an object, or if the `member_name` is not defined in the object, the JsonReader will be put in an error state until `json_reader_end_member()` is called.

`reader` : | a JsonReader
`member_name` : | the name of the member to read
Returns : | `TRUE` on success, and `FALSE` otherwise

Since 0.12

### json_reader_end_member ()

    void                json_reader_end_member              (JsonReader *reader);

Moves the cursor back to the previous node after being positioned inside an object

This function resets the error state of `reader`, if any was set

`reader` : | a JsonReader

Since 0.12

### json_reader_is_object ()

    gboolean            json_reader_is_object               (JsonReader *reader);

Checks whether the `reader` is currently on an object

`reader` : | a JsonReader
Returns : | `TRUE` if the JsonReader is on an object, and `FALSE` otherwise

Since 0.12

### json_reader_count_members ()

    gint                json_reader_count_members           (JsonReader *reader);

Counts the members of the current position, if `reader` is positioned on an object

`reader` : | a JsonReader
Returns : | the number of members, or -1. In case of failure the JsonReader is set in an error state

Since 0.12

### json_reader_list_members ()

    gchar **            json_reader_list_members            (JsonReader *reader);

Retrieves a list of member names from the current position, if `reader` is positioned on an object.

`reader` : | a JsonReader
Returns : | a newly allocated, `NULL`-terminated array of strings holding the members name. Use `g_strfreev()` when done. [transfer full]

Since 0.14

### json_reader_get_member_name ()

    const gchar *       json_reader_get_member_name         (JsonReader *reader);

Retrieves the name of the current member.

`reader` : | a JsonReader
Returns : | the name of the member, or `NULL`. [transfer none]

Since 0.14

### json_reader_is_value ()

    gboolean            json_reader_is_value                (JsonReader *reader);

Checks whether the `reader` is currently on a value

`reader` : | a JsonReader
Returns : | `TRUE` if the JsonReader is on a value, and `FALSE` otherwise

Since 0.12

### json_reader_get_value ()

    JsonNode *          json_reader_get_value               (JsonReader *reader);

Retrieves the JsonNode of the current position of `reader`

`reader` : | a JsonReader
Returns : | a JsonNode, or `NULL`. The returned node is owned by the JsonReader and it should not be modified or freed directly. [transfer none]

Since 0.12

### json_reader_get_int_value ()

    gint64              json_reader_get_int_value           (JsonReader *reader);

Retrieves the integer value of the current position of `reader`

`reader` : | a JsonReader
Returns : | the integer value

Since 0.12

### json_reader_get_double_value ()

    gdouble             json_reader_get_double_value        (JsonReader *reader);

Retrieves the floating point value of the current position of `reader`

`reader` : | a JsonReader
Returns : | the floating point value

Since 0.12

### json_reader_get_string_value ()

    const gchar *       json_reader_get_string_value        (JsonReader *reader);

Retrieves the string value of the current position of `reader`

`reader` : | a JsonReader
Returns : | the string value

Since 0.12

### json_reader_get_boolean_value ()

    gboolean            json_reader_get_boolean_value       (JsonReader *reader);

Retrieves the boolean value of the current position of `reader`

`reader` : | a JsonReader
Returns : | the boolean value

Since 0.12

### json_reader_get_null_value ()

    gboolean            json_reader_get_null_value          (JsonReader *reader);

Checks whether the value of the current position of `reader` is 'null'

`reader` : | a JsonReader
Returns : | `TRUE` if 'null' is set, and `FALSE` otherwise

Since 0.12

### enum JsonReaderError

    typedef enum {
      JSON_READER_ERROR_NO_ARRAY,
      JSON_READER_ERROR_INVALID_INDEX,
      JSON_READER_ERROR_NO_OBJECT,
      JSON_READER_ERROR_INVALID_MEMBER,
      JSON_READER_ERROR_INVALID_NODE,
      JSON_READER_ERROR_NO_VALUE,
      JSON_READER_ERROR_INVALID_TYPE
    } JsonReaderError;

Error codes enumeration for JsonReader errors

`JSON_READER_ERROR_NO_ARRAY` | No array found at the current position
`JSON_READER_ERROR_INVALID_INDEX` | Index out of bounds
`JSON_READER_ERROR_NO_OBJECT` | No object found at the current position
`JSON_READER_ERROR_INVALID_MEMBER` | Member not found
`JSON_READER_ERROR_INVALID_NODE` | No valid node found at the current position
`JSON_READER_ERROR_NO_VALUE` | The node at the current position does not hold a value
`JSON_READER_ERROR_INVALID_TYPE` | The node at the current position does not hold a value of the desired type

Since 0.12

### JSON_READER_ERROR

    #define JSON_READER_ERROR               (json_reader_error_quark ())

Error domain for JsonReader errors

Since 0.12

### json_reader_get_error ()

    const GError *      json_reader_get_error               (JsonReader *reader);

Retrieves the GError currently set on `reader`, if the JsonReader is in error state

`reader` : | a JsonReader
Returns : | the pointer to the error, or `NULL`. [transfer none]

Since 0.12

## Property Details

### The `"root"` property

      "root"                     JsonNode*             : Read / Write / Construct

The root of the JSON tree that the JsonReader should read.

Since 0.12