APG
… an ABNF Parser Generator
|
Header file for the JSON component. Defines API prototypes. More...
#include "../utilities/utilities.h"
Go to the source code of this file.
Data Structures | |
struct | json_number |
The structure of a JSON number value. More... | |
struct | json_value_tag |
The structure of a JSON value. More... | |
Macros | |
Value Identifiers | |
Integer identifiers for each of the JSON value types. | |
#define | JSON_ID_OBJECT 11 |
Object value. More... | |
#define | JSON_ID_ARRAY 13 |
Array value. More... | |
#define | JSON_ID_STRING 14 |
String value. More... | |
#define | JSON_ID_NUMBER 15 |
Number value. More... | |
#define | JSON_ID_TRUE 16 |
Literal value is true. More... | |
#define | JSON_ID_FALSE 17 |
Literal value is false. More... | |
#define | JSON_ID_NULL 18 |
Literal value is null. More... | |
Number Type Identifiers | |
APG specifies numbers as one of three types – floating point, unsigned integer and signed integer. These identifiers are used to indicate which. | |
#define | JSON_ID_FLOAT 19 |
Number value is a double floating point number. More... | |
#define | JSON_ID_SIGNED 20 |
Number value is a 64-bit signed integer. More... | |
#define | JSON_ID_UNSIGNED 21 |
Number value is a 64-bit unsigned integer. More... | |
Functions | |
Construction and Destruction | |
void * | vpJsonCtor (exception *spEx) |
The JSON constructor. More... | |
void | vJsonDtor (void *vpCtx) |
The JSON Parser component destructor. More... | |
abool | bJsonValidate (void *vpCtx) |
Validate a JSON context pointer. More... | |
Read and Write | |
Reads and writes UTF-8 byte streams. JSON files are parsed as they are read. JSON files are converted to UTF-8 as they are written. | |
void * | vpJsonReadFile (void *vpCtx, const char *cpFileName) |
The JSON file reader. More... | |
void * | vpJsonReadArray (void *vpCtx, uint8_t *ucpData, aint uiDataLen) |
The JSON array reader. More... | |
uint8_t * | ucpJsonWrite (void *vpCtx, json_value *spValue, aint *uipCount) |
Converts a sub-tree of values into UTF-8 byte stream of JSON text. More... | |
Accessing JSON Tree Nodes | |
Find trees, sub-trees, node siblings and specified key names. | |
void * | vpJsonFindKeyA (void *vpCtx, const char *cpKey, json_value *spValue) |
Find JSON values with a specified ASCII key. More... | |
void * | vpJsonFindKeyU (void *vpCtx, const uint32_t *uipKey, aint uiLength, json_value *spValue) |
Find JSON values with the specified 32-bit Unicode key. More... | |
void * | vpJsonTree (void *vpCtx, json_value *spValue) |
Initialize the iterator to walk a value tree. More... | |
void * | vpJsonChildren (void *vpCtx, json_value *spValue) |
Initialize the iterator over the children of the given value as the parent node. More... | |
Value Iterators | |
void | vJsonIteratorDtor (void *vpIteratorCtx) |
The JSON iterator destructor. More... | |
json_value * | spJsonIteratorFirst (void *vpIteratorCtx) |
Find the first value in the list represented by this iterator. More... | |
json_value * | spJsonIteratorLast (void *vpIteratorCtx) |
Find the last value in the list represented by this iterator. More... | |
json_value * | spJsonIteratorNext (void *vpIteratorCtx) |
Find the next value in the list represented by this iterator. More... | |
json_value * | spJsonIteratorPrev (void *vpIteratorCtx) |
Find the prev value in the list represented by this iterator. More... | |
aint | uiJsonIteratorCount (void *vpIteratorCtx) |
Find the number of values in the list represented by this iterator. More... | |
JSON Builder | |
For simple ASCII characters, one can easily just type a JSON file into a word processor. The syntax is that simple. However, for general 32- or even 64-bit alphabet characters this is not possible. This suite of functions – implemented as a sub-object – can build Unicode strings and arbitrary-width numbers into JSON | |
void * | vpJsonBuildCtor (void *vpJsonCtx) |
The builder object constructor. More... | |
void | vJsonBuildDtor (void *vpBuildCtx) |
The builder object destructor. More... | |
void | vJsonBuildClear (void *vpBuildCtx) |
Clears all memory associated with this builder object. More... | |
aint | uiJsonBuildMakeStringA (void *vpBuildCtx, const char *cpString) |
Make a string value from a null-terminated ASCII string. More... | |
aint | uiJsonBuildMakeStringU (void *vpBuildCtx, const uint32_t *uipData, aint uiLength) |
Make a string value from UTF-32 code points. More... | |
aint | uiJsonBuildMakeNumberF (void *vpBuildCtx, double dNumber) |
Make a JSON floating point number value. More... | |
aint | uiJsonBuildMakeNumberS (void *vpBuildCtx, int64_t iNumber) |
Make a JSON signed integer number value. More... | |
aint | uiJsonBuildMakeNumberU (void *vpBuildCtx, uint64_t uiNumber) |
Make a JSON unsigned integer number value. More... | |
aint | uiJsonBuildMakeTrue (void *vpBuildCtx) |
Make a JSON true value. More... | |
aint | uiJsonBuildMakeFalse (void *vpBuildCtx) |
Make a JSON false value. More... | |
aint | uiJsonBuildMakeNull (void *vpBuildCtx) |
Make a JSON null value. More... | |
aint | uiJsonBuildMakeObject (void *vpBuildCtx) |
Make a JSON object value. More... | |
aint | uiJsonBuildMakeArray (void *vpBuildCtx) |
Makea JSON array value. More... | |
aint | uiJsonBuildAddToObject (void *vpBuildCtx, aint uiObject, aint uiKey, aint uiAdd) |
Add a child value to a parent object value. More... | |
aint | uiJsonBuildAddToArray (void *vpBuildCtx, aint uiArray, aint uiAdd) |
Add a child value to a parent array value. More... | |
void * | vpJsonBuild (void *vpBuildCtx, aint uiRoot) |
Build the JSON object. More... | |
Display Helpers | |
void | vJsonDisplayValue (void *vpCtx, json_value *spValue, aint uiDepth) |
Display a value and optionally the values in the branch below, if any. More... | |
void | vJsonDisplayInput (void *vpCtx, abool bShowLines) |
Display the input JSON byte stream. More... | |
Header file for the JSON component. Defines API prototypes.
Definition in file json.h.
#define JSON_ID_FLOAT 19 |
#define JSON_ID_SIGNED 20 |
#define JSON_ID_UNSIGNED 21 |
abool bJsonValidate | ( | void * | vpCtx | ) |
Validate a JSON context pointer.
vpCtx | Pointer to a possibly valid JSON context returned from vpJsonCtor(). |
json_value* spJsonIteratorFirst | ( | void * | vpIteratorCtx | ) |
Find the first value in the list represented by this iterator.
vpIteratorCtx | A valid context pointer returned from any of the iterator-generating functions. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
json_value* spJsonIteratorLast | ( | void * | vpIteratorCtx | ) |
Find the last value in the list represented by this iterator.
vpIteratorCtx | A valid context pointer returned from any of the iterator-generating functions. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
json_value* spJsonIteratorNext | ( | void * | vpIteratorCtx | ) |
Find the next value in the list represented by this iterator.
It should be preceded by a call to spJsonIteratorFirst()
vpIteratorCtx | A valid context pointer returned from any of the iterator-generating functions. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
json_value* spJsonIteratorPrev | ( | void * | vpIteratorCtx | ) |
Find the prev value in the list represented by this iterator.
It should be preceded by a call to spJsonIteratorNext()
vpIteratorCtx | A valid context pointer returned from any of the iterator-generating functions. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
uint8_t* ucpJsonWrite | ( | void * | vpCtx, |
json_value * | spValue, | ||
aint * | uipCount | ||
) |
Converts a sub-tree of values into UTF-8 byte stream of JSON text.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
spValue | The root node of the sub-tree to write. spValue can be any value, including the root value, of an existing value tree. |
uipCount | Pointer to an unsigned integer. On completion the number of bytes in the output JSON text is written here. |
Add a child value to a parent array value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
uiArray | The parent array value to add a child value to. The return index from uiJsonBuildMakeArray(). |
uiAdd | The index of the value to add as a child of uiParent. |
Add a child value to a parent object value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
uiObject | The parent object value to add a child value to. The return index from uiJsonBuildMakeObject(). |
uiKey | Must the index of a string object defining the object's member key.e.g. uiKey = uiJsonBuilderStringA(vpBuildCtx, "my key"); |
uiAdd | The index of the value to add as a child of uiParent. |
aint uiJsonBuildMakeArray | ( | void * | vpBuildCtx | ) |
Makea JSON array value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtof(); Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
aint uiJsonBuildMakeFalse | ( | void * | vpBuildCtx | ) |
Make a JSON false value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtof(); Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
aint uiJsonBuildMakeNull | ( | void * | vpBuildCtx | ) |
Make a JSON null value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtof(); Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
aint uiJsonBuildMakeNumberF | ( | void * | vpBuildCtx, |
double | dNumber | ||
) |
Make a JSON floating point number value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
dNumber | The floating point number to make a JSON value from. |
aint uiJsonBuildMakeNumberS | ( | void * | vpBuildCtx, |
int64_t | iNumber | ||
) |
Make a JSON signed integer number value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
iNumber | The signed integer to make a JSON value from. If iNumber >= 0, an unsigned integer value will be created. |
aint uiJsonBuildMakeNumberU | ( | void * | vpBuildCtx, |
uint64_t | uiNumber | ||
) |
Make a JSON unsigned integer number value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
uiNumber | The unsigned integer to make a JSON value from. |
aint uiJsonBuildMakeObject | ( | void * | vpBuildCtx | ) |
Make a JSON object value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
aint uiJsonBuildMakeStringA | ( | void * | vpBuildCtx, |
const char * | cpString | ||
) |
Make a string value from a null-terminated ASCII string.
Note that the input is raw UTF-32, 32-bit code points.
Note that the input must be a valid RFC8259-compliant string. Be especially careful since the input argument is a C-language string which must result in a RFC8259-compliant string. In particular, this means the the reverse solidus, "\", must always be escaped. For example:
Also note that this means the characters 0x00-0x1F must be escaped, e.g. \u0000 or \u00FF, and that characters 0x80-0xFF must be either escaped or UTF-8 encoded. Example, the character value 0xFF can be input with either of these C-language strings.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
cpString | Pointer to the string to make into a value. String may be empty but not NULL. |
Make a string value from UTF-32 code points.
Note that the input is raw UTF-32, 32-bit code points.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
uipData | Pointer to the array of Unicode UTF-32 code points. May be NULL for empty array (uiLength ignored.) |
uiLength | The number of code points in the array. May be zero. |
aint uiJsonBuildMakeTrue | ( | void * | vpBuildCtx | ) |
Make a JSON true value.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
aint uiJsonIteratorCount | ( | void * | vpIteratorCtx | ) |
Find the number of values in the list represented by this iterator.
vpIteratorCtx | A valid context pointer returned from any of the iterator-generating functions. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
void vJsonBuildClear | ( | void * | vpBuildCtx | ) |
Clears all memory associated with this builder object.
Reset this object for building a new value tree.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
void vJsonBuildDtor | ( | void * | vpBuildCtx | ) |
The builder object destructor.
Frees all memory allocations associated with this object. Note however, that vJsonDtor(), the parent object destructor, will free all memory associated with this builder object,
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
void vJsonDisplayInput | ( | void * | vpCtx, |
abool | bShowLines | ||
) |
Display the input JSON byte stream.
This will use a format object to display the JSON input byte stream in a hexdump-style format.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
bShowLines | - if true, the display will show a separate hexdump-type display for each line. |
void vJsonDisplayValue | ( | void * | vpCtx, |
json_value * | spValue, | ||
aint | uiDepth | ||
) |
Display a value and optionally the values in the branch below, if any.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
spValue | - pointer to value to display |
uiDepth | - Indicates the tree depth of the value's sub branch to display. Use zero(0) to display the full sub-tree, one(1) to display just the given value. |
void vJsonDtor | ( | void * | vpCtx | ) |
The JSON Parser component destructor.
Clears the context to prevent accidental use after release and frees all memory allocated by this object. Freed memory includes any and all memory that may have been allocated to iterator or builder objects.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. A NULL pointer is silently ignored. However, a non-NULL pointers must be a valid JSON context pointer. |
void vJsonIteratorDtor | ( | void * | vpIteratorCtx | ) |
The JSON iterator destructor.
Can be called to clean up all memory allocations used by this iterator. However, the JSON destructor vJsonDtor() will free all memory associated with the JSON object, including all iterators and builders.
vpIteratorCtx | A valid context pointer returned from any of the iterator-generating functions. |
NULL is silently ignored. However, if non-NULL must be valid. If invalid the application will silently exit with a BAD_CONTEXT exit code.
void* vpJsonBuild | ( | void * | vpBuildCtx, |
aint | uiRoot | ||
) |
Build the JSON object.
Build a tree of values, from the collection of values "added" with uiJsonBuilderAdd() calls.
vpBuildCtx | A context pointer returned from a previous call to vpJsonBuildCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
uiRoot | Index of the value to use as the tree root. Must be a return value from one of the uiJsonBuildMake...() functions. |
void* vpJsonBuildCtor | ( | void * | vpJsonCtx | ) |
The builder object constructor.
vpJsonCtx | - Pointer to a valid JSON object previously created with vpJsonCtor(). Silently exits the application with exit code BAD_CONTEXT if pointer is invalid. |
void* vpJsonChildren | ( | void * | vpCtx, |
json_value * | spValue | ||
) |
Initialize the iterator over the children of the given value as the parent node.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
spValue | Pointer to the tree value to use at the root node of the walk. |
void* vpJsonCtor | ( | exception * | spEx | ) |
The JSON constructor.
spEx | Pointer to a valid exception structure initialized with XCTOR(). If not valid the application will silently exit with a BAD_CONTEXT exit code. |
void* vpJsonFindKeyA | ( | void * | vpCtx, |
const char * | cpKey, | ||
json_value * | spValue | ||
) |
Find JSON values with a specified ASCII key.
Search for all values with the specified key.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
cpKey | The key as a null-terminated ASCII string. |
spValue | - Pointer to the root node of the sub-tree to search. The given node and all nodes in the sub-tree below, if any, will be searched. |
void* vpJsonFindKeyU | ( | void * | vpCtx, |
const uint32_t * | uipKey, | ||
aint | uiLength, | ||
json_value * | spValue | ||
) |
Find JSON values with the specified 32-bit Unicode key.
Search for all values with the specified key.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
uipKey | Pointer to the array of key string Unicode code points. |
uiLength | The number of code points in the string. |
spValue | Pointer to the root node of the sub-tree to search. The given value and all values in the sub-tree below, if any, will be searched. |
void* vpJsonReadArray | ( | void * | vpCtx, |
uint8_t * | ucpData, | ||
aint | uiDataLen | ||
) |
The JSON array reader.
Reads a an array containing JSON text in UTF-8 format and parses the file into a value tree.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
ucpData | Pointer to the UTF-8 encoded JSON text. |
uiDataLen | The number of bytes of JSON text data. |
void* vpJsonReadFile | ( | void * | vpCtx, |
const char * | cpFileName | ||
) |
The JSON file reader.
Reads a file containing JSON text in UTF-8 format and parses the file into a value tree.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
cpFileName | The name of the file to read. |
void* vpJsonTree | ( | void * | vpCtx, |
json_value * | spValue | ||
) |
Initialize the iterator to walk a value tree.
"Walk" refers to a depth-first traversal of the value tree.
vpCtx | Pointer to a valid parser context previously returned from vpJsonCtor. If invalid the application will silently exit with a BAD_CONTEXT exit code. |
spValue | Pointer to the start value. The given value and all values in the sub-tree below, if any, will be walked. |