Tree data structure manipulation and I/O. More...

Collaboration diagram for OyjlTree JSON Parsing and Tree Handling:

Data Structures
struct	oyjl_val_s

Macros
#define	OYJL_NUMBER_DETECTION 0x1000
	try to parse values as number More...

#define	OYJL_DECIMAL_SEPARATOR_COMMA 0x2000
	use comma ',' as decimal separator More...

#define	OYJL_ALLOW_STATIC 0x10
	allow to read static format More...

#define	OYJL_DELIMITER_COMMA 0x20
	',' comma More...

#define	OYJL_DELIMITER_SEMICOLON 0x40
	';' semicolon More...

#define	OYJL_JSON 0x01
	JSON format; default. More...

#define	OYJL_YAML 0x04
	YAML format. More...

#define	OYJL_XML 0x08
	XML format. More...

#define	OYJL_CSV 0x20
	CSV format - needs 2D array. More...

#define	OYJL_CSV_SEMICOLON 0x40
	CSV format - needs 2D array. More...

#define	OYJL_HTML 0x100
	Formatting flag for markup on output. More...

#define	OYJL_NO_MARKUP 0x10000
	expect plain text More...

#define	OYJL_PATH 0x08
	flag to obtain only path More...

#define	OYJL_KEY 0x10
	flat to obtain only keys More...

#define	OYJL_NO_ALLOC 0x800
	avoid malloc for oyjlOBJECT_JSON More...

#define	OYJL_CREATE_NEW 0x02
	flag to allocate a new tree node, in case it is not inside More...

#define	OYJL_PATH_MATCH_LEN 0x20
	flag to test if the specified path match with the full length. More...

#define	OYJL_PATH_MATCH_LAST_ITEMS 0x40
	flag to test only the last path segments, which are separated by slash '/'. More...

#define	OYJL_OBSERVE 0x200000
	be verbose on change More...

Typedefs
typedef struct oyjl_val_s *	oyjl_val

typedef struct oyjl_val_s	oyjl_val_s

Enumerations
enum	oyjl_type { oyjl_t_string = 1, oyjl_t_number = 2, oyjl_t_object = 3, oyjl_t_array = 4, oyjl_t_true = 5, oyjl_t_false = 6, oyjl_t_null = 7 }

enum	oyjlPARSE_STATE_e { oyjlPARSE_STATE_NONE, oyjlPARSE_STATE_NOT_COMPILED, oyjlPARSE_STATE_FORMAT_ERROR, oyjlPARSE_STATE_PARSER_ERROR, oyjlPARSE_STATE_RETURN_STATIC }

Functions
int	oyjlDataFormat (const char *text)
	detect data type More...

const char *	oyjlDataFormatToString (int format)
	name data format More...

char *	oyjlValueText (oyjl_val v, void (alloc)(size_t size))
	get the value as text string with user allocator More...

char **	oyjlTreeToPaths (oyjl_val root, int levels, const char xpath, int flags, int count)
	find matching paths More...

const char *	oyjlJsonEscape (const char *in, int flags)
	Convert strings to pass through JSON. More...

char *	oyjlTreeToText (oyjl_val v, int flags)
	convert a C tree into a text string More...

void	oyjlTreeToJson (oyjl_val v, int level, char *json)
	convert a C tree into a JSON string More...

void	oyjlTreeToYaml (oyjl_val v, int level, char *text)
	convert a C tree into a YAML string More...

void	oyjlTreeToXml (oyjl_val v, int level, char *text)
	convert a C tree into a XML string More...

void	oyjlTreeToCsv (oyjl_val table, int flags, char **text)
	convert a C 2D table into a CSV string More...

oyjl_val	oyjlTreeParseCsv (const char text, const char delimiter, int flags, char *error_buffer OYJL_UNUSED, size_t error_buffer_size OYJL_UNUSED)
	read a CSV text string into a C data structure (libOyjl) More...

int	oyjlValueCount (oyjl_val v)
	return the number of members if any at the node level More...

oyjl_val	oyjlValuePosGet (oyjl_val v, int pos)
	obtain a child node at the nth position from a object or array node More...

int	oyjlPathMatch (const char path, const char xpath, int flags)
	search for xpath pattern matching in a full path More...

oyjl_val	oyjlTreeNew (const char *path)
	create a node by a path expression More...

char *	oyjlTreeGetPath (oyjl_val v, oyjl_val node)
	get a full path string from a child node More...

oyjl_val	oyjlTreeGetValue (oyjl_val v, int flags, const char *xpath)
	obtain a node by a path expression More...

oyjl_val	oyjlTreeGetValueF (oyjl_val v, int flags, const char *xformat,...)
	get a child node by a path expression More...

int	oyjlTreeSetStringF (oyjl_val root, int flags, const char value_text, const char xformat,...)
	set a child node to a string value More...

int	oyjlTreeSetDoubleF (oyjl_val root, int flags, double value, const char *xformat,...)
	set a child node to a string value More...

int	oyjlValueSetDouble (oyjl_val v, double value)
	set a child node to a string value More...

int	oyjlTreeSetIntF (oyjl_val root, int flags, long long value, const char *xformat,...)
	set a child node to a string value More...

int	oyjlValueSetInt (oyjl_val v, long long value)
	set a child node to a number value More...

int	oyjlValueSetString (oyjl_val v, const char *string)
	set the node value to a string More...

void	oyjlValueClear (oyjl_val v)
	release all childs recursively More...

void	oyjlValueCopy (oyjl_val v, oyjl_val src)
	copy only one level of allocation More...

void	oyjlTreeClearValue (oyjl_val root, const char *xpath)
	release a specific node and all its childs More...

void	oyjlTreeFree (oyjl_val v)
	release a node and all its childs recursively More...

OYJL_API oyjl_val	oyjlTreeParse (const char input, char error_buffer, size_t error_buffer_size)
	Parse a string. (libOyjl) More...

oyjl_val	oyjlTreeParse2 (const char text, int flags, const char error_name, int *status)
	read a JSON, XML or YAML text string into a C data structure (libOyjl) More...

oyjl_val	oyjlTreeGetNewValueFromArray (oyjl_val root, const char name, oyjl_val array_ret, int *pos_ret)
	obtain a new node object possibly in array More...

oyjl_val	oyjlTreeSerialise (oyjl_val v, int flags, int *size)
	write tree to data block More...

oyjl_val	oyjlTreeDeSerialise (oyjl_val v, int flags, int size)
	create tree from serialised data block More...

Detailed Description

Tree data structure manipulation and I/O.

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 oyjlTreeToPaths() and oyjlPathMatch(). oyjlTreeToPaths() 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 node = 0;
  char * json = 0;
  /* read JSON into C data struct */
  oyjl_val root = oyjlTreeParse2( text, 0, __func__, NULL );
  
  /* convert back to JSON */
  json = oyjlTreeToText( root, OYJL_JSON );
    fprintf( stderr, "root = oyjlTreeParse2( text ):\n%s\n", json?json:"" );
    free(json); json = NULL;
  /* use a xpath to obtain a node */
  node = oyjlTreeGetValueF( root, 0, "org/test/[%d]", 1 );
    json = oyjlTreeToText( node, OYJL_JSON );
    fprintf( stderr, "node = oyjlTreeGetValueF( root, \"org/test/[%%d]\", 1 ):\n%s\n", json?json:"" );
    free(json); json = NULL;
  /* use a xpath to remove a node */
  oyjlTreeClearValue( root, "org/test/[1]/" );
    json = oyjlTreeToText( node, OYJL_JSON );
    fprintf( stderr, "oyjlTreeClearValue( root, \"org/test/[1]/\" ):\n%s\n", json?json:"" );
    free(json); json = NULL;
  /* use a xpath to get a new node in a existing tree */
  node = oyjlTreeGetValue( root, OYJL_CREATE_NEW, "org/add/opt" );
    json = oyjlTreeToText( root, OYJL_JSON );
    fprintf( stderr, "node = oyjlTreeGetValue( root, OYJL_CREATE_NEW, \"org/add/opt\" ):\n%s\n", json?json:"" );
    free(json); json = NULL;
  /* set the new node to some string value  */
  oyjlValueSetString( node, "opt_value" );
    json = oyjlTreeToText( root, OYJL_JSON );
    fprintf( stderr, "oyjlValueSetString( node, \"opt_value\" ):\n%s\n", json?json:"" );
    free(json); json = NULL;
  /* release memory */
  oyjlTreeFree ( root );
  /* use a xpath to create new tree */
  root = oyjlTreeNew( "new/tree/key" );
    json = oyjlTreeToText( root, OYJL_JSON );
    fprintf( stderr, "oyjlTreeNew( \"new/tree/key\" ):\n%s\n", json?json:"" );
    free(json); json = NULL;
  /* release memory */
  oyjlTreeFree( root );
}

Macro Definition Documentation

◆ OYJL_ALLOW_STATIC

#define OYJL_ALLOW_STATIC 0x10

allow to read static format

◆ OYJL_CREATE_NEW

#define OYJL_CREATE_NEW 0x02

flag to allocate a new tree node, in case it is not inside

Examples:: tutorial_json_options.c.

Referenced by oyjlOptionStringToJson(), and oyjlTreeGetNewValueFromArray().

◆ OYJL_CSV

#define OYJL_CSV 0x20

CSV format - needs 2D array.

Referenced by oyjlTreeToText().

◆ OYJL_CSV_SEMICOLON

#define OYJL_CSV_SEMICOLON 0x40

CSV format - needs 2D array.

Referenced by oyjlTreeToText().

◆ OYJL_DECIMAL_SEPARATOR_COMMA

#define OYJL_DECIMAL_SEPARATOR_COMMA 0x2000

use comma ',' as decimal separator

◆ OYJL_DELIMITER_COMMA

#define OYJL_DELIMITER_COMMA 0x20

',' comma

◆ OYJL_DELIMITER_SEMICOLON

#define OYJL_DELIMITER_SEMICOLON 0x40

';' semicolon

Referenced by oyjlTreeToCsv().

◆ OYJL_HTML

#define OYJL_HTML 0x100

Formatting flag for markup on output.

◆ OYJL_JSON

#define OYJL_JSON 0x01

JSON format; default.

Examples:: tutorial_json_options.c.

◆ OYJL_KEY

#define OYJL_KEY 0x10

flat to obtain only keys

Referenced by oyjlTreeGetPath(), and oyjlUiJsonSetDefaults().

◆ OYJL_NO_ALLOC

#define OYJL_NO_ALLOC 0x800

avoid malloc for oyjlOBJECT_JSON

◆ OYJL_NO_MARKUP

#define OYJL_NO_MARKUP 0x10000

expect plain text

Referenced by oyjlTreeToCsv(), and oyjlTreeToText().

◆ OYJL_NUMBER_DETECTION

#define OYJL_NUMBER_DETECTION 0x1000

try to parse values as number

Referenced by oyjlTreeGetNewValueFromArray().

◆ OYJL_OBSERVE

#define OYJL_OBSERVE 0x200000

be verbose on change

Referenced by oyjlTermColorInit().

◆ OYJL_PATH

#define OYJL_PATH 0x08

flag to obtain only path

◆ OYJL_PATH_MATCH_LAST_ITEMS

#define OYJL_PATH_MATCH_LAST_ITEMS 0x40

flag to test only the last path segments, which are separated by slash '/'.

Referenced by oyjlPathMatch().

◆ OYJL_PATH_MATCH_LEN

#define OYJL_PATH_MATCH_LEN 0x20

flag to test if the specified path match with the full length.

Referenced by oyjlPathMatch().

◆ OYJL_XML

#define OYJL_XML 0x08

XML format.

Referenced by oyjlTreeToText().

◆ OYJL_YAML

#define OYJL_YAML 0x04

YAML format.

Referenced by oyjlTreeToText().

Typedef Documentation

◆ oyjl_val

typedef struct oyjl_val_s* oyjl_val

A pointer to a node in the parse tree

◆ oyjl_val_s

typedef struct oyjl_val_s oyjl_val_s

A JSON value representation capable of holding one of the seven types above. For "string", "number", "object", and "array" additional data is available in the union. The "OYJL_IS_*" and "OYJL_GET_*" macros below allow type checking and convenient value extraction.

Enumeration Type Documentation

◆ oyjl_type

enum oyjl_type

The original yajl_val_s structure was renamed to oyjl_val_s by Kai-Uwe Behrmann for libOyjl. possible data types that a oyjl_val_s can hold

Enumerator
oyjl_t_string	a text in UTF-8
oyjl_t_number	floating or integer number
oyjl_t_object	a JSON object
oyjl_t_array	a JSON array
oyjl_t_true	boolean true or 1
oyjl_t_false	boolean false or 0
oyjl_t_null	empty value

◆ oyjlPARSE_STATE_e

enum oyjlPARSE_STATE_e

Enumerator
oyjlPARSE_STATE_NONE	nothing to report
oyjlPARSE_STATE_NOT_COMPILED	the format is currently not compiled
oyjlPARSE_STATE_FORMAT_ERROR	check with oyjlDataFormat()
oyjlPARSE_STATE_PARSER_ERROR	message is sent to oyjlMessage_p
oyjlPARSE_STATE_RETURN_STATIC	oyjl_val is static and must not be freed; needs OYJL_ALLOW_STATIC flag

Function Documentation

◆ oyjlDataFormat()

int oyjlDataFormat ( const char * text )

detect data type

Parameters

text string

Returns

format

7 : JSON
8 : XML
9 : YAML
10 : C
0 : not detected
-1 : no input
-2 : no data

References OYJL_COMPARE_CASE, and oyjlStringStartsWith().

◆ oyjlDataFormatToString()

const char * oyjlDataFormatToString ( int format )

name data format

Parameters

format number from oyjlDataFormat()

Returns: string

◆ oyjlJsonEscape()

const char * oyjlJsonEscape	(	const char *	in,
		int	flags
	)

Convert strings to pass through JSON.

Parameters

in input string

flags

support filters:

OYJL_JSON: mask to not break JSON format
OYJL_KEY: handle input as a key string; mask out xpath expressions
OYJL_JSON_VALUE: handle input as a JSON value string
OYJL_NO_INDEX: escape square brackets
OYJL_QUOTE: escape quotation marks '"'
OYJL_REVERSE: undo all escaping for storing JSON keys
OYJL_REGEXP | OYJL_REVERSE: undo oyjlRegExpEscape()
0 apply common basic JSON VALUE escaping

Returns: the resulting string

Version: Oyjl: 1.0.0

Date: 2024/05/07

Since: 2021/09/01 (Oyjl: 1.0.0)

◆ oyjlPathMatch()

int oyjlPathMatch	(	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.

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

Parameters

path	a path expression
xpath	a extented path expression
flags	optional 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_PATH_MATCH_LAST_ITEMS, OYJL_PATH_MATCH_LEN, and oyjlStringSplit().

◆ oyjlTreeClearValue()

void oyjlTreeClearValue	(	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_val_s::array, oyjl_val_s::object, oyjl_t_array, oyjl_t_object, oyjlStringCopy(), oyjlStringSplit(), oyjlTreeFree(), oyjlTreeGetValue(), oyjlValueClear(), oyjl_val_s::type, and oyjl_val_s::u.

◆ oyjlTreeDeSerialise()

oyjl_val oyjlTreeDeSerialise	(	oyjl_val	v,
		int flags	OYJL_UNUSED,
		int size	OYJL_UNUSED
	)

create tree from serialised data block

Parameters

[in]	v	serialised tree
[in]	flags	unused:
[in]	size	the size of the data block v - not used

Returns: serialised tree

See also: oyjlTreeSerialise()

Version: Oyjl: 1.0.0

Date: 2021/11/01

Since: 2021/11/01 (Oyjl: 1.0.0)

References oyjlBT(), oyjlOBJECT_JSON, and oyjl_val_s::type.

◆ oyjlTreeFree()

void oyjlTreeFree ( oyjl_val v )

release a node and all its childs recursively

Free a parse tree returned by oyjlTreeParse().

Parameters

v	Pointer to a JSON value returned by oyjlTreeParse(). Passing NULL is valid and results in a no-op.

References oyjlOBJECT_JSON, oyjlValueClear(), and oyjl_val_s::type.

Referenced by oyjlTreeClearValue().

◆ oyjlTreeGetNewValueFromArray()

oyjl_val oyjlTreeGetNewValueFromArray	(	oyjl_val	root,
		const char *	name,
		oyjl_val *	array_ret,
		int *	pos_ret
	)

obtain a new node object possibly in array

The node can even have the same name. It works only for flat path level.

Parameters

[in,out]	root	the node
[in]	name	flat path, without leveling slash
[out]	array_ret	tell if the node is child of that array
[out]	pos_ret	position of returned node in array_ret -1 means object is direct child without array >= 0 -> index in array

Returns: new node

References oyjl_val_s::number, OYJL_CREATE_NEW, OYJL_NUMBER_DETECTION, oyjl_t_array, oyjl_t_number, oyjlStringAdd(), oyjlStringToDouble(), oyjlTreeGetValue(), oyjlTreeGetValueF(), oyjlValueCount(), oyjlValueSetString(), oyjl_val_s::type, and oyjl_val_s::u.

◆ oyjlTreeGetPath()

char * oyjlTreeGetPath	(	oyjl_val	v,
		oyjl_val	node
	)

get a full path string from a child node

This function is the reverse from oyjlTreeGetValue(). Use this function to get parent names and resolve xpath expressions to full paths.

Parameters

[in]	v	the oyjl node
[in]	node	the node to search for inside the v tree

Returns: the path or zero

Version: Oyranos: 0.9.7

Date: 2020/03/27

Since: 2020/03/27 (Oyranos: 0.9.7)

References OYJL_KEY, oyjlStringListRelease(), oyjlTreeGetValue(), and oyjlTreeToPaths().

◆ oyjlTreeGetValue()

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

obtain a node by a path expression

See also: oyjlTreeGetValueF()

Examples:: tutorial_json_options.c.

Referenced by oyjlArgsWebGroupIsMan_(), oyjlTreeClearValue(), oyjlTreeGetNewValueFromArray(), oyjlTreeGetPath(), oyjlTreeGetValueF(), oyjlTreeSetDoubleF(), oyjlTreeSetIntF(), oyjlUi_s::oyjlUiExportToCode(), and oyjlUiJsonSetDefaults().

◆ oyjlTreeGetValueF()

oyjl_val oyjlTreeGetValueF	(	oyjl_val	v,
		int	flags,
		const char *	xformat,
			...
	)

get a child node by a path expression

Function oyjlTreeGetValueF 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 = oyjlTreeGetValueF( 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 = oyjlTreeGetValueF( root, OYJL_CREATE_NEW, "foo/[]/bar" );

Parameters

[in]	v	the oyjl node
[in]	flags	OYJL_CREATE_NEW - returns nodes even if they did not yet exist
[in]	xformat	the format for the slashed xpath 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_CREATE_VA_STRING, and oyjlTreeGetValue().

Referenced by oyjlOptionStringToJson(), and oyjlTreeGetNewValueFromArray().

◆ oyjlTreeNew()

oyjl_val oyjlTreeNew ( const char * path )

create a node by a path expression

A NULL argument allocates just a node of type oyjl_t_null.

See also: oyjlTreeGetValueF()

Examples:: tutorial_json_options.c.

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

◆ oyjlTreeParse()

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

Parse a string. (libOyjl)

Parses an null-terminated string containing JSON data and returns a pointer to the top-level value (root of the parse tree).

This function needs linking to libOyjl.

See also: oyjlTreeToJson()

Parameters

input	Pointer to a null-terminated utf8 string containing JSON data.
error_buffer	Pointer to a buffer in which an error message will be stored if oyjlTreeParse() fails, or `NULL`. The buffer will be initialized before parsing, so its content will be destroyed even if oyjlTreeParse() succeeds.
error_buffer_size	Size of the memory area pointed to by error_buffer_size. If error_buffer_size is `NULL`, this argument is ignored.

Returns: Pointer to the top-level value or NULL on error. The memory pointed to must be freed using oyjlTreeFree(). In case of an error, a null terminated message describing the error in more detail is stored in error_buffer if it is not NULL.

◆ oyjlTreeParse2()

oyjl_val oyjlTreeParse2	(	const char *	text,
		int	flags,
		const char *	error_name,
		int *	status
	)

read a JSON, XML or YAML text string into a C data structure (libOyjl)

This function needs linking to libOyjl.

JSON, Xml and Yaml parsers can not handle term color codes in the data structures. They need to be removed before parsing.

const char * data_text = "{ \"key\": true }";
int status = 0;
oyjl_val root = oyjlTreeParse2( data_text, OYJL_NO_MARKUP, __func__, &status );
if(state)
  fprintf( stderr, "%s() found issue: %s\n", __func__, oyjlPARSE_STATE_eToString(status) );

See also: oyjlTreeParse() oyjlTreeParseXml oyjlTreeParseYaml() oyjlTreeToText() oyjlDataFormat()

Parameters

[in]	text	the JSON/XML/YAML text
[in]	flags	for processing OYJL_NUMBER_DETECTION for parsing of values as possibly numbers OYJL_QUIET for error reporting as oyjlMSG_INFO OYJL_NO_MARKUP omit remove of term color codes; deactivates oyjlTermColorToPlain( flags ) OYJL_REGEXP for oyjlTermColorToPlain()
[in]	error_name	add text for error messages
[out]	state	report oyjlPARSE_STATE_e

Returns: object tree on success, else check error_buffer

Examples:: tutorial_json_options.c.

◆ oyjlTreeParseCsv()

oyjl_val oyjlTreeParseCsv	(	const char *	text,
		const char *	delimiter,
		int	flags,
		char *error_buffer	OYJL_UNUSED,
		size_t error_buffer_size	OYJL_UNUSED
	)

read a CSV text string into a C data structure (libOyjl)

Expected is a 2D table on input.

See also: oyjlTreeToCsv()

Parameters

[in]	text	the CSV text
[in]	delimiter	separator for oyjlStringSplit2
[in]	flags	for processing OYJL_NUMBER_DETECTION for parsing of values as possibly numbers
[out]	error_buffer	place a error message
[out]	error_buffer_size	size of error_buffer

Returns: object tree on success, else check error_buffer

◆ oyjlTreeSerialise()

oyjl_val oyjlTreeSerialise	(	oyjl_val	v,
		int	flags,
		int *	size
	)

write tree to data block

Parameters

	v	tree to serialise
[in]	flags	supported: OYJL_OBSERVE : to print verbose info message
[out]	size	the size of the returned data block

Returns: serialised tree

See also: oyjlTreeDeSerialise()

Version: Oyjl: 1.0.0

Date: 2021/11/01

Since: 2021/09/16 (Oyjl: 1.0.0)

◆ oyjlTreeSetDoubleF()

int oyjlTreeSetDoubleF	(	oyjl_val	root,
		int	flags,
		double	value,
		const char *	xformat,
			...
	)

set a child node to a string value

Function oyjlTreeSetDoubleF

Parameters

[in,out]	root	the oyjl node
[in]	flags	OYJL_CREATE_NEW - allocates nodes even if they did not yet exist
[in]	value	IEEE floating point number with double precission
[in]	xformat	the format for the slashed xpath string
[in]	...	the variable argument list; optional

Returns

error

-1 - if not found
0 on success
else error

Version: Oyranos: 0.9.7

Date: 2019/01/26

Since: 2019/01/26 (Oyranos: 0.9.7)

References OYJL_CREATE_VA_STRING, oyjlTreeGetValue(), and oyjlValueSetDouble().

◆ oyjlTreeSetIntF()

int oyjlTreeSetIntF	(	oyjl_val	root,
		int	flags,
		long long	value,
		const char *	xformat,
			...
	)

set a child node to a string value

Function oyjlTreeSetIntF

Parameters

[in,out]	root	the oyjl node
[in]	flags	OYJL_CREATE_NEW - allocates nodes even if they did not yet exist
[in]	value	integer number
[in]	xformat	the format for the slashed xpath string
[in]	...	the variable argument list; optional

Returns

error

-1 - if not found
0 on success
else error

Version: Oyjl: 1.0.0

Date: 2021/12/20

Since: 2021/12/20 (Oyjl: 1.0.0)

References OYJL_CREATE_VA_STRING, oyjlTreeGetValue(), and oyjlValueSetInt().

◆ oyjlTreeSetStringF()

int oyjlTreeSetStringF	(	oyjl_val	root,
		int	flags,
		const char *	value_text,
		const char *	xformat,
			...
	)

set a child node to a string value

Function oyjlTreeSetStringF

Parameters

[in,out]	root	the oyjl node
[in]	flags	OYJL_CREATE_NEW - allocates nodes even if they did not yet exist
[in]	value_text	a string
[in]	xformat	the format for the slashed xpath string
[in]	...	the variable argument list; optional

Returns

error

-1 - if not found
0 on success
else error

Version: Oyranos: 0.9.7

Date: 2019/01/10

Since: 2019/01/10 (Oyranos: 0.9.7)

References OYJL_CREATE_VA_STRING.

◆ oyjlTreeToCsv()

void oyjlTreeToCsv	(	oyjl_val	table,
		int	flags,
		char **	text
	)

convert a C 2D table into a CSV string

The function uses some assumptions for mapping features of JSON to CSV.

The root object is assumed to be a array of arrays of plain values. Further levels of nesting are ignored.

See also: oyjlTreeParseCsv()

Parameters

table	node of 2D array [[],[]]
flags	OYJL_DELIMITER_COMMA, OYJL_DELIMITER_SEMICOLON, OYJL_HTML for HTML markup
text	the resulting string

Version: Oyjl: 1.0.0

Date: 2023/02/21

Since: 2022/12/31 (Oyjl: 1.0)

References oyjl_val_s::array, oyjl_val_s::number, oyjl_val_s::object, OYJL_DELIMITER_SEMICOLON, OYJL_NO_MARKUP, oyjl_t_array, oyjl_t_null, oyjl_t_number, oyjl_t_object, oyjlStr_Add(), oyjlStr_AppendN(), oyjlStr_New(), oyjlValueCount(), oyjl_val_s::type, and oyjl_val_s::u.

Referenced by oyjlTreeToText().

◆ oyjlTreeToJson()

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

convert a C tree into a JSON string

See also: oyjlTreeParse()

References oyjlStr_New().

Referenced by oyjlTreeToText().

◆ oyjlTreeToPaths()

char ** oyjlTreeToPaths	(	oyjl_val	root,
		int	levels,
		const char *	xpath,
		int	flags,
		int *	count
	)

find matching paths

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

Parameters

[in]	root	node
	levels	desired level depth
	xpath	extented path expression; It accepts even empty terms.
	flags	support filters: OYJL_KEY: only keys OYJL_PATH: only paths 0 for both, paths and keys OYJL_OBSERVE: verbose info OYJL_NO_ALLOC: alloc only array and not strings for oyjlOBJECT_JSON
[out]	count	number of strings in returned list

Returns: the resulting string list

Version: Oyjl: 1.0.0

Date: 2021/10/21

Since: 2017/11/10 (Oyranos: 0.9.7)

References oyjlOBJECT_JSON, oyjlStringSplit(), and oyjl_val_s::type.

Referenced by oyjlTreeGetPath(), and oyjlUiJsonSetDefaults().

◆ oyjlTreeToText()

char * oyjlTreeToText	(	oyjl_val	v,
		int	flags
	)

convert a C tree into a text string

Parameters

[in]	v	input
[in]	flags	support OYJL_JSON for JSON OYJL_XML for Xml OYJL_YAML for Yaml OYJL_CSV for CSV OYJL_CSV_SEMICOLON for CSV-semicolon OYJL_NO_MARKUP remove term color codes; activates oyjlTermColorToPlain( flags ) OYJL_REGEXP for oyjlTermColorToPlain()

Returns: structured data text, which is possibly formatted with term color

See also: oyjlTreeToJson() oyjlTreeToYaml() oyjlTreeToXml()

Version: Oyjl: 1.0.0

Date: 2022/06/04

Since: 2022/04/03 (Oyjl: 1.0.0)

Examples:: tutorial_json_options.c.

References OYJL_CSV, OYJL_CSV_SEMICOLON, OYJL_NO_MARKUP, OYJL_XML, OYJL_YAML, oyjlTreeToCsv(), oyjlTreeToJson(), oyjlTreeToXml(), and oyjlTreeToYaml().

◆ oyjlTreeToXml()

void oyjlTreeToXml	(	oyjl_val	v,
		int *	level,
		char **	text
	)

convert a C tree into a XML string

The function uses some assumptions for mapping features of JSON to XML.

The JSON tree shall consist of one root object. Object keys starting with '@' are mapped to a attribute of the parent key. A object key of "@text" is mapped to the inner XML content of the parent tree object.

See also: oyjlTreeParseXml()

Parameters

v	node
level	desired level depth
text	the resulting string

Version: Oyranos: 0.9.7

Date: 2019/06/14

Since: 2019/01/01 (Oyranos: 0.9.7)

References oyjl_t_array, oyjl_t_false, oyjl_t_null, oyjl_t_number, oyjl_t_string, oyjl_t_true, oyjlStringAdd(), and oyjl_val_s::type.

Referenced by oyjlTreeToText().

◆ oyjlTreeToYaml()

void oyjlTreeToYaml	(	oyjl_val	v,
		int *	level,
		char **	text
	)

convert a C tree into a YAML string

See also: oyjlTreeParseYaml()

Parameters

v	node
level	desired level depth
text	the resulting string

Version: Oyranos: 0.9.7

Date: 2019/01/01

Since: 2019/01/01 (Oyranos: 0.9.7)

References oyjl_val_s::array, oyjl_val_s::number, oyjl_t_array, oyjl_t_false, oyjl_t_null, oyjl_t_number, oyjl_t_string, oyjl_t_true, oyjlBLUE, oyjlBOLD, oyjlGREEN, oyjlRED, oyjlStringAdd(), oyjlStringCopy(), oyjlStringReplace(), oyjlTermColor(), oyjl_val_s::string, oyjl_val_s::type, and oyjl_val_s::u.

Referenced by oyjlTreeToText().

◆ oyjlValueClear()

void oyjlValueClear ( oyjl_val v )

release all childs recursively

Referenced by oyjlTreeClearValue(), oyjlTreeFree(), oyjlValueSetDouble(), oyjlValueSetInt(), and oyjlValueSetString().

◆ oyjlValueCopy()

void oyjlValueCopy	(	oyjl_val	v,
		oyjl_val	src
	)

copy only one level of allocation

◆ oyjlValueCount()

int oyjlValueCount ( 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.

References oyjl_val_s::array, oyjl_val_s::object, oyjl_t_array, oyjl_t_object, oyjl_val_s::type, and oyjl_val_s::u.

Referenced by oyjlOptionStringToJson(), oyjlTreeGetNewValueFromArray(), oyjlTreeToCsv(), and oyjlUiJsonSetDefaults().

◆ oyjlValuePosGet()

oyjl_val oyjlValuePosGet	(	oyjl_val	v,
		int	pos
	)

obtain a child node at the nth position from a object or array node

References oyjl_val_s::array, oyjl_val_s::object, oyjl_t_array, oyjl_t_object, oyjl_val_s::type, and oyjl_val_s::u.

◆ oyjlValueSetDouble()

int oyjlValueSetDouble	(	oyjl_val	v,
		double	value
	)

set a child node to a string value

Function oyjlValueSetDouble

Parameters

[in,out]	v	the oyjl node
[in]	value	IEEE floating point number with double precission

Returns

error

-1 - if not found
0 on success
else error

Version: Oyjl: 1.0.0

Date: 2020/10/12

Since: 2020/10/12 (Oyjl: 1.0.0)

References oyjl_val_s::number, oyjl_t_number, oyjlStringAdd(), oyjlStringCopy(), oyjlValueClear(), oyjl_val_s::type, and oyjl_val_s::u.

Referenced by oyjlTreeSetDoubleF().

◆ oyjlValueSetInt()

int oyjlValueSetInt	(	oyjl_val	v,
		long long	value
	)

set a child node to a number value

Function oyjlValueSetInt

Parameters

[in,out]	v	the oyjl node
[in]	value	integer number

Returns

error

-1 - if not found
0 on success
else error

Version: Oyjl: 1.0.0

Date: 2021/12/20

Since: 2021/12/20 (Oyjl: 1.0.0)

References oyjl_val_s::number, oyjl_t_number, oyjlStringAdd(), oyjlValueClear(), oyjl_val_s::type, and oyjl_val_s::u.

Referenced by oyjlTreeSetIntF().

◆ oyjlValueSetString()

int oyjlValueSetString	(	oyjl_val	v,
		const char *	string
	)

set the node value to a string

Examples:: tutorial_json_options.c.

References oyjl_t_string, oyjlStringAdd(), oyjlValueClear(), oyjl_val_s::string, oyjl_val_s::type, and oyjl_val_s::u.

Referenced by oyjlOptionStringToJson(), and oyjlTreeGetNewValueFromArray().

◆ oyjlValueText()

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

get the value as text string with user allocator

References oyjl_val_s::number, oyjl_t_array, oyjl_t_false, oyjl_t_null, oyjl_t_number, oyjl_t_object, oyjl_t_string, oyjl_t_true, oyjlStringAdd(), oyjl_val_s::string, oyjl_val_s::type, and oyjl_val_s::u.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OYJL_ALLOW_STATIC

◆ OYJL_CREATE_NEW

◆ OYJL_CSV

◆ OYJL_CSV_SEMICOLON

◆ OYJL_DECIMAL_SEPARATOR_COMMA

◆ OYJL_DELIMITER_COMMA

◆ OYJL_DELIMITER_SEMICOLON

◆ OYJL_HTML

◆ OYJL_JSON

◆ OYJL_KEY

◆ OYJL_NO_ALLOC

◆ OYJL_NO_MARKUP

◆ OYJL_NUMBER_DETECTION

◆ OYJL_OBSERVE

◆ OYJL_PATH

◆ OYJL_PATH_MATCH_LAST_ITEMS

◆ OYJL_PATH_MATCH_LEN

◆ OYJL_XML

◆ OYJL_YAML

Typedef Documentation

◆ oyjl_val

◆ oyjl_val_s

Enumeration Type Documentation

◆ oyjl_type

◆ oyjlPARSE_STATE_e

Function Documentation

◆ oyjlDataFormat()

◆ oyjlDataFormatToString()

◆ oyjlJsonEscape()

◆ oyjlPathMatch()

◆ oyjlTreeClearValue()

◆ oyjlTreeDeSerialise()

◆ oyjlTreeFree()

◆ oyjlTreeGetNewValueFromArray()

◆ oyjlTreeGetPath()

◆ oyjlTreeGetValue()

◆ oyjlTreeGetValueF()

◆ oyjlTreeNew()

◆ oyjlTreeParse()

◆ oyjlTreeParse2()

◆ oyjlTreeParseCsv()

◆ oyjlTreeSerialise()

◆ oyjlTreeSetDoubleF()

◆ oyjlTreeSetIntF()

◆ oyjlTreeSetStringF()

◆ oyjlTreeToCsv()

◆ oyjlTreeToJson()

◆ oyjlTreeToPaths()

◆ oyjlTreeToText()

◆ oyjlTreeToXml()

◆ oyjlTreeToYaml()

◆ oyjlValueClear()

◆ oyjlValueCopy()

◆ oyjlValueCount()

◆ oyjlValuePosGet()

◆ oyjlValueSetDouble()

◆ oyjlValueSetInt()

◆ oyjlValueSetString()

◆ oyjlValueText()