Json.Reader

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class	new (node)
	count_elements ()
	count_members ()
	end_element ()
	end_member ()
	get_boolean_value ()
	get_current_node ()
	get_double_value ()
	get_error ()
	get_int_value ()
	get_member_name ()
	get_null_value ()
	get_string_value ()
	get_value ()
	is_array ()
	is_object ()
	is_value ()
	list_members ()
	read_element (index_)
	read_member (member_name)
	set_root (root)

Virtual Methods

Inherited:

GObject.Object (7)

Properties

Name	Type	Flags	Short Description
root	Json.Node	r/w/c	The root of the tree to read

Signals

Inherited:

GObject.Object (1)

Fields

Inherited:

GObject.Object (1)

Name	Type	Access	Description
parent_instance	GObject.Object	r

Class Details

class Json.Reader(**kwargs)

Bases:

GObject.Object

Abstract:

No

Structure:

Json.ReaderClass

JsonReader provides a simple, cursor-based API for parsing a JSON DOM.

It is similar, in spirit, to the XML Reader API.

Using Json.Reader

```c g_autoptr(Json.Parser) parser = Json.Parser.new ();

// str is defined elsewhere Json.Parser.load_from_data (parser, str, -1, None);

g_autoptr(Json.Reader) reader = Json.Reader.new (Json.Parser.get_root (parser));

Json.Reader.read_member (reader, “url”); const str *url = Json.Reader.get_string_value (reader); Json.Reader.end_member (reader);

Json.Reader.read_member (reader, “size”); Json.Reader.read_element (reader, 0); int width = Json.Reader.get_int_value (reader); Json.Reader.end_element (reader); Json.Reader.read_element (reader, 1); int height = Json.Reader.get_int_value (reader); Json.Reader.end_element (reader); Json.Reader.end_member (reader); ```

Error handling

In case of error, JsonReader will be set in an error state; all subsequent calls will simply be ignored until a function that resets the error state is called, e.g.:

```c // ask for the 7th element; if the element does not exist, the // reader will be put in an error state Json.Reader.read_element (reader, 6);

// in case of error, this will return None, otherwise it will // return the value of the element str = Json.Reader.get_string_value (value);

// this function resets the error state if any was set Json.Reader.end_element (reader); ```

If you want to detect the error state as soon as possible, you can use [method`Json`.Reader.get_error]:

``c // like the example above, but in this case we print out the // error immediately if (!json_reader_read_element (reader, 6))

{

const GError *error = json_reader_get_error (reader); g_print (“Unable to read the element: %s”, error->message);

}

``

New in version 0.12.

classmethod new(node)

Parameters:

node (Json.Node or None) – the root node

Returns:

the newly created reader

Return type:

Json.Reader

Creates a new reader.

You can use this object to read the contents of the JSON tree starting from the given node.

New in version 0.12.

count_elements()

Returns:

the number of elements, or -1.

Return type:

int

Counts the elements of the current position, if the reader is positioned on an array.

In case of failure, the reader is set to an error state.

New in version 0.12.

count_members()

Returns:

the number of members, or -1

Return type:

int

Counts the members of the current position, if the reader is positioned on an object.

In case of failure, the reader is set to an error state.

New in version 0.12.

end_element()

Moves the cursor back to the previous node after being positioned inside an array.

This function resets the error state of the reader, if any was set.

New in version 0.12.

end_member()

Moves the cursor back to the previous node after being positioned inside an object.

This function resets the error state of the reader, if any was set.

New in version 0.12.

get_boolean_value()

Returns:

the boolean value

Return type:

bool

Retrieves the boolean value of the current position of the reader.

See also: [method`Json`.Reader.get_value]

New in version 0.12.

get_current_node()

Returns:

the current node of the reader

Return type:

Json.Node or None

Retrieves the reader node at the current position.

New in version 1.8.

get_double_value()

Returns:

the floating point value

Return type:

float

Retrieves the floating point value of the current position of the reader.

See also: [method`Json`.Reader.get_value]

New in version 0.12.

get_error()

Returns:

the current error

Return type:

GLib.Error or None

Retrieves the error currently set on the reader.

New in version 0.12.

get_int_value()

Returns:

the integer value

Return type:

int

Retrieves the integer value of the current position of the reader.

See also: [method`Json`.Reader.get_value]

New in version 0.12.

get_member_name()

Returns:

the name of the member

Return type:

str or None

Retrieves the name of the current member.

In case of failure, the reader is set to an error state.

New in version 0.14.

get_null_value()

Returns:

TRUE if null is set, and FALSE otherwise

Return type:

bool

Checks whether the value of the current position of the reader is null.

See also: [method`Json`.Reader.get_value]

New in version 0.12.

get_string_value()

Returns:

the string value

Return type:

str

Retrieves the string value of the current position of the reader.

See also: [method`Json`.Reader.get_value]

New in version 0.12.

get_value()

Returns:

the current value node

Return type:

Json.Node or None

Retrieves the value node at the current position of the reader.

If the current position does not contain a scalar value, the reader is set to an error state.

New in version 0.12.

is_array()

Returns:

TRUE if the reader is on an array

Return type:

bool

Checks whether the reader is currently on an array.

New in version 0.12.

is_object()

Returns:

TRUE if the reader is on an object

Return type:

bool

Checks whether the reader is currently on an object.

New in version 0.12.

is_value()

Returns:

TRUE if the reader is on a value

Return type:

bool

Checks whether the reader is currently on a value.

New in version 0.12.

list_members()

Returns:

the members of the object

Return type:

[str]

Retrieves a list of member names from the current position, if the reader is positioned on an object.

In case of failure, the reader is set to an error state.

New in version 0.14.

read_element(index_)

Parameters:

index (int) – the index of the element

Returns:

TRUE on success, and FALSE otherwise

Return type:

bool

Advances the cursor of the reader to the element of the array or the member of the object at the given position.

You can use [method`Json`.Reader.get_value] and its wrapper functions to retrieve the value of the element; for instance, the following code will read the first element of the array at the current cursor position:

``c json_reader_read_element (reader, 0); int_value = json_reader_get_int_value (reader); ``

After reading the value, you should call [method`Json`.Reader.end_element] to reposition the cursor inside the reader, e.g.:

```c const str *str_value = None;

Json.Reader.read_element (reader, 1); str_value = Json.Reader.get_string_value (reader); Json.Reader.end_element (reader);

Json.Reader.read_element (reader, 2); str_value = Json.Reader.get_string_value (reader); Json.Reader.end_element (reader); ```

If the reader is not currently on an array or an object, or if the index is bigger than the size of the array or the object, the reader will be put in an error state until [method`Json`.Reader.end_element] is called. This means that, if used conditionally, [method`Json`.Reader.end_element] must be called on all branches:

```c if (!:obj:Json.Reader.read_element (reader, 1)) { GLib.propagate_error (error, Json.Reader.get_error (reader)); Json.Reader.end_element (reader); return False; } else { const str *str_value = Json.Reader.get_string_value (reader); Json.Reader.end_element (reader);

// use str_value

return True; } ```c

New in version 0.12.

read_member(member_name)

Parameters:

member_name (str) – the name of the member to read

Returns:

TRUE on success, and FALSE otherwise

Return type:

bool

Advances the cursor of the reader to the member_name of the object at the current position.

You can use [method`Json`.Reader.get_value] and its wrapper functions to retrieve the value of the member; for instance:

``c json_reader_read_member (reader, “width”); width = json_reader_get_int_value (reader); ``

After reading the value, json_reader_end_member() should be called to reposition the cursor inside the reader, e.g.:

```c Json.Reader.read_member (reader, “author”); author = Json.Reader.get_string_value (reader); Json.Reader.end_member (reader);

Json.Reader.read_member (reader, “title”); title = Json.Reader.get_string_value (reader); Json.Reader.end_member (reader); ```

If the reader is not currently on an object, or if the member_name is not defined in the object, the reader will be put in an error state until [method`Json`.Reader.end_member] is called. This means that if used conditionally, [method`Json`.Reader.end_member] must be called on all branches:

```c if (!:obj:Json.Reader.read_member (reader, “title”)) { GLib.propagate_error (error, Json.Reader.get_error (reader)); Json.Reader.end_member (reader); return False; } else { const str *str_value = Json.Reader.get_string_value (reader); Json.Reader.end_member (reader);

// use str_value

return True; } ```

New in version 0.12.

set_root(root)

Parameters:

root (Json.Node or None) – the root node

Sets the root node of the JSON tree to be read by self.

The reader will take a copy of the node.

New in version 0.12.

Property Details

Json.Reader.props.root

Name:

root

Type:

Json.Node

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT

The root of the JSON tree that the reader should read.

New in version 0.12.