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 |
- Exported types
- Methods
- alloc
- copy
- dupArray
- dupObject
- dupString
- equal
- free
- getArray
- getBoolean
- getDouble
- getInt
- getNodeType
- getObject
- getParent
- getString
- getValue
- getValueType
- hash
- init
- initArray
- initBoolean
- initDouble
- initInt
- initNull
- initObject
- initString
- isImmutable
- isNull
- new
- ref
- seal
- setArray
- setBoolean
- setDouble
- setInt
- setObject
- setParent
- setString
- setValue
- takeArray
- takeObject
- typeName
- unref
A generic container of JSON data types.
JsonNode
can contain fundamental types (integers, booleans, floating point
numbers, strings) and complex types (arrays and objects).
When parsing a JSON data stream you extract the root node and walk
the node tree by retrieving the type of data contained inside the
node with the JSON_NODE_TYPE
macro. If the node contains a fundamental
type you can retrieve a copy of the GValue
holding it with the
[methodjson
.Node.get_value] function, and then use the GValue
API to extract
the data; if the node contains a complex type you can retrieve the
[structjson
.Object] or the [structjson
.Array] using [methodjson
.Node.get_object]
or [methodjson
.Node.get_array] respectively, and then retrieve the nodes
they contain.
A JsonNode
may be marked as immutable using [methodjson
.Node.seal]. This
marks the node and all its descendents as read-only, and means that
subsequent calls to setter functions (such as [methodjson
.Node.set_array])
on them will abort as a programmer error. By marking a node tree as
immutable, it may be referenced in multiple places and its hash value cached
for fast lookups, without the possibility of a value deep within the tree
changing and affecting hash values. Immutable nodes may be passed to
functions which retain a reference to them without needing to take a copy.
A JsonNode
supports two types of memory management: malloc
/free
semantics, and reference counting semantics. The two may be mixed to a
limited extent: nodes may be allocated (which gives them a reference count
of 1), referenced one or more times, unreferenced exactly that number of
times (using [methodjson
.Node.unref]), then either unreferenced exactly
once more or freed (using [methodjson
.Node.free]) to destroy them.
The [methodjson
.Node.free] function must not be used when a node might
have a reference count not equal to 1. To this end, JSON-GLib uses
[methodjson
.Node.copy] and [methodjson
.Node.unref] internally.
Synopsis
- newtype Node = Node (ManagedPtr Node)
- nodeAlloc :: (HasCallStack, MonadIO m) => m Node
- nodeCopy :: (HasCallStack, MonadIO m) => Node -> m Node
- nodeDupArray :: (HasCallStack, MonadIO m) => Node -> m (Maybe Array)
- nodeDupObject :: (HasCallStack, MonadIO m) => Node -> m (Maybe Object)
- nodeDupString :: (HasCallStack, MonadIO m) => Node -> m (Maybe Text)
- nodeEqual :: (HasCallStack, MonadIO m) => Node -> Node -> m Bool
- nodeFree :: (HasCallStack, MonadIO m) => Node -> m ()
- nodeGetArray :: (HasCallStack, MonadIO m) => Node -> m (Maybe Array)
- nodeGetBoolean :: (HasCallStack, MonadIO m) => Node -> m Bool
- nodeGetDouble :: (HasCallStack, MonadIO m) => Node -> m Double
- nodeGetInt :: (HasCallStack, MonadIO m) => Node -> m Int64
- nodeGetNodeType :: (HasCallStack, MonadIO m) => Node -> m NodeType
- nodeGetObject :: (HasCallStack, MonadIO m) => Node -> m (Maybe Object)
- nodeGetParent :: (HasCallStack, MonadIO m) => Node -> m (Maybe Node)
- nodeGetString :: (HasCallStack, MonadIO m) => Node -> m (Maybe Text)
- nodeGetValue :: (HasCallStack, MonadIO m) => Node -> m GValue
- nodeGetValueType :: (HasCallStack, MonadIO m) => Node -> m GType
- nodeHash :: (HasCallStack, MonadIO m) => Node -> m Word32
- nodeInit :: (HasCallStack, MonadIO m) => Node -> NodeType -> m Node
- nodeInitArray :: (HasCallStack, MonadIO m) => Node -> Maybe Array -> m Node
- nodeInitBoolean :: (HasCallStack, MonadIO m) => Node -> Bool -> m Node
- nodeInitDouble :: (HasCallStack, MonadIO m) => Node -> Double -> m Node
- nodeInitInt :: (HasCallStack, MonadIO m) => Node -> Int64 -> m Node
- nodeInitNull :: (HasCallStack, MonadIO m) => Node -> m Node
- nodeInitObject :: (HasCallStack, MonadIO m) => Node -> Maybe Object -> m Node
- nodeInitString :: (HasCallStack, MonadIO m) => Node -> Maybe Text -> m Node
- nodeIsImmutable :: (HasCallStack, MonadIO m) => Node -> m Bool
- nodeIsNull :: (HasCallStack, MonadIO m) => Node -> m Bool
- nodeNew :: (HasCallStack, MonadIO m) => NodeType -> m Node
- nodeRef :: (HasCallStack, MonadIO m) => Node -> m Node
- nodeSeal :: (HasCallStack, MonadIO m) => Node -> m ()
- nodeSetArray :: (HasCallStack, MonadIO m) => Node -> Array -> m ()
- nodeSetBoolean :: (HasCallStack, MonadIO m) => Node -> Bool -> m ()
- nodeSetDouble :: (HasCallStack, MonadIO m) => Node -> Double -> m ()
- nodeSetInt :: (HasCallStack, MonadIO m) => Node -> Int64 -> m ()
- nodeSetObject :: (HasCallStack, MonadIO m) => Node -> Maybe Object -> m ()
- nodeSetParent :: (HasCallStack, MonadIO m) => Node -> Maybe Node -> m ()
- nodeSetString :: (HasCallStack, MonadIO m) => Node -> Text -> m ()
- nodeSetValue :: (HasCallStack, MonadIO m) => Node -> GValue -> m ()
- nodeTakeArray :: (HasCallStack, MonadIO m) => Node -> Array -> m ()
- nodeTakeObject :: (HasCallStack, MonadIO m) => Node -> Object -> m ()
- nodeTypeName :: (HasCallStack, MonadIO m) => Node -> m Text
- nodeUnref :: (HasCallStack, MonadIO m) => Node -> m ()
Exported types
Memory-managed wrapper type.
Instances
Eq Node Source # | |
GBoxed Node Source # | |
Defined in GI.Json.Structs.Node | |
ManagedPtrNewtype Node Source # | |
Defined in GI.Json.Structs.Node toManagedPtr :: Node -> ManagedPtr Node # | |
TypedObject Node Source # | |
Defined in GI.Json.Structs.Node | |
HasParentTypes Node Source # | |
Defined in GI.Json.Structs.Node | |
IsGValue (Maybe Node) Source # | Convert |
Defined in GI.Json.Structs.Node | |
type ParentTypes Node Source # | |
Defined in GI.Json.Structs.Node |
Methods
Click to display all available methods, including inherited ones
Methods
copy, dupArray, dupObject, dupString, equal, free, hash, init, initArray, initBoolean, initDouble, initInt, initNull, initObject, initString, isImmutable, isNull, ref, seal, takeArray, takeObject, typeName, unref.
Getters
getArray, getBoolean, getDouble, getInt, getNodeType, getObject, getParent, getString, getValue, getValueType.
Setters
setArray, setBoolean, setDouble, setInt, setObject, setParent, setString, setValue.
alloc
:: (HasCallStack, MonadIO m) | |
=> m Node | Returns: the newly allocated node |
Allocates a new, uninitialized node.
Use [methodjson
.Node.init] and its variants to initialize the returned value.
Since: 0.16
copy
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Node | Returns: the copied of the given node |
Copies node
.
If the node contains complex data types, their reference counts are increased, regardless of whether the node is mutable or immutable.
The copy will be immutable if, and only if, node
is immutable. However,
there should be no need to copy an immutable node.
dupArray
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Array) | Returns: the JSON array with its reference count increased. |
Retrieves the JSON array inside node
.
The reference count of the returned array is increased.
It is a programmer error to call this on a node which doesn’t hold an
array value. Use JSON_NODE_HOLDS_ARRAY
first.
dupObject
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Object) | Returns: the JSON object |
Retrieves the object inside node
.
The reference count of the returned object is increased.
It is a programmer error to call this on a node which doesn’t hold an
object value. Use JSON_NODE_HOLDS_OBJECT
first.
dupString
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Text) | Returns: a copy of the string inside the node |
Gets a copy of the string value stored inside a node.
If the node does not hold a string value, NULL
is returned.
equal
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Node |
|
-> m Bool | Returns: |
Check whether a
and b
are equal node, meaning they have the same
type and same values (checked recursively).
Note that integer values are compared numerically, ignoring type, so a double value 4.0 is equal to the integer value 4.
Since: 1.2
free
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m () |
Frees the resources allocated by the node.
getArray
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Array) | Returns: the JSON array |
Retrieves the JSON array stored inside a node.
It is a programmer error to call this on a node which doesn’t hold an
array value. Use JSON_NODE_HOLDS_ARRAY
first.
getBoolean
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Bool | Returns: a boolean value. |
Gets the boolean value stored inside a node.
If the node holds an integer or double value which is zero, FALSE
is
returned; otherwise TRUE
is returned.
If the node holds a JSON_NODE_NULL
value or a value of another
non-boolean type, FALSE
is returned.
getDouble
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Double | Returns: a double value. |
Gets the double value stored inside a node.
If the node holds an integer value, it is returned as a double.
If the node holds a FALSE
boolean value, 0.0
is returned; otherwise
a non-zero double is returned.
If the node holds a JSON_NODE_NULL
value or a value of another
non-double type, 0.0
is returned.
getInt
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Int64 | Returns: an integer value. |
Gets the integer value stored inside a node.
If the node holds a double value, its integer component is returned.
If the node holds a FALSE
boolean value, 0
is returned; otherwise,
a non-zero integer is returned.
If the node holds a JSON_NODE_NULL
value or a value of another
non-integer type, 0
is returned.
getNodeType
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m NodeType | Returns: the type of the node |
Retrieves the type of a node
.
Since: 0.8
getObject
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Object) | Returns: the JSON object |
Retrieves the object stored inside a node.
It is a programmer error to call this on a node which doesn’t hold an
object value. Use JSON_NODE_HOLDS_OBJECT
first.
getParent
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Node) | Returns: the parent node, or |
Retrieves the parent node of the given node
.
getString
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m (Maybe Text) | Returns: a string value. |
Gets the string value stored inside a node.
If the node does not hold a string value, NULL
is returned.
getValue
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m GValue |
Retrieves a value from a node and copies into value
.
When done using it, call g_value_unset()
on the GValue
to free the
associated resources.
It is a programmer error to call this on a node which doesn’t hold a scalar
value. Use JSON_NODE_HOLDS_VALUE
first.
getValueType
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m GType | Returns: the type for the payload |
Returns the GType
of the payload of the node.
For JSON_NODE_NULL
nodes, the returned type is G_TYPE_INVALID
.
Since: 0.4
hash
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Word32 | Returns: hash value for |
Calculate a hash value for the given key
.
The hash is calculated over the node and its value, recursively. If the node is immutable, this is a fast operation; otherwise, it scales proportionally with the size of the node’s value (for example, with the number of members in the JSON object if this node contains an object).
Since: 1.2
init
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> NodeType |
|
-> m Node | Returns: the initialized node |
Initializes a node
to a specific type
.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initArray
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Maybe Array |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_ARRAY
and sets array
into it.
This function will take a reference on array
.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initBoolean
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Bool |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_VALUE
and sets value
into it.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initDouble
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Double |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_VALUE
and sets value
into it.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initInt
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Int64 |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_VALUE
and sets value
into it.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initNull
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_NULL
.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initObject
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Maybe Object |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_OBJECT
and sets object
into it.
This function will take a reference on object
.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
initString
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Maybe Text |
|
-> m Node | Returns: the initialized node |
Initializes node
to JSON_NODE_VALUE
and sets value
into it.
If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.
Since: 0.16
isImmutable
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Bool | Returns: |
Check whether the given node
has been marked as immutable by calling
[methodjson
.Node.seal] on it.
Since: 1.2
isNull
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Bool | Returns: |
Checks whether node
is a JSON_NODE_NULL
.
A JSON_NODE_NULL
node is not the same as a NULL
node; a JSON_NODE_NULL
represents a literal null
value in the JSON tree.
Since: 0.8
new
:: (HasCallStack, MonadIO m) | |
=> NodeType |
|
-> m Node | Returns: the newly created node |
Creates a new node holding the given type
.
This is a convenience function for [ctorjson
.Node.alloc] and
[methodjson
.Node.init], and it's the equivalent of:
``c
json_node_init (json_node_alloc (), type);
``
ref
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Node | Returns: a pointer to |
Increments the reference count of node
.
Since: 1.2
seal
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m () |
Seals the given node, making it immutable to further changes.
In order to be sealed, the node
must have a type and value set. The value
will be recursively sealed — if the node holds an object, that JSON object
will be sealed, etc.
If the node
is already immutable, this is a no-op.
Since: 1.2
setArray
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Array |
|
-> m () |
Sets array
inside node
.
The reference count of array
is increased.
It is a programmer error to call this on a node which doesn’t hold an
array value. Use JSON_NODE_HOLDS_ARRAY
first.
setBoolean
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Bool |
|
-> m () |
Sets value
as the boolean content of the node
, replacing any existing
content.
It is an error to call this on an immutable node, or on a node which is not a value node.
setDouble
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Double |
|
-> m () |
Sets value
as the double content of the node
, replacing any existing
content.
It is an error to call this on an immutable node, or on a node which is not a value node.
setInt
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Int64 |
|
-> m () |
Sets value
as the integer content of the node
, replacing any existing
content.
It is an error to call this on an immutable node, or on a node which is not a value node.
setObject
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Maybe Object |
|
-> m () |
Sets objects
inside node
.
The reference count of object
is increased.
If object
is NULL
, the node’s existing object is cleared.
It is an error to call this on an immutable node, or on a node which is not an object node.
setParent
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Maybe Node |
|
-> m () |
Sets the parent node for the given node
.
It is an error to call this with an immutable parent
.
The node
may be immutable.
Since: 0.8
setString
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Text |
|
-> m () |
Sets value
as the string content of the node
, replacing any existing
content.
It is an error to call this on an immutable node, or on a node which is not a value node.
setValue
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> GValue |
|
-> m () |
Sets a scalar value inside the given node.
The contents of the given GValue
are copied into the JsonNode
.
The following GValue
types have a direct mapping to JSON types:
G_TYPE_INT64
G_TYPE_DOUBLE
G_TYPE_BOOLEAN
G_TYPE_STRING
JSON-GLib will also automatically promote the following GValue
types:
G_TYPE_INT
toG_TYPE_INT64
G_TYPE_FLOAT
toG_TYPE_DOUBLE
It is an error to call this on an immutable node, or on a node which is not a value node.
takeArray
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Array |
|
-> m () |
Sets array
inside node
.
The reference count of array
is not increased.
It is a programmer error to call this on a node which doesn’t hold an
array value. Use JSON_NODE_HOLDS_ARRAY
first.
takeObject
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> Object |
|
-> m () |
Sets object
inside node
.
The reference count of object
is not increased.
It is an error to call this on an immutable node, or on a node which is not an object node.
typeName
:: (HasCallStack, MonadIO m) | |
=> Node |
|
-> m Text | Returns: a string containing the name of the type |
Retrieves the user readable name of the data type contained by node
.
- *Note**: The name is only meant for debugging purposes, and there is no guarantee the name will stay the same across different versions.