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

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

classmethod new()¶

Returns:	the newly created `Json.Parser`. Use `GObject.Object.unref`() to release all the memory it allocates.
Return type:	`Json.Parser`

Creates a new Json.Parser instance. You can use the Json.Parser 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:	a new `Json.Parser`
Return type:	`Json.Parser`

Creates a new Json.Parser instance with its 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 Json.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 Json.Parser will yield 0.

get_root()¶

Returns:	the root `Json.Node` . The returned node is owned by the `Json.Parser` and should never be modified or freed.
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, this will be None. It will also be None if it has been stolen using Json.Parser.steal_root().

has_assignment()¶

Returns:

True if there was an assignment, False otherwise. If variable_name is not None it will be set to the name of the variable used in the assignment. The string is owned by Json.Parser and should never be modified or freed.

variable_name:	Return location for the variable name, or `None`

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.

Json.Parser will ignore the left hand identifier and parse the right hand value of the assignment. Json.Parser 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
Raises:	`GLib.Error`
Returns:	`True` if the buffer was succesfully parsed. In case of error, error is set accordingly and `False` is returned
Return type:	`bool`

Loads a JSON stream from a buffer and parses it. You can call this function multiple times with the same Json.Parser object, 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. In case of error, error is set accordingly and `False` is returned
Return type:	`bool`

Loads a JSON stream from the content of filename and parses it. See Json.Parser.load_from_data().

If the file is large or shared between processes, Json.Parser.load_from_mapped_file() may be a more efficient way to load it.

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. In case of error, error is set accordingly and `False` is returned
Return type:	`bool`

Loads a JSON stream from the content of filename and parses it. Unlike 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`) – an open `Gio.InputStream` cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`, or `None`
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 None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be set on the passed error.

New in version 0.12.

load_from_stream_async(stream, cancellable, callback, *user_data)¶

Parameters:	stream (`Gio.InputStream`) – a `Gio.InputStream` cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – the data to pass to callback

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.

New in version 0.12.

load_from_stream_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` if the content of the stream was successfully retrieves and parsed, and `False` otherwise. In case of error, the `GLib.Error` will be filled accordingly.
Return type:	`bool`

Finishes an asynchronous stream loading started with Json.Parser.load_from_stream_async().

New in version 0.12.

steal_root()¶

Returns:	the top level `Json.Node`
Return type:	`Json.Node` or `None`

Steals the top level node from the parsed JSON stream. This will be None in the same situations as Json.Parser.get_root() returns None.

New in version 1.4.

do_array_element(array, index_) virtual¶

Parameters:	array (`Json.Array`) – index (`int`) –

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:	object (`Json.Object`) – member_name (`str`) –

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 element

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

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 the Json.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 the Json.Parser starts parsing a Json.Array

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`) – a pointer to the `GLib.Error`

The ::error signal is emitted each time a Json.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 the Json.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`) – a `Json.Object` member_name (`str`) – the name of the newly parsed member

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

Json.Parser.signals.object_start(parser)¶

Signal Name:	`object-start`
Flags:	`RUN_LAST`
Parameters:	parser (`Json.Parser`) – The object which received the signal

The ::object-start signal is emitted each time the Json.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

The ::parse-end signal is emitted when the 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

The ::parse-start signal is emitted when the parser began 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 Json.Node tree built by the Json.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.