1268896Sbapt# API documentation 2262395Sbapt 3268896Sbapt**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* 4268896Sbapt 5268896Sbapt- [Synopsis](#synopsis) 6268896Sbapt- [Description](#description) 7268896Sbapt - [Parser functions](#parser-functions) 8268896Sbapt - [Emitting functions](#emitting-functions) 9268896Sbapt - [Conversion functions](#conversion-functions) 10268896Sbapt - [Generation functions](#generation-functions) 11268896Sbapt - [Iteration functions](#iteration-functions) 12268896Sbapt - [Validation functions](#validation-functions) 13268896Sbapt - [Utility functions](#utility-functions) 14268896Sbapt- [Parser functions](#parser-functions-1) 15268896Sbapt - [ucl_parser_new](#ucl_parser_new) 16268896Sbapt - [ucl_parser_register_macro](#ucl_parser_register_macro) 17268896Sbapt - [ucl_parser_register_variable](#ucl_parser_register_variable) 18268896Sbapt - [ucl_parser_add_chunk](#ucl_parser_add_chunk) 19268896Sbapt - [ucl_parser_add_string](#ucl_parser_add_string) 20268896Sbapt - [ucl_parser_add_file](#ucl_parser_add_file) 21268896Sbapt - [ucl_parser_get_object](#ucl_parser_get_object) 22268896Sbapt - [ucl_parser_get_error](#ucl_parser_get_error) 23268896Sbapt - [ucl_parser_free](#ucl_parser_free) 24268896Sbapt - [ucl_pubkey_add](#ucl_pubkey_add) 25268896Sbapt - [ucl_parser_set_filevars](#ucl_parser_set_filevars) 26268896Sbapt - [Parser usage example](#parser-usage-example) 27268896Sbapt- [Emitting functions](#emitting-functions-1) 28268896Sbapt - [ucl_object_emit](#ucl_object_emit) 29268896Sbapt - [ucl_object_emit_full](#ucl_object_emit_full) 30268896Sbapt- [Conversion functions](#conversion-functions-1) 31268896Sbapt- [Generation functions](#generation-functions-1) 32268896Sbapt - [ucl_object_new](#ucl_object_new) 33268896Sbapt - [ucl_object_typed_new](#ucl_object_typed_new) 34268896Sbapt - [Primitive objects generation](#primitive-objects-generation) 35268896Sbapt - [ucl_object_fromstring_common](#ucl_object_fromstring_common) 36268896Sbapt- [Iteration functions](#iteration-functions-1) 37268896Sbapt - [ucl_iterate_object](#ucl_iterate_object) 38268896Sbapt- [Validation functions](#validation-functions-1) 39268896Sbapt - [ucl_object_validate](#ucl_object_validate) 40268896Sbapt 41268896Sbapt# Synopsis 42268896Sbapt 43262395Sbapt`#include <ucl.h>` 44262395Sbapt 45268896Sbapt# 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 50268896SbaptUsed 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 53268896SbaptConvert `ucl` objects to some textual or binary representation. Currently, libucl supports the following exports: 54262395Sbapt 55268896Sbapt- `JSON` - valid json format (can possibly loose some original data, such as implicit arrays) 56268896Sbapt- `Config` - human-readable configuration format (losseless) 57268896Sbapt- `YAML` - embedded yaml format (has the same limitations as `json` output) 58268896Sbapt 59262395Sbapt### Conversion functions 60268896SbaptHelp 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 63268896SbaptAllow creating 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 66268896SbaptIterate 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 68268896Sbapt### Validation functions 69268896SbaptValidation 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. 70268896Sbapt 71262395Sbapt### Utility functions 72268896SbaptProvide 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) 88268896Sbapt- `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 136268896Sbapt### ucl_parser_add_string 137268896Sbapt~~~C 138268896Sbaptbool ucl_parser_add_string (struct ucl_parser *parser, 139268896Sbapt const char *data, size_t len); 140268896Sbapt~~~ 141268896Sbapt 142268896SbaptThis 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. 143268896Sbapt 144262395Sbapt### ucl_parser_add_file 145262395Sbapt 146262395Sbapt~~~C 147262395Sbaptbool ucl_parser_add_file (struct ucl_parser *parser, 148262395Sbapt const char *filename); 149262395Sbapt~~~ 150262395Sbapt 151262395SbaptLoad file `filename` and parse it with the specified `parser`. This function uses `mmap` call to load file, therefore, it should not be `shrinked` 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)) { 228262395Sbapt printf ("Error occured: %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 254262395Sbaptefficent 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 285268896Sbaptunsigned 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 293268896Sbaptbool 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 301262395SbaptConversion 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 306262395SbaptAlso 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 compound 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) 314262395Sbapt- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string can be not NULL terminated) 315262395Sbapt- `ucl_object_tostring_forced` - returns string representation of any UCL object 316262395Sbapt 317263019SbaptStrings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory. 318263019Sbapt 319263019Sbapt# Generation functions 320263019Sbapt 321263019SbaptIt is possible to generate UCL objects from C primitive types. Moreover, libucl permits to create and modify complex UCL objects, such as arrays or associative objects. 322263019Sbapt 323263019Sbapt## ucl_object_new 324263019Sbapt~~~C 325263019Sbaptucl_object_t * ucl_object_new (void) 326263019Sbapt~~~ 327263019Sbapt 328263019SbaptCreates new object of type `UCL_NULL`. This object should be released by caller. 329263019Sbapt 330263019Sbapt## ucl_object_typed_new 331263019Sbapt~~~C 332263019Sbaptucl_object_t * ucl_object_typed_new (unsigned int type) 333263019Sbapt~~~ 334263019Sbapt 335263019SbaptCreate an object of a specified type: 336263019Sbapt- `UCL_OBJECT` - UCL object - key/value pairs 337263019Sbapt- `UCL_ARRAY` - UCL array 338263019Sbapt- `UCL_INT` - integer number 339263019Sbapt- `UCL_FLOAT` - floating point number 340263019Sbapt- `UCL_STRING` - NULL terminated string 341263019Sbapt- `UCL_BOOLEAN` - boolean value 342263019Sbapt- `UCL_TIME` - time value (floating point number of seconds) 343263019Sbapt- `UCL_USERDATA` - opaque userdata pointer (may be used in macros) 344263019Sbapt- `UCL_NULL` - null value 345263019Sbapt 346263019SbaptThis object should be released by caller. 347263019Sbapt 348263019Sbapt## Primitive objects generation 349263019SbaptLibucl provides the functions similar to inverse conversion functions called with the specific C type: 350263019Sbapt- `ucl_object_fromint` - converts `int64_t` to UCL object 351263019Sbapt- `ucl_object_fromdouble` - converts `double` to UCL object 352263019Sbapt- `ucl_object_fromboolean` - converts `bool` to UCL object 353263019Sbapt- `ucl_object_fromstring` - converts `const char *` to UCL object (this string is NULL terminated) 354263019Sbapt- `ucl_object_fromlstring` - converts `const char *` and `size_t` len to UCL object (string can be not NULL terminated) 355263019Sbapt 356263019SbaptAlso there is a function to generate UCL object from a string performing various parsing or conversion operations called `ucl_object_fromstring_common`. 357263019Sbapt 358263019Sbapt## ucl_object_fromstring_common 359263019Sbapt~~~C 360263019Sbaptucl_object_t * ucl_object_fromstring_common (const char *str, 361263019Sbapt size_t len, enum ucl_string_flags flags) 362263019Sbapt~~~ 363263019Sbapt 364263019SbaptThis function is used to convert a string `str` of size `len` to an UCL objects 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): 365263019Sbapt 366263019Sbapt- `UCL_STRING_ESCAPE` - perform JSON escape 367263019Sbapt- `UCL_STRING_TRIM` - trim leading and trailing whitespaces 368263019Sbapt- `UCL_STRING_PARSE_BOOLEAN` - parse passed string and detect boolean 369263019Sbapt- `UCL_STRING_PARSE_INT` - parse passed string and detect integer number 370263019Sbapt- `UCL_STRING_PARSE_DOUBLE` - parse passed string and detect integer or float number 371268896Sbapt- `UCL_STRING_PARSE_TIME` - parse time values as floating point numbers 372268896Sbapt- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float, integer and time types) 373268896Sbapt- `UCL_STRING_PARSE` - parse passed string (and detect booleans, numbers and time values) 374263019Sbapt- `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 375263019Sbapt 376263019SbaptIf 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. 377263019Sbapt 378268896Sbapt# Iteration functions 379263019Sbapt 380263019SbaptIteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). To iterate over an object, an array or a key with multiple values there is a function `ucl_iterate_object`. 381263019Sbapt 382263019Sbapt## ucl_iterate_object 383263019Sbapt~~~C 384268896Sbaptconst ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, 385263019Sbapt ucl_object_iter_t *iter, bool expand_values); 386263019Sbapt~~~ 387263019Sbapt 388263019SbaptThis function accept 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 throught 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 are 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): 389263019Sbapt 390263019Sbapt~~~C 391263019Sbaptucl_object_iter_t it = NULL, it_obj = NULL; 392268896Sbaptconst ucl_object_t *cur, *tmp; 393263019Sbapt 394263019Sbapt/* Iterate over the object */ 395263019Sbaptwhile ((obj = ucl_iterate_object (top, &it, true))) { 396263019Sbapt printf ("key: \"%s\"\n", ucl_object_key (obj)); 397263019Sbapt /* Iterate over the values of a key */ 398263019Sbapt while ((cur = ucl_iterate_object (obj, &it_obj, false))) { 399263019Sbapt printf ("value: \"%s\"\n", 400263019Sbapt ucl_object_tostring_forced (cur)); 401263019Sbapt } 402263019Sbapt} 403268896Sbapt~~~ 404268896Sbapt 405268896Sbapt# Validation functions 406268896Sbapt 407268896SbaptCurrently, 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: 408268896Sbapt 409268896Sbapt## ucl_object_validate 410268896Sbapt~~~C 411268896Sbaptbool ucl_object_validate (const ucl_object_t *schema, 412268896Sbapt const ucl_object_t *obj, struct ucl_schema_error *err); 413268896Sbapt~~~ 414268896Sbapt 415268896SbaptThis 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 caller set `err` to NULL then this function does not set any error just returning `false`. Error is the structure defined as following: 416268896Sbapt 417268896Sbapt~~~C 418268896Sbaptstruct ucl_schema_error { 419268896Sbapt enum ucl_schema_error_code code; /* error code */ 420268896Sbapt char msg[128]; /* error message */ 421268896Sbapt ucl_object_t *obj; /* object where error occured */ 422268896Sbapt}; 423268896Sbapt~~~ 424268896Sbapt 425268896SbaptCaller may use `code` field to get a numeric error code: 426268896Sbapt 427268896Sbapt~~~C 428268896Sbaptenum ucl_schema_error_code { 429268896Sbapt UCL_SCHEMA_OK = 0, /* no error */ 430268896Sbapt UCL_SCHEMA_TYPE_MISMATCH, /* type of object is incorrect */ 431268896Sbapt UCL_SCHEMA_INVALID_SCHEMA, /* schema is invalid */ 432268896Sbapt UCL_SCHEMA_MISSING_PROPERTY,/* missing properties */ 433268896Sbapt UCL_SCHEMA_CONSTRAINT, /* constraint found */ 434268896Sbapt UCL_SCHEMA_MISSING_DEPENDENCY, /* missing dependency */ 435268896Sbapt UCL_SCHEMA_UNKNOWN /* generic error */ 436268896Sbapt}; 437268896Sbapt~~~ 438268896Sbapt 439268896Sbapt`msg` is a stiring description of an error and `obj` is an object where error has been 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).