gp_json_writer.h File Reference

A JSON writer. More...

#include <utils/gp_json_common.h>

Go to the source code of this file.

Data Structures
struct	gp_json_writer
	A JSON writer. More...

Macros
#define	GP_JSON_WRITER_INIT(vout, vout_priv)
	A gp_json_writer initializer with default values.

Functions
gp_json_writer *	gp_json_writer_vec_new (void)
	Allocates a JSON writer with a vector as a storage.
void	gp_json_writer_vec_free (gp_json_writer *self)
	Frees a JSON writer with a vector as a storage.
static char *	gp_json_writer_vec (gp_json_writer *self)
	Returns a pointer to a vector storage.
gp_json_writer *	gp_json_writer_file_open (const char *path)
	Allocates a JSON file writer.
int	gp_json_writer_file_close (gp_json_writer *self)
	Closes and frees a JSON file writer.
static int	gp_json_writer_err (gp_json_writer *self)
	Returns true if writer error happened.
int	gp_json_obj_start (gp_json_writer *self, const char *id)
	Starts a JSON object.
int	gp_json_obj_finish (gp_json_writer *self)
	Finishes a JSON object.
int	gp_json_arr_start (gp_json_writer *self, const char *id)
	Starts a JSON array.
int	gp_json_arr_finish (gp_json_writer *self)
	Finishes a JSON array.
int	gp_json_null_add (gp_json_writer *self, const char *id)
	Adds a null value.
int	gp_json_int_add (gp_json_writer *self, const char *id, long val)
	Adds an integer value.
int	gp_json_bool_add (gp_json_writer *self, const char *id, int val)
	Adds a bool value.
int	gp_json_float_add (gp_json_writer *self, const char *id, double val)
	Adds a float value.
int	gp_json_str_add (gp_json_writer *self, const char *id, const char *str)
	Adds a string value.
int	gp_json_writer_finish (gp_json_writer *self)
	Finalizes json writer.

Detailed Description

A JSON writer.

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

Failures may occur:

• if we call the functions out of order, e.g. attempt to finish array when we are not writing out an array.
• if we run out of recursion stack
• may be propagated from the writer function, e.g. allocation failure, no space on disk, etc.

Definition in file gp_json_writer.h.

Macro Definition Documentation

GP_JSON_WRITER_INIT

#define GP_JSON_WRITER_INIT	(		vout,
			vout_priv
	)

Value:

        { \
        .err_print = GP_JSON_ERR_PRINT, \
        .err_print_priv = GP_JSON_ERR_PRINT_PRIV, \
        .out = vout, \
        .out_priv = vout_priv \
}

A gp_json_writer initializer with default values.

Parameters

vout	A pointer to function to write out the data.
vout_priv	An user pointer passed to the out function.

Returns

A gp_json_writer initialized with default values.

Definition at line 53 of file gp_json_writer.h.

Function Documentation

gp_json_arr_finish()

int gp_json_arr_finish

(

gp_json_writer *

self

)

Finishes a JSON array.

The call will fail if we are currenlty not writing out an array.

Parameters

self	A JSON writer.

Returns

Zero on success, non-zero otherwise.

gp_json_arr_start()

int gp_json_arr_start	(	gp_json_writer *	self,
		const char *	id
	)

Starts a JSON array.

For a top level array the id must be NULL, every other array has to have non-NULL id. The call will also fail if maximal recursion depth GP_JSON_RECURSION_MAX has been reached.

Parameters

self	A JSON writer.
id	An array name.

Returns

Zero on success, non-zero otherwise.

gp_json_bool_add()

int gp_json_bool_add	(	gp_json_writer *	self,
		const char *	id,
		int	val
	)

Adds a bool value.

The id must be NULL inside of an array, and must be non-NULL inside of an object.

Parameters

self	A JSON writer.
id	An boolean value name.
val	A boolean value.

Returns

Zero on success, non-zero otherwise.

gp_json_float_add()

int gp_json_float_add	(	gp_json_writer *	self,
		const char *	id,
		double	val
	)

Adds a float value.

The id must be NULL inside of an array, and must be non-NULL inside of an object.

Parameters

self	A JSON writer.
id	A floating point value name.
val	A floating point value.

Returns

Zero on success, non-zero otherwise.

gp_json_int_add()

int gp_json_int_add	(	gp_json_writer *	self,
		const char *	id,
		long	val
	)

Adds an integer value.

The id must be NULL inside of an array, and must be non-NULL inside of an object.

Parameters

self	A JSON writer.
id	An integer value name.
val	An integer value.

Returns

Zero on success, non-zero otherwise.

gp_json_null_add()

int gp_json_null_add	(	gp_json_writer *	self,
		const char *	id
	)

Adds a null value.

The id must be NULL inside of an array, and must be non-NULL inside of an object.

Parameters

self	A JSON writer.
id	A null value name.

Returns

Zero on success, non-zero otherwise.

gp_json_obj_finish()

int gp_json_obj_finish

(

gp_json_writer *

self

)

Finishes a JSON object.

The call will fail if we are currenlty not writing out an object.

Parameters

self	A JSON writer.

Returns

Zero on success, non-zero otherwise.

gp_json_obj_start()

int gp_json_obj_start	(	gp_json_writer *	self,
		const char *	id
	)

Starts a JSON object.

For a top level object the id must be NULL, every other object has to have non-NULL id. The call will also fail if maximal recursion depth GP_JSON_RECURSION_MAX has been reached.

Parameters

self	A JSON writer.
id	An object name.

Returns

Zero on a success, non-zero otherwise.

gp_json_str_add()

int gp_json_str_add	(	gp_json_writer *	self,
		const char *	id,
		const char *	str
	)

Adds a string value.

The id must be NULL inside of an array, and must be non-NULL inside of an object.

Parameters

self	A JSON writer.
id	A string value name.
str	A UTF8 string value.

Returns

Zero on success, non-zero otherwise.

gp_json_writer_err()

static int gp_json_writer_err ( gp_json_writer *  self )

inlinestatic

Returns true if writer error happened.

Parameters

self	A JSON writer.

Returns

True if error has happened.

Definition at line 115 of file gp_json_writer.h.

gp_json_writer_file_close()

int gp_json_writer_file_close

(

gp_json_writer *

self

)

Closes and frees a JSON file writer.

Parameters

self	A gp_json_writer file writer.

Returns

Zero on success, non-zero on a failure and errno is set.

gp_json_writer_file_open()

gp_json_writer * gp_json_writer_file_open

(

const char *

path

)

Allocates a JSON file writer.

The call may fail either when file cannot be opened for writing or if allocation has failed. In all cases errno should be set correctly.

Parameters

path	A path to the file, file is opened for writing and created if it does not exist.

Returns

A gp_json_writer pointer or NULL in a case of failure.

gp_json_writer_finish()

int gp_json_writer_finish

(

gp_json_writer *

self

)

Finalizes json writer.

Finalizes the json writer, throws possible errors through the error printing function.

Parameters

self	A JSON writer.

Returns

Overall error value.

gp_json_writer_vec()

static char * gp_json_writer_vec ( gp_json_writer *  self )

inlinestatic

Returns a pointer to a vector storage.

Parameters

self	A JSON writer.

Returns

A pointer to the vector storage.

Definition at line 81 of file gp_json_writer.h.

gp_json_writer_vec_free()

void gp_json_writer_vec_free

(

gp_json_writer *

self

)

Frees a JSON writer with a vector as a storage.

Parameters

self	A gp_json_writer with vector as a storage.

gp_json_writer_vec_new()

gp_json_writer * gp_json_writer_vec_new

(

void

)

Allocates a JSON writer with a vector as a storage.

Returns

A gp_json_writer pointer or NULL in a case of allocation failure.