GI.Json.Objects.Parser

JsonParser provides an object for parsing a JSON data stream, either inside a file or inside a static buffer.

Using JsonParser

The JsonParser API is fairly simple:

``@c gboolean parse_json (const char *filename) { g_autoptr(JsonParser) parser = json_parser_new (); g_autoptr(GError) error = NULL

json_parser_load_from_file (parser, filename, &error); if (error != NULL) { g_critical ("Unable to parse '%s': %s", filename, error->message); return FALSE; }

g_autoptr(JsonNode) root = json_parser_get_root (parser);

// manipulate the object tree from the root node

return TRUE } `

By default, the entire process of loading the data and parsing it is synchronous; the [[e-mail]_from_stream_async()] API will load the data asynchronously, but parse it in the main context as the signals of the parser must be emitted in the same thread. If you do not use signals, and you wish to also parse the JSON data without blocking, you should use a GTask and the synchronous @JsonParser` API inside the task itself.

Exported types

newtype Parser

Memory-managed wrapper type.

Constructors

Parser (ManagedPtr Parser)

Instances

Eq Parser

Defined in GI.Json.Objects.Parser

Methods

(==) :: Parser -> Parser -> Bool

(/=) :: Parser -> Parser -> Bool

GObject Parser

Defined in GI.Json.Objects.Parser

ManagedPtrNewtype Parser

Defined in GI.Json.Objects.Parser

Methods

toManagedPtr :: Parser -> ManagedPtr Parser

TypedObject Parser

Defined in GI.Json.Objects.Parser

Methods

glibType :: IO GType

HasParentTypes Parser

Defined in GI.Json.Objects.Parser

IsGValue (Maybe Parser)

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

Defined in GI.Json.Objects.Parser

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Parser -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Parser)

type ParentTypes Parser

Defined in GI.Json.Objects.Parser

type ParentTypes Parser = '[Object]

class (GObject o, IsDescendantOf Parser o) => IsParser o

Type class for types which can be safely cast to Parser, for instance with toParser.

Instances

(GObject o, IsDescendantOf Parser o) => IsParser o

Defined in GI.Json.Objects.Parser

toParser :: (MonadIO m, IsParser o) => o -> m Parser

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

Methods

Click to display all available methods, including inherited ones

Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, hasAssignment, isFloating, loadFromData, loadFromFile, loadFromMappedFile, loadFromStream, loadFromStreamAsync, loadFromStreamFinish, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, stealRoot, thawNotify, unref, watchClosure.

Getters

getCurrentLine, getCurrentPos, getData, getProperty, getQdata, getRoot.

Setters

setData, setDataFull, setProperty.

getCurrentLine

parserGetCurrentLine

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> m Word32

Returns: the currently parsed line, or 0.

Retrieves the line currently parsed, starting from 1.

This function has defined behaviour only while parsing; calling this function from outside the signal handlers emitted by the parser will yield 0.

getCurrentPos

parserGetCurrentPos

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> m Word32

Returns: the position in the current line, or 0.

Retrieves the current position inside the current line, starting from 0.

This function has defined behaviour only while parsing; calling this function from outside the signal handlers emitted by the parser will yield 0.

getRoot

parserGetRoot

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> m (Maybe Node)

Returns: the root node.

Retrieves the top level node from the parsed JSON stream.

If the parser input was an empty string, or if parsing failed, the root will be NULL. It will also be NULL if it has been stolen using [methodjson.Parser.steal_root].

hasAssignment

parserHasAssignment

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> m (Bool, Text)

Returns: TRUE if there was an assignment, and FALSE otherwise

A JSON data stream might sometimes contain an assignment, like:

`` var _json_data = { "member_name" : [ ... `@

even though it would technically constitute a violation of the RFC.

JsonParser will ignore the left hand identifier and parse the right hand value of the assignment. @JsonParser` will record, though, the existence of the assignment in the data stream and the variable name used.

Since: 0.4

loadFromData

parserLoadFromData

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> Text

data: the buffer to parse

-> Int64

length: the length of the buffer, or -1 if it is NUL terminated

-> m ()

(Can throw GError)

Loads a JSON stream from a buffer and parses it.

You can call this function multiple times with the same parser, but the contents of the parser will be destroyed each time.

loadFromFile

parserLoadFromFile

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> [Char]

filename: the path for the file to parse

-> m ()

(Can throw GError)

Loads a JSON stream from the content of filename and parses it.

If the file is large or shared between processes, [methodjson.Parser.load_from_mapped_file] may be a more efficient way to load it.

See also: [methodjson.Parser.load_from_data]

loadFromMappedFile

parserLoadFromMappedFile

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> [Char]

filename: the path for the file to parse

-> m ()

(Can throw GError)

Loads a JSON stream from the content of filename and parses it.

Unlike [methodjson.Parser.load_from_file], filename will be memory mapped as read-only and parsed. filename will be unmapped before this function returns.

If mapping or reading the file fails, a G_FILE_ERROR will be returned.

Since: 1.6

loadFromStream

parserLoadFromStream

Arguments

:: (HasCallStack, MonadIO m, IsParser a, IsInputStream b, IsCancellable c)

=> a

parser: a parser

-> b

stream: the input stream with the JSON data

-> Maybe c

cancellable: a Cancellable

-> m ()

(Can throw GError)

Loads the contents of an input stream and parses them.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, G_IO_ERROR_CANCELLED will be set on the given error.

Since: 0.12

loadFromStreamAsync

parserLoadFromStreamAsync

Arguments

:: (HasCallStack, MonadIO m, IsParser a, IsInputStream b, IsCancellable c)

=> a

parser: a parser

-> b

stream: the input stream with the JSON data

-> Maybe c

cancellable: a Cancellable

-> Maybe AsyncReadyCallback

callback: the function to call when the request is satisfied

-> m ()

Asynchronously reads the contents of a stream.

For more details, see [methodjson.Parser.load_from_stream], which is the synchronous version of this call.

When the operation is finished, callback will be called. You should then call [methodjson.Parser.load_from_stream_finish] to get the result of the operation.

Since: 0.12

loadFromStreamFinish

parserLoadFromStreamFinish

Arguments

:: (HasCallStack, MonadIO m, IsParser a, IsAsyncResult b)

=> a

parser: a parser

-> b

result: the result of the asynchronous operation

-> m ()

(Can throw GError)

Finishes an asynchronous stream loading started with [methodjson.Parser.load_from_stream_async].

Since: 0.12

new

parserNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Parser

Returns: the newly created parser

Creates a new JSON parser.

You can use the JsonParser to load a JSON stream from either a file or a buffer and then walk the hierarchy using the data types API.

newImmutable

parserNewImmutable

Arguments

:: (HasCallStack, MonadIO m)

=> m Parser

Returns: the newly created parser

Creates a new parser instance with its [propertyjson.Parser:immutable] property set to TRUE to create immutable output trees.

Since: 1.2

stealRoot

parserStealRoot

Arguments

:: (HasCallStack, MonadIO m, IsParser a)

=> a

parser: a parser

-> m (Maybe Node)

Returns: the root node

Steals the top level node from the parsed JSON stream.

This will be NULL in the same situations as [methodjson.Parser.get_root] return NULL.

Since: 1.4

Properties

immutable

Whether the tree built by the parser should be immutable when created.

Making the output immutable on creation avoids the expense of traversing it to make it immutable later.

Since: 1.2

constructParserImmutable :: (IsParser o, MonadIO m) => Bool -> m (GValueConstruct o)

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

getParserImmutable :: (MonadIO m, IsParser o) => o -> m Bool

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

get parser #immutable

Signals

arrayElement

type ParserArrayElementCallback

Arguments

 = Array

array: a JSON array

-> Int32

index_: the index of the newly parsed array element

-> IO ()

The ::array-element signal is emitted each time a parser has successfully parsed a single element of a JSON array.

afterParserArrayElement :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserArrayElementCallback) -> m SignalHandlerId

Connect a signal handler for the arrayElement signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #arrayElement callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserArrayElement :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserArrayElementCallback) -> m SignalHandlerId

Connect a signal handler for the arrayElement signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #arrayElement callback

arrayEnd

type ParserArrayEndCallback

Arguments

 = Array

array: the parsed JSON array

-> IO ()

The ::array-end signal is emitted each time a parser has successfully parsed an entire JSON array.

afterParserArrayEnd :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserArrayEndCallback) -> m SignalHandlerId

Connect a signal handler for the arrayEnd signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #arrayEnd callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserArrayEnd :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserArrayEndCallback) -> m SignalHandlerId

Connect a signal handler for the arrayEnd signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #arrayEnd callback

arrayStart

type ParserArrayStartCallback = IO ()

The ::array-start signal is emitted each time a parser starts parsing a JSON array.

afterParserArrayStart :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserArrayStartCallback) -> m SignalHandlerId

Connect a signal handler for the arrayStart signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #arrayStart callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserArrayStart :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserArrayStartCallback) -> m SignalHandlerId

Connect a signal handler for the arrayStart signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #arrayStart callback

error

type ParserErrorCallback

Arguments

 = Ptr ()

error: the error

-> IO ()

The ::error signal is emitted each time a parser encounters an error in a JSON stream.

afterParserError :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserErrorCallback) -> m SignalHandlerId

Connect a signal handler for the error signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #error callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserError :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserErrorCallback) -> m SignalHandlerId

Connect a signal handler for the error signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #error callback

objectEnd

type ParserObjectEndCallback

Arguments

 = Object

object: the parsed JSON object

-> IO ()

The ::object-end signal is emitted each time a parser has successfully parsed an entire JSON object.

afterParserObjectEnd :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserObjectEndCallback) -> m SignalHandlerId

Connect a signal handler for the objectEnd signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #objectEnd callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserObjectEnd :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserObjectEndCallback) -> m SignalHandlerId

Connect a signal handler for the objectEnd signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #objectEnd callback

objectMember

type ParserObjectMemberCallback

Arguments

 = Object

object: the JSON object being parsed

-> Text

memberName: the name of the newly parsed member

-> IO ()

The ::object-member signal is emitted each time a parser has successfully parsed a single member of a JSON object

afterParserObjectMember :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserObjectMemberCallback) -> m SignalHandlerId

Connect a signal handler for the objectMember signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #objectMember callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserObjectMember :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserObjectMemberCallback) -> m SignalHandlerId

Connect a signal handler for the objectMember signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #objectMember callback

objectStart

type ParserObjectStartCallback = IO ()

This signal is emitted each time a parser starts parsing a JSON object.

afterParserObjectStart :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserObjectStartCallback) -> m SignalHandlerId

Connect a signal handler for the objectStart signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #objectStart callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserObjectStart :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserObjectStartCallback) -> m SignalHandlerId

Connect a signal handler for the objectStart signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #objectStart callback

parseEnd

type ParserParseEndCallback = IO ()

This signal is emitted when a parser successfully finished parsing a JSON data stream

afterParserParseEnd :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserParseEndCallback) -> m SignalHandlerId

Connect a signal handler for the parseEnd signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #parseEnd callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserParseEnd :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserParseEndCallback) -> m SignalHandlerId

Connect a signal handler for the parseEnd signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #parseEnd callback

parseStart

type ParserParseStartCallback = IO ()

This signal is emitted when a parser starts parsing a JSON data stream.

afterParserParseStart :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserParseStartCallback) -> m SignalHandlerId

Connect a signal handler for the parseStart signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after parser #parseStart callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onParserParseStart :: (IsParser a, MonadIO m) => a -> ((?self :: a) => ParserParseStartCallback) -> m SignalHandlerId

Connect a signal handler for the parseStart signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on parser #parseStart callback