Oyranos  0.9.7
Oyranos is a full featured Color Management System
Functions
Oyjl JSON Parsing

Easy to use JSON API. More...

Collaboration diagram for Oyjl JSON Parsing:

Functions

oyjl_val oyjl_tree_parse (const char *input, char *error_buffer, size_t error_buffer_size)
 read a json text string into a C data structure More...
 
char * oyjl_value_text (oyjl_val v, void *(*alloc)(size_t size))
 get the value as text string with user allocator More...
 
void oyjl_tree_to_paths (oyjl_val root, int levels, const char *xpath, int flags, char ***paths)
 find matching paths More...
 
void oyjl_tree_to_json (oyjl_val v, int *level, char **json)
 convert a C tree into a JSON string More...
 
int oyjl_value_count (oyjl_val v)
 return the number of members if any at the node level More...
 
oyjl_val oyjl_value_pos_get (oyjl_val v, int pos)
 obtain a child node at the nth position from a object or array node More...
 
int oyjl_path_match (const char *path, const char *xpath, int flags)
 search for xpath pattern matching in a full path More...
 
oyjl_val oyjl_tree_new (const char *path)
 create a node by a path expression More...
 
oyjl_val oyjl_tree_get_value (oyjl_val v, int flags, const char *xpath)
 obtain a node by a path expression More...
 
oyjl_val oyjl_tree_get_valuef (oyjl_val v, int flags, const char *format,...)
 get a child node by a path expression More...
 
int oyjl_value_set_string (oyjl_val v, const char *string)
 set the node value to a string More...
 
void oyjl_value_clear (oyjl_val v)
 release all childs recursively More...
 
void oyjl_tree_clear_value (oyjl_val root, const char *xpath)
 release a specific node and all its childs More...
 
void oyjl_tree_free (oyjl_val v)
 release a node and all its childs recursively More...
 

Detailed Description

Easy to use JSON API.

The API is designed to be easily useable without much boilerplate. It includes a xpath alike syntax to obtain or create nodes inside a tree. A path string is constructed of terms and the slash delimiter '/'. Understood terms are object names or the squared brackets index operator [].

Path Example:

"foo/[3]/bar" will return the "bar" node with the "found" string.

{
  "foo": [
    { "ignore": 0 },
    { "ignore_too": 0 },
    { "ignore_it": 0 },
    { "bar": "found" }
  ]
}

Some API's accept extended paths expressions. Those can contain empty terms, like "//", which matches all keys in the above example. Those are oyjl_tree_to_paths() and oyjl_path_match(). oyjl_tree_to_paths() works on the whole tree to match a extended xpath.

Programming Tutorial

The following code examples come from tutorial_json_options.c .

void testOyjl(void)
{
/* JSON string */
const char * text = "{\"org\":{\"test\":[{\"s1key_a\":\"val_a\",\"s1key_b\":\"val_b\"},{\"s2key_c\":\"val_c\",\"s2key_d\":\"val_d\"}],\"key_e\":\"val_e_yyy\",\"key_f\":\"val_f\"}}";
oyjl_val value = 0;
int level = 0;
char * json = 0;
char error_buffer[128];
/* read JSON into C data struct */
oyjl_val root = oyjl_tree_parse( text, error_buffer, 128 );
/* convert back to JSON */
oyjl_tree_to_json( root, &level, &json );
fprintf( stderr, "%s\n", json );
free(json); json = NULL;
/* use a xpath to obtain a node */
value = oyjl_tree_get_valuef( root, 0, "org/test/[%d]", 1 );
oyjl_tree_to_json( value, &level, &json );
fprintf( stderr, "%s\n", json );
free(json); json = NULL;
/* use a xpath to remove a node */
oyjl_tree_clear_value( root, "org/test/[0]" );
oyjl_tree_to_json( root, &level, &json );
fprintf( stderr, "%s\n", json );
free(json); json = NULL;
/* use a xpath to get a new node in a existing tree */
value = oyjl_tree_get_value( root, OYJL_CREATE_NEW, "org/add/opt" );
oyjl_tree_to_json( root, &level, &json );
fprintf( stderr, "%s\n", json );
free(json); json = NULL;
/* set the new node to some string value */
oyjl_value_set_string( value, "value" );
oyjl_tree_to_json( root, &level, &json );
fprintf( stderr, "%s\n", json );
free(json); json = NULL;
/* release memory */
oyjl_tree_free ( root );
/* use a xpath to create new tree */
root = oyjl_tree_new( "new/tree/key" );
oyjl_tree_to_json( root, &level, &json );
fprintf( stderr, "%s\n", json );
free(json); json = NULL;
/* release memory */
oyjl_tree_free( root );

Function Documentation

int oyjl_path_match ( const char *  path,
const char *  xpath,
int  flags 
)

search for xpath pattern matching in a full path

The function tries to match a single path expression level by level.

1 // the second xpath expression matches the first path
2 int matches = oyjl_path_match( "org/free/[1]/s2key_d", "org///s2key_d", 0 );
3 // "//[1]/s2key_d" or "///s2key_d" would fit as well; "//[0]/s2key_d" not
Parameters
patha path expression
xpatha extented path expression
flagsoptional switches
  • 0 : match all xpaths from start
  • OYJL_PATH_MATCH_LEN : match all xpaths of the exact same number of terms
  • OYJL_PATH_MATCH_LAST_ITEMS : search the last terms(s) from xpath
Returns
0 - fail, 1 - match

References oyjl_tree_free(), oyjl_value_clear(), oyjl_value_count(), and oyjl_value_pos_get().

void oyjl_tree_clear_value ( oyjl_val  root,
const char *  xpath 
)

release a specific node and all its childs

In case parents have no children, release them or clear root.

Examples:
tutorial_json_options.c.

References oyjl_tree_free(), oyjl_tree_get_value(), and oyjl_value_clear().

void oyjl_tree_free ( oyjl_val  v)
oyjl_val oyjl_tree_get_value ( oyjl_val  v,
int  flags,
const char *  xpath 
)
oyjl_val oyjl_tree_get_valuef ( oyjl_val  v,
int  flags,
const char *  format,
  ... 
)

get a child node by a path expression

Function oyjl_tree_get_valuef Creating a new node inside a existing tree needs just a root node - v. The flags should contain OYJL_CREATE_NEW.

1 oyjl_val new_node = oyjl_tree_get_valuef( root, OYJL_CREATE_NEW, "my/new/node" );

Example: "foo/[]/bar" will append a node to the foo array and create the bar node, which is empty.

1 oyjl_val new_node = oyjl_tree_get_valuef( root, OYJL_CREATE_NEW, "foo/[]/bar" );
Parameters
[in]vthe oyjl node
[in]flagsOYJL_CREATE_NEW - returns nodes even if they did not yet exist
[in]formatthe format for the slashed path string
[in]...the variable argument list; optional
Returns
the requested node or a new tree or zero
Version
Oyranos: 0.9.7
Date
2017/10/12
Since
2011/09/24 (Oyranos: 0.3.3)
Examples:
tutorial_json_options.c.

References oyjl_tree_get_value().

Referenced by oyDevicesFromTaxiDB(), oyFilterNode_s::oyFilterNode_GetUi(), and oyConfig_s::oyRankMapFromJSON().

oyjl_val oyjl_tree_new ( const char *  path)

create a node by a path expression

A NULL argument allocates just a node of type oyjl_t_null.

See also
oyjl_tree_get_valuef()
Examples:
tutorial_json_options.c.

Referenced by oyOptions_s::oyOptions_GetText().

oyjl_val oyjl_tree_parse ( const char *  input,
char *  error_buffer,
size_t  error_buffer_size 
)

read a json text string into a C data structure

1  const char * text = "{\"org\":{\"test\":[{\"s1key_a\":\"val_a\",\"s1key_b\":\"val_b\"},{\"s2key_c\":\"val_c\",\"s2key_d\":\"val_d\"}],\"key_e\":\"val_e_yyy\",\"key_f\":\"val_f\"}}";
1  char error_buffer[128];
2 
3  /* read JSON into C data struct */
4  oyjl_val root = oyjl_tree_parse( text, error_buffer, 128 );

Examples:
tutorial_json_options.c.

Referenced by oyConfig_s::oyConfig_FromJSON(), oyDeviceFromJSON(), oyDevicesFromTaxiDB(), oyOptions_s::oyOptions_FromJSON(), oyraFilter_ImageChannelRun(), and oyConfig_s::oyRankMapFromJSON().

void oyjl_tree_to_json ( oyjl_val  v,
int *  level,
char **  json 
)

convert a C tree into a JSON string

Examples:
tutorial_json_options.c.

References oyjl_tree_to_json().

Referenced by oyjl_tree_to_json(), and oyOptions_s::oyOptions_GetText().

void oyjl_tree_to_paths ( oyjl_val  root,
int  levels,
const char *  xpath,
int  flags,
char ***  paths 
)

find matching paths

The function works on the whole tree to match a xpath.

Parameters
rootnode
levelsdesired level depth
xpathextented path expression; It accepts even empty terms.
flagssupport filters:
  • OYJL_KEY: only keys
  • OYJL_PATH: only paths
  • 0 for both, paths and keys
xpathsthe resulting string list
Version
Oyranos: 0.9.7
Date
2017/11/12
Since
2017/11/10 (Oyranos: 0.9.7)
void oyjl_value_clear ( oyjl_val  v)

release all childs recursively

Referenced by oyjl_path_match(), oyjl_tree_clear_value(), oyjl_tree_free(), and oyjl_value_set_string().

int oyjl_value_count ( oyjl_val  v)

return the number of members if any at the node level

This function is useful to traverse through objects and arrays of a unknown JSON tree.

Referenced by oyConfig_s::oyConfig_FromJSON(), oyDeviceFromJSON(), oyDevicesFromTaxiDB(), oyFilterNode_s::oyFilterNode_GetUi(), oyjl_path_match(), oyjl_value_text(), oyOptions_s::oyOptions_FromJSON(), oyraFilter_ImageChannelRun(), and oyConfig_s::oyRankMapFromJSON().

oyjl_val oyjl_value_pos_get ( oyjl_val  v,
int  pos 
)
int oyjl_value_set_string ( oyjl_val  v,
const char *  string 
)

set the node value to a string

Examples:
tutorial_json_options.c.

References oyjl_value_clear().

Referenced by oyOptions_s::oyOptions_GetText().

char* oyjl_value_text ( oyjl_val  v,
void *(*)(size_t size)  alloc 
)

get the value as text string with user allocator

References oyjl_value_count().

Referenced by oyConfig_s::oyConfig_FromJSON(), oyDeviceFromJSON(), oyDevicesFromTaxiDB(), and oyOptions_s::oyOptions_FromJSON().