cctools
Data Structures | Enumerations | Functions
jx.h File Reference

JSON Expressions (JX) library. More...

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

Go to the source code of this file.

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 jxjx_null ()
 Create a JX null value. More...
 
struct jxjx_boolean (int boolean_value)
 Create a JX boolean value. More...
 
struct jxjx_integer (jx_int_t integer_value)
 Create a JX integer value. More...
 
struct jxjx_double (double double_value)
 Create a JX floating point value. More...
 
struct jxjx_string (const char *string_value)
 Create a JX string value. More...
 
struct jxjx_string_nocopy (char *string_value)
 Create a JX string value without copying (uncommon). More...
 
struct jxjx_format (const char *fmt,...)
 Create a JX string value using prinf style formatting. More...
 
struct jxjx_symbol (const char *symbol_name)
 Create a JX symbol. More...
 
struct jxjx_error (struct jx *err)
 Create a JX_ERROR. More...
 
struct jxjx_array (struct jx_item *items)
 Create a JX array. More...
 
struct jxjx_arrayv (struct jx *value,...)
 Create a JX array with inline items. More...
 
struct jxjx_object (struct jx_pair *pairs)
 Create a JX object. More...
 
struct jxjx_objectv (const char *key, struct jx *value,...)
 Create a JX object. More...
 
struct jxjx_operator (jx_operator_t oper, struct jx *left, struct jx *right)
 Create a JX binary expression,. More...
 
struct jx_pairjx_pair (struct jx *key, struct jx *value, struct jx_pair *next)
 Create a JX key-value pair. More...
 
struct jx_itemjx_item (struct jx *value, struct jx_item *next)
 Create a JX array item. More...
 
struct jx_comprehensionjx_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_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 jxjx_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 jxjx_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 jxjx_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 jxjx_array_index (struct jx *array, int nth)
 Get the nth item in an array. More...
 
struct jxjx_array_concat (struct jx *array,...)
 Concatenate the given arrays into a single array. More...
 
struct jxjx_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 jxjx_iterate_array (struct jx *j, void **i)
 Iterate over the values in an array. More...
 
struct jxjx_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 jxjx_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_valueA C boolean value.
Returns
A JX boolean value.
struct jx* jx_integer ( jx_int_t  integer_value)

Create a JX integer value.

Parameters
integer_valueA C integer.
Returns
a JX integer value.
struct jx* jx_double ( double  double_value)

Create a JX floating point value.

Parameters
double_valueA 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_valueA 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_valueA 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
fmtA 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_nameA C string.
Returns
A JX expression.
struct jx* jx_error ( struct jx err)

Create a JX_ERROR.

Parameters
errThe 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
itemsA 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
valueOne 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
pairsA 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
keyName of the first property
valueValue 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
operThe kind of operator.
leftThe left side of the expression.
rightThe 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
keyThe key.
valueThe value.
nextThe 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
valueThe value of this item.
nextThe 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
variableThe variable name to bind.
elementsThe elements to bind.
conditionThe boolean filter to evaluate.
nextNested comprehension(s).
Returns
A JX comprehension.
int jx_istype ( struct jx j,
jx_type_t  type 
)

Test an expression's type.

Parameters
jAn expression.
typeThe desired type.
Returns
True if the expression type matches, false otherwise.
int jx_isatomic ( struct jx j)

Test for an atomic value.

Parameters
jAn 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
jAn expression to test.
Returns
True if the expression is boolean and true.
int jx_equals ( struct jx j,
struct jx k 
)

Test two expressions for equality.

Parameters
jA constant expression.
kA 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
arrayThe array to check.
struct jx* jx_copy ( struct jx j)

Duplicate an expression.

Parameters
jAn 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
jAn expression to delete.
void jx_pair_delete ( struct jx_pair p)

Delete a key-value pair.

Parameters
pThe key-value pair to delete.
void jx_item_delete ( struct jx_item i)

Delete an array item.

Parameters
iThe array item to delete.
void jx_comprehension_delete ( struct jx_comprehension comp)

Delete a comprehension.

Parameters
compThe comprehension to delete.
struct jx* jx_remove ( struct jx object,
struct jx key 
)

Remove a key-value pair from an object.

Parameters
objectThe object.
keyThe 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
objectThe object.
keyThe key.
valueThe 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
objectThe target object.
keyThe key.
valueThe 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
objectThe object
keyThe key represented as a C string
valueThe boolean value.
void jx_insert_integer ( struct jx object,
const char *  key,
jx_int_t  value 
)

Insert an integer value into an object.

Parameters
objectThe object
keyThe key represented as a C string
valueThe integer value.
void jx_insert_double ( struct jx object,
const char *  key,
double  value 
)

Insert a double value into an object.

Parameters
objectThe object
keyThe key represented as a C string
valueThe double value.
void jx_insert_string ( struct jx object,
const char *  key,
const char *  value 
)

Insert a string value into an object.

Parameters
objectThe object
keyThe key represented as a C string
valueThe 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
objectThe object in which to search.
keyThe 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
objectThe object in which to search.
keyThe 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
objectThe object in which to search.
keyThe 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
objectThe object in which to search.
keyThe 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
objectThe object in which to search.
keyThe 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
objectThe object in which to search.
keyThe 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
arrayThe array to modify.
valueThe value to insert.
void jx_array_append ( struct jx array,
struct jx value 
)

Append an item at the end of an array.

Parameters
arrayThe array to modify.
valueThe value to append.
struct jx* jx_array_index ( struct jx array,
int  nth 
)

Get the nth item in an array.

Parameters
arrayThe array to search.
nthThe 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
arrayAn 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
arrayThe 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
jThe expression to evaluate.
Returns
True if constant.
void jx_export ( struct jx j)

Export a jx object as a set of environment variables.

Parameters
jA 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
jThe JX_ARRAY to iterate over.
iA 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
jThe JX_OBJECT to iterate over.
iA 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
jThe JX_OBJECT to iterate over.
iA 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.