api.md revision 279549
1263648Sbapt# API documentation 2262395Sbapt 3263648Sbapt**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* 4263648Sbapt 5263648Sbapt- [Synopsis](#synopsis) 6263648Sbapt- [Description](#description) 7263648Sbapt - [Parser functions](#parser-functions) 8263648Sbapt - [Emitting functions](#emitting-functions) 9263648Sbapt - [Conversion functions](#conversion-functions) 10263648Sbapt - [Generation functions](#generation-functions) 11263648Sbapt - [Iteration functions](#iteration-functions) 12263648Sbapt - [Validation functions](#validation-functions) 13263648Sbapt - [Utility functions](#utility-functions) 14263648Sbapt- [Parser functions](#parser-functions-1) 15263648Sbapt - [ucl_parser_new](#ucl_parser_new) 16263648Sbapt - [ucl_parser_register_macro](#ucl_parser_register_macro) 17263648Sbapt - [ucl_parser_register_variable](#ucl_parser_register_variable) 18263648Sbapt - [ucl_parser_add_chunk](#ucl_parser_add_chunk) 19263648Sbapt - [ucl_parser_add_string](#ucl_parser_add_string) 20263648Sbapt - [ucl_parser_add_file](#ucl_parser_add_file) 21263648Sbapt - [ucl_parser_get_object](#ucl_parser_get_object) 22263648Sbapt - [ucl_parser_get_error](#ucl_parser_get_error) 23263648Sbapt - [ucl_parser_free](#ucl_parser_free) 24263648Sbapt - [ucl_pubkey_add](#ucl_pubkey_add) 25263648Sbapt - [ucl_parser_set_filevars](#ucl_parser_set_filevars) 26263648Sbapt - [Parser usage example](#parser-usage-example) 27263648Sbapt- [Emitting functions](#emitting-functions-1) 28263648Sbapt - [ucl_object_emit](#ucl_object_emit) 29263648Sbapt - [ucl_object_emit_full](#ucl_object_emit_full) 30263648Sbapt- [Conversion functions](#conversion-functions-1) 31263648Sbapt- [Generation functions](#generation-functions-1) 32263648Sbapt - [ucl_object_new](#ucl_object_new) 33263648Sbapt - [ucl_object_typed_new](#ucl_object_typed_new) 34263648Sbapt - [Primitive objects generation](#primitive-objects-generation) 35263648Sbapt - [ucl_object_fromstring_common](#ucl_object_fromstring_common) 36263648Sbapt- [Iteration functions](#iteration-functions-1) 37263648Sbapt - [ucl_iterate_object](#ucl_iterate_object) 38263648Sbapt- [Validation functions](#validation-functions-1) 39263648Sbapt - [ucl_object_validate](#ucl_object_validate) 40263648Sbapt 41263648Sbapt# Synopsis 42263648Sbapt 43262395Sbapt`#include <ucl.h>` 44262395Sbapt 45263648Sbapt# Description 46262395Sbapt 47262395SbaptLibucl is a parser and `C` API to parse and generate `ucl` objects. Libucl consist of several groups of functions: 48262395Sbapt 49262395Sbapt### Parser functions 50263648SbaptUsed 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. 51262395Sbapt 52262395Sbapt### Emitting functions 53263648SbaptConvert `ucl` objects to some textual or binary representation. Currently, libucl supports the following exports: 54262395Sbapt 55268831Sbapt- `JSON` - valid json format (can possibly lose some original data, such as implicit arrays) 56268831Sbapt- `Config` - human-readable configuration format (lossless) 57263648Sbapt- `YAML` - embedded yaml format (has the same limitations as `json` output) 58263648Sbapt 59262395Sbapt### Conversion functions 60263648SbaptHelp 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. 61262395Sbapt 62262395Sbapt### Generation functions 63268831SbaptAllow 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. 64262395Sbapt 65262395Sbapt### Iteration functions 66263648SbaptIterate 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). 67262395Sbapt 68263648Sbapt### Validation functions 69263648SbaptValidation 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. 70263648Sbapt 71262395Sbapt### Utility functions 72263648SbaptProvide basic utilities to manage `ucl` objects: creating, removing, retaining and releasing reference count and so on. 73262395Sbapt 74262395Sbapt# Parser functions 75262395Sbapt 76262395SbaptParser functions operates with `struct ucl_parser`. 77262395Sbapt 78262395Sbapt### ucl_parser_new 79262395Sbapt 80262395Sbapt~~~C 81262395Sbaptstruct ucl_parser* ucl_parser_new (int flags); 82262395Sbapt~~~ 83262395Sbapt 84262395SbaptCreates new parser with the specified flags: 85262395Sbapt 86262395Sbapt- `UCL_PARSER_KEY_LOWERCASE` - lowercase keys parsed 87262395Sbapt- `UCL_PARSER_ZEROCOPY` - try to use zero-copy mode when reading files (in zero-copy mode text chunk being parsed without copying strings so it should exist till any object parsed is used) 88263648Sbapt- `UCL_PARSER_NO_TIME` - treat time values as strings without parsing them as floats 89262395Sbapt 90262395Sbapt### ucl_parser_register_macro 91262395Sbapt 92262395Sbapt~~~C 93262395Sbaptvoid ucl_parser_register_macro (struct ucl_parser *parser, 94262395Sbapt const char *macro, ucl_macro_handler handler, void* ud); 95262395Sbapt~~~ 96262395Sbapt 97262395SbaptRegister new macro with name .`macro` parsed by handler `handler` that accepts opaque data pointer `ud`. Macro handler should be of the following type: 98262395Sbapt 99262395Sbapt~~~C 100262395Sbaptbool (*ucl_macro_handler) (const unsigned char *data, 101262395Sbapt size_t len, void* ud);` 102262395Sbapt~~~ 103262395Sbapt 104262395SbaptHandler function accepts macro text `data` of length `len` and the opaque pointer `ud`. If macro is parsed successfully the handler should return `true`. `false` indicates parsing failure and the parser can be terminated. 105262395Sbapt 106262395Sbapt### ucl_parser_register_variable 107262395Sbapt 108262395Sbapt~~~C 109262395Sbaptvoid ucl_parser_register_variable (struct ucl_parser *parser, 110262395Sbapt const char *var, const char *value); 111262395Sbapt~~~ 112262395Sbapt 113262395SbaptRegister new variable $`var` that should be replaced by the parser to the `value` string. 114262395Sbapt 115262395Sbapt### ucl_parser_add_chunk 116262395Sbapt 117262395Sbapt~~~C 118262395Sbaptbool ucl_parser_add_chunk (struct ucl_parser *parser, 119262395Sbapt const unsigned char *data, size_t len); 120262395Sbapt~~~ 121262395Sbapt 122262395SbaptAdd new text chunk with `data` of length `len` to the parser. At the moment, `libucl` parser is not a streamlined parser and chunk *must* contain the *valid* ucl object. For example, this object should be valid: 123262395Sbapt 124262395Sbapt~~~json 125262395Sbapt{ "var": "value" } 126262395Sbapt~~~ 127262395Sbapt 128262395Sbaptwhile this one won't be parsed correctly: 129262395Sbapt 130262395Sbapt~~~json 131262395Sbapt{ "var": 132262395Sbapt~~~ 133262395Sbapt 134262395SbaptThis limitation may possible be removed in future. 135262395Sbapt 136263648Sbapt### ucl_parser_add_string 137263648Sbapt~~~C 138263648Sbaptbool ucl_parser_add_string (struct ucl_parser *parser, 139263648Sbapt const char *data, size_t len); 140263648Sbapt~~~ 141263648Sbapt 142263648SbaptThis function acts exactly like `ucl_parser_add_chunk` does but if `len` argument is zero, then the string `data` must be zero-terminated and the actual length is calculated up to `\0` character. 143263648Sbapt 144262395Sbapt### ucl_parser_add_file 145262395Sbapt 146262395Sbapt~~~C 147262395Sbaptbool ucl_parser_add_file (struct ucl_parser *parser, 148262395Sbapt const char *filename); 149262395Sbapt~~~ 150262395Sbapt 151268831SbaptLoad file `filename` and parse it with the specified `parser`. This function uses `mmap` call to load file, therefore, it should not be `shrunk` during parsing. Otherwise, `libucl` can cause memory corruption and terminate the calling application. This function is also used by the internal handler of `include` macro, hence, this macro has the same limitation. 152262395Sbapt 153262395Sbapt### ucl_parser_get_object 154262395Sbapt 155262395Sbapt~~~C 156262395Sbaptucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); 157262395Sbapt~~~ 158262395Sbapt 159262395SbaptIf the `ucl` data has been parsed correctly this function returns the top object for the parser. Otherwise, this function returns the `NULL` pointer. The reference count for `ucl` object returned is increased by one, therefore, a caller should decrease reference by using `ucl_object_unref` to free object after usage. 160262395Sbapt 161262395Sbapt### ucl_parser_get_error 162262395Sbapt 163262395Sbapt~~~C 164262395Sbaptconst char *ucl_parser_get_error(struct ucl_parser *parser); 165262395Sbapt~~~ 166262395Sbapt 167262395SbaptReturns the constant error string for the parser object. If no error occurred during parsing a `NULL` object is returned. A caller should not try to free or modify this string. 168262395Sbapt 169262395Sbapt### ucl_parser_free 170262395Sbapt 171262395Sbapt~~~C 172262395Sbaptvoid ucl_parser_free (struct ucl_parser *parser); 173262395Sbapt~~~ 174262395Sbapt 175262395SbaptFrees memory occupied by the parser object. The reference count for top object is decreased as well, however if the function `ucl_parser_get_object` was called previously then the top object won't be freed. 176262395Sbapt 177262395Sbapt### ucl_pubkey_add 178262395Sbapt 179262395Sbapt~~~C 180262395Sbaptbool ucl_pubkey_add (struct ucl_parser *parser, 181262395Sbapt const unsigned char *key, size_t len); 182262395Sbapt~~~ 183262395Sbapt 184262395SbaptThis function adds a public key from text blob `key` of length `len` to the `parser` object. This public key should be in the `PEM` format and can be used by `.includes` macro for checking signatures of files included. `Openssl` support should be enabled to make this function working. If a key cannot be added (e.g. due to format error) or `openssl` was not linked to `libucl` then this function returns `false`. 185262395Sbapt 186262395Sbapt### ucl_parser_set_filevars 187262395Sbapt 188262395Sbapt~~~C 189262395Sbaptbool ucl_parser_set_filevars (struct ucl_parser *parser, 190262395Sbapt const char *filename, bool need_expand); 191262395Sbapt~~~ 192262395Sbapt 193262395SbaptAdd the standard file variables to the `parser` based on the `filename` specified: 194262395Sbapt 195262395Sbapt- `$FILENAME` - a filename of `ucl` input 196262395Sbapt- `$CURDIR` - a current directory of the input 197262395Sbapt 198262395SbaptFor example, if a `filename` param is `../something.conf` then the variables will have the following values: 199262395Sbapt 200262395Sbapt- `$FILENAME` - "../something.conf" 201262395Sbapt- `$CURDIR` - ".." 202262395Sbapt 203262395Sbaptif `need_expand` parameter is `true` then all relative paths are expanded using `realpath` call. In this example if `..` is `/etc/dir` then variables will have these values: 204262395Sbapt 205262395Sbapt- `$FILENAME` - "/etc/something.conf" 206262395Sbapt- `$CURDIR` - "/etc" 207262395Sbapt 208262395Sbapt## Parser usage example 209262395Sbapt 210262395SbaptThe following example loads, parses and extracts `ucl` object from stdin using `libucl` parser functions (the length of input is limited to 8K): 211262395Sbapt 212262395Sbapt~~~C 213262395Sbaptchar inbuf[8192]; 214262395Sbaptstruct ucl_parser *parser = NULL; 215262395Sbaptint ret = 0, r = 0; 216262395Sbaptucl_object_t *obj = NULL; 217262395SbaptFILE *in; 218262395Sbapt 219262395Sbaptin = stdin; 220262395Sbaptparser = ucl_parser_new (0); 221262395Sbaptwhile (!feof (in) && r < (int)sizeof (inbuf)) { 222262395Sbapt r += fread (inbuf + r, 1, sizeof (inbuf) - r, in); 223262395Sbapt} 224262395Sbaptucl_parser_add_chunk (parser, inbuf, r); 225262395Sbaptfclose (in); 226262395Sbapt 227262395Sbaptif (ucl_parser_get_error (parser)) { 228268831Sbapt printf ("Error occurred: %s\n", ucl_parser_get_error (parser)); 229262395Sbapt ret = 1; 230262395Sbapt} 231262395Sbaptelse { 232262395Sbapt obj = ucl_parser_get_object (parser); 233262395Sbapt} 234262395Sbapt 235262395Sbaptif (parser != NULL) { 236262395Sbapt ucl_parser_free (parser); 237262395Sbapt} 238262395Sbaptif (obj != NULL) { 239262395Sbapt ucl_object_unref (obj); 240262395Sbapt} 241262395Sbaptreturn ret; 242262395Sbapt~~~ 243262395Sbapt 244262395Sbapt# Emitting functions 245262395Sbapt 246262395SbaptLibucl can transform UCL objects to a number of tectual formats: 247262395Sbapt 248262395Sbapt- configuration (`UCL_EMIT_CONFIG`) - nginx like human readable configuration file where implicit arrays are transformed to the duplicate keys 249262395Sbapt- compact json: `UCL_EMIT_JSON_COMPACT` - single line valid json without spaces 250262395Sbapt- formatted json: `UCL_EMIT_JSON` - pretty formatted JSON with newlines and spaces 251262395Sbapt- compact yaml: `UCL_EMIT_YAML` - compact YAML output 252262395Sbapt 253262395SbaptMoreover, libucl API allows to select a custom set of emitting functions allowing 254268831Sbaptefficient and zero-copy output of libucl objects. Libucl uses the following structure to support this feature: 255262395Sbapt 256262395Sbapt~~~C 257262395Sbaptstruct ucl_emitter_functions { 258262395Sbapt /** Append a single character */ 259262395Sbapt int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud); 260262395Sbapt /** Append a string of a specified length */ 261262395Sbapt int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud); 262262395Sbapt /** Append a 64 bit integer */ 263262395Sbapt int (*ucl_emitter_append_int) (int64_t elt, void *ud); 264262395Sbapt /** Append floating point element */ 265262395Sbapt int (*ucl_emitter_append_double) (double elt, void *ud); 266262395Sbapt /** Opaque userdata pointer */ 267262395Sbapt void *ud; 268262395Sbapt}; 269262395Sbapt~~~ 270262395Sbapt 271262395SbaptThis structure defines the following callbacks: 272262395Sbapt 273262395Sbapt- `ucl_emitter_append_character` - a function that is called to append `nchars` characters equal to `c` 274262395Sbapt- `ucl_emitter_append_len` - used to append a string of length `len` starting from pointer `str` 275262395Sbapt- `ucl_emitter_append_int` - this function applies to integer numbers 276262395Sbapt- `ucl_emitter_append_double` - this function is intended to output floating point variable 277262395Sbapt 278262395SbaptThe set of these functions could be used to output text formats of `UCL` objects to different structures or streams. 279262395Sbapt 280262395SbaptLibucl provides the following functions for emitting UCL objects: 281262395Sbapt 282262395Sbapt### ucl_object_emit 283262395Sbapt 284262395Sbapt~~~C 285264789Sbaptunsigned char *ucl_object_emit (const ucl_object_t *obj, enum ucl_emitter emit_type); 286262395Sbapt~~~ 287262395Sbapt 288262395SbaptAllocate a string that is suitable to fit the underlying UCL object `obj` and fill it with the textual representation of the object `obj` according to style `emit_type`. The caller should free the returned string after using. 289262395Sbapt 290262395Sbapt### ucl_object_emit_full 291262395Sbapt 292262395Sbapt~~~C 293264789Sbaptbool ucl_object_emit_full (const ucl_object_t *obj, enum ucl_emitter emit_type, 294262395Sbapt struct ucl_emitter_functions *emitter); 295262395Sbapt~~~ 296262395Sbapt 297262395SbaptThis function is similar to the previous with the exception that it accepts the additional argument `emitter` that defines the concrete set of output functions. This emit function could be useful for custom structures or streams emitters (including C++ ones, for example). 298262395Sbapt 299262395Sbapt# Conversion functions 300262395Sbapt 301268831SbaptConversion functions are used to convert UCL objects to primitive types, such as strings, numbers, or boolean values. There are two types of conversion functions: 302262395Sbapt 303262395Sbapt- safe: try to convert an ucl object to a primitive type and fail if such a conversion is not possible 304262395Sbapt- 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) 305262395Sbapt 306268831SbaptAlso 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. 307262395Sbapt 308262395SbaptHere is a list of all conversion functions: 309262395Sbapt 310262395Sbapt- `ucl_object_toint` - returns `int64_t` of UCL object 311262395Sbapt- `ucl_object_todouble` - returns `double` of UCL object 312262395Sbapt- `ucl_object_toboolean` - returns `bool` of UCL object 313262395Sbapt- `ucl_object_tostring` - returns `const char *` of UCL object (this string is NULL terminated) 314268831Sbapt- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string does not need to be NULL terminated) 315262395Sbapt- `ucl_object_tostring_forced` - returns string representation of any UCL object 316262395Sbapt 317262975SbaptStrings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory. 318262975Sbapt 319262975Sbapt# Generation functions 320262975Sbapt 321268831SbaptIt 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. 322262975Sbapt 323262975Sbapt## ucl_object_new 324262975Sbapt~~~C 325262975Sbaptucl_object_t * ucl_object_new (void) 326262975Sbapt~~~ 327262975Sbapt 328262975SbaptCreates new object of type `UCL_NULL`. This object should be released by caller. 329262975Sbapt 330262975Sbapt## ucl_object_typed_new 331262975Sbapt~~~C 332262975Sbaptucl_object_t * ucl_object_typed_new (unsigned int type) 333262975Sbapt~~~ 334262975Sbapt 335262975SbaptCreate an object of a specified type: 336262975Sbapt- `UCL_OBJECT` - UCL object - key/value pairs 337262975Sbapt- `UCL_ARRAY` - UCL array 338262975Sbapt- `UCL_INT` - integer number 339262975Sbapt- `UCL_FLOAT` - floating point number 340262975Sbapt- `UCL_STRING` - NULL terminated string 341262975Sbapt- `UCL_BOOLEAN` - boolean value 342262975Sbapt- `UCL_TIME` - time value (floating point number of seconds) 343262975Sbapt- `UCL_USERDATA` - opaque userdata pointer (may be used in macros) 344262975Sbapt- `UCL_NULL` - null value 345262975Sbapt 346262975SbaptThis object should be released by caller. 347262975Sbapt 348262975Sbapt## Primitive objects generation 349262975SbaptLibucl provides the functions similar to inverse conversion functions called with the specific C type: 350262975Sbapt- `ucl_object_fromint` - converts `int64_t` to UCL object 351262975Sbapt- `ucl_object_fromdouble` - converts `double` to UCL object 352262975Sbapt- `ucl_object_fromboolean` - converts `bool` to UCL object 353268831Sbapt- `ucl_object_fromstring` - converts `const char *` to UCL object (this string should be NULL terminated) 354268831Sbapt- `ucl_object_fromlstring` - converts `const char *` and `size_t` len to UCL object (string does not need to be NULL terminated) 355262975Sbapt 356262975SbaptAlso there is a function to generate UCL object from a string performing various parsing or conversion operations called `ucl_object_fromstring_common`. 357262975Sbapt 358262975Sbapt## ucl_object_fromstring_common 359262975Sbapt~~~C 360262975Sbaptucl_object_t * ucl_object_fromstring_common (const char *str, 361262975Sbapt size_t len, enum ucl_string_flags flags) 362262975Sbapt~~~ 363262975Sbapt 364268831SbaptThis 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 specified using logical `OR` operation): 365262975Sbapt 366262975Sbapt- `UCL_STRING_ESCAPE` - perform JSON escape 367262975Sbapt- `UCL_STRING_TRIM` - trim leading and trailing whitespaces 368262975Sbapt- `UCL_STRING_PARSE_BOOLEAN` - parse passed string and detect boolean 369262975Sbapt- `UCL_STRING_PARSE_INT` - parse passed string and detect integer number 370262975Sbapt- `UCL_STRING_PARSE_DOUBLE` - parse passed string and detect integer or float number 371263648Sbapt- `UCL_STRING_PARSE_TIME` - parse time values as floating point numbers 372263648Sbapt- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float, integer and time types) 373263648Sbapt- `UCL_STRING_PARSE` - parse passed string (and detect booleans, numbers and time values) 374262975Sbapt- `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 375262975Sbapt 376262975SbaptIf 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. 377262975Sbapt 378263648Sbapt# Iteration functions 379262975Sbapt 380279549SbaptIteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). 381279549SbaptThere are two types of iterators API: old and unsafe one via `ucl_iterate_object` and the proposed interface of safe iterators. 382262975Sbapt 383279549Sbapt 384262975Sbapt## ucl_iterate_object 385262975Sbapt~~~C 386264789Sbaptconst ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, 387262975Sbapt ucl_object_iter_t *iter, bool expand_values); 388262975Sbapt~~~ 389262975Sbapt 390268831SbaptThis 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` if all objects have been iterated. The reference count of the object returned is not increased, so a caller should not unref the object or modify its content (e.g. by inserting to another compound object). The object `obj` should not be changed during the iteration process as well. `expand_values` flag speicifies whether `ucl_iterate_object` should expand keys with multiple values. The general rule is that if you need to iterate through the *object* or *explicit array*, then you always need to set this flag to `true`. However, if you get some key in the object and want to extract all its values then you should set `expand_values` to `false`. Mixing of iteration types is not permitted since the iterator is set according to the iteration type and cannot be reused. Here is an example of iteration over the objects using libucl API (assuming that `top` is `UCL_OBJECT` in this example): 391262975Sbapt 392262975Sbapt~~~C 393262975Sbaptucl_object_iter_t it = NULL, it_obj = NULL; 394264789Sbaptconst ucl_object_t *cur, *tmp; 395262975Sbapt 396262975Sbapt/* Iterate over the object */ 397262975Sbaptwhile ((obj = ucl_iterate_object (top, &it, true))) { 398262975Sbapt printf ("key: \"%s\"\n", ucl_object_key (obj)); 399262975Sbapt /* Iterate over the values of a key */ 400262975Sbapt while ((cur = ucl_iterate_object (obj, &it_obj, false))) { 401262975Sbapt printf ("value: \"%s\"\n", 402262975Sbapt ucl_object_tostring_forced (cur)); 403262975Sbapt } 404262975Sbapt} 405263648Sbapt~~~ 406263648Sbapt 407279549Sbapt## Safe iterators API 408279549Sbapt 409279549SbaptSafe iterators are defined to clarify iterating over UCL objects and simplify flattening of UCL objects in non-trivial cases. 410279549SbaptFor example, if there is an implicit array that contains another array and a boolean value it is extremely unclear how to iterate over 411279549Sbaptsuch an object. Safe iterators are desinged to define two sorts of iteration: 412279549Sbapt 413279549Sbapt1. Iteration over complex objects with expanding all values 414279549Sbapt2. Iteration over complex objects without expanding of values 415279549Sbapt 416279549SbaptThe following example demonstrates the difference between these two types of iteration: 417279549Sbapt 418279549Sbapt~~~ 419279549Sbaptkey = 1; 420279549Sbaptkey = [2, 3, 4]; 421279549Sbapt 422279549SbaptIteration with expansion: 423279549Sbapt 424279549Sbapt1, 2, 3, 4 425279549Sbapt 426279549SbaptIteration without expansion: 427279549Sbapt 428279549Sbapt1, [2, 3, 4] 429279549Sbapt~~~ 430279549Sbapt 431279549SbaptUCL defines the following functions to manage safe iterators: 432279549Sbapt 433279549Sbapt- `ucl_object_iterate_new` - creates new safe iterator 434279549Sbapt- `ucl_object_iterate_reset` - resets iterator to a new object 435279549Sbapt- `ucl_object_iterate_safe` - safely iterate the object inside iterator 436279549Sbapt- `ucl_object_iterate_free` - free memory associated with the safe iterator 437279549Sbapt 438279549SbaptPlease note that unlike unsafe iterators, safe iterators *must* be explicitly initialized and freed. 439279549SbaptAn assert is likely generated if you use uninitialized or `NULL` iterator in all safe iterators functions. 440279549Sbapt 441279549Sbapt~~~C 442279549Sbaptucl_object_iter_t it; 443279549Sbaptconst ucl_object_t *cur; 444279549Sbapt 445279549Sbaptit = ucl_object_iterate_new (obj); 446279549Sbapt 447279549Sbaptwhile ((cur = ucl_object_iterate_safe (it, true)) != NULL) { 448279549Sbapt /* Do something */ 449279549Sbapt} 450279549Sbapt 451279549Sbapt/* Switch to another object */ 452279549Sbaptit = ucl_object_iterate_reset (it, another_obj); 453279549Sbapt 454279549Sbaptwhile ((cur = ucl_object_iterate_safe (it, true)) != NULL) { 455279549Sbapt /* Do something else */ 456279549Sbapt} 457279549Sbapt 458279549Sbaptucl_object_iterate_free (it); 459279549Sbapt~~~ 460279549Sbapt 461263648Sbapt# Validation functions 462263648Sbapt 463263648SbaptCurrently, 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: 464263648Sbapt 465263648Sbapt## ucl_object_validate 466263648Sbapt~~~C 467264789Sbaptbool ucl_object_validate (const ucl_object_t *schema, 468264789Sbapt const ucl_object_t *obj, struct ucl_schema_error *err); 469263648Sbapt~~~ 470263648Sbapt 471268831SbaptThis function uses ucl object `schema`, that must be valid in terms of `json-schema` draft v4, to validate input object `obj`. If this function returns `true` then validation procedure has been succeed. Otherwise, `false` is returned and `err` is set to a specific value. If a caller sets `err` to NULL then this function does not set any error just returning `false`. Error is the structure defined as following: 472263648Sbapt 473263648Sbapt~~~C 474263648Sbaptstruct ucl_schema_error { 475263648Sbapt enum ucl_schema_error_code code; /* error code */ 476263648Sbapt char msg[128]; /* error message */ 477268831Sbapt ucl_object_t *obj; /* object where error occurred */ 478263648Sbapt}; 479263648Sbapt~~~ 480263648Sbapt 481263648SbaptCaller may use `code` field to get a numeric error code: 482263648Sbapt 483263648Sbapt~~~C 484263648Sbaptenum ucl_schema_error_code { 485263648Sbapt UCL_SCHEMA_OK = 0, /* no error */ 486263648Sbapt UCL_SCHEMA_TYPE_MISMATCH, /* type of object is incorrect */ 487263648Sbapt UCL_SCHEMA_INVALID_SCHEMA, /* schema is invalid */ 488263648Sbapt UCL_SCHEMA_MISSING_PROPERTY,/* missing properties */ 489263648Sbapt UCL_SCHEMA_CONSTRAINT, /* constraint found */ 490263648Sbapt UCL_SCHEMA_MISSING_DEPENDENCY, /* missing dependency */ 491263648Sbapt UCL_SCHEMA_UNKNOWN /* generic error */ 492263648Sbapt}; 493263648Sbapt~~~ 494263648Sbapt 495268831Sbapt`msg` is a string description of an error and `obj` is an object where error has occurred. Error object is not allocated by libucl, so there is no need to free it after validation (a static object should thus be used). 496