JsonParser

JsonParser — Parse JSON data streams

Synopsis

enum                JsonParserError;

struct              JsonParser;
struct              JsonParserClass;
JsonParser *        json_parser_new                     (void);
gboolean            json_parser_load_from_file          (JsonParser *parser,
                                                         const gchar *filename,
                                                         GError **error);
gboolean            json_parser_load_from_data          (JsonParser *parser,
                                                         const gchar *data,
                                                         gssize length,
                                                         GError **error);
gboolean            json_parser_load_from_stream        (JsonParser *parser,
                                                         GInputStream *stream,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                json_parser_load_from_stream_async  (JsonParser *parser,
                                                         GInputStream *stream,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            json_parser_load_from_stream_finish (JsonParser *parser,
                                                         GAsyncResult *result,
                                                         GError **error);

JsonNode *          json_parser_get_root                (JsonParser *parser);

guint               json_parser_get_current_line        (JsonParser *parser);
guint               json_parser_get_current_pos         (JsonParser *parser);
gboolean            json_parser_has_assignment          (JsonParser *parser,
                                                         gchar **variable_name);

Object Hierarchy

  GObject
   +----JsonParser

Signals

  "array-element"                                  : Run Last
  "array-end"                                      : Run Last
  "array-start"                                    : Run Last
  "error"                                          : Run Last
  "object-end"                                     : Run Last
  "object-member"                                  : Run Last
  "object-start"                                   : Run Last
  "parse-end"                                      : Run Last
  "parse-start"                                    : Run Last

Description

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

Details

enum JsonParserError

typedef enum {
  JSON_PARSER_ERROR_PARSE,
  JSON_PARSER_ERROR_TRAILING_COMMA,
  JSON_PARSER_ERROR_MISSING_COMMA,
  JSON_PARSER_ERROR_MISSING_COLON,
  JSON_PARSER_ERROR_INVALID_BAREWORD,
  
  JSON_PARSER_ERROR_UNKNOWN
} JsonParserError;

Error enumeration for JsonParser

This enumeration can be extended at later date

JSON_PARSER_ERROR_PARSE

 parse error

JSON_PARSER_ERROR_TRAILING_COMMA

 unexpected trailing comma

JSON_PARSER_ERROR_MISSING_COMMA

 expected comma

JSON_PARSER_ERROR_MISSING_COLON

 expected colon

JSON_PARSER_ERROR_INVALID_BAREWORD

 invalid bareword

JSON_PARSER_ERROR_UNKNOWN

 unknown error

struct JsonParser

struct JsonParser;

JSON data streams parser. The contents of the JsonParser structure are private and should only be accessed via the provided API.

struct JsonParserClass

struct JsonParserClass {
  void (* parse_start)   (JsonParser   *parser);

  void (* object_start)  (JsonParser   *parser);
  void (* object_member) (JsonParser   *parser,
                          JsonObject   *object,
                          const gchar  *member_name);
  void (* object_end)    (JsonParser   *parser,
                          JsonObject   *object);

  void (* array_start)   (JsonParser   *parser);
  void (* array_element) (JsonParser   *parser,
                          JsonArray    *array,
                          gint          index_);
  void (* array_end)     (JsonParser   *parser,
                          JsonArray    *array);

  void (* parse_end)     (JsonParser   *parser);
  
  void (* error)         (JsonParser   *parser,
                          const GError *error);
};

JsonParser class.

parse_start ()

 class handler for the JsonParser::parse-start signal

object_start ()

 class handler for the JsonParser::object-start signal

object_member ()

 class handler for the JsonParser::object-member signal

object_end ()

 class handler for the JsonParser::object-end signal

array_start ()

 class handler for the JsonParser::array-start signal

array_element ()

 class handler for the JsonParser::array-element signal

array_end ()

 class handler for the JsonParser::array-end signal

parse_end ()

 class handler for the JsonParser::parse-end signal

error ()

 class handler for the JsonParser::error signal

json_parser_new ()

JsonParser *        json_parser_new                     (void);

Creates a new JsonParser instance. 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.

Returns :

 the newly created JsonParser. Use g_object_unref() to release all the memory it allocates.

json_parser_load_from_file ()

gboolean            json_parser_load_from_file          (JsonParser *parser,
                                                         const gchar *filename,
                                                         GError **error);

Loads a JSON stream from the content of filename and parses it. See json_parser_load_from_data().

parser :

 a JsonParser

filename :

 the path for the file to parse

error :

 return location for a GError, or NULL

Returns :

 TRUE if the file was successfully loaded and parsed. In case of error, error is set accordingly and FALSE is returned

json_parser_load_from_data ()

gboolean            json_parser_load_from_data          (JsonParser *parser,
                                                         const gchar *data,
                                                         gssize length,
                                                         GError **error);

Loads a JSON stream from a buffer and parses it. You can call this function multiple times with the same JsonParser object, but the contents of the parser will be destroyed each time.

parser :

 a JsonParser

data :

 the buffer to parse

length :

 the length of the buffer, or -1

error :

 return location for a GError, or NULL

Returns :

 TRUE if the buffer was succesfully parser. In case of error, error is set accordingly and FALSE is returned

json_parser_load_from_stream ()

gboolean            json_parser_load_from_stream        (JsonParser *parser,
                                                         GInputStream *stream,
                                                         GCancellable *cancellable,
                                                         GError **error);

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, the error G_IO_ERROR_CANCELLED will be set on the passed error.

parser :

 a JsonParser

stream :

 an open GInputStream

cancellable :

 a GCancellable, or NULL. [allow-none]

error :

 the return location for a GError, or NULL

Returns :

 TRUE if the data stream was successfully read and parsed, and FALSE otherwise

Since 0.12

json_parser_load_from_stream_async ()

void                json_parser_load_from_stream_async  (JsonParser *parser,
                                                         GInputStream *stream,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously reads the contents of stream.

For more details, see json_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 json_parser_load_from_stream_finish() to get the result of the operation.

parser :

 a JsonParser

stream :

 a GInputStream

cancellable :

 a GCancellable, or NULL. [allow-none]

callback :

 a GAsyncReadyCallback to call when the request is satisfied

user_data :

 the data to pass to callback

Since 0.12

json_parser_load_from_stream_finish ()

gboolean            json_parser_load_from_stream_finish (JsonParser *parser,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an asynchronous stream loading started with json_parser_load_from_stream_async().

parser :

 a JsonParser

result :

 a GAsyncResult

error :

 the return location for a GError or NULL

Returns :

 TRUE if the content of the stream was successfully retrieves and parsed, and FALSE otherwise. In case of error, the GError will be filled accordingly.

Since 0.12

json_parser_get_root ()

JsonNode *          json_parser_get_root                (JsonParser *parser);

Retrieves the top level node from the parsed JSON stream.

parser :

 a JsonParser

Returns :

 the root JsonNode . The returned node is owned by the JsonParser and should never be modified or freed. [transfer none]

json_parser_get_current_line ()

guint               json_parser_get_current_line        (JsonParser *parser);

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 JsonParser will yield 0.

parser :

 a JsonParser

Returns :

 the currently parsed line, or 0.

json_parser_get_current_pos ()

guint               json_parser_get_current_pos         (JsonParser *parser);

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 JsonParser will yield 0.

parser :

 a JsonParser

Returns :

 the position in the current line, or 0.

json_parser_has_assignment ()

gboolean            json_parser_has_assignment          (JsonParser *parser,
                                                         gchar **variable_name);

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

1
 
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.

parser :

 a JsonParser

variable_name :

 Return location for the variable name, or NULL. [out][allow-none][transfer none]

Returns :

 TRUE if there was an assignment, FALSE otherwise. If variable_name is not NULL it will be set to the name of the variable used in the assignment. The string is owned by JsonParser and should never be modified or freed.

Since 0.4

Signal Details

The "array-element" signal

void                user_function                      (JsonParser *parser,
                                                        JsonArray  *array,
                                                        gint        index_,
                                                        gpointer    user_data)      : Run Last

The ::array-element signal is emitted each time the JsonParser has successfully parsed a single element of a JsonArray. The array and element index are passed to the signal handlers.

parser :

 the JsonParser that received the signal

array :

 a JsonArray

index_ :

 the index of the newly parsed element

user_data :

 user data set when the signal handler was connected.

The "array-end" signal

void                user_function                      (JsonParser *parser,
                                                        JsonArray  *array,
                                                        gpointer    user_data)      : Run Last

The ::array-end signal is emitted each time the JsonParser has successfully parsed an entire JsonArray

parser :

 the JsonParser that received the signal

array :

 the parsed JsonArray

user_data :

 user data set when the signal handler was connected.

The "array-start" signal

void                user_function                      (JsonParser *parser,
                                                        gpointer    user_data)      : Run Last

The ::array-start signal is emitted each time the JsonParser starts parsing a JsonArray

parser :

 the JsonParser that received the signal

user_data :

 user data set when the signal handler was connected.

The "error" signal

void                user_function                      (JsonParser *parser,
                                                        gpointer    error,
                                                        gpointer    user_data)      : Run Last

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

parser :

 the parser instance that received the signal

error :

 a pointer to the GError

user_data :

 user data set when the signal handler was connected.

The "object-end" signal

void                user_function                      (JsonParser *parser,
                                                        JsonObject *object,
                                                        gpointer    user_data)      : Run Last

The ::object-end signal is emitted each time the JsonParser has successfully parsed an entire JsonObject.

parser :

 the JsonParser that received the signal

object :

 the parsed JsonObject

user_data :

 user data set when the signal handler was connected.

The "object-member" signal

void                user_function                      (JsonParser *parser,
                                                        JsonObject *object,
                                                        gchar      *member_name,
                                                        gpointer    user_data)        : Run Last

The ::object-member signal is emitted each time the JsonParser has successfully parsed a single member of a JsonObject. The object and member are passed to the signal handlers.

parser :

 the JsonParser that received the signal

object :

 a JsonObject

member_name :

 the name of the newly parsed member

user_data :

 user data set when the signal handler was connected.

The "object-start" signal

void                user_function                      (JsonParser *parser,
                                                        gpointer    user_data)      : Run Last

The ::object-start signal is emitted each time the JsonParser starts parsing a JsonObject.

parser :

 the JsonParser that received the signal

user_data :

 user data set when the signal handler was connected.

The "parse-end" signal

void                user_function                      (JsonParser *parser,
                                                        gpointer    user_data)      : Run Last

The ::parse-end signal is emitted when the parser successfully finished parsing a JSON data stream

parser :

 the JsonParser that received the signal

user_data :

 user data set when the signal handler was connected.

The "parse-start" signal

void                user_function                      (JsonParser *parser,
                                                        gpointer    user_data)      : Run Last

The ::parse-start signal is emitted when the parser began parsing a JSON data stream.

parser :

 the JsonParser that received the signal

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.15.1