AOJLS definitions. More...

#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>

Data Structures
struct	aojls_serialization_prefs
	Serialization preferences. More...

struct	aojls_deserialization_prefs
	Deserialization preferences. More...

Macros
#define	AOJLS_OBJECT_START_ALLOC_SIZE 16

#define	AOJLS_ARRAY_START_ALLOC_SIZE 16

Typedefs
typedef struct aojls_ctx	aojls_ctx_t
	AOJLS Context object, holding all memory references to JSON values and strings.

typedef struct json_value	json_value_t
	Unified type for any JSON value. More...

typedef struct json_object	json_object
	JSON object. More...

typedef struct json_array	json_array
	JSON array. More...

typedef struct json_string	json_string
	JSON string. More...

typedef struct json_number	json_number
	JSON number.

typedef struct json_boolean	json_boolean
	JSON boolean.

typedef struct json_null	json_null
	JSON null.

typedef bool(*	writer_function_t) (const char buffer, size_t len, void writer_data)
	Custom serialization callback. More...

typedef long(*	reader_function_t) (char buffer, size_t len, void reader_data)
	Custom deserialization callback. More...

Enumerations
enum	json_type_t { JS_OBJECT, JS_ARRAY, JS_NUMBER, JS_STRING, JS_BOOL, JS_NULL, INVALID }
	JSON value tags. More...

Functions
json_type_t	json_get_type (json_value_t *value)
	Returns type for provided value. More...

json_object *	json_as_object (json_value_t *value)
	Converts reference to JSON value to JSON object. More...

json_array *	json_as_array (json_value_t *value)
	Converts reference to JSON value to JSON array. More...

double	json_as_number (json_value_t value, bool correct_type)
	Converts reference to numeric double value. More...

char *	json_as_string (json_value_t *value)
	Converts reference to string. More...

bool	json_as_bool (json_value_t value, bool correct_type)
	Converts reference to boolean. More...

bool	json_is_null (json_value_t *value)
	Checks if reference is JSON null. More...

json_object *	json_make_object (aojls_ctx_t *ctx)
	Creates new empty JSON object. More...

json_object *	json_object_add (json_object o, char key, json_value_t *value)
	Adds key-value pair to this JSON object. More...

json_object *	json_object_nadd (json_object o, char key, size_t len, json_value_t *value)
	Adds key-value pair to this JSON object. More...

size_t	json_object_numkeys (json_object *o)

char *	json_object_get_key (json_object *o, size_t i)
	Returns key bound to the iteration position `i`. More...

json_value_t *	json_object_get_object_as_value (json_object o, char key)
	Returns JSON value bound to this key. More...

json_object *	json_object_get_object (json_object o, char key)
	Returns JSON object bound to this key. More...

json_array *	json_object_get_array (json_object o, char key)
	Returns JSON array bound to this key. More...

double	json_object_get_double (json_object o, char key, bool *valid)
	Returns double bound to this key. More...

double	json_object_get_double_default (json_object o, char key, double defval)
	Returns double bound to this key or default value. More...

char *	json_object_get_string (json_object o, char key)
	Returns string bound to this key. More...

char *	json_object_get_string_default (json_object o, char key, char *defval)
	Returns string bound to this key or default value. More...

bool	json_object_get_bool (json_object o, char key, bool *valid)
	Returns boolean bound to this key. More...

bool	json_object_get_bool_default (json_object o, char key, bool defval)

bool	json_object_is_null (json_object o, char key)
	Returns if null is bound for that key. More...

json_array *	json_make_array (aojls_ctx_t *ctx)
	Creates new empty JSON array. More...

json_array *	json_array_add (json_array a, json_value_t value)
	Adds new JSON value to the JSON array. More...

size_t	json_array_size (json_array *a)
	Returns number of elements in this array. More...

json_value_t *	json_array_get (json_array *a, size_t i)
	Returns JSON value at position `i`. More...

json_object *	json_array_get_object (json_array *a, size_t i)
	Returns JSON object in JSON array at position `i`. More...

json_array *	json_array_get_array (json_array *a, size_t i)
	Returns JSON array in JSON array at position `i`. More...

double	json_array_get_double (json_array a, size_t i, bool valid)
	Returns double value in JSON array at position `i`. More...

double	json_array_get_double_default (json_array *a, size_t i, double defval)
	Returns double value in JSON array at position `i` or default value. More...

char *	json_array_get_string (json_array *a, size_t i)
	Returns string in JSON array at position `i`. More...

char *	json_array_get_string_default (json_array a, size_t i, char defval)
	Returns string in JSON array at position `i` or default. More...

bool	json_array_get_bool (json_array a, size_t i, bool valid)
	Returns boolean value in JSON array at position `i`. More...

bool	json_array_get_bool_default (json_array *a, size_t i, bool defval)
	Returns boolean value in JSON array at position `i` or default value. More...

bool	json_array_is_null (json_array *a, size_t i)
	Returns whether JSON null is at the position `i`. More...

json_string *	json_from_string (aojls_ctx_t ctx, char string)
	Creates JSON string from `string`. More...

json_number *	json_from_number (aojls_ctx_t *ctx, double number)
	Creates JSON number from `number`. More...

json_boolean *	json_from_boolean (aojls_ctx_t *ctx, bool b)
	Creates JSON boolean from `b`. More...

json_null *	json_make_null (aojls_ctx_t *ctx)
	Creates JSON null. More...

aojls_ctx_t *	json_make_context ()
	Creates new AOJLS context. More...

bool	json_context_error_happened (aojls_ctx_t *ctx)
	Whether any error is detected while manipulating with this context or values bound to it. More...

json_value_t *	json_context_get_result (aojls_ctx_t *ctx)

void	json_free_context (aojls_ctx_t *ctx)
	frees the context and all bound values More...

char *	aojls_serialize (json_value_t value, aojls_serialization_prefs prefs)
	Serializes JSON value. More...

aojls_ctx_t *	aojls_deserialize (char source, size_t len, aojls_deserialization_prefs prefs)
	Deserialization function. More...

Detailed Description

AOJLS definitions.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of AOJLS nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author: Peter Vanusanik

Date: 2016 13. 3. All public api of AOJLS resides here. You only need to include this file to work with AOJLS

See also: http://enerccio.github.io/aojls/

Typedef Documentation

typedef struct json_array json_array

JSON array.

JSON array is an array of JSON values. json_array references are one-way mutabe, ie new value can be inserted, however no value can be removed

typedef struct json_object json_object

JSON object.

JSON object is a map between string keys and JSON values. In AOLJS you can have multiple identical keys, which will be no problem (however, serialized form might not be valid JSON).

json_object references are one-way mutable, ie new key-value pairs might be defined, but none can be removed.

typedef struct json_string json_string

JSON string.

immutable, also string value is also tracked by context

typedef struct json_value json_value_t

Unified type for any JSON value.

All JSON value references can be casted into this.

typedef long(* reader_function_t) (char *buffer, size_t len, void *reader_data)

Custom deserialization callback.

This callback is called each time deserializer needs to read new data. This callback must return number of bytes actually read in the buffer and it must be <= len, or negative in case of failure. If 0 is returned, deserializer considers that as EOF.

typedef bool(* writer_function_t) (const char *buffer, size_t len, void *writer_data)

Custom serialization callback.

This callback is called each time serializer needs to write byte output. writer_data is user provided writer state that is passed in the preferences

See also: aojls_serialization_prefs

Enumeration Type Documentation

enum json_type_t

JSON value tags.

Every JSON value is identified by one of these tags

Enumerator
JS_OBJECT	Tag for JSON object
JS_ARRAY	Tag for JSON array
JS_NUMBER	Tag for JSON number
JS_STRING	Tag for JSON string
JS_BOOL	Tag for JSON bool
JS_NULL	Tag for JSON null
INVALID	This tag is never used in any object, however, it may be returned from tag query, in case of invalid reference

Function Documentation

aojls_ctx_t* aojls_deserialize	(	char *	source,
		size_t	len,
		aojls_deserialization_prefs *	prefs
	)

Deserialization function.

Parameters

source	string containing JSON data, may be NULL if custom reader is used instead
len	size of previous string, if applicable
prefs	preferences used for this deserialization

Returns: context where the result may be (if there was no error) or NULL if context is not provided and there was failure when creating a new one

See also: aojls_ctx_t; json_context_get_result; json_free_context

char* aojls_serialize	(	json_value_t *	value,
		aojls_serialization_prefs *	prefs
	)

Serializes JSON value.

Serializes the JSON value according to the preferences specified. Returns serialized string if no writer_function is specified or NULL in case of error or when custom writer_function is specified.

Parameters

value	to be serialized
prefs	preferences, may be NULL

Returns: serialized value or NULL

See also: aojls_serialization_prefs

Warning: Any cycles in nested JSON values will cause stack overflow!; If returned string is non-NULL, it must be freed by calling free when it is not needed!

json_array* json_array_add	(	json_array *	a,
		json_value_t *	value
	)

Adds new JSON value to the JSON array.

Parameters

a	JSON array
value	JSON value

Returns: NULL in case of failure, JSON array on success

json_value_t* json_array_get	(	json_array *	a,
		size_t	i
	)

Returns JSON value at position i.

Parameters

a	array
i	position

Returns: JSON value in the JSON array at position i or NULL if invalid position is specified

json_array* json_array_get_array	(	json_array *	a,
		size_t	i
	)

Returns JSON array in JSON array at position i.

Parameters

a	array
i	position

Returns: JSON array or NULL if position is invalid or there is no JSON array at that position

See also: json_array_get

bool json_array_get_bool	(	json_array *	a,
		size_t	i,
		bool *	valid
	)

Returns boolean value in JSON array at position i.

Parameters

a	array
i	position
valid	will contain true if position is valid and JSON boolean is at that position or false

Returns: bool or false if position is invalid or there is no JSON boolean at that position

See also: json_array_get

bool json_array_get_bool_default	(	json_array *	a,
		size_t	i,
		bool	defval
	)

Returns boolean value in JSON array at position i or default value.

Parameters

a	array
i	position
defval	returned in case of failure

See also: json_array_get

double json_array_get_double	(	json_array *	a,
		size_t	i,
		bool *	valid
	)

Returns double value in JSON array at position i.

Parameters

a	array
i	position
valid	will contain true if position is valid and JSON number is at that position or false

Returns: double or 0 if position is invalid or there is no JSON number at that position

See also: json_array_get

double json_array_get_double_default	(	json_array *	a,
		size_t	i,
		double	defval
	)

Returns double value in JSON array at position i or default value.

Parameters

a	array
i	position
defval	returned in case of failure

See also: json_array_get

json_object* json_array_get_object	(	json_array *	a,
		size_t	i
	)

Returns JSON object in JSON array at position i.

Parameters

a	array
i	position

Returns: JSON object or NULL if position is invalid or there is no JSON object at that position

See also: json_array_get

char* json_array_get_string	(	json_array *	a,
		size_t	i
	)

Returns string in JSON array at position i.

Parameters

a	array
i	position

Returns: string or NULL if position is invalid or there is no JSON string at that position

See also: json_array_get

Warning: Do not deallocate this string, it is tracked by context bound to the JSON string in the array

char* json_array_get_string_default	(	json_array *	a,
		size_t	i,
		char *	defval
	)

Returns string in JSON array at position i or default.

Parameters

a	array
i	position
defval	is returned in any case of failure

Returns: string

See also: json_array_get

Warning: Do not deallocate this string , it is tracked by context bound to the JSON string in the array This only applies if defval was not returned.

bool json_array_is_null	(	json_array *	a,
		size_t	i
	)

Returns whether JSON null is at the position i.

Parameters

a	array
i	position

Returns: whether JSON null is at that position

See also: json_array_get

size_t json_array_size ( json_array * a )

Returns number of elements in this array.

Parameters

a	JSON array

json_array* json_as_array ( json_value_t * value )

Converts reference to JSON value to JSON array.

If value is NULL, returns NULL, otherwise returns reference to json_array, if value is JSON array or NULL.

Parameters

value JSON value

Returns: json_array if it is valid JSON array

See also: json_array; json_get_type

bool json_as_bool	(	json_value_t *	value,
		bool *	correct_type
	)

Converts reference to boolean.

Returns false and sets correct_type to false if JSON value is invalid or not a boolean, otherwise correct_type is set to true and value is converted to boolean.

Parameters

value	JSON value
checker,if	not NULL, state of conversion is stored there

Returns: true/false value or false if invalid

See also: json_boolean; json_get_type

double json_as_number	(	json_value_t *	value,
		bool *	correct_type
	)

Converts reference to numeric double value.

Returns 0 and sets correct_type to false if JSON value is invalid or not a number, otherwise correct_type is set to true and value is converted to double.

Parameters

value	JSON value
checker,if	not NULL, state of conversion is stored there

Returns: double value or 0 if invalid

See also: json_number; json_get_type

json_object* json_as_object ( json_value_t * value )

Converts reference to JSON value to JSON object.

If value is NULL, returns NULL, otherwise returns reference to json_object, if value is JSON object or NULL.

Parameters

value JSON value

Returns: json_object if it is valid JSON object

See also: json_object; json_get_type

char* json_as_string ( json_value_t * value )

Converts reference to string.

Returns NULL if string is invalid.

Parameters

value JSON value

Returns: char* string or NULL if invalid

See also: json_string; json_get_type

Warning: Do not deallocate this returned string in any way. It is tracked by context and will be freed when context is freed.

bool json_context_error_happened ( aojls_ctx_t * ctx )

Whether any error is detected while manipulating with this context or values bound to it.

Returns: true if any error has happened, false if none

json_value_t* json_context_get_result ( aojls_ctx_t * ctx )

this context was used in deserialization, returns result of last deserialization

Returns: deserialized JSON value or NULL in case of an error or if this context was not used in deserialization

Warning: if same context is used in multiple deserialization, the result will be overwritten!

void json_free_context ( aojls_ctx_t * ctx )

frees the context and all bound values

Frees all the memory used by all bound values in this context, all strings used by those values and then context itself.

Warning: After this operation, all references to any values in this context is undefined!

json_boolean* json_from_boolean	(	aojls_ctx_t *	ctx,
		bool	b
	)

Creates JSON boolean from b.

Failure is marked in ctx.

Parameters

ctx	context to which this JSON boolean will be bound
b	boolean value

Returns: json_boolean reference or NULL in case of failure

See also: json_object; aojls_ctx_t; json_context_error_happened

json_number* json_from_number	(	aojls_ctx_t *	ctx,
		double	number
	)

Creates JSON number from number.

Failure is marked in ctx.

Parameters

ctx	context to which this JSON number will be bound
number	value

Returns: json_number reference or NULL in case of failure

See also: json_object; aojls_ctx_t; json_context_error_happened

json_string* json_from_string	(	aojls_ctx_t *	ctx,
		char *	string
	)

Creates JSON string from string.

Failure is marked in ctx.

Parameters

ctx	context to which this JSON string will be bound
string	value

Returns: json_string reference or NULL in case of failure

See also: json_object; aojls_ctx_t; json_context_error_happened

Warning: string may be deallocated/modified after this call

json_type_t json_get_type ( json_value_t * value )

Returns type for provided value.

If NULL pointer is passed as value, returns INVALID. Otherwise returns the type of that JSON value.

Parameters

value queried JSON value

Returns: type of queried JSON value

See also: json_type_t

bool json_is_null ( json_value_t * value )

Checks if reference is JSON null.

Parameters

value JSON value

Returns: true/false if value is JSON null or not.

See also: json_null; json_get_type

Warning: returns false if reference passed into json_is_null is NULL itself!

json_array* json_make_array ( aojls_ctx_t * ctx )

Creates new empty JSON array.

Failure is marked in ctx.

Parameters

ctx	context to which this JSON array will be bound

Returns: json_array reference or NULL in case of failure

See also: json_object; aojls_ctx_t; json_context_error_happened

aojls_ctx_t* json_make_context ( )

Creates new AOJLS context.

All JSON value creating operations require valid context. All JSON value's memory is then tracked by this context and therefore should not be freed explicitedly.

Returns: NULL on failure or reference to new context

json_null* json_make_null ( aojls_ctx_t * ctx )

Creates JSON null.

Failure is marked in ctx.

Parameters

ctx	context to which this JSON boolean will be bound

Returns: json_boolean reference or NULL in case of failure

See also: json_object; aojls_ctx_t; json_context_error_happened

json_object* json_make_object ( aojls_ctx_t * ctx )

Creates new empty JSON object.

Failure is marked in ctx.

Parameters

ctx	context to which this JSON object will be bound

Returns: json_object reference or NULL in case of failure

See also: json_object; aojls_ctx_t; json_context_error_happened

json_object* json_object_add	(	json_object *	o,
		char *	key,
		json_value_t *	value
	)

Adds key-value pair to this JSON object.

Parameters

o	JSON object
key	null terminated string value to be bound to this key

Returns: NULL in case of failure or JSON object

Warning: Key must be null terminated and will be copied and stored in the context bound to the JSON object!

json_array* json_object_get_array	(	json_object *	o,
		char *	key
	)

Returns JSON array bound to this key.

Returns: JSON array bound to that key or NULL in case of an error, if there is no such key or if key points to other than JSON array JSON value.

See also: json_object_get_key

bool json_object_get_bool	(	json_object *	o,
		char *	key,
		bool *	valid
	)

Returns boolean bound to this key.

Parameters

o	JSON object
key	key
valid	will contain true if position is valid and JSON boolean is at that position or false

Returns: boolean bound to that key or NULL in case of an error, if there is no such key or if key points to other than JSON boolean JSON value.

See also: json_object_get_key

double json_object_get_double	(	json_object *	o,
		char *	key,
		bool *	valid
	)

Returns double bound to this key.

Parameters

o	JSON object
key	key
valid	will contain true if position is valid and JSON number is at that position or false

Returns: double bound to that key or 0 in case of an error, if there is no such key or if key points to other than JSON number JSON value.

See also: json_object_get_key

double json_object_get_double_default	(	json_object *	o,
		char *	key,
		double	defval
	)

Returns double bound to this key or default value.

Parameters

o	JSON object
key	key
defval	default value

Returns: double bound to that key or defval in case of an error, if there is no such key or if key points to other than JSON number JSON value.

See also: json_object_get_key

char* json_object_get_key	(	json_object *	o,
		size_t	i
	)

Returns key bound to the iteration position i.

Parameters

o	JSON object
i	iterator, `i` <= number of keys in JSON object

Returns: key

Warning: Do not deallocate this key

See also: json_object_numkeys

json_object* json_object_get_object	(	json_object *	o,
		char *	key
	)

Returns JSON object bound to this key.

Returns: JSON object bound to that key or NULL in case of an error, if there is no such key or if key points to other than JSON object JSON value.

See also: json_object_get_key

json_value_t* json_object_get_object_as_value	(	json_object *	o,
		char *	key
	)

Returns JSON value bound to this key.

O(N) complexity where N is number of keys in this JSON object. Keys are compared via strcmp.

Parameters

o	JSON object
key

Returns: JSON value bound to that key or NULL in case of an error or no such key in this JSON object

char* json_object_get_string	(	json_object *	o,
		char *	key
	)

Returns string bound to this key.

Parameters

o	JSON object
key	key

Returns: string bound to that key or NULL in case of an error, if there is no such key or if key points to other than JSON string JSON value.

See also: json_object_get_key

char* json_object_get_string_default	(	json_object *	o,
		char *	key,
		char *	defval
	)

Returns string bound to this key or default value.

Parameters

o	JSON object
key	key
defval	default value

Returns: string bound to that key or defval in case of an error, if there is no such key or if key points to other than JSON string JSON value.

See also: json_object_get_key

bool json_object_is_null	(	json_object *	o,
		char *	key
	)

Returns if null is bound for that key.

Parameters

o	JSON object
key	key

Returns: true if JSON null is bound to that key

See also: json_object_get_key

json_object* json_object_nadd	(	json_object *	o,
		char *	key,
		size_t	len,
		json_value_t *	value
	)

Adds key-value pair to this JSON object.

Parameters

o	JSON object
key	string
len	size of string key value to be bound to this key

Returns: NULL in case of failure or JSON object

Warning: Key may not be null terminated and will be copied and stored in the context bound to the JSON object!

size_t json_object_numkeys ( json_object * o )

Returns: number of keys in this JSON object

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation