jx.h File Reference

JSON Expressions (JX) library. More...

#include <stdint.h>
#include <assert.h>

Go to the source code of this file.

Data Structures

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_function
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_FUNCTION,
  JX_ERROR
}
 

JX atomic type.

More...

Functions

struct jxjx_null ()
 Create a JX null value.
struct jxjx_boolean (int boolean_value)
 Create a JX boolean value.
struct jxjx_integer (jx_int_t integer_value)
 Create a JX integer value.
struct jxjx_double (double double_value)
 Create a JX floating point value.
struct jxjx_string (const char *string_value)
 Create a JX string value.
struct jxjx_format (const char *fmt,...)
 Create a JX string value using prinf style formatting.
struct jxjx_function (jx_function_t func, struct jx *args)
 Create a JX function on the given arguments.
struct jxjx_symbol (const char *symbol_name)
 Create a JX symbol.
struct jxjx_error (struct jx *err)
 Create a JX_ERROR.
struct jxjx_array (struct jx_item *items)
 Create a JX array.
struct jxjx_arrayv (struct jx *value,...)
 Create a JX array with inline items.
struct jxjx_object (struct jx_pair *pairs)
 Create a JX object.
struct jxjx_operator (jx_operator_t oper, struct jx *left, struct jx *right)
 Create a JX binary expression,.
struct jx_pairjx_pair (struct jx *key, struct jx *value, struct jx_pair *next)
 Create a JX key-value pair.
struct jx_itemjx_item (struct jx *value, struct jx_item *next)
 Create a JX array item.
int jx_istype (struct jx *j, jx_type_t type)
 Test an expression's type.
int jx_istrue (struct jx *j)
 Test an expression for the boolean value TRUE.
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 jxjx_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.
struct jxjx_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_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 jxjx_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.
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 jxjx_array_index (struct jx *j, int nth)
 Get the nth item in an array.
struct jxjx_array_concat (struct jx *array,...)
 Concatenate the given arrays into a single array.
int jx_is_constant (struct jx *j)
 Determine if an expression is constant.
void jx_export (struct jx *j)
 Export a jx object as a set of environment variables.
struct jxjx_iterate_array (struct jx *j, void **i)
 Iterate over the values in an array.
struct jxjx_iterate_values (struct jx *j, void **i)
 Iterate over the values in an object.
struct jxjx_iterate_keys (struct jx *j, void **i)
 Iterate over the keys in an object.
struct jxjx_merge (struct jx *j,...)
 Merge an arbitrary number of JX_OBJECTs into a single new one.
const char * jx_error_name (int code)
 Get a human-readable name from an error code.
int jx_error_valid (struct jx *j)
 Check if the given JX object has all the required fields for an error.

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_FUNCTION 

function to be applied to some values

JX_ERROR 

indicates failed evaluation


Function Documentation

struct jx* jx_null (  )  [read]

Create a JX null value.

Returns:
A JX expression.
struct jx* jx_boolean ( int  boolean_value  )  [read]

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  )  [read]

Create a JX integer value.

Parameters:
integer_value A C integer.
Returns:
a JX integer value.
struct jx* jx_double ( double  double_value  )  [read]

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  )  [read]

Create a JX string value.

Parameters:
string_value A C string, which will be duplciated via strdup().
Returns:
A JX string value.
struct jx* jx_format ( const char *  fmt,
  ... 
) [read]

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_function ( jx_function_t  func,
struct jx args 
) [read]

Create a JX function on the given arguments.

Parameters:
func The function to be applied.
args The function arguments.
struct jx* jx_symbol ( const char *  symbol_name  )  [read]

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  )  [read]

Create a JX_ERROR.

Parameters:
err The associated data for the error. This object MUST have a string at the "source" key.
Returns:
A JX error value, or NULL if "source" is missing.
struct jx* jx_array ( struct jx_item items  )  [read]

Create a JX array.

Parameters:
items A linked list of jx_item values.
Returns:
A JX array.
struct jx* jx_arrayv ( struct jx value,
  ... 
) [read]

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  )  [read]

Create a JX object.

Parameters:
pairs A linked list of jx_pair key-value pairs.
Returns:
a JX object.
struct jx* jx_operator ( jx_operator_t  oper,
struct jx left,
struct jx right 
) [read]

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 
) [read]

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 
) [read]

Create a JX array item.

Parameters:
value The value of this item.
next The next item in the linked list.
Returns:
An array item.
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_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_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  )  [read]

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.
struct jx* jx_remove ( struct jx object,
struct jx key 
) [read]

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:
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_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 
) [read]

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.
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 j,
int  nth 
) [read]

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,
  ... 
) [read]

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.
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 
) [read]

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 
) [read]

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.
struct jx* jx_iterate_keys ( struct jx j,
void **  i 
) [read]

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,
  ... 
) [read]

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.
const char* jx_error_name ( int  code  ) 

Get a human-readable name from an error code.

Parameters:
code The numeric error code to check.
int jx_error_valid ( struct jx j  ) 

Check if the given JX object has all the required fields for an error.

Parameters:
j The object to check.

Generated on 27 Oct 2016 for cctools by  doxygen 1.6.1