Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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
- newtype Reader = Reader (ManagedPtr Reader)
- class (GObject o, IsDescendantOf Reader o) => IsReader o
- toReader :: (MonadIO m, IsReader o) => o -> m Reader
- readerCountElements :: (HasCallStack, MonadIO m, IsReader a) => a -> m Int32
- readerCountMembers :: (HasCallStack, MonadIO m, IsReader a) => a -> m Int32
- readerEndElement :: (HasCallStack, MonadIO m, IsReader a) => a -> m ()
- readerEndMember :: (HasCallStack, MonadIO m, IsReader a) => a -> m ()
- readerGetBooleanValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m Bool
- readerGetDoubleValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m Double
- readerGetError :: (HasCallStack, MonadIO m, IsReader a) => a -> m (Maybe GError)
- readerGetIntValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m Int64
- readerGetMemberName :: (HasCallStack, MonadIO m, IsReader a) => a -> m (Maybe Text)
- readerGetNullValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m Bool
- readerGetStringValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m Text
- readerGetValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m (Maybe Node)
- readerIsArray :: (HasCallStack, MonadIO m, IsReader a) => a -> m Bool
- readerIsObject :: (HasCallStack, MonadIO m, IsReader a) => a -> m Bool
- readerIsValue :: (HasCallStack, MonadIO m, IsReader a) => a -> m Bool
- readerListMembers :: (HasCallStack, MonadIO m, IsReader a) => a -> m [Text]
- readerNew :: (HasCallStack, MonadIO m) => Maybe Node -> m Reader
- readerReadElement :: (HasCallStack, MonadIO m, IsReader a) => a -> Word32 -> m Bool
- readerReadMember :: (HasCallStack, MonadIO m, IsReader a) => a -> Text -> m Bool
- readerSetRoot :: (HasCallStack, MonadIO m, IsReader a) => a -> Maybe Node -> m ()
- clearReaderRoot :: (MonadIO m, IsReader o) => o -> m ()
- constructReaderRoot :: (IsReader o, MonadIO m) => Node -> m (GValueConstruct o)
- getReaderRoot :: (MonadIO m, IsReader o) => o -> m (Maybe Node)
- setReaderRoot :: (MonadIO m, IsReader o) => o -> Node -> m ()
Exported types
Memory-managed wrapper type.
Instances
Eq Reader Source # | |
GObject Reader Source # | |
Defined in GI.Json.Objects.Reader | |
ManagedPtrNewtype Reader Source # | |
Defined in GI.Json.Objects.Reader toManagedPtr :: Reader -> ManagedPtr Reader # | |
TypedObject Reader Source # | |
Defined in GI.Json.Objects.Reader | |
HasParentTypes Reader Source # | |
Defined in GI.Json.Objects.Reader | |
IsGValue (Maybe Reader) Source # | Convert |
Defined in GI.Json.Objects.Reader | |
type ParentTypes Reader Source # | |
Defined in GI.Json.Objects.Reader |
class (GObject o, IsDescendantOf Reader o) => IsReader o Source #
Instances
(GObject o, IsDescendantOf Reader o) => IsReader o Source # | |
Defined in GI.Json.Objects.Reader |
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, countElements, countMembers, endElement, endMember, forceFloating, freezeNotify, getv, isArray, isFloating, isObject, isValue, listMembers, notify, notifyByPspec, readElement, readMember, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getBooleanValue, getData, getDoubleValue, getError, getIntValue, getMemberName, getNullValue, getProperty, getQdata, getStringValue, getValue.
Setters
countElements
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> m (Maybe GError) | Returns: the current error |
Retrieves the error currently set on the reader.
Since: 0.12
getIntValue
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> m Bool | Returns: |
Checks whether the value of the current position of the reader is null
.
See also: [methodjson
.Reader.get_value]
Since: 0.12
getStringValue
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> m Bool | Returns: |
Checks whether the reader is currently on an array.
Since: 0.12
isObject
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> m Bool | Returns: |
Checks whether the reader is currently on an object.
Since: 0.12
isValue
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> m Bool | Returns: |
Checks whether the reader is currently on a value.
Since: 0.12
listMembers
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Maybe 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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> Word32 |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> Text |
|
-> m Bool | Returns: |
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,
should be called to
reposition the cursor inside the reader, e.g.:readerEndMember
`
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
:: (HasCallStack, MonadIO m, IsReader a) | |
=> a |
|
-> Maybe 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 ]