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

GI.Json.Structs.Node

Contents

Exported types
Methods

Description

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 nodeGetValue 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 nodeGetObject or nodeGetArray respectively, and then retrieve the nodes they contain.

A JsonNode may be marked as immutable using nodeSeal. This marks the node and all its descendents as read-only, and means that subsequent calls to setter functions (such as nodeSetArray) 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 nodeUnref), then either unreferenced exactly once more or freed (using nodeFree) to destroy them. The nodeFree function must not be used when a node might have a reference count not equal to 1. To this end, JSON-GLib uses nodeCopy and nodeUnref 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

newtype Node Source #

Memory-managed wrapper type.

Constructors

Node (ManagedPtr Node)

Instances

Instances details

Eq Node Source #
Instance details Defined in GI.Json.Structs.Node Methods (==) :: Node -> Node -> Bool # (/=) :: Node -> Node -> Bool #
GBoxed Node Source #
Instance details Defined in GI.Json.Structs.Node
ManagedPtrNewtype Node Source #
Instance details Defined in GI.Json.Structs.Node Methods toManagedPtr :: Node -> ManagedPtr Node
TypedObject Node Source #
Instance details Defined in GI.Json.Structs.Node Methods glibType :: IO GType
HasParentTypes Node Source #
Instance details Defined in GI.Json.Structs.Node
IsGValue (Maybe Node) Source #	Convert `Node` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Json.Structs.Node Methods gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Node -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Node)
type ParentTypes Node Source #
Instance details Defined in GI.Json.Structs.Node type ParentTypes Node = '[] :: [Type]

Methods

Click to display all available methods, including inherited ones

Expand

alloc

nodeAlloc Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m Node	Returns: the newly allocated node

Allocates a new, uninitialized node.

Use nodeInit and its variants to initialize the returned value.

Since: 0.16

copy

nodeCopy Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to copy
-> 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

nodeDupArray Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding an array
-> 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

nodeDupObject Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding a JSON object
-> 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

nodeDupString Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding a string
-> 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

nodeEqual Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`a`: a JSON node
-> Node	`b`: another JSON node
-> m Bool	Returns: `TRUE` if `a` and `b` are equal; `FALSE` otherwise

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

nodeFree Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to free
-> m ()

Frees the resources allocated by the node.

getArray

nodeGetArray Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding an array
-> 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

nodeGetBoolean Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding a boolean value
-> 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

nodeGetDouble Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding a floating point value
-> 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

nodeGetInt Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding an integer
-> 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

nodeGetNodeType Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to check
-> m NodeType	Returns: the type of the node

Retrieves the type of a node.

Since: 0.8

getObject

nodeGetObject Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding a JSON object
-> 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

nodeGetParent Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to query
-> m (Maybe Node)	Returns: the parent node, or `NULL` if `node` is the root node

Retrieves the parent node of the given node.

getString

nodeGetString Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node holding a string
-> 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

nodeGetValue Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a 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

nodeGetValueType Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to check
-> 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

nodeHash Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`key`: a JSON node to hash
-> m Word32	Returns: hash value for `key`

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

nodeInit Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> NodeType	`type`: the type of JSON node to initialize `node` to
-> 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

nodeInitArray Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> Maybe Array	`array`: the JSON array to initialize `node` with, or `NULL`
-> 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

nodeInitBoolean Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> Bool	`value`: a boolean value
-> 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

nodeInitDouble Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> Double	`value`: a floating point value
-> 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

nodeInitInt Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> Int64	`value`: an integer
-> 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

nodeInitNull Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> 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

nodeInitObject Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> Maybe Object	`object`: the JSON object to initialize `node` with, or `NULL`
-> 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

nodeInitString Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to initialize
-> Maybe Text	`value`: a string value
-> 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

nodeIsImmutable Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to check
-> m Bool	Returns: `TRUE` if the `node` is immutable

Check whether the given node has been marked as immutable by calling nodeSeal on it.

Since: 1.2

isNull

nodeIsNull Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to check
-> m Bool	Returns: `TRUE` if the node is null

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

nodeNew Source #

Arguments

:: (HasCallStack, MonadIO m)
=> NodeType	`type`: the type of the node to create
-> m Node	Returns: the newly created node

Creates a new node holding the given type.

This is a convenience function for nodeAlloc and nodeInit, and it's the equivalent of:

c code

  json_node_init (json_node_alloc (), type);

ref

nodeRef Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to reference
-> m Node	Returns: a pointer to `node`

Increments the reference count of node.

Since: 1.2

seal

nodeSeal Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to seal
-> 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

nodeSetArray Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_ARRAY`
-> Array	`array`: a JSON 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

nodeSetBoolean Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_VALUE`
-> Bool	`value`: a boolean value
-> 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

nodeSetDouble Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_VALUE`
-> Double	`value`: a double value
-> 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

nodeSetInt Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_VALUE`
-> Int64	`value`: an integer value
-> 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

nodeSetObject Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_OBJECT`
-> Maybe Object	`object`: a JSON 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

nodeSetParent Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to change
-> Maybe Node	`parent`: the parent 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

nodeSetString Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_VALUE`
-> Text	`value`: a string value
-> 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

nodeSetValue Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_VALUE`
-> GValue	`value`: the value to set
-> 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 to G_TYPE_INT64
G_TYPE_FLOAT to G_TYPE_DOUBLE

It is an error to call this on an immutable node, or on a node which is not a value node.

takeArray

nodeTakeArray Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_ARRAY`
-> Array	`array`: a JSON 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

nodeTakeObject Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a node initialized to `JSON_NODE_OBJECT`
-> Object	`object`: a JSON 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

nodeTypeName Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: a 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.

unref

nodeUnref Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Node	`node`: the node to unreference
-> m ()

Decrements the reference count of node.

If the reference count reaches zero, the node is freed.

Since: 1.2

Exported types

Instances

Methods

Click to display all available methods, including inherited ones

Methods

Getters

Setters

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

c code

ref

seal

setArray

setBoolean

setDouble

setInt

setObject

setParent

setString

setValue

takeArray

takeObject

typeName

unref