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 jx * | jx_null ()
| Create a JX null value.
struct jx * | jx_boolean (int boolean_value)
| Create a JX boolean value.
struct jx * | jx_integer (jx_int_t integer_value)
| Create a JX integer value.
struct jx * | jx_double (double double_value)
| Create a JX floating point value.
struct jx * | jx_string (const char *string_value)
| Create a JX string value.
struct jx * | jx_string_nocopy (char *string_value)
| Create a JX string value without copying (uncommon).
struct jx * | jx_format (const char *fmt,...)
| Create a JX string value using prinf style formatting.
struct jx * | jx_symbol (const char *symbol_name)
| Create a JX symbol.
struct jx * | jx_error (struct jx *err)
| Create a JX_ERROR.
struct jx * | jx_array (struct jx_item *items)
| Create a JX array.
struct jx * | jx_arrayv (struct jx *value,...)
| Create a JX array with inline items.
struct jx * | jx_object (struct jx_pair *pairs)
| Create a JX object.
struct jx * | jx_objectv (const char *key, struct jx *value,...)
| Create a JX object.
struct jx * | jx_operator (jx_operator_t oper, struct jx *left, struct jx *right)
| Create a JX binary expression,.
struct jx_pair * | jx_pair (struct jx *key, struct jx *value, struct jx_pair *next)
| Create a JX key-value pair.
struct jx_item * | jx_item (struct jx *value, struct jx_item *next)
| Create a JX array item.
struct jx_comprehension * | jx_comprehension (const char *variable, struct jx *elements, struct jx *condition, struct jx_comprehension *next)
| Create a JX comprehension.
int | jx_istype (struct jx *j, jx_type_t type)
| Test an expression's type.
int | jx_isatomic (struct jx *j)
| Test for an atomic value.
int | jx_istrue (struct jx *j)
| Test an expression for the boolean value TRUE.
int | jx_isfalse (struct jx *j)
| Test an expression for the boolean value FALSE.
int | jx_equals (struct jx *j, struct jx *k)
| Test two expressions for equality.
int | jx_array_length (struct jx *array)
| Get the length of an array.
struct jx * | jx_copy (struct jx *j)
| Duplicate an expression.
void | jx_delete (struct jx *j)
| Delete an expression recursively.
void | jx_pair_delete (struct jx_pair *p)
| Delete a key-value pair.
void | jx_item_delete (struct jx_item *i)
| Delete an array item.
void | jx_comprehension_delete (struct jx_comprehension *comp)
| Delete a comprehension.
struct jx * | jx_remove (struct jx *object, struct jx *key)
| Remove a key-value pair from an object.
int | jx_insert (struct jx *object, struct jx *key, struct jx *value)
| Insert a key-value pair into an 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.
void | jx_insert_boolean (struct jx *object, const char *key, int value)
| Insert a boolean value into an object.
void | jx_insert_integer (struct jx *object, const char *key, jx_int_t value)
| Insert an integer value into an object.
void | jx_insert_double (struct jx *object, const char *key, double value)
| Insert a double value into an object.
void | jx_insert_string (struct jx *object, const char *key, const char *value)
| Insert a string value into an object.
struct jx * | jx_lookup (struct jx *object, const char *key)
| Search for a arbitrary item in an object.
const char * | jx_lookup_string (struct jx *object, const char *key)
| Search for a string item in an object.
char * | jx_lookup_string_dup (struct jx *object, const char *key)
| Search for a string item in an object.
jx_int_t | jx_lookup_integer (struct jx *object, const char *key)
| Search for an integer item in an object.
int | jx_lookup_boolean (struct jx *object, const char *key)
| Search for a boolean item in an object.
double | jx_lookup_double (struct jx *object, const char *key)
| Search for a double item in an object.
void | jx_array_insert (struct jx *array, struct jx *value)
| Insert an item at the beginning of an array.
void | jx_array_append (struct jx *array, struct jx *value)
| Append an item at the end of an array.
struct jx * | jx_array_index (struct jx *array, int nth)
| Get the nth item in an array.
struct jx * | jx_array_concat (struct jx *array,...)
| Concatenate the given arrays into a single array.
struct jx * | jx_array_shift (struct jx *array)
| Remove and return the first element in the array.
int | jx_is_constant (struct jx *j)
| Determine if an expression is constant.
void | jx_export (struct jx *j)
| Export a jx object into the current environment using setenv().
struct jx * | jx_iterate_array (struct jx *j, void **i)
| Iterate over the values in an array.
struct jx * | jx_iterate_values (struct jx *j, void **i)
| Iterate over the values in an object.
const char * | jx_iterate_keys (struct jx *j, void **i)
| Iterate over the keys in an object.
struct jx * | jx_merge (struct jx *j,...)
| Merge an arbitrary number of JX_OBJECTs into a single new one.

## 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

## jx_type_t

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

## jx_null()

struct jx * jx_null | ( |  | ) |

Create a JX null value.

Returns
  A JX expression.

## jx_boolean()

struct jx * jx_boolean | ( | int | boolean_value | ) |

Create a JX boolean value.

Parameters

  boolean_value | A C boolean value.

Returns
  A JX boolean value.

## jx_integer()

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.

## jx_double()

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.

## jx_string()

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.

## jx_string_nocopy()

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.

## jx_format()

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.

## jx_symbol()

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.

## jx_error()

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.

## jx_array()

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.

## jx_arrayv()

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.

## jx_object()

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.

## jx_objectv()

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

## jx_operator()

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.

## jx_pair()

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.

## jx_item()

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.

## jx_comprehension()

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.

## jx_istype()

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.

## jx_isatomic()

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.

## jx_istrue()

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.

## jx_isfalse()

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.

## jx_equals()

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.

## jx_array_length()

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.

## jx_copy()

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

## jx_delete()

void jx_delete | ( | struct jx * | j | ) |

Delete an expression recursively.

Parameters

  j | An expression to delete.

## jx_pair_delete()

void jx_pair_delete | ( | struct jx_pair * | p | ) |

Delete a key-value pair.

Parameters

  p | The key-value pair to delete.

## jx_item_delete()

void jx_item_delete | ( | struct jx_item * | i | ) |

Delete an array item.

Parameters

  i | The array item to delete.

## jx_comprehension_delete()

void jx_comprehension_delete | ( | struct jx_comprehension * | comp | ) |

Delete a comprehension.

Parameters

  comp | The comprehension to delete.

## jx_remove()

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.

## jx_insert()

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.

## jx_insert_unless_empty()

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.

## jx_insert_boolean()

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.

## jx_insert_integer()

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.

## jx_insert_double()

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.

## jx_insert_string()

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.

## jx_lookup()

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.

## jx_lookup_string()

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.

## jx_lookup_string_dup()

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_lookup_integer()

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.

## jx_lookup_boolean()

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.

## jx_lookup_double()

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.

## jx_array_insert()

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.

## jx_array_append()

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.

## jx_array_index()

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.

## jx_array_concat()

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.

## jx_array_shift()

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.

## jx_is_constant()

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.

## jx_export()

void jx_export | ( | struct jx * | j | ) |

Export a jx object into the current environment using setenv().

Parameters

  j | A JX_OBJECT.

## jx_iterate_array()

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.

## jx_iterate_values()

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.

## jx_iterate_keys()

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.

## jx_merge()

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.