Json.Parser

g GObject.Object GObject.Object Json.Parser Json.Parser GObject.Object->Json.Parser

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class

new ()

class

new_immutable ()

get_current_line ()

get_current_pos ()

get_root ()

has_assignment ()

load_from_data (data, length)

load_from_file (filename)

load_from_mapped_file (filename)

load_from_stream (stream, cancellable)

load_from_stream_async (stream, cancellable, callback, *user_data)

load_from_stream_finish (result)

steal_root ()

Virtual Methods

Inherited:

GObject.Object (7)

do_array_element (array, index_)

do_array_end (array)

do_array_start ()

do_error (error)

do_object_end (object)

do_object_member (object, member_name)

do_object_start ()

do_parse_end ()

do_parse_start ()

Properties

Name

Type

Flags

Short Description

immutable

bool

r/w/co

Whether the parser output is immutable.

Signals

Inherited:

GObject.Object (1)

Name

Short Description

array-element

The ::array-element signal is emitted each time a parser has successfully parsed a single element of a JSON array.

array-end

The ::array-end signal is emitted each time a parser has successfully parsed an entire JSON array.

array-start

The ::array-start signal is emitted each time a parser starts parsing a JSON array.

error

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

object-end

The ::object-end signal is emitted each time a parser has successfully parsed an entire JSON object.

object-member

The ::object-member signal is emitted each time a parser has successfully parsed a single member of a JSON object

object-start

This signal is emitted each time a parser starts parsing a JSON object.

parse-end

This signal is emitted when a parser successfully finished parsing a JSON data stream

parse-start

This signal is emitted when a parser starts parsing a JSON data stream.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent_instance

GObject.Object

r

Class Details

class Json.Parser(**kwargs)
Bases:

GObject.Object

Abstract:

No

Structure:

Json.ParserClass

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

Using Json.Parser

The JsonParser API is fairly simple:

```c bool parse_json (const str *filename) { g_autoptr(Json.Parser) parser = Json.Parser.new (); g_autoptr(GLib.Error) error = None

Json.Parser.load_from_file (parser, filename, &error); if (error != None) { g_critical (“Unable to parse ‘%s’: %s”, filename, error->message); return False; }

g_autoptr(Json.Node) 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 [method`Json`.Parser.load_from_stream_async()] 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 GTask and the synchronous JsonParser API inside the task itself.

classmethod new()
Returns:

the newly created parser

Return type:

Json.Parser

Creates a new JSON parser.

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.

classmethod new_immutable()
Returns:

the newly created parser

Return type:

Json.Parser

Creates a new parser instance with its [property`Json`.Parser:immutable] property set to TRUE to create immutable output trees.

New in version 1.2.

get_current_line()
Returns:

the currently parsed line, or 0.

Return type:

int

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 the parser will yield 0.

get_current_pos()
Returns:

the position in the current line, or 0.

Return type:

int

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 the parser will yield 0.

get_root()
Returns:

the root node.

Return type:

Json.Node or None

Retrieves the top level node from the parsed JSON stream.

If the parser input was an empty string, or if parsing failed, the root will be NULL. It will also be NULL if it has been stolen using [method`Json`.Parser.steal_root].

has_assignment()
Returns:

TRUE if there was an assignment, and FALSE otherwise

variable_name:

the variable name

Return type:

(bool, variable_name: str)

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

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

New in version 0.4.

load_from_data(data, length)
Parameters:
  • data (str) – the buffer to parse

  • length (int) – the length of the buffer, or -1 if it is NUL terminated

Raises:

GLib.Error

Returns:

TRUE if the buffer was succesfully parsed

Return type:

bool

Loads a JSON stream from a buffer and parses it.

You can call this function multiple times with the same parser, but the contents of the parser will be destroyed each time.

load_from_file(filename)
Parameters:

filename (str) – the path for the file to parse

Raises:

GLib.Error

Returns:

TRUE if the file was successfully loaded and parsed.

Return type:

bool

Loads a JSON stream from the content of filename and parses it.

If the file is large or shared between processes, [method`Json`.Parser.load_from_mapped_file] may be a more efficient way to load it.

See also: [method`Json`.Parser.load_from_data]

load_from_mapped_file(filename)
Parameters:

filename (str) – the path for the file to parse

Raises:

GLib.Error

Returns:

TRUE if the file was successfully loaded and parsed.

Return type:

bool

Loads a JSON stream from the content of filename and parses it.

Unlike [method`Json`.Parser.load_from_file], filename will be memory mapped as read-only and parsed. filename will be unmapped before this function returns.

If mapping or reading the file fails, a G_FILE_ERROR will be returned.

New in version 1.6.

load_from_stream(stream, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

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

Return type:

bool

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, G_IO_ERROR_CANCELLED will be set on the given error.

New in version 0.12.

load_from_stream_async(stream, cancellable, callback, *user_data)
Parameters:

Asynchronously reads the contents of a stream.

For more details, see [method`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 [method`Json`.Parser.load_from_stream_finish] to get the result of the operation.

New in version 0.12.

load_from_stream_finish(result)
Parameters:

result (Gio.AsyncResult) – the result of the asynchronous operation

Raises:

GLib.Error

Returns:

TRUE if the content of the stream was successfully retrieved and parsed, and FALSE otherwise

Return type:

bool

Finishes an asynchronous stream loading started with [method`Json`.Parser.load_from_stream_async].

New in version 0.12.

steal_root()
Returns:

the root node

Return type:

Json.Node or None

Steals the top level node from the parsed JSON stream.

This will be NULL in the same situations as [method`Json`.Parser.get_root] return NULL.

New in version 1.4.

do_array_element(array, index_) virtual
Parameters:
do_array_end(array) virtual
Parameters:

array (Json.Array) –

do_array_start() virtual
do_error(error) virtual
Parameters:

error (GLib.Error) –

do_object_end(object) virtual
Parameters:

object (Json.Object) –

do_object_member(object, member_name) virtual
Parameters:
do_object_start() virtual
do_parse_end() virtual
do_parse_start() virtual

Signal Details

Json.Parser.signals.array_element(parser, array, index_)
Signal Name:

array-element

Flags:

RUN_LAST

Parameters:
  • parser (Json.Parser) – The object which received the signal

  • array (Json.Array) – a JSON array

  • index (int) – the index of the newly parsed array element

The ::array-element signal is emitted each time a parser has successfully parsed a single element of a JSON array.

Json.Parser.signals.array_end(parser, array)
Signal Name:

array-end

Flags:

RUN_LAST

Parameters:
  • parser (Json.Parser) – The object which received the signal

  • array (Json.Array) – the parsed JSON array

The ::array-end signal is emitted each time a parser has successfully parsed an entire JSON array.

Json.Parser.signals.array_start(parser)
Signal Name:

array-start

Flags:

RUN_LAST

Parameters:

parser (Json.Parser) – The object which received the signal

The ::array-start signal is emitted each time a parser starts parsing a JSON array.

Json.Parser.signals.error(parser, error)
Signal Name:

error

Flags:

RUN_LAST

Parameters:

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

Json.Parser.signals.object_end(parser, object)
Signal Name:

object-end

Flags:

RUN_LAST

Parameters:
  • parser (Json.Parser) – The object which received the signal

  • object (Json.Object) – the parsed JSON object

The ::object-end signal is emitted each time a parser has successfully parsed an entire JSON object.

Json.Parser.signals.object_member(parser, object, member_name)
Signal Name:

object-member

Flags:

RUN_LAST

Parameters:
  • parser (Json.Parser) – The object which received the signal

  • object (Json.Object) – the JSON object being parsed

  • member_name (str) – the name of the newly parsed member

The ::object-member signal is emitted each time a parser has successfully parsed a single member of a JSON object

Json.Parser.signals.object_start(parser)
Signal Name:

object-start

Flags:

RUN_LAST

Parameters:

parser (Json.Parser) – The object which received the signal

This signal is emitted each time a parser starts parsing a JSON object.

Json.Parser.signals.parse_end(parser)
Signal Name:

parse-end

Flags:

RUN_LAST

Parameters:

parser (Json.Parser) – The object which received the signal

This signal is emitted when a parser successfully finished parsing a JSON data stream

Json.Parser.signals.parse_start(parser)
Signal Name:

parse-start

Flags:

RUN_LAST

Parameters:

parser (Json.Parser) – The object which received the signal

This signal is emitted when a parser starts parsing a JSON data stream.

Property Details

Json.Parser.props.immutable
Name:

immutable

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Whether the tree built by the parser should be immutable when created.

Making the output immutable on creation avoids the expense of traversing it to make it immutable later.

New in version 1.2.