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)
 search for xpath pattern matching in a full path More...
 
oyjl_val oyjl_tree_new (const char *xpath)
 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.

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

◆ oyjl_path_match()

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

search for xpath pattern matching in a full path

// the second xpath expression matches the first path
int matches = oyjl_path_match( "org/free/[1]/s2key_d", "org///s2key_d" );
// "//[1]/s2key_d" or "///s2key_d" would fit as well; "//[0]/s2key_d" not

◆ oyjl_tree_clear_value()

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

◆ oyjl_tree_free()

void oyjl_tree_free ( oyjl_val  v)

release a node and all its childs recursively

Examples:
tutorial_json_options.c.

References oyjl_value_clear().

Referenced by oyjl_tree_clear_value().

◆ oyjl_tree_get_value()

oyjl_val oyjl_tree_get_value ( oyjl_val  v,
int  flags,
const char *  xpath 
)

obtain a node by a path expression

See also
oyjl_tree_get_valuef()
Examples:
tutorial_json_options.c.

Referenced by oyjl_tree_clear_value(), and oyjl_tree_get_valuef().

◆ oyjl_tree_get_valuef()

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.

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.

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

◆ oyjl_tree_new()

oyjl_val oyjl_tree_new ( const char *  xpath)

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.

◆ oyjl_tree_parse()

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

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\"}}";
char error_buffer[128];
/* read JSON into C data struct */
oyjl_val root = oyjl_tree_parse( text, error_buffer, 128 );

Examples:
tutorial_json_options.c.

◆ oyjl_tree_to_json()

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

◆ oyjl_tree_to_paths()

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

find matching paths

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

◆ oyjl_value_clear()

void oyjl_value_clear ( oyjl_val  v)

release all childs recursively

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

◆ oyjl_value_count()

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.

◆ oyjl_value_pos_get()

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

◆ oyjl_value_set_string()

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

◆ oyjl_value_text()

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

get the value as text string with user allocator