The JSON parser API. More...

#include <limits.h>
#include "json.h"
#include "jsonp.h"
#include "json-grammar.h"

Include dependency graph for json.c:

Macros
#define	CHARS_LINE_LEN 8
	Private Object use Only. More...

Functions
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...

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

void	vJsonDisplayInput (void *vpCtx, abool bShowLines)
	Display the input JSON byte stream. More...

void	vJsonDisplayValue (void vpCtx, json_value spValue, aint uiDepth)
	Display a value and optionally the values in the branch below, if any. More...

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

json_iterator *	spJsonIteratorCtor (json *spJson)
	Private function for internal object use only. Never called by the application. More...

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

Detailed Description

The JSON parser API.

This JSON parser is meant to be fully compliant with RFC8259. Some of the main features are:

Data encapsulation keeps each parser distinct and thread-safe.
JSON data is parsed into an array of value structures. The sequence of values is in the order of a depth-first traversal of the JSON object tree.
Values (see json_value_tag) are very general, accommodating all of the types:
- object (Contains a count of and pointer to its list members. Note that members are also json_value_tag structs.)
- array (Contains a count of and pointer to its list values.)
- u32_phrase pointer to both a null-terminated C-string, if possible, as well as an array of 32-bit Unicode code points.
- json_number Has a double, unsigned or signed integer value, depending on the number's form.
- true
- false
- null
A number of tools are available for, among other things, display and navigation of the JSON input and values.
- functions for input of the JSON data byte stream from a file or array
  - vpJsonReadFile()
  - vpJsonReadArray()
- functions for finding and displaying the JSON data in a hex dump format (the UTF-8 requirement for JSON input means that, in general, not all bytes will be printable.)
- functions for displaying the parsed values
  - vJsonDisplayValue()
- functions for finding specific key named values (global and for a specific object)
  - vpJsonFindKeyA() - for finding null-terminated C-string keys
  - vpJsonFindKeyU() - for finding keys that are an array of Unicode code points.

Definition in file json.c.

Macro Definition Documentation

◆ CHARS_LINE_LEN

#define CHARS_LINE_LEN 8

Private Object use Only.

Definition at line 71 of file json.c.

Function Documentation

◆ bJsonValidate()

abool bJsonValidate ( void * vpCtx )

Validate a JSON context pointer.

Parameters

vpCtx Pointer to a possibly valid JSON context returned from vpJsonCtor().

Returns: True if the pointer is valid, false otherwise.

Definition at line 188 of file json.c.

◆ spJsonIteratorCtor()

json_iterator* spJsonIteratorCtor ( json * spJson )

Private function for internal object use only. Never called by the application.

JSON iterators are constructed internally by the JSON object. These functions will return iterators.

Definition at line 561 of file json.c.

◆ spJsonIteratorFirst()

json_value* spJsonIteratorFirst ( void * vpIteratorCtx )

Find the first value in the list represented by this iterator.

Parameters

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.

Returns: A pointer to the first value in the list.

Definition at line 613 of file json.c.

◆ spJsonIteratorLast()

json_value* spJsonIteratorLast ( void * vpIteratorCtx )

Find the last value in the list represented by this iterator.

Parameters

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.

Returns: A pointer to the last value in the list.

Definition at line 627 of file json.c.

◆ spJsonIteratorNext()

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

Parameters

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.

Returns: A pointer to the next value in the list. NULL if there are no more values in the list.

Definition at line 647 of file json.c.

◆ spJsonIteratorPrev()

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

Parameters

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.

Returns: A pointer to the previous value in the list. NULL if the current value is the first value in the list.

Definition at line 671 of file json.c.

◆ ucpJsonWrite()

uint8_t* ucpJsonWrite	(	void *	vpCtx,
		json_value *	spValue,
		aint *	uipCount
	)

Converts a sub-tree of values into UTF-8 byte stream of JSON text.

Parameters

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.

Returns: Returns a pointer to the JSON text byte stream. The pointer is valid until another call to this function.

Definition at line 329 of file json.c.

◆ uiJsonIteratorCount()

aint uiJsonIteratorCount ( void * vpIteratorCtx )

Find the number of values in the list represented by this iterator.

Parameters

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.

Returns: The number of values in the list.

Definition at line 691 of file json.c.

◆ vJsonDisplayInput()

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.

Parameters

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.

Definition at line 365 of file json.c.

◆ vJsonDisplayValue()

void vJsonDisplayValue	(	void *	vpCtx,
		json_value *	spValue,
		aint	uiDepth
	)

Display a value and optionally the values in the branch below, if any.

Parameters

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.

Returns: APG_SUCCESS if successful, APG_FAILURE otherwise.

Definition at line 412 of file json.c.

◆ vJsonDtor()

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.

Parameters

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.

Definition at line 165 of file json.c.

◆ vJsonIteratorDtor()

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.

Parameters

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.

Returns: void. Frees all memory associated with this iterator object.

Definition at line 591 of file json.c.

◆ vpJsonChildren()

void* vpJsonChildren	(	void *	vpCtx,
		json_value *	spValue
	)

Initialize the iterator over the children of the given value as the parent node.

Parameters

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.

Returns: Initializes an iterator for a horizontal walk of the sibling children of the root value. Walks the children left to right. Returns NULL if the value has no children.

Definition at line 530 of file json.c.

◆ vpJsonCtor()

void* vpJsonCtor ( exception * spEx )

The JSON constructor.

Parameters

spEx	Pointer to a valid exception structure initialized with XCTOR(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns: Pointer to the object context on success.

Definition at line 115 of file json.c.

◆ vpJsonFindKeyA()

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.

Parameters

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.

Returns: A pointer to an iterator for the values with the specified key. NULL if no key matches are found.

Definition at line 434 of file json.c.

◆ vpJsonFindKeyU()

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.

Parameters

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.

Returns: A pointer to an iterator for the values with the specified key. NULL if no key matches are found.

Definition at line 474 of file json.c.

◆ vpJsonReadArray()

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.

Parameters

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.

Returns: Returns an iterator to the values in the value tree. The order of values is that of a depth-first walk of the value tree.

Definition at line 289 of file json.c.

◆ vpJsonReadFile()

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.

Parameters

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.

Returns: Returns an iterator to the values in the value tree. The order of values is that of a depth-first walk of the value tree.

Definition at line 207 of file json.c.

◆ vpJsonTree()

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.

Parameters

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.

Returns: An initialized iterator to the first node. In this case it is the root node or spValue.

Definition at line 501 of file json.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CHARS_LINE_LEN

Function Documentation

◆ bJsonValidate()

◆ spJsonIteratorCtor()

◆ spJsonIteratorFirst()

◆ spJsonIteratorLast()

◆ spJsonIteratorNext()

◆ spJsonIteratorPrev()

◆ ucpJsonWrite()

◆ uiJsonIteratorCount()

◆ vJsonDisplayInput()

◆ vJsonDisplayValue()

◆ vJsonDtor()

◆ vJsonIteratorDtor()

◆ vpJsonChildren()

◆ vpJsonCtor()

◆ vpJsonFindKeyA()

◆ vpJsonFindKeyU()

◆ vpJsonReadArray()

◆ vpJsonReadFile()

◆ vpJsonTree()