JSON Expressions (JX) library. More...

#include <stdint.h>
#include <inttypes.h>

Data Structures
struct	jx_comprehension

struct	jx_item
	JX item linked-list used by JX_ARRAY and jx::items. More...

struct	jx_pair
	JX key-value pairs used by JX_OBJECT and jx::pairs. More...

struct	jx_operator

struct	jx
	JX value representing any expression type. More...

Enumerations
enum	jx_type_t { JX_NULL = 0, JX_BOOLEAN, JX_INTEGER, JX_DOUBLE, JX_STRING, JX_SYMBOL, JX_ARRAY, JX_OBJECT, JX_OPERATOR, JX_ERROR }
	JX atomic type. More...

Functions
struct jx *	jx_null ()
	Create a JX null value. More...

struct jx *	jx_boolean (int boolean_value)
	Create a JX boolean value. More...

struct jx *	jx_integer (jx_int_t integer_value)
	Create a JX integer value. More...

struct jx *	jx_double (double double_value)
	Create a JX floating point value. More...

struct jx *	jx_string (const char *string_value)
	Create a JX string value. More...

struct jx *	jx_string_nocopy (char *string_value)
	Create a JX string value without copying (uncommon). More...

struct jx *	jx_format (const char *fmt,...)
	Create a JX string value using prinf style formatting. More...

struct jx *	jx_symbol (const char *symbol_name)
	Create a JX symbol. More...

struct jx *	jx_error (struct jx *err)
	Create a JX_ERROR. More...

struct jx *	jx_array (struct jx_item *items)
	Create a JX array. More...

struct jx *	jx_arrayv (struct jx *value,...)
	Create a JX array with inline items. More...

struct jx *	jx_object (struct jx_pair *pairs)
	Create a JX object. More...

struct jx *	jx_objectv (const char key, struct jx value,...)
	Create a JX object. More...

struct jx *	jx_operator (jx_operator_t oper, struct jx left, struct jx right)
	Create a JX binary expression,. More...

struct jx_pair *	jx_pair (struct jx key, struct jx value, struct jx_pair *next)
	Create a JX key-value pair. More...

struct jx_item *	jx_item (struct jx value, struct jx_item next)
	Create a JX array item. More...

struct jx_comprehension *	jx_comprehension (const char variable, struct jx elements, struct jx condition, struct jx_comprehension next)
	Create a JX comprehension. More...

int	jx_istype (struct jx *j, jx_type_t type)
	Test an expression's type. More...

int	jx_isatomic (struct jx *j)
	Test for an atomic value. More...

int	jx_istrue (struct jx *j)
	Test an expression for the boolean value TRUE. More...

int	jx_isfalse (struct jx *j)
	Test an expression for the boolean value FALSE. More...

int	jx_equals (struct jx j, struct jx k)
	Test two expressions for equality. More...

int	jx_array_length (struct jx *array)
	Get the length of an array. More...

struct jx *	jx_copy (struct jx *j)
	Duplicate an expression. More...

void	jx_delete (struct jx *j)
	Delete an expression recursively. More...

void	jx_pair_delete (struct jx_pair *p)
	Delete a key-value pair. More...

void	jx_item_delete (struct jx_item *i)
	Delete an array item. More...

void	jx_comprehension_delete (struct jx_comprehension *comp)
	Delete a comprehension. More...

struct jx *	jx_remove (struct jx object, struct jx key)
	Remove a key-value pair from an object. More...

int	jx_insert (struct jx object, struct jx key, struct jx *value)
	Insert a key-value pair into an object. More...

int	jx_insert_unless_empty (struct jx object, struct jx key, struct jx *value)
	Insert a key-value pair into an object, unless the value is an empty collection, in which case delete the key and value. More...

void	jx_insert_boolean (struct jx object, const char key, int value)
	Insert a boolean value into an object. More...

void	jx_insert_integer (struct jx object, const char key, jx_int_t value)
	Insert an integer value into an object. More...

void	jx_insert_double (struct jx object, const char key, double value)
	Insert a double value into an object. More...

void	jx_insert_string (struct jx object, const char key, const char *value)
	Insert a string value into an object. More...

struct jx *	jx_lookup (struct jx object, const char key)
	Search for a arbitrary item in an object. More...

const char *	jx_lookup_string (struct jx object, const char key)
	Search for a string item in an object. More...

char *	jx_lookup_string_dup (struct jx object, const char key)
	Search for a string item in an object. More...

jx_int_t	jx_lookup_integer (struct jx object, const char key)
	Search for an integer item in an object. More...

int	jx_lookup_boolean (struct jx object, const char key)
	Search for a boolean item in an object. More...

double	jx_lookup_double (struct jx object, const char key)
	Search for a double item in an object. More...

void	jx_array_insert (struct jx array, struct jx value)
	Insert an item at the beginning of an array. More...

void	jx_array_append (struct jx array, struct jx value)
	Append an item at the end of an array. More...

struct jx *	jx_array_index (struct jx *array, int nth)
	Get the nth item in an array. More...

struct jx *	jx_array_concat (struct jx *array,...)
	Concatenate the given arrays into a single array. More...

struct jx *	jx_array_shift (struct jx *array)
	Remove and return the first element in the array. More...

int	jx_is_constant (struct jx *j)
	Determine if an expression is constant. More...

void	jx_export (struct jx *j)
	Export a jx object as a set of environment variables. More...

struct jx *	jx_iterate_array (struct jx j, void *i)
	Iterate over the values in an array. More...

struct jx *	jx_iterate_values (struct jx j, void *i)
	Iterate over the values in an object. More...

const char *	jx_iterate_keys (struct jx j, void *i)
	Iterate over the keys in an object. More...

struct jx *	jx_merge (struct jx *j,...)
	Merge an arbitrary number of JX_OBJECTs into a single new one. More...

Detailed Description

JSON Expressions (JX) library.

This module implements extended JSON expressions as a C library. We use our own custom library to avoid external dependencies and to implement various extensions to strict JSON.

For example, the following bit of code:

struct jx * obj = jx_object(
        jx_pair(
                jx_string("hello"),
                jx_string("world"),
                0)
        );

jx_print_file(jx,stdout);

jx_delete(jx);

Will create the following output:

{ "hello" : "world" }

See Also: jx_parse.h; jx_print.h

Enumeration Type Documentation

enum jx_type_t

JX atomic type.

Enumerator
JX_NULL	null value
JX_BOOLEAN	true or false
JX_INTEGER	integer value
JX_DOUBLE	floating point value
JX_STRING	string value
JX_SYMBOL	variable identifier
JX_ARRAY	array containing values
JX_OBJECT	object containing key-value pairs
JX_OPERATOR	operator on multiple values.
JX_ERROR	indicates failed evaluation

Function Documentation

struct jx* jx_null ( )

Create a JX null value.

Returns: A JX expression.

struct jx* jx_boolean ( int boolean_value )

Create a JX boolean value.

Parameters

boolean_value A C boolean value.

Returns: A JX boolean value.

struct jx* jx_integer ( jx_int_t integer_value )

Create a JX integer value.

Parameters

integer_value A C integer.

Returns: a JX integer value.

struct jx* jx_double ( double double_value )

Create a JX floating point value.

Parameters

double_value A C double precision floating point.

Returns: a JX double value.

struct jx* jx_string ( const char * string_value )

Create a JX string value.

Parameters

string_value A C string, which will be duplicated via strdup().

Returns: A JX string value.

struct jx* jx_string_nocopy ( char * string_value )

Create a JX string value without copying (uncommon).

Parameters

string_value A C string, which will be not be duplicated, but will be freed at object deletion.

Returns: A JX string value.

struct jx* jx_format	(	const char *	fmt,
			...
	)

Create a JX string value using prinf style formatting.

Parameters

fmt	A printf-style format string, followed by matching arguments.

Returns: A JX string value.

struct jx* jx_symbol ( const char * symbol_name )

Create a JX symbol.

Note that symbols are an extension to the JSON standard. A symbol is a reference to an external variable, which can be resolved by using jx_eval.

Parameters

symbol_name A C string.

Returns: A JX expression.

struct jx* jx_error ( struct jx * err )

Create a JX_ERROR.

Parameters

err	The associated data for the error. This should be a string description of the error.

Returns: A JX error value.

struct jx* jx_array ( struct jx_item * items )

Create a JX array.

Parameters

items A linked list of jx_item values.

Returns: A JX array.

struct jx* jx_arrayv	(	struct jx *	value,
			...
	)

Create a JX array with inline items.

Parameters

value One or more items of the array must be given, terminated with a null value.

Returns: A JX array.

struct jx* jx_object ( struct jx_pair * pairs )

Create a JX object.

Parameters

pairs A linked list of jx_pair key-value pairs.

Returns: a JX object.

struct jx* jx_objectv	(	const char *	key,
		struct jx *	value,
			...
	)

Create a JX object.

Arguments are alternating string key – *jx values. Must be termianted with a null value. This is syntactic sugar for jx_object(jx_pair(jx_string(k), v, jx_pair(jx_string(k), v, jx_pair( etc.))));

struct jx *j = jx_objectv("A", jx_integer(42), // key and value of A, "B", jx_objectv("C", jx_string("xyz") // key and value of B NULL)); // terminating null value.

Parameters

key	Name of the first property
value	Value for the first property
...	Alternating key-value pairs

Returns: a JX object

struct jx* jx_operator	(	jx_operator_t	oper,
		struct jx *	left,
		struct jx *	right
	)

Create a JX binary expression,.

Parameters

oper	The kind of operator.
left	The left side of the expression.
right	The right side of the expression.

struct jx_pair* jx_pair	(	struct jx *	key,
		struct jx *	value,
		struct jx_pair *	next
	)

Create a JX key-value pair.

Parameters

key	The key.
value	The value.
next	The next item in the linked list.

Returns: A key-value pair.

struct jx_item* jx_item	(	struct jx *	value,
		struct jx_item *	next
	)

Create a JX array item.

Parameters

value	The value of this item.
next	The next item in the linked list.

Returns: An array item.

struct jx_comprehension* jx_comprehension	(	const char *	variable,
		struct jx *	elements,
		struct jx *	condition,
		struct jx_comprehension *	next
	)

Create a JX comprehension.

Parameters

variable	The variable name to bind.
elements	The elements to bind.
condition	The boolean filter to evaluate.
next	Nested comprehension(s).

Returns: A JX comprehension.

int jx_istype	(	struct jx *	j,
		jx_type_t	type
	)

Test an expression's type.

Parameters

j	An expression.
type	The desired type.

Returns: True if the expression type matches, false otherwise.

int jx_isatomic ( struct jx * j )

Test for an atomic value.

Parameters

j	An expression.

Returns: True if the expression is an atomic integer, float, string or boolean.

int jx_istrue ( struct jx * j )

Test an expression for the boolean value TRUE.

Parameters

j	An expression to test.

Returns: True if the expression is boolean and true.

int jx_isfalse ( struct jx * j )

Test an expression for the boolean value FALSE.

Parameters

j	An expression to test.

Returns: True if the expression is boolean and false.

int jx_equals	(	struct jx *	j,
		struct jx *	k
	)

Test two expressions for equality.

Parameters

j	A constant expression.
k	A constant expression.

Returns: True if equal, false if not.

int jx_array_length ( struct jx * array )

Get the length of an array.

Returns -1 if array is null or not an array.

Parameters

array The array to check.

struct jx* jx_copy ( struct jx * j )

Duplicate an expression.

Parameters

j	An expression.

Returns: A copy of the expression, which must be deleted by jx_delete

void jx_delete ( struct jx * j )

Delete an expression recursively.

Parameters

j	An expression to delete.

void jx_pair_delete ( struct jx_pair * p )

Delete a key-value pair.

Parameters

p	The key-value pair to delete.

void jx_item_delete ( struct jx_item * i )

Delete an array item.

Parameters

i	The array item to delete.

void jx_comprehension_delete ( struct jx_comprehension * comp )

Delete a comprehension.

Parameters

comp	The comprehension to delete.

struct jx* jx_remove	(	struct jx *	object,
		struct jx *	key
	)

Remove a key-value pair from an object.

Parameters

object	The object.
key	The key.

Returns: The corresponding value, or null if it is not present.

int jx_insert	(	struct jx *	object,
		struct jx *	key,
		struct jx *	value
	)

Insert a key-value pair into an object.

Parameters

object	The object.
key	The key.
value	The value.

Returns: True on success, false on failure. Failure can only occur if the object is not a JX_OBJECT.

int jx_insert_unless_empty	(	struct jx *	object,
		struct jx *	key,
		struct jx *	value
	)

Insert a key-value pair into an object, unless the value is an empty collection, in which case delete the key and value.

Parameters

object	The target object.
key	The key.
value	The value.

Returns: 1 on success, -1 on empty value, 0 on failure. Failure can only occur if the object is not a JX_OBJECT.

void jx_insert_boolean	(	struct jx *	object,
		const char *	key,
		int	value
	)

Insert a boolean value into an object.

Parameters

object	The object
key	The key represented as a C string
value	The boolean value.

void jx_insert_integer	(	struct jx *	object,
		const char *	key,
		jx_int_t	value
	)

Insert an integer value into an object.

Parameters

object	The object
key	The key represented as a C string
value	The integer value.

void jx_insert_double	(	struct jx *	object,
		const char *	key,
		double	value
	)

Insert a double value into an object.

Parameters

object	The object
key	The key represented as a C string
value	The double value.

void jx_insert_string	(	struct jx *	object,
		const char *	key,
		const char *	value
	)

Insert a string value into an object.

Parameters

object	The object
key	The key represented as a C string
value	The C string value.

struct jx* jx_lookup	(	struct jx *	object,
		const char *	key
	)

Search for a arbitrary item in an object.

The key is an ordinary string value.

Parameters

object	The object in which to search.
key	The string key to match.

Returns: The value of the matching pair, or null if none is found.

const char* jx_lookup_string	(	struct jx *	object,
		const char *	key
	)

Search for a string item in an object.

The key is an ordinary string value.

Parameters

object	The object in which to search.
key	The string key to match.

Returns: The C string value of the matching object, or null if it is not found, or is not a string.

char* jx_lookup_string_dup	(	struct jx *	object,
		const char *	key
	)

Search for a string item in an object.

Behaves the same as jx_lookup_string, but returns a duplicated copy. The result must be deallocated with free().

Parameters

object	The object in which to search.
key	The string key to match.

Returns: The C string value of the matching object, or null if it is not found, or is not a string.

jx_int_t jx_lookup_integer	(	struct jx *	object,
		const char *	key
	)

Search for an integer item in an object.

The key is an ordinary string value.

Parameters

object	The object in which to search.
key	The string key to match.

Returns: The integer value of the matching object, or zero if it is not found, or is not an integer.

int jx_lookup_boolean	(	struct jx *	object,
		const char *	key
	)

Search for a boolean item in an object.

The key is an ordinary string value.

Parameters

object	The object in which to search.
key	The string key to match.

Returns: One if the value of the matching object is true, or zero if it is false, not found, or not a boolean.

double jx_lookup_double	(	struct jx *	object,
		const char *	key
	)

Search for a double item in an object.

The key is an ordinary string value.

Parameters

object	The object in which to search.
key	The string key to match.

Returns: The double value of the matching object, or null if it is not found, or is not a double.

void jx_array_insert	(	struct jx *	array,
		struct jx *	value
	)

Insert an item at the beginning of an array.

Parameters

array	The array to modify.
value	The value to insert.

void jx_array_append	(	struct jx *	array,
		struct jx *	value
	)

Append an item at the end of an array.

Parameters

array	The array to modify.
value	The value to append.

struct jx* jx_array_index	(	struct jx *	array,
		int	nth
	)

Get the nth item in an array.

Parameters

array	The array to search.
nth	The index of the desired value.

Returns: The nth element, or NULL if the index is out of bounds.

struct jx* jx_array_concat	(	struct jx *	array,
			...
	)

Concatenate the given arrays into a single array.

The passed arrays are consumed.

Parameters

array An array to concatenate. The list of arrays must be terminated by NULL.

struct jx* jx_array_shift ( struct jx * array )

Remove and return the first element in the array.

Parameters

array The JX_ARRAY to update.

Returns: The first value in array, or NULL if array is empty or not a JX_ARRAY.

int jx_is_constant ( struct jx * j )

Determine if an expression is constant.

Traverses the expression recursively, and returns true if it consists only of constant values, arrays, and objects.

Parameters

j	The expression to evaluate.

Returns: True if constant.

void jx_export ( struct jx * j )

Export a jx object as a set of environment variables.

Parameters

j	A JX_OBJECT.

struct jx* jx_iterate_array	(	struct jx *	j,
		void **	i
	)

Iterate over the values in an array.

The iteration state is stored by the caller in an opaque pointer variable. When starting iteration, the caller MUST pass the address of a pointer initialized to NULL as i. It is undefined behavior to pass a non-NULL iterator variable not set by a previous call. Subsequent calls should use the same variable to continue iteration. After the initial call, the value of j is ignored.

struct jx *item;
for (void *i = NULL; (item = jx_iterate_array(j, &i));) {
    printf("array item: ");
    jx_print_stream(item, stdout);
    printf("\n");
}

Parameters

j	The JX_ARRAY to iterate over.
i	A variable to store the iteration state.

Returns: A pointer to each item in the array, and NULL when iteration is finished.

struct jx* jx_iterate_values	(	struct jx *	j,
		void **	i
	)

Iterate over the values in an object.

The iteration state is stored by the caller in an opaque pointer variable. When starting iteration, the caller MUST pass the address of a pointer initialized to NULL as i. It is undefined behavior to pass a non-NULL iterator variable not set by a previous call. Subsequent calls should use the same variable to continue iteration. After the initial call, the value of j is ignored.

struct jx *item;
void *i = NULL;
while ((item = jx_iterate_values(j, &i))) {
    printf("object value: ");
    jx_print_stream(item, stdout);
    printf("\n");
}

Parameters

j	The JX_OBJECT to iterate over.
i	A variable to store the iteration state.

Returns: A pointer to each value in the object, and NULL when iteration is finished.

const char* jx_iterate_keys	(	struct jx *	j,
		void **	i
	)

Iterate over the keys in an object.

The iteration state is stored by the caller in an opaque pointer variable. When starting iteration, the caller MUST pass the address of a pointer initialized to NULL as i. It is undefined behavior to pass a non-NULL iterator variable not set by a previous call. Subsequent calls should use the same variable to continue iteration. After the initial call, the value of j is ignored.

struct jx *item;
void *i = NULL;
while ((item = jx_iterate_keys(j, &i))) {
    printf("object key: ");
    jx_print_stream(item, stdout);
    printf("\n");
}

Parameters

j	The JX_OBJECT to iterate over.
i	A variable to store the iteration state.

Returns: A pointer to each key in the object, and NULL when iteration is finished.

struct jx* jx_merge	(	struct jx *	j,
			...
	)

Merge an arbitrary number of JX_OBJECTs into a single new one.

The constituent objects are not consumed. Objects are merged in the order given, i.e. a key can replace an identical key in a preceding object. The last argument must be NULL to mark the end of the list.

Returns: A merged JX_OBJECT that must be deleted with jx_delete.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation