Manual Pages  — LIBUCL

ucl_parser_new], ucl_parser_register_macro], ucl_parser_register_variable], ucl_parser_add_chunk], ucl_parser_add_string], ucl_parser_add_file], ucl_parser_get_object], ucl_parser_get_error], ucl_parser_free], ucl_pubkey_add], ucl_parser_set_filevars] - universal configuration library parser and utility functions

UCL library (libucl, -lucl)

#include <ucl.h>]

Libucl is a parser and C] API to parse and generate ucl] objects. Libucl consist of several groups of functions:

Used to parse ucl] files and provide interface to extract ucl] object. Currently, libucl] can parse only full ucl] documents, for instance, it is impossible to parse a part of document and therefore it is impossible to use libucl] as a streaming parser. In future, this limitation can be removed.

Convert ucl] objects to some textual or binary representation. Currently, libucl supports the following exports:

[bu]	JSON] - valid json format (can possibly lose some original data, such as implicit arrays)
[bu]	Config] - human-readable configuration format (lossless)
[bu]	YAML] - embedded yaml format (has the same limitations as json] output)

Help to convert ucl] objects to C types. These functions are used to convert ucl_object_t] to C primitive types, such as numbers, strings or boolean values.

Allow creation of ucl] objects from C types and creating of complex ucl] objects, such as hashes or arrays from primitive ucl] objects, such as numbers or strings.

Iterate over ucl] complex objects or over a chain of values, for example when a key in an object has multiple values (that can be treated as implicit array or implicit consolidation).

Validation functions are used to validate some object obj] using json-schema compatible object schema]. Both input and schema must be UCL objects to perform validation.

Provide basic utilities to manage ucl] objects: creating, removing, retaining and releasing reference count and so on.

Parser functions operates with struct ucl_parser].

The following example loads, parses and extracts ucl] object from stdin using libucl] parser functions (the length of input is limited to 8K):

char inbuf[8192]; struct ucl_parser *parser = NULL; int ret = 0, r = 0; ucl_object_t *obj = NULL; FILE *in; in = stdin; parser = ucl_parser_new (0); while (!feof (in) && r < (int)sizeof (inbuf)) { r += fread (inbuf + r, 1, sizeof (inbuf) - r, in); } ucl_parser_add_chunk (parser, inbuf, r); fclose (in); if (ucl_parser_get_error (parser)) { printf ("Error occurred: %s , ucl_parser_get_error (parser)); ret = 1; } else { obj = ucl_parser_get_object (parser); } if (parser != NULL) { ucl_parser_free (parser); } if (obj != NULL) { ucl_object_unref (obj); } return ret; ]

Libucl can transform UCL objects to a number of tectual formats:

[bu]	configuration (UCL_EMIT_CONFIG]) - nginx like human readable configuration file where implicit arrays are transformed to the duplicate keys
[bu]	compact json: UCL_EMIT_JSON_COMPACT] - single line valid json without spaces
[bu]	formatted json: UCL_EMIT_JSON] - pretty formatted JSON with newlines and spaces
[bu]	compact yaml: UCL_EMIT_YAML] - compact YAML output

Moreover, libucl API allows to select a custom set of emitting functions allowing efficient and zero-copy output of libucl objects. Libucl uses the following structure to support this feature:

	struct ucl_emitter_functions { /** Append a single character */ int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud); /** Append a string of a specified length */ int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud); /** Append a 64 bit integer */ int (*ucl_emitter_append_int) (int64_t elt, void *ud); /** Append floating point element */ int (*ucl_emitter_append_double) (double elt, void *ud); /** Opaque userdata pointer */ void *ud; }; ]
This structure defines the following callbacks:

[bu]	ucl_emitter_append_character] - a function that is called to append nchars] characters equal to c]
[bu]	ucl_emitter_append_len] - used to append a string of length len] starting from pointer str]
[bu]	ucl_emitter_append_int] - this function applies to integer numbers
[bu]	ucl_emitter_append_double] - this function is intended to output floating point variable

The set of these functions could be used to output text formats of UCL] objects to different structures or streams.

Libucl provides the following functions for emitting UCL objects:

Conversion functions are used to convert UCL objects to primitive types, such as strings, numbers, or boolean values. There are two types of conversion functions:

[bu]	safe: try to convert an ucl object to a primitive type and fail if such a conversion is not possible
[bu]	unsafe: return primitive type without additional checks, if the object cannot be converted then some reasonable default is returned (NULL for strings and 0 for numbers)

Also there is a single ucl_object_tostring_forced] function that converts any UCL object (including compound types - arrays and objects) to a string representation. For objects, arrays, booleans and numeric types this function performs emitting to a compact json format actually.

Here is a list of all conversion functions:

[bu]	ucl_object_toint] - returns int64_t] of UCL object
[bu]	ucl_object_todouble] - returns double] of UCL object
[bu]	ucl_object_toboolean] - returns bool] of UCL object
[bu]	ucl_object_tostring] - returns const char *] of UCL object (this string is NULL terminated)
[bu]	ucl_object_tolstring] - returns const char *] and size_t] len of UCL object (string does not need to be NULL terminated)
[bu]	ucl_object_tostring_forced] - returns string representation of any UCL object

Strings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory.

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_t * ucl_object_typed_new (unsigned int type)
]

This object should be released by caller.

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_fromboolean] - 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].

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.

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:

[bu]	ucl_object_iterate_new] - creates new safe iterator.
[bu]	ucl_object_iterate_reset] - resets iterator to a new object.
[bu]	ucl_object_iterate_safe] - safely iterate the object inside iterator. Note: function may allocate and free memory during its operation. Therefore it returns NULL] either while trying to access item after the last one or when exception (such as memory allocation failure) happens.
[bu]	ucl_object_iter_chk_excpn] - check if the last call to ucl_object_iterate_safe] ended up in unrecoverable exception (e.g. ENOMEM]).
[bu]	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.

ucl_object_iter_t it; const ucl_object_t *cur; it = ucl_object_iterate_new (obj); while ((cur = ucl_object_iterate_safe (it, true)) != NULL) { /* Do something */ } /* Check error condition */ if (ucl_object_iter_chk_excpn (it)) { ucl_object_iterate_free (it); exit (1); } /* Switch to another object */ it = ucl_object_iterate_reset (it, another_obj); while ((cur = ucl_object_iterate_safe (it, true)) != NULL) { /* Do something else */ } /* Check error condition */ if (ucl_object_iter_chk_excpn (it)) { ucl_object_iterate_free (it); exit (1); } ucl_object_iterate_free (it); ]

Currently, there is only one validation function called ucl_object_validate]. It performs validation of object using the specified schema. This function is defined as following: