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 code
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 code
// 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
readerGetError
:
c code
// 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 gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Reader -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Reader) | |
type ParentTypes Reader Source # | |
Defined in GI.Json.Objects.Reader type ParentTypes Reader = '[Object] |
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: readerGetValue
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: readerGetValue
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: readerGetValue
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: readerGetValue
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: readerGetValue
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 readerGetValue
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 code
json_reader_read_element (reader, 0); int_value = json_reader_get_int_value (reader);
After reading the value, you should call readerEndElement
to reposition the cursor inside the reader, e.g.:
c code
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 readerEndElement
is called. This
means that, if used conditionally, readerEndElement
must be
called on all branches:
c code
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 readerGetValue
and its wrapper functions to
retrieve the value of the member; for instance:
c code
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 code
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
readerEndMember
is called. This means that if used
conditionally, readerEndMember
must be called on all branches:
c code
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 ]