view release on metacpan or  search on metacpan

libucl-0.8.1/doc/api.md  view on Meta::CPAN

It is possible to generate UCL objects from C primitive types. Moreover, libucl allows creation and modifying complex UCL objects, such as arrays or associative objects. 

## ucl_object_new
~~~C
ucl_object_t * ucl_object_new (void)
~~~

Creates new object of type `UCL_NULL`. This object should be released by caller.

## ucl_object_typed_new
~~~C
ucl_object_t * ucl_object_typed_new (unsigned int type)
~~~

Create an object of a specified type:
- `UCL_OBJECT` - UCL object - key/value pairs
- `UCL_ARRAY` - UCL array
- `UCL_INT` - integer number
- `UCL_FLOAT` - floating point number
- `UCL_STRING` - NULL terminated string
- `UCL_BOOLEAN` - boolean value
- `UCL_TIME` - time value (floating point number of seconds)
- `UCL_USERDATA` - opaque userdata pointer (may be used in macros)
- `UCL_NULL` - null value

This object should be released by caller.

## Primitive objects generation
Libucl provides the functions similar to inverse conversion functions called with the specific C type:
- `ucl_object_fromint` - converts `int64_t` to UCL object
- `ucl_object_fromdouble` - converts `double` to UCL object
- `ucl_object_frombool` - converts `bool` to UCL object
- `ucl_object_fromstring` - converts `const char *` to UCL object (this string should be NULL terminated)
- `ucl_object_fromlstring` - converts `const char *` and `size_t` len to UCL object (string does not need to be NULL terminated)

Also there is a function to generate UCL object from a string performing various parsing or conversion operations called `ucl_object_fromstring_common`.

## ucl_object_fromstring_common
~~~C
ucl_object_t * ucl_object_fromstring_common (const char *str, 
	size_t len, enum ucl_string_flags flags)
~~~

This function is used to convert a string `str` of size `len` to a UCL object applying `flags` conversions. If `len` is equal to zero then a `str` is assumed as NULL-terminated. This function supports the following flags (a set of flags can be specif...

- `UCL_STRING_ESCAPE` - perform JSON escape
- `UCL_STRING_TRIM` - trim leading and trailing whitespaces
- `UCL_STRING_PARSE_BOOLEAN` - parse passed string and detect boolean
- `UCL_STRING_PARSE_INT` - parse passed string and detect integer number
- `UCL_STRING_PARSE_DOUBLE` - parse passed string and detect integer or float number
- `UCL_STRING_PARSE_TIME` - parse time values as floating point numbers
- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float, integer and time types)
- `UCL_STRING_PARSE` - parse passed string (and detect booleans, numbers and time values)
- `UCL_STRING_PARSE_BYTES` - assume that numeric multipliers are in bytes notation, for example `10k` means `10*1024` and not `10*1000` as assumed without this flag

If parsing operations fail then the resulting UCL object will be a `UCL_STRING`. A caller should always check the type of the returned object and release it after using.

# Iteration functions

Iteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays).
There are two types of iterators API: old and unsafe one via `ucl_iterate_object` and the proposed interface of safe iterators.


## ucl_iterate_object
~~~C
const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, 
	ucl_object_iter_t *iter, bool expand_values);
~~~

This function accepts opaque iterator pointer `iter`. In the first call this iterator *must* be initialized to `NULL`. Iterator is changed by this function call. `ucl_iterate_object` returns the next UCL object in the compound object `obj` or `NULL` ...

~~~C
ucl_object_iter_t it = NULL, it_obj = NULL;
const ucl_object_t *cur, *tmp;

/* Iterate over the object */
while ((obj = ucl_iterate_object (top, &it, true))) {
	printf ("key: \"%s\"\n", ucl_object_key (obj));
	/* Iterate over the values of a key */
	while ((cur = ucl_iterate_object (obj, &it_obj, false))) {
		printf ("value: \"%s\"\n", 
			ucl_object_tostring_forced (cur));
	}
}
~~~

## Safe iterators API

Safe iterators are defined to clarify iterating over UCL objects and simplify flattening of UCL objects in non-trivial cases.
For example, if there is an implicit array that contains another array and a boolean value it is extremely unclear how to iterate over
such an object. Safe iterators are desinged to define two sorts of iteration:

1. Iteration over complex objects with expanding all values
2. Iteration over complex objects without expanding of values

The following example demonstrates the difference between these two types of iteration:

~~~
key = 1;
key = [2, 3, 4];

Iteration with expansion:

1, 2, 3, 4

Iteration without expansion:

1, [2, 3, 4]
~~~

UCL defines the following functions to manage safe iterators:

- `ucl_object_iterate_new` - creates new safe iterator
- `ucl_object_iterate_reset` - resets iterator to a new object
- `ucl_object_iterate_safe` - safely iterate the object inside iterator
- `ucl_object_iterate_free` - free memory associated with the safe iterator

Please note that unlike unsafe iterators, safe iterators *must* be explicitly initialized and freed.
An assert is likely generated if you use uninitialized or `NULL` iterator in all safe iterators functions.