JsonParser

JsonParser — Parse JSON data streams

Properties

gboolean immutable Read / Write / Construct Only

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

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

JsonParser *
json_parser_new_immutable (void);

Creates a new JsonParser instance with its “immutable” property set to TRUE to create immutable output trees.

Returns

a new JsonParser.

[transfer full]

Since: 1.2


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

 

Property Details

The “immutable” property

  “immutable”                gboolean

Whether the JsonNode tree built by the JsonParser should be immutable when created. Making the output immutable on creation avoids the expense of traversing it to make it immutable later.

Flags: Read / Write / Construct Only

Default value: FALSE

Since: 1.2

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