JSON Native API

Extensions

Json JSON Object.

Functions

Json*jsonAlloc(int flags)
 Allocate a json object.
intjsonBlend(Json *dest, Json *src, int flags)
 Blend two JSON objects.
intjsonBlendNodes(Json *dest, int did, Json *src, int sid, int flags)
 Blend nodes by copying from one Json to another.
voidjsonFree(Json *json)
 Free a json object.
cchar*jsonGet(Json *json, int nid, cchar *key, cchar *defaultValue)
 Get a json node value as a string.
booljsonGetBool(Json *json, int nid, cchar *key, bool defaultValue)
 Get a json node value as a boolean.
JsonNode*jsonGetChildNode(Json *json, int nid, int nth)
 Get the Nth child node for a json node.
intjsonGetId(Json *json, int nid, cchar *key)
 Get a json node ID.
intjsonGetInt(Json *json, int nid, cchar *key, int defaultValue)
 Get a json node value as an integer.
JsonNode*jsonGetNode(Json *json, int nid, cchar *key)
 Get a json node object.
intjsonGetType(Json *json, int nid, cchar *key)
 Get the value type for a node.
char*jsonNodeToString(Json *json, int nid, int flags, RBuf *buf)
 Serialize and convert a json sub-tree into a buffer.
intjsonParse(Json *json, cchar *text)
 Parse a json string into a json object.
Json*jsonParseFile(cchar *path, cchar **errorMsg, int flags)
 Load a JSON object from a filename.
Json*jsonParseString(cchar *text, cchar **errorMsg, int flags)
 Parse a JSON string into an object tree.
intjsonRemove(Json *obj, int nid, cchar *key)
 Remove a Property from a JSON object.
intjsonSave(Json *obj, int nid, cchar *path, int mode, int flags)
 Save a JSON object to a filename.
intjsonSet(Json *obj, int nid, cchar *key, cchar *value, int type)
 Update a key/value in the JSON object with a string value.
voidjsonToBuf(RBuf *buf, cchar *value, int flags)
 Convert a json value to serialized JSON representation and save in the given buffer.
voidjsonToHash(Json *json, int nid, cchar *key, RHash *hash)
 Convert a json sub-tree into a hash.
char*jsonToString(Json *json, int flags)
 Serialize a JSON object into a string.

Typedefs

Defines

#defineJSON_APPEND   0x4
 Default to append to existing '+' (default).
#defineJSON_CCREATE   0x10
 Conditional create if not already existing '?'.
#defineJSON_COMBINE   0x1
 Combine properies using '+' '-' '=' '?' prefixes.
#defineJSON_OVERWRITE   0x2
 Default to overwrite existing properies '='.
#defineJSON_REPLACE   0x8
 Replace existing properies '-'.

Json

Json

JSON Object.

API Stability:
Prototype.
See Also:
Fields:
uint__pad0__ Input text is mutable.
uintallocated Set to true if text was allocated and must be freed.
struct Json *blended Link to blended json trees.
uintcount Number of allocated nodes (count <= size).
char *end End of text + 1.
char *errorMsg Parsing error details.
REventevent Saving event.
uintlineNumber Current parse line number.
char *next Pointer to next token.
char *path Filename being parsed.
uintsize Size of Json.nodes in elements (includes spare).
uintstrict Strict JSON standard mode.
char *text Text being parsed.
Json * jsonAlloc (int flags)

Allocate a json object.

Parameters:
flagsSet to one or more of: JSON_STRICT, JSON_MUTABLE.
Returns:
A json object.
API Stability:
Evolving.
See Also:
int jsonBlend (Json *dest, Json *src, int flags)

Blend two JSON objects.

Description:
This performs an N-level deep clone of the source JSON object to be blended into the destination object. By default, this add new object properies and overwrite arrays and string values. The Property combination prefixes: '+', '=', '-' and '?' to append, overwrite, replace and conditionally overwrite are supported if the JSON_COMBINE flag is present.
Parameters:
destParsed JSON object. This is the destination object. The "src" object will be blended into this object.
srcSource JSON object to blend into dest. Parsed JSON object returned by jsonParse.
flagsThe JSON_COMBINE flag enables Property name prefixes: '+', '=', '-', '?' to append, overwrite, replace and and conditionally overwrite key values if not already present. When adding string properies, values will be appended using a space separator. Extra spaces will not be removed on replacement.

Without JSON_COMBINE or for properies without a prefix, the default is to blend objects by creating new properies if not already existing in the destination, and to treat overwrite arrays and strings. Use the JSON_OVERWRITE flag to override the default appending of objects and rather overwrite existing properies. Use the JSON_APPEND flag to override the default of overwriting arrays and strings and rather append to existing properies.
Returns:
Zero if successful.
API Stability:
Evolving.
See Also:
int jsonBlendNodes (Json *dest, int did, Json *src, int sid, int flags)

Blend nodes by copying from one Json to another.

Description:
This performs an N-level deep clone of the source JSON nodes to be blended into the destination object. By default, this add new object properies and overwrite arrays and string values. The Property combination prefixes: '+', '=', '-' and '?' to append, overwrite, replace and conditionally overwrite are supported if the JSON_COMBINE flag is present.
Parameters:
destDestination json.
didBase node ID from which to store the copied nodes.
srcSource json.
sidBase node ID from which to copy nodes.
flagsThe JSON_COMBINE flag enables Property name prefixes: '+', '=', '-', '?' to append, overwrite, replace and and conditionally overwrite key values if not already present. When adding string properies, values will be appended using a space separator. Extra spaces will not be removed on replacement.

Without JSON_COMBINE or for properies without a prefix, the default is to blend objects by creating new properies if not already existing in the destination, and to treat overwrite arrays and strings. Use the JSON_OVERWRITE flag to override the default appending of objects and rather overwrite existing properies. Use the JSON_APPEND flag to override the default of overwriting arrays and strings and rather append to existing properies.
Returns:
Zero if successful.
API Stability:
Evolving.
See Also:
void jsonFree (Json *json)

Free a json object.

Parameters:
jsonA json object.
API Stability:
Evolving.
See Also:
cchar * jsonGet (Json *json, int nid, cchar *key, cchar *defaultValue)

Get a json node value as a string.

Parameters:
jsonSource json.
nidBase node ID from which to examine. Set to zero for the top level.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
defaultValueIf the key is not defined, return the defaultValue.
Returns:
The key value as a string or defaultValue if not defined.
API Stability:
Evolving.
See Also:
bool jsonGetBool (Json *json, int nid, cchar *key, bool defaultValue)

Get a json node value as a boolean.

Parameters:
jsonSource json.
nidBase node ID from which to examine. Set to zero for the top level.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
defaultValueIf the key is not defined, return the defaultValue.
Returns:
The key value as a boolean or defaultValue if not defined.
API Stability:
Evolving.
See Also:
JsonNode * jsonGetChildNode (Json *json, int nid, int nth)

Get the Nth child node for a json node.

Parameters:
jsonSource json.
nidBase node ID to examine.
nthSpecify which child to return.
Returns:
The Nth child node object for the specified node.
API Stability:
Evolving.
See Also:
int jsonGetId (Json *json, int nid, cchar *key)

Get a json node ID.

Parameters:
jsonSource json.
nidBase node ID from which to start the search. Set to zero for the top level.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
Returns:
The node ID for the specified key.
API Stability:
Evolving.
See Also:
int jsonGetInt (Json *json, int nid, cchar *key, int defaultValue)

Get a json node value as an integer.

Parameters:
jsonSource json.
nidBase node ID from which to examine. Set to zero for the top level.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
defaultValueIf the key is not defined, return the defaultValue.
Returns:
The key value as an integer or defaultValue if not defined.
API Stability:
Evolving.
See Also:
JsonNode * jsonGetNode (Json *json, int nid, cchar *key)

Get a json node object.

Parameters:
jsonSource json.
nidBase node ID from which to start the search. Set to zero for the top level.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
Returns:
The node object for the specified key. Returns NULL if not found.
API Stability:
Evolving.
See Also:
int jsonGetType (Json *json, int nid, cchar *key)

Get the value type for a node.

Parameters:
jsonSource json.
nidBase node ID from which to start the search.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
Returns:
The data type. Set to JSON_OBJECT, JSON_ARRAY, JSON_COMMENT, JSON_STRING, JSON_PRIMITIVE or JSON_REGEXP.
API Stability:
Evolving.
See Also:
char * jsonNodeToString (Json *json, int nid, int flags, RBuf *buf)

Serialize and convert a json sub-tree into a buffer.

Description:
Converts the sub-tree rooted at the supplied key into a serialized string in the given buffer. The string is returned and the buffer is freed. The caller must free the return string.
Parameters:
jsonObject returned via jsonParse
nidBase node ID from which to convert. Set to zero for the top level.
flagsSerialization flags. Supported flags include JSON_PRETTY for a human-readable multiline format. JSON_QUOTES to wrap Property names in quotes. Use JSON_QUOTES to emit all Property values as quoted strings.
bufBuffer to serialize into. Set to null and a new buffer will be allocated.
Returns:
A serialized string that the caller must free. The buffer is freed.
API Stability:
Evolving.
See Also:
int jsonParse (Json *json, cchar *text)

Parse a json string into a json object.

Parameters:
jsonJson object created via jsonAlloc.
textJson string to parse.
Returns:
Zero if successful.
API Stability:
Evolving.
See Also:
Json * jsonParseFile (cchar *path, cchar **errorMsg, int flags)

Load a JSON object from a filename.

Parameters:
pathFilename path containing a JSON string to load.
errorMsgError message string set if the parse fails. Caller must not free.
flagsSet to JSON_STRICT to parse json, otherwise a relaxed json6 syntax is supported. Set to JSON_MUTABLE to permit the chaning of node values after parsing.
Returns:
JSON object tree.
API Stability:
Prototype.
See Also:
Json * jsonParseString (cchar *text, cchar **errorMsg, int flags)

Parse a JSON string into an object tree.

Description:
Deserializes a JSON string created into an object. The top level of the JSON string must be an object, array, string, number or boolean value.
Parameters:
textJSON string to deserialize.
errorMsgError message string set if the parse fails. Caller must not free.
flagsSet to JSON_STRICT to parse json, otherwise a relaxed json6 syntax is supported. Set to JSON_MUTABLE to permit the chaning of node values after parsing.
Returns:
Returns a tree of Json objects. Each object represents a level in the JSON input stream.
API Stability:
Prototype.
See Also:
int jsonRemove (Json *obj, int nid, cchar *key)

Remove a Property from a JSON object.

Parameters:
objParsed JSON object returned by jsonParse.
nidBase node ID from which to start searching for key. Set to zero for the top level.
keyProperty name to remove for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
Returns:
Returns a JSON object array of all removed properies. Array will be empty if not qualifying properies were found and removed.
API Stability:
Prototype.
See Also:
int jsonSave (Json *obj, int nid, cchar *path, int mode, int flags)

Save a JSON object to a filename.

Parameters:
objParsed JSON object returned by jsonParse.
nidBase node ID from which to start searching for key. Set to zero for the top level.
pathFilename path to contain the saved JSON string.
flagsSame flags as for jsonToString: JSON_PRETTY, JSON_QUOTES.
modePermissions mode.
Returns:
Zero if successful, otherwise a negative RT error code.
API Stability:
Prototype.
See Also:
int jsonSet (Json *obj, int nid, cchar *key, cchar *value, int type)

Update a key/value in the JSON object with a string value.

Description:
This call takes a multipar Property name and will operate at any level of depth in the JSON object. This routine supports the rQueryJson key syntax.
Parameters:
objParsed JSON object returned by jsonParse.
nidBase node ID from which to start search for key. Set to zero for the top level.
keyProperty name to add/update. This may include "." and the full rQueryJson syntax. For example: "settings.mode". See rQueryJson for a full description of key formats.
valueCharacter string value.
typeSet to JSON_ARRAY, JSON_OBJECT, JSON_PRIMITIVE or JSON_STRING.
Returns:
Positive node id if updated successfully. Otherwise a negative error code.
API Stability:
Prototype.
See Also:
void jsonToBuf (RBuf *buf, cchar *value, int flags)

Convert a json value to serialized JSON representation and save in the given buffer.

Parameters:
bufDestination buffer.
valueValue to convert.
flagsProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
Returns:
The data type. Set to JSON_OBJECT, JSON_ARRAY, JSON_COMMENT, JSON_STRING, JSON_PRIMITIVE or JSON_REGEXP.
API Stability:
Evolving.
See Also:
void jsonToHash (Json *json, int nid, cchar *key, RHash *hash)

Convert a json sub-tree into a hash.

Description:
Converts the sub-tree rooted at the supplied key into the given hash table.
Parameters:
jsonSource json.
nidBase node ID from which to start the search.
keyProperty name to search for. This may include ".". For example: "settings.mode". See rQueryJson for a full description of key formats.
hashHash table to use for the result.
API Stability:
Evolving.
See Also:
char * jsonToString (Json *json, int flags)

Serialize a JSON object into a string.

Description:
Serializes a top level JSON object created via jsonParse into a characters string in JSON format.
Parameters:
jsonSource json.
flagsSerialization flags. Supported flags include JSON_PRETTY for a human-readable multiline format. JSON_QUOTES to wrap Property names in quotes. Use JSON_QUOTES to emit all Property values as quoted strings.
Returns:
Returns a serialized JSON character string.
API Stability:
Prototype.
See Also:

Functions

Typedefs

© Embedthis Software. All rights reserved.