JsonParser: JSON-GLib Reference Manual

## JsonParser JsonParser — Parse JSON data streams |

## Functions

JsonParser * | json_parser_new ()
gboolean | json_parser_load_from_file ()
gboolean | json_parser_load_from_data ()
gboolean | json_parser_load_from_stream ()
void | json_parser_load_from_stream_async ()
gboolean | json_parser_load_from_stream_finish ()
JsonNode * | json_parser_get_root ()
guint | json_parser_get_current_line ()
guint | json_parser_get_current_pos ()
gboolean | json_parser_has_assignment ()

## Signals

void | array-element | Run Last
void | array-end | Run Last
void | array-start | Run Last
void | error | Run Last
void | object-end | Run Last
void | object-member | Run Last
void | object-start | Run Last
void | parse-end | Run Last
void | parse-start | Run Last

## Types and Values

enum | JsonParserError
struct | JsonParser
struct | JsonParserClass

## Object Hierarchy

        GObject
        ╰── JsonParser

## Description

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

## Functions

### json_parser_new ()

    JsonParser *
    json_parser_new (void);

Creates a new JsonParser instance. You can use the JsonParser to load a JSON stream from either a file or a buffer and then walk the hierarchy using the data types API.

#### Returns

the newly created JsonParser. Use `g_object_unref()` to release all the memory it allocates.

### json_parser_load_from_file ()

    gboolean
    json_parser_load_from_file (JsonParser *parser,
                                const gchar *filename,
                                GError **error);

Loads a JSON stream from the content of `filename` and parses it. See `json_parser_load_from_data()`.

#### Parameters

parser | a JsonParser |
filename | the path for the file to parse |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the file was successfully loaded and parsed. In case of error, `error` is set accordingly and `FALSE` is returned

### json_parser_load_from_data ()

    gboolean
    json_parser_load_from_data (JsonParser *parser,
                                const gchar *data,
                                gssize length,
                                GError **error);

Loads a JSON stream from a buffer and parses it. You can call this function multiple times with the same JsonParser object, but the contents of the parser will be destroyed each time.

#### Parameters

parser | a JsonParser |
data | the buffer to parse |
length | the length of the buffer, or -1 |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the buffer was succesfully parser. In case of error, `error` is set accordingly and `FALSE` is returned

### json_parser_load_from_stream ()

    gboolean
    json_parser_load_from_stream (JsonParser *parser,
                                  GInputStream *stream,
                                  GCancellable *cancellable,
                                  GError **error);

Loads the contents of an input stream and parses them.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be set on the passed `error` .

#### Parameters

parser | a JsonParser |
stream | an open GInputStream |
cancellable | a GCancellable, or `NULL`. | [allow-none]
error | the return location for a GError, or `NULL` |

#### Returns

`TRUE` if the data stream was successfully read and parsed, and `FALSE` otherwise

Since 0.12

### json_parser_load_from_stream_async ()

    void
    json_parser_load_from_stream_async (JsonParser *parser,
                                        GInputStream *stream,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

Asynchronously reads the contents of `stream` .

For more details, see `json_parser_load_from_stream()` which is the synchronous version of this call.

When the operation is finished, `callback` will be called. You should then call `json_parser_load_from_stream_finish()` to get the result of the operation.

#### Parameters

parser | a JsonParser |
stream | a GInputStream |
cancellable | a GCancellable, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to `callback` |

Since 0.12

### json_parser_load_from_stream_finish ()

    gboolean
    json_parser_load_from_stream_finish (JsonParser *parser,
                                         GAsyncResult *result,
                                         GError **error);

Finishes an asynchronous stream loading started with `json_parser_load_from_stream_async()`.

#### Parameters

parser | a JsonParser |
result | a GAsyncResult |
error | the return location for a GError or `NULL` |

#### Returns

`TRUE` if the content of the stream was successfully retrieves and parsed, and `FALSE` otherwise. In case of error, the GError will be filled accordingly.

Since 0.12

### json_parser_get_root ()

    JsonNode *
    json_parser_get_root (JsonParser *parser);

Retrieves the top level node from the parsed JSON stream.

#### Parameters

parser | a JsonParser |

#### Returns

the root JsonNode . The returned node is owned by the JsonParser and should never be modified or freed.

[transfer none]

### json_parser_get_current_line ()

    guint
    json_parser_get_current_line (JsonParser *parser);

Retrieves the line currently parsed, starting from 1.

This function has defined behaviour only while parsing; calling this function from outside the signal handlers emitted by JsonParser will yield 0.

#### Parameters

parser | a JsonParser |

#### Returns

the currently parsed line, or 0.

### json_parser_get_current_pos ()

    guint
    json_parser_get_current_pos (JsonParser *parser);

Retrieves the current position inside the current line, starting from 0.

This function has defined behaviour only while parsing; calling this function from outside the signal handlers emitted by JsonParser will yield 0.

#### Parameters

parser | a JsonParser |

#### Returns

the position in the current line, or 0.

### json_parser_has_assignment ()

    gboolean
    json_parser_has_assignment (JsonParser *parser,
                                gchar **variable_name);

A JSON data stream might sometimes contain an assignment, like:

    1
    var _json_data = { "member_name" : [ ...

even though it would technically constitute a violation of the RFC.

JsonParser will ignore the left hand identifier and parse the right hand value of the assignment. JsonParser will record, though, the existence of the assignment in the data stream and the variable name used.

#### Parameters

parser | a JsonParser |
variable_name | Return location for the variable name, or `NULL`. | [out][allow-none][transfer none]

#### Returns

`TRUE` if there was an assignment, `FALSE` otherwise. If `variable_name` is not `NULL` it will be set to the name of the variable used in the assignment. The string is owned by JsonParser and should never be modified or freed.

Since 0.4

## Types and Values

### enum JsonParserError

Error enumeration for JsonParser

This enumeration can be extended at later date

#### Members

JSON_PARSER_ERROR_PARSE | parse error |
JSON_PARSER_ERROR_TRAILING_COMMA | unexpected trailing comma |
JSON_PARSER_ERROR_MISSING_COMMA | expected comma |
JSON_PARSER_ERROR_MISSING_COLON | expected colon |
JSON_PARSER_ERROR_INVALID_BAREWORD | invalid bareword |
JSON_PARSER_ERROR_EMPTY_MEMBER_NAME | empty member name (Since: 0.16) |
JSON_PARSER_ERROR_INVALID_DATA | invalid data (Since: 0.18) |
JSON_PARSER_ERROR_UNKNOWN | unknown error |

### struct JsonParser

    struct JsonParser;

JSON data streams parser. The contents of the JsonParser structure are private and should only be accessed via the provided API.

### struct JsonParserClass

    struct JsonParserClass {
      void (* parse_start)   (JsonParser   *parser);

      void (* object_start)  (JsonParser   *parser);
      void (* object_member) (JsonParser   *parser,
                              JsonObject   *object,
                              const gchar  *member_name);
      void (* object_end)    (JsonParser   *parser,
                              JsonObject   *object);

      void (* array_start)   (JsonParser   *parser);
      void (* array_element) (JsonParser   *parser,
                              JsonArray    *array,
                              gint          index_);
      void (* array_end)     (JsonParser   *parser,
                              JsonArray    *array);

      void (* parse_end)     (JsonParser   *parser);

      void (* error)         (JsonParser   *parser,
                              const GError *error);
    };

JsonParser class.

#### Members

`parse_start` () | class handler for the JsonParser::parse-start signal |
`object_start` () | class handler for the JsonParser::object-start signal |
`object_member` () | class handler for the JsonParser::object-member signal |
`object_end` () | class handler for the JsonParser::object-end signal |
`array_start` () | class handler for the JsonParser::array-start signal |
`array_element` () | class handler for the JsonParser::array-element signal |
`array_end` () | class handler for the JsonParser::array-end signal |
`parse_end` () | class handler for the JsonParser::parse-end signal |
`error` () | class handler for the JsonParser::error signal |

## Signal Details

### The `“array-element”` signal

    void
    user_function (JsonParser *parser,
                   JsonArray  *array,
                   gint        index_,
                   gpointer    user_data)

The ::array-element signal is emitted each time the JsonParser has successfully parsed a single element of a JsonArray. The array and element index are passed to the signal handlers.

#### Parameters

parser | the JsonParser that received the signal |
array | a JsonArray |
index_ | the index of the newly parsed element |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“array-end”` signal

    void
    user_function (JsonParser *parser,
                   JsonArray  *array,
                   gpointer    user_data)

The ::array-end signal is emitted each time the JsonParser has successfully parsed an entire JsonArray

#### Parameters

parser | the JsonParser that received the signal |
array | the parsed JsonArray |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“array-start”` signal

    void
    user_function (JsonParser *parser,
                   gpointer    user_data)

The ::array-start signal is emitted each time the JsonParser starts parsing a JsonArray

#### Parameters

parser | the JsonParser that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“error”` signal

    void
    user_function (JsonParser *parser,
                   gpointer    error,
                   gpointer    user_data)

The ::error signal is emitted each time a JsonParser encounters an error in a JSON stream.

#### Parameters

parser | the parser instance that received the signal |
error | a pointer to the GError |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“object-end”` signal

    void
    user_function (JsonParser *parser,
                   JsonObject *object,
                   gpointer    user_data)

The ::object-end signal is emitted each time the JsonParser has successfully parsed an entire JsonObject.

#### Parameters

parser | the JsonParser that received the signal |
object | the parsed JsonObject |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“object-member”` signal

    void
    user_function (JsonParser *parser,
                   JsonObject *object,
                   gchar      *member_name,
                   gpointer    user_data)

The ::object-member signal is emitted each time the JsonParser has successfully parsed a single member of a JsonObject. The object and member are passed to the signal handlers.

#### Parameters

parser | the JsonParser that received the signal |
object | a JsonObject |
member_name | the name of the newly parsed member |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“object-start”` signal

    void
    user_function (JsonParser *parser,
                   gpointer    user_data)

The ::object-start signal is emitted each time the JsonParser starts parsing a JsonObject.

#### Parameters

parser | the JsonParser that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“parse-end”` signal

    void
    user_function (JsonParser *parser,
                   gpointer    user_data)

The ::parse-end signal is emitted when the parser successfully finished parsing a JSON data stream

#### Parameters

parser | the JsonParser that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“parse-start”` signal

    void
    user_function (JsonParser *parser,
                   gpointer    user_data)

The ::parse-start signal is emitted when the parser began parsing a JSON data stream.

#### Parameters

parser | the JsonParser that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last