Json.Parser¶
- Subclasses:
None
Methods¶
- Inherited:
- Structs:
class |
|
class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
|
|
|
|
|
|
|
|
|
|
|
|
Properties¶
Name |
Type |
Flags |
Short Description |
---|---|---|---|
r/w/co |
Whether the parser output is immutable. |
Signals¶
- Inherited:
Name |
Short Description |
---|---|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
This signal is emitted each time a parser starts parsing a JSON object. |
|
This signal is emitted when a parser successfully finished parsing a JSON data stream |
|
This signal is emitted when a parser starts parsing a JSON data stream. |
Fields¶
- Inherited:
Name |
Type |
Access |
Description |
---|---|---|---|
parent_instance |
r |
Class Details¶
- class Json.Parser(**kwargs)¶
- Bases:
- Abstract:
No
- Structure:
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 (conststr
*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); returnFalse
; }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 synchronousJsonParser
API inside the task itself.- classmethod new()¶
- Returns:
the newly created parser
- Return type:
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:
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:
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:
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()¶
-
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 beNULL
if it has been stolen using [method`Json`.Parser.steal_root].
- has_assignment()¶
- Returns:
TRUE
if there was an assignment, andFALSE
otherwise- variable_name:
the variable name
- Return type:
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:
- Raises:
- Returns:
TRUE
if the buffer was succesfully parsed- Return type:
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:
- Returns:
TRUE
if the file was successfully loaded and parsed.- Return type:
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:
- Returns:
TRUE
if the file was successfully loaded and parsed.- Return type:
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 datacancellable (
Gio.Cancellable
orNone
) – aGio.Cancellable
- Raises:
- Returns:
TRUE
if the data stream was successfully read and parsed, andFALSE
otherwise- Return type:
Loads the contents of an input stream and parses them.
If
cancellable
is notNULL
, 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 givenerror
.New in version 0.12.
- load_from_stream_async(stream, cancellable, callback, *user_data)¶
- Parameters:
stream (
Gio.InputStream
) – the input stream with the JSON datacancellable (
Gio.Cancellable
orNone
) – aGio.Cancellable
callback (
Gio.AsyncReadyCallback
orNone
) – the function to call when the request is satisfied
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:
- Returns:
TRUE
if the content of the stream was successfully retrieved and parsed, andFALSE
otherwise- Return type:
Finishes an asynchronous stream loading started with [method`Json`.Parser.load_from_stream_async].
New in version 0.12.
- steal_root()¶
-
Steals the top level node from the parsed JSON stream.
This will be
NULL
in the same situations as [method`Json`.Parser.get_root] returnNULL
.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:
- Parameters:
parser (
Json.Parser
) – The object which received the signalarray (
Json.Array
) – a JSON arrayindex (
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:
- Parameters:
parser (
Json.Parser
) – The object which received the signalarray (
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:
- 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:
- Parameters:
parser (
Json.Parser
) – The object which received the signal
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:
- Parameters:
parser (
Json.Parser
) – The object which received the signalobject (
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:
- Parameters:
parser (
Json.Parser
) – The object which received the signalobject (
Json.Object
) – the JSON object being parsedmember_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:
- 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:
- 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:
- 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:
- Default Value:
- Flags:
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.