gi-json-1.0.2: JSON GObject bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Json.Objects.Reader

Description

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

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

Using JsonReader

``@c g_autoptr(JsonParser) parser = json_parser_new ();

// str is defined elsewhere json_parser_load_from_data (parser, str, -1, NULL);

g_autoptr(JsonReader) reader = json_reader_new (json_parser_get_root (parser));

json_reader_read_member (reader, "url"); const char *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 NULL, 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); } @``

Since: 0.12

Synopsis

Exported types

newtype Reader Source #

Memory-managed wrapper type.

Constructors

Reader (ManagedPtr Reader) 

Instances

Instances details
Eq Reader Source # 
Instance details

Defined in GI.Json.Objects.Reader

Methods

(==) :: Reader -> Reader -> Bool #

(/=) :: Reader -> Reader -> Bool #

GObject Reader Source # 
Instance details

Defined in GI.Json.Objects.Reader

ManagedPtrNewtype Reader Source # 
Instance details

Defined in GI.Json.Objects.Reader

TypedObject Reader Source # 
Instance details

Defined in GI.Json.Objects.Reader

Methods

glibType :: IO GType #

HasParentTypes Reader Source # 
Instance details

Defined in GI.Json.Objects.Reader

IsGValue (Maybe Reader) Source #

Convert Reader to and from GValue. See toGValue and fromGValue.

Instance details

Defined in GI.Json.Objects.Reader

type ParentTypes Reader Source # 
Instance details

Defined in GI.Json.Objects.Reader

class (GObject o, IsDescendantOf Reader o) => IsReader o Source #

Type class for types which can be safely cast to Reader, for instance with toReader.

Instances

Instances details
(GObject o, IsDescendantOf Reader o) => IsReader o Source # 
Instance details

Defined in GI.Json.Objects.Reader

toReader :: (MonadIO m, IsReader o) => o -> m Reader Source #

Cast to Reader, for types for which this is known to be safe. For general casts, use castTo.

Methods

countElements

readerCountElements Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Int32

Returns: the number of elements, or -1.

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.

Since: 0.12

countMembers

readerCountMembers Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Int32

Returns: the number of members, or -1

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.

Since: 0.12

endElement

readerEndElement Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m () 

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.

Since: 0.12

endMember

readerEndMember Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m () 

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.

Since: 0.12

getBooleanValue

readerGetBooleanValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Bool

Returns: the boolean value

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

See also: [methodjson.Reader.get_value]

Since: 0.12

getDoubleValue

readerGetDoubleValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Double

Returns: the floating point value

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

See also: [methodjson.Reader.get_value]

Since: 0.12

getError

readerGetError Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m (Maybe GError)

Returns: the current error

Retrieves the error currently set on the reader.

Since: 0.12

getIntValue

readerGetIntValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Int64

Returns: the integer value

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

See also: [methodjson.Reader.get_value]

Since: 0.12

getMemberName

readerGetMemberName Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m (Maybe Text)

Returns: the name of the member

Retrieves the name of the current member.

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

Since: 0.14

getNullValue

readerGetNullValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Bool

Returns: TRUE if null is set, and FALSE otherwise

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

See also: [methodjson.Reader.get_value]

Since: 0.12

getStringValue

readerGetStringValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Text

Returns: the string value

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

See also: [methodjson.Reader.get_value]

Since: 0.12

getValue

readerGetValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m (Maybe Node)

Returns: the current value node

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.

Since: 0.12

isArray

readerIsArray Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Bool

Returns: TRUE if the reader is on an array

Checks whether the reader is currently on an array.

Since: 0.12

isObject

readerIsObject Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Bool

Returns: TRUE if the reader is on an object

Checks whether the reader is currently on an object.

Since: 0.12

isValue

readerIsValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m Bool

Returns: TRUE if the reader is on a value

Checks whether the reader is currently on a value.

Since: 0.12

listMembers

readerListMembers Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> m [Text]

Returns: the members of the object

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.

Since: 0.14

new

readerNew Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Maybe Node

node: the root node

-> m Reader

Returns: the newly created reader

Creates a new reader.

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

Since: 0.12

readElement

readerReadElement Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> Word32

index_: the index of the element

-> m Bool

Returns: TRUE on success, and FALSE otherwise

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 [methodjson.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 char *str_value = NULL;

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 (!json_reader_read_element (reader, 1)) { g_propagate_error (error, json_reader_get_error (reader)); json_reader_end_element (reader); return FALSE; } else { const char *str_value = json_reader_get_string_value (reader); json_reader_end_element (reader);

// use str_value

return TRUE; } @``c

Since: 0.12

readMember

readerReadMember Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> Text

memberName: the name of the member to read

-> m Bool

Returns: TRUE on success, and FALSE otherwise

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

You can use [methodjson.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, readerEndMember 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 (!json_reader_read_member (reader, "title")) { g_propagate_error (error, json_reader_get_error (reader)); json_reader_end_member (reader); return FALSE; } else { const char *str_value = json_reader_get_string_value (reader); json_reader_end_member (reader);

// use str_value

return TRUE; } @``

Since: 0.12

setRoot

readerSetRoot Source #

Arguments

:: (HasCallStack, MonadIO m, IsReader a) 
=> a

reader: a reader

-> Maybe Node

root: the root node

-> m () 

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

The reader will take a copy of the node.

Since: 0.12

Properties

root

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

Since: 0.12

clearReaderRoot :: (MonadIO m, IsReader o) => o -> m () Source #

Set the value of the “root” property to Nothing. When overloading is enabled, this is equivalent to

clear #root

constructReaderRoot :: (IsReader o, MonadIO m) => Node -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “root” property. This is rarely needed directly, but it is used by new.

getReaderRoot :: (MonadIO m, IsReader o) => o -> m (Maybe Node) Source #

Get the value of the “root” property. When overloading is enabled, this is equivalent to

get reader #root

setReaderRoot :: (MonadIO m, IsReader o) => o -> Node -> m () Source #

Set the value of the “root” property. When overloading is enabled, this is equivalent to

set reader [ #root := value ]