ujson_reader.h File Reference

A recursive descend JSON parser. More...

#include <stdio.h>
#include <ujson_common.h>

Go to the source code of this file.

Data Structures
struct	ujson_reader
	A JSON parser internal state. More...
struct	ujson_val
	A parsed JSON key value pair. More...
struct	ujson_obj_attr
	A JSON object attribute description i.e. key and type. More...
struct	ujson_obj
	A JSON object description. More...
struct	ujson_reader_state
	A JSON reader state. More...

Macros
#define	UJSON_READER_INIT(buf, buf_len, rflags)
	An ujson_reader initializer with default values. More...
#define	UJSON_VAL_INIT(sbuf, sbuf_size)
	An ujson_val initializer. More...
#define	UJSON_OBJ_FOREACH(self, res)    for (ujson_obj_first(self, res); ujson_val_valid(res); ujson_obj_next(self, res))
	A loop over a JSON object. More...
#define	UJSON_OBJ_ATTR(keyv, typev)    {.key = keyv, .type = typev}
	An ujson_obj_attr initializer.
#define	UJSON_OBJ_ATTR_IDX(key_idx, keyv, typev)    [key_idx] = {.key = keyv, .type = typev}
	An ujson_obj_attr intializer with an array index.
#define	UJSON_OBJ_FOREACH_FILTER(self, res, obj, ign)
	A loop over a JSON object with a pre-defined list of expected attributes. More...
#define	UJSON_ARR_FOREACH(self, res)    for (ujson_arr_first(self, res); ujson_val_valid(res); ujson_arr_next(self, res))
	A loop over a JSON array. More...

Typedefs
typedef struct ujson_obj_attr	ujson_obj_attr
	A JSON object attribute description i.e. key and type.
typedef struct ujson_obj	ujson_obj
	A JSON object description.
typedef struct ujson_reader_state	ujson_reader_state
	A JSON reader state.

Enumerations
enum	ujson_reader_flags { UJSON_READER_STRICT = 0x01 }
	Reader flags. More...

Functions
ujson_val *	ujson_val_alloc (size_t buf_size)
	Allocates a JSON value. More...
void	ujson_val_free (ujson_val *self)
	Frees a JSON value. More...
static int	ujson_val_valid (struct ujson_val *res)
	Checks is result has valid type. More...
void	ujson_err (ujson_reader *self, const char *fmt,...) __attribute__((format(printf
	Fills the reader error. More...
void void	ujson_err_print (ujson_reader *self)
	Prints error stored in the buffer. More...
void	ujson_warn (ujson_reader *self, const char *fmt,...) __attribute__((format(printf
	Prints a warning. More...
void static int	ujson_reader_err (ujson_reader *self)
	Returns true if error was encountered. More...
enum ujson_type	ujson_next_type (ujson_reader *self)
	Returns the type of next element in buffer. More...
enum ujson_type	ujson_reader_start (ujson_reader *self)
	Returns if first element in JSON is object or array. More...
int	ujson_obj_first (ujson_reader *self, struct ujson_val *res)
	Starts parsing of a JSON object. More...
int	ujson_obj_next (ujson_reader *self, struct ujson_val *res)
	Parses next value from a JSON object. More...
size_t	ujson_lookup (const void *arr, size_t memb_size, size_t list_len, const char *key)
	Utility function for log(n) lookup in a sorted array. More...
int	ujson_obj_first_filter (ujson_reader *self, struct ujson_val *res, const struct ujson_obj *obj, const struct ujson_obj *ign)
	Starts parsing of a JSON object with attribute lists. More...
int	ujson_obj_next_filter (ujson_reader *self, struct ujson_val *res, const struct ujson_obj *obj, const struct ujson_obj *ign)
	Parses next value from a JSON object with attribute lists. More...
int	ujson_obj_skip (ujson_reader *self)
	Skips parsing of a JSON object. More...
int	ujson_arr_first (ujson_reader *self, struct ujson_val *res)
	Starts parsing of a JSON array. More...
int	ujson_arr_next (ujson_reader *self, struct ujson_val *res)
	Parses next value from a JSON array. More...
int	ujson_arr_skip (ujson_reader *self)
	Skips parsing of a JSON array. More...
static ujson_reader_state	ujson_reader_state_save (ujson_reader *self)
	Returns a parser state at the start of current object/array. More...
static void	ujson_reader_state_load (ujson_reader *self, ujson_reader_state state)
	Returns the parser to a saved state. More...
static void	ujson_reader_reset (ujson_reader *self)
	Resets the parser to a start. More...
ujson_reader *	ujson_reader_load (const char *path)
	Loads a file into an ujson_reader buffer. More...
void	ujson_reader_free (ujson_reader *self)
	Frees an ujson_reader buffer. More...
void	ujson_reader_finish (ujson_reader *self)
	Prints errors and warnings at the end of parsing. More...
static int	ujson_reader_consumed (ujson_reader *self)
	Returns non-zero if whole buffer has been consumed. More...

Variables
const struct ujson_obj *	ujson_empty_obj
	An empty object attribute list. More...

Detailed Description

A recursive descend JSON parser.

All the function that parse JSON return zero on success and non-zero on a failure. Once an error has happened all subsequent attempts to parse more return with non-zero exit status immediatelly. This is designed so that we can parse several values without checking each return value and only check if error has happened at the end of the sequence.

Definition in file ujson_reader.h.

Macro Definition Documentation

UJSON_ARR_FOREACH

#define UJSON_ARR_FOREACH	(		self,
			res
	)		for (ujson_arr_first(self, res); ujson_val_valid(res); ujson_arr_next(self, res))

A loop over a JSON array.

UJSON_ARR_FOREACH(reader, val) {
     printf("Got value type '%s'", ujson_type_name(val->type));
     ...
}

Parameters

self	An ujson_reader.
res	An ujson_val to store the next parsed value to.

Definition at line 431 of file ujson_reader.h.

UJSON_OBJ_FOREACH

#define UJSON_OBJ_FOREACH	(		self,
			res
	)		for (ujson_obj_first(self, res); ujson_val_valid(res); ujson_obj_next(self, res))

A loop over a JSON object.

UJSON_OBJ_FOREACH(reader, val) {
     printf("Got value id '%s' type '%s'", val->id, ujson_type_name(val->type));
     ...
}

Parameters

self	An ujson_reader.
res	An ujson_val to store the next parsed value to.

Definition at line 262 of file ujson_reader.h.

UJSON_OBJ_FOREACH_FILTER

#define UJSON_OBJ_FOREACH_FILTER	(		self,
			res,
			obj,
			ign
	)

Value:

        for (ujson_obj_first_filter(self, res, obj, ign); \
             ujson_val_valid(res); \
             ujson_obj_next_filter(self, res, obj, ign))

A loop over a JSON object with a pre-defined list of expected attributes.

static struct ujson_obj_attr attrs[] = {
     UJSON_OBJ_ATTR("bool", UJSON_BOOL),
     UJSON_OBJ_ATTR("number", UJSON_INT),
};
 
static struct ujson_obj obj = {
     .attrs = filter_attrs,
     .attr_cnt = UJSON_ARRAY_SIZE(filter_attrs)
};
 
UJSON_OBJ_FOREACH_FILTER(reader, val, &obj, NULL) {
     printf("Got value id '%s' type '%s'",
            attrs[val->idx].id, ujson_type_name(val->type));
     ...
}

Parameters

self	An ujson_reader.
res	An ujson_val to store the next parsed value to.
obj	An ujson_obj with a description of attributes to parse.
ign	An ujson_obj with a description of attributes to ignore.

Definition at line 381 of file ujson_reader.h.

UJSON_READER_INIT

#define UJSON_READER_INIT	(		buf,
			buf_len,
			rflags
	)

Value:

        { \
        .max_depth = UJSON_RECURSION_MAX, \
        .err_print = UJSON_ERR_PRINT, \
        .err_print_priv = UJSON_ERR_PRINT_PRIV, \
        .json = buf, \
        .len = buf_len, \
        .flags = rflags \
}

An ujson_reader initializer with default values.

Parameters

buf	A pointer to a buffer with JSON data.
buf_len	A JSON data buffer lenght.
rflags	enum ujson_reader_flags.

Returns

An ujson_reader initialized with default values.

Definition at line 32 of file ujson_reader.h.

UJSON_VAL_INIT

#define UJSON_VAL_INIT	(		sbuf,
			sbuf_size
	)

Value:

        { \
        .buf = sbuf, \
        .buf_size = sbuf_size, \
}

An ujson_val initializer.

Parameters

sbuf	A pointer to a buffer used for string values.
sbuf_size	A length of the buffer used for string values.

Returns

An ujson_val initialized with default values.

Definition at line 83 of file ujson_reader.h.

Enumeration Type Documentation

ujson_reader_flags

enum ujson_reader_flags

Reader flags.

Enumerator
UJSON_READER_STRICT	If set warnings are treated as errors.

Definition at line 42 of file ujson_reader.h.

Function Documentation

ujson_arr_first()

int ujson_arr_first	(	ujson_reader *	self,
		struct ujson_val *	res
	)

Starts parsing of a JSON array.

Parameters

self	An ujson_reader.
res	An ujson_val to store the parsed value to.

Returns

Zero on success, non-zero otherwise.

ujson_arr_next()

int ujson_arr_next	(	ujson_reader *	self,
		struct ujson_val *	res
	)

Parses next value from a JSON array.

If the res->type is UJSON_OBJ or UJSON_ARR it has to be parsed or skipped before next call to this function.

Parameters

self	An ujson_reader.
res	An ujson_val to store the parsed value to.

Returns

Zero on success, non-zero otherwise.

ujson_arr_skip()

int ujson_arr_skip

(

ujson_reader *

self

)

Skips parsing of a JSON array.

Parameters

self	A ujson_reader.

Returns

Zero on success, non-zero otherwise.

ujson_err()

void ujson_err	(	ujson_reader *	self,
		const char *	fmt,
			...
	)

Fills the reader error.

Once buffer error is set all parsing functions return immediatelly with type set to UJSON_VOID.

Parameters

self	An ujson_reader
fmt	A printf like format string
...	A printf like parameters

ujson_err_print()

void void ujson_err_print

(

ujson_reader *

self

)

Prints error stored in the buffer.

The error takes into consideration the current offset in the buffer and prints a few preceding lines along with the exact position of the error.

The error is passed to the err_print() handler.

Parameters

self	A ujson_reader

ujson_lookup()

size_t ujson_lookup	(	const void *	arr,
		size_t	memb_size,
		size_t	list_len,
		const char *	key
	)

Utility function for log(n) lookup in a sorted array.

Parameters

list	Analphabetically sorted array.
list_len	Array length.

Returns

An array index or (size_t)-1 if key wasn't found.

ujson_next_type()

enum ujson_type ujson_next_type

(

ujson_reader *

self

)

Returns the type of next element in buffer.

Parameters

self	An ujson_reader

Returns

A type of next element in the buffer.

ujson_obj_first()

int ujson_obj_first	(	ujson_reader *	self,
		struct ujson_val *	res
	)

Starts parsing of a JSON object.

Parameters

self	An ujson_reader
res	An ujson_val to store the parsed value to.

Returns

Zero on success, non-zero otherwise.

ujson_obj_first_filter()

int ujson_obj_first_filter	(	ujson_reader *	self,
		struct ujson_val *	res,
		const struct ujson_obj *	obj,
		const struct ujson_obj *	ign
	)

Starts parsing of a JSON object with attribute lists.

Parameters

self	An ujson_reader.
res	An ujson_val to store the parsed value to.
obj	An ujson_obj object description.
ign	A list of keys to ignore.

Returns

Zero on success, non-zero otherwise.

ujson_obj_next()

int ujson_obj_next	(	ujson_reader *	self,
		struct ujson_val *	res
	)

Parses next value from a JSON object.

If the res->type is UJSON_OBJ or UJSON_ARR it has to be parsed or skipped before next call to this function.

Parameters

self	An ujson_reader.
res	A ujson_val to store the parsed value to.

Returns

Zero on success, non-zero otherwise.

ujson_obj_next_filter()

int ujson_obj_next_filter	(	ujson_reader *	self,
		struct ujson_val *	res,
		const struct ujson_obj *	obj,
		const struct ujson_obj *	ign
	)

Parses next value from a JSON object with attribute lists.

If the res->type is UJSON_OBJ or UJSON_ARR it has to be parsed or skipped before next call to this function.

Parameters

self	An ujson_reader.
res	An ujson_val to store the parsed value to.
obj	An ujson_obj object description.
ign	A list of keys to ignore. If set to NULL all unknown keys are ignored, if set to ujson_empty_obj all unknown keys produce warnings.

Returns

Zero on success, non-zero otherwise.

ujson_obj_skip()

int ujson_obj_skip

(

ujson_reader *

self

)

Skips parsing of a JSON object.

Parameters

self	An ujson_reader.

Returns

Zero on success, non-zero otherwise.

ujson_reader_consumed()

static int ujson_reader_consumed ( ujson_reader *  self )

inlinestatic

Returns non-zero if whole buffer has been consumed.

Parameters

self	A ujson_reader.

Returns

Non-zero if whole buffer was consumed.

Definition at line 538 of file ujson_reader.h.

ujson_reader_err()

void static int ujson_reader_err ( ujson_reader *  self )

inlinestatic

Returns true if error was encountered.

Parameters

self	A ujson_reader

Returns

True if error was encountered false otherwise.

Definition at line 205 of file ujson_reader.h.

Referenced by ujson_reader_state_load().

ujson_reader_finish()

void ujson_reader_finish

(

ujson_reader *

self

)

Prints errors and warnings at the end of parsing.

Checks if self->err is set and prints the error with ujson_reader_err()

Checks if there is any text left after the parser has finished with ujson_reader_consumed() and prints a warning if there were any non-whitespace characters left.

Parameters

self	A ujson_reader

ujson_reader_free()

void ujson_reader_free

(

ujson_reader *

self

)

Frees an ujson_reader buffer.

Parameters

self	A ujson_reader allocated by ujson_reader_load() function.

ujson_reader_load()

ujson_reader* ujson_reader_load

(

const char *

path

)

Loads a file into an ujson_reader buffer.

The reader has to be later freed by ujson_reader_free().

Parameters

path	A path to a file.

Returns

A ujson_reader or NULL in a case of a failure.

ujson_reader_reset()

static void ujson_reader_reset ( ujson_reader *  self )

inlinestatic

Resets the parser to a start.

Parameters

self	A ujson_reader

Definition at line 494 of file ujson_reader.h.

ujson_reader_start()

enum ujson_type ujson_reader_start

(

ujson_reader *

self

)

Returns if first element in JSON is object or array.

Parameters

self	A ujson_reader

Returns

On success returns UJSON_OBJ or UJSON_ARR. On failure UJSON_VOID.

ujson_reader_state_load()

static void ujson_reader_state_load ( ujson_reader *  self, ujson_reader_state  state  )

inlinestatic

Returns the parser to a saved state.

This function could be used for the parser to return to the start of object or array saved by t the ujson_reader_state_get() function.

Parameters

self	A ujson_reader
state	An parser state as returned by the ujson_reader_state_get().

Definition at line 479 of file ujson_reader.h.

References ujson_reader_err().

ujson_reader_state_save()

static ujson_reader_state ujson_reader_state_save ( ujson_reader *  self )

inlinestatic

Returns a parser state at the start of current object/array.

This function could be used for the parser to return to the start of the currently parsed object or array.

Parameters

self	A ujson_reader

Returns

A state that points to a start of the last object or array.

Definition at line 460 of file ujson_reader.h.

ujson_val_alloc()

ujson_val* ujson_val_alloc

(

size_t

buf_size

)

Allocates a JSON value.

Parameters

buf_size

A maximal buffer size for a string value, pass 0 for default.

Returns

A newly allocated JSON value.

ujson_val_free()

void ujson_val_free

(

ujson_val *

self

)

Frees a JSON value.

Parameters

self	A JSON value previously allocated by ujson_val_alloc().

ujson_val_valid()

static int ujson_val_valid ( struct ujson_val *  res )

inlinestatic

Checks is result has valid type.

Parameters

res	An ujson value.

Returns

Zero if result is not valid, non-zero otherwise.

Definition at line 156 of file ujson_reader.h.

References ujson_val::type.

ujson_warn()

void ujson_warn	(	ujson_reader *	self,
		const char *	fmt,
			...
	)

Prints a warning.

Uses the print handler in the buffer to print a warning along with a few lines of context from the JSON at the current position.

Parameters

self	A ujson_reader
fmt	A printf-like error string.
...	A printf-like parameters.

Variable Documentation

ujson_empty_obj

const struct ujson_obj* ujson_empty_obj

extern

An empty object attribute list.

To be passed to UJSON_OBJ_FOREACH_FITLER() as ignore list.