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` ()
	`get_strict` ()
	`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)
	`set_strict` (strict)
	`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
`strict`	`bool`	r/w/en

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. `deprecated`
`array-end`	The `::array-end` signal is emitted each time a parser has successfully parsed an entire JSON array. `deprecated`
`array-start`	The `::array-start` signal is emitted each time a parser starts parsing a JSON array. `deprecated`
`error`	The `::error` signal is emitted each time a parser encounters an error in a JSON stream. `deprecated`
`object-end`	The `::object-end` signal is emitted each time a parser has successfully parsed an entire JSON object. `deprecated`
`object-member`	The `::object-member` signal is emitted each time a parser has successfully parsed a single member of a JSON object. `deprecated`
`object-start`	This signal is emitted each time a parser starts parsing a JSON object. `deprecated`
`parse-end`	This signal is emitted when a parser successfully finished parsing a JSON data stream. `deprecated`
`parse-start`	This signal is emitted when a parser starts parsing a JSON data stream. `deprecated`

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

get_strict()¶

Returns:: true if the parser is strict, and false otherwise
Return type:: bool

Retrieves whether the parser is operating in strict mode.

New in version 1.10.

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:

stream (Gio.InputStream) – the input stream with the JSON data
cancellable (Gio.Cancellable or None) – a Gio.Cancellable

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:

stream (Gio.InputStream) – the input stream with the JSON data
cancellable (Gio.Cancellable or None) – a Gio.Cancellable
callback (Gio.AsyncReadyCallback or None) – the function to call when the request is satisfied
user_data (object or None) – the data to pass to callback

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.

set_strict(strict)¶

Parameters:: strict (bool) – whether the parser should be strict

Sets whether the parser should operate in strict mode.

If strict is true, JsonParser will strictly conform to the JSON format.

If strict is false, JsonParser will allow custom extensions to the JSON format, like comments.

New in version 1.10.

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:

array (Json.Array) –
index (int) –

class handler for the Json.Parser ::array-element signal

do_array_end(array) virtual¶

Parameters:: array (Json.Array) –

class handler for the Json.Parser ::array-end signal

do_array_start() virtual¶: class handler for the Json.Parser ::array-start signal

do_error(error) virtual¶

Parameters:: error (GLib.Error) –

class handler for the Json.Parser ::error signal

do_object_end(object) virtual¶

Parameters:: object (Json.Object) –

class handler for the Json.Parser ::object-end signal

do_object_member(object, member_name) virtual¶

Parameters:

object (Json.Object) –
member_name (str) –

class handler for the Json.Parser ::object-member signal

do_object_start() virtual¶: class handler for the Json.Parser ::object-start signal

do_parse_end() virtual¶: class handler for the Json.Parser ::parse-end signal

do_parse_start() virtual¶: class handler for the Json.Parser ::parse-start signal

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.array_element] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.array_end] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.array_start] virtual function

Json.Parser.signals.error(parser, error)¶

Signal Name:

error

Flags:

RUN_LAST

Parameters:

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

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

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.error] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.object_end] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.object_member] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.object_start] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.parse_end] virtual function

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.

Deprecated since version 1.10: Derive your own parser type from JsonParser and override the [vfunc`Json`.Parser.parse_start] virtual function

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.

Json.Parser.props.strict¶

Name:: strict
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the parser should be strictly conforming to the JSON format, or allow custom extensions like comments.

New in version 1.10.