api.md revision 262975
1262395SbaptSynopsis 2262395Sbapt======== 3262395Sbapt 4262395Sbapt`#include <ucl.h>` 5262395Sbapt 6262395SbaptDescription 7262395Sbapt=========== 8262395Sbapt 9262395SbaptLibucl is a parser and `C` API to parse and generate `ucl` objects. Libucl consist of several groups of functions: 10262395Sbapt 11262395Sbapt### Parser functions 12262395SbaptUsed to parse `ucl` files and provide interface to extract `ucl` object 13262395Sbapt 14262395Sbapt### Emitting functions 15262395SbaptConvert `ucl` objects to some textual or binary representation. 16262395Sbapt 17262395Sbapt### Conversion functions 18262395SbaptHelp to convert `ucl` objects to C types 19262395Sbapt 20262395Sbapt### Generation functions 21262395SbaptAllow creating of `ucl` objects from C types 22262395Sbapt 23262395Sbapt### Iteration functions 24262395SbaptIterate over `ucl` objects 25262395Sbapt 26262395Sbapt### Utility functions 27262395SbaptProvide basic utilities to manage `ucl` objects 28262395Sbapt 29262395Sbapt# Parser functions 30262395Sbapt 31262395SbaptParser functions operates with `struct ucl_parser`. 32262395Sbapt 33262395Sbapt### ucl_parser_new 34262395Sbapt 35262395Sbapt~~~C 36262395Sbaptstruct ucl_parser* ucl_parser_new (int flags); 37262395Sbapt~~~ 38262395Sbapt 39262395SbaptCreates new parser with the specified flags: 40262395Sbapt 41262395Sbapt- `UCL_PARSER_KEY_LOWERCASE` - lowercase keys parsed 42262395Sbapt- `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) 43262395Sbapt 44262395Sbapt### ucl_parser_register_macro 45262395Sbapt 46262395Sbapt~~~C 47262395Sbaptvoid ucl_parser_register_macro (struct ucl_parser *parser, 48262395Sbapt const char *macro, ucl_macro_handler handler, void* ud); 49262395Sbapt~~~ 50262395Sbapt 51262395SbaptRegister new macro with name .`macro` parsed by handler `handler` that accepts opaque data pointer `ud`. Macro handler should be of the following type: 52262395Sbapt 53262395Sbapt~~~C 54262395Sbaptbool (*ucl_macro_handler) (const unsigned char *data, 55262395Sbapt size_t len, void* ud);` 56262395Sbapt~~~ 57262395Sbapt 58262395SbaptHandler 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. 59262395Sbapt 60262395Sbapt### ucl_parser_register_variable 61262395Sbapt 62262395Sbapt~~~C 63262395Sbaptvoid ucl_parser_register_variable (struct ucl_parser *parser, 64262395Sbapt const char *var, const char *value); 65262395Sbapt~~~ 66262395Sbapt 67262395SbaptRegister new variable $`var` that should be replaced by the parser to the `value` string. 68262395Sbapt 69262395Sbapt### ucl_parser_add_chunk 70262395Sbapt 71262395Sbapt~~~C 72262395Sbaptbool ucl_parser_add_chunk (struct ucl_parser *parser, 73262395Sbapt const unsigned char *data, size_t len); 74262395Sbapt~~~ 75262395Sbapt 76262395SbaptAdd 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: 77262395Sbapt 78262395Sbapt~~~json 79262395Sbapt{ "var": "value" } 80262395Sbapt~~~ 81262395Sbapt 82262395Sbaptwhile this one won't be parsed correctly: 83262395Sbapt 84262395Sbapt~~~json 85262395Sbapt{ "var": 86262395Sbapt~~~ 87262395Sbapt 88262395SbaptThis limitation may possible be removed in future. 89262395Sbapt 90262395Sbapt### ucl_parser_add_file 91262395Sbapt 92262395Sbapt~~~C 93262395Sbaptbool ucl_parser_add_file (struct ucl_parser *parser, 94262395Sbapt const char *filename); 95262395Sbapt~~~ 96262395Sbapt 97262395SbaptLoad 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. 98262395Sbapt 99262395Sbapt### ucl_parser_get_object 100262395Sbapt 101262395Sbapt~~~C 102262395Sbaptucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); 103262395Sbapt~~~ 104262395Sbapt 105262395SbaptIf 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. 106262395Sbapt 107262395Sbapt### ucl_parser_get_error 108262395Sbapt 109262395Sbapt~~~C 110262395Sbaptconst char *ucl_parser_get_error(struct ucl_parser *parser); 111262395Sbapt~~~ 112262395Sbapt 113262395SbaptReturns 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. 114262395Sbapt 115262395Sbapt### ucl_parser_free 116262395Sbapt 117262395Sbapt~~~C 118262395Sbaptvoid ucl_parser_free (struct ucl_parser *parser); 119262395Sbapt~~~ 120262395Sbapt 121262395SbaptFrees 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. 122262395Sbapt 123262395Sbapt### ucl_pubkey_add 124262395Sbapt 125262395Sbapt~~~C 126262395Sbaptbool ucl_pubkey_add (struct ucl_parser *parser, 127262395Sbapt const unsigned char *key, size_t len); 128262395Sbapt~~~ 129262395Sbapt 130262395SbaptThis 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`. 131262395Sbapt 132262395Sbapt### ucl_parser_set_filevars 133262395Sbapt 134262395Sbapt~~~C 135262395Sbaptbool ucl_parser_set_filevars (struct ucl_parser *parser, 136262395Sbapt const char *filename, bool need_expand); 137262395Sbapt~~~ 138262395Sbapt 139262395SbaptAdd the standard file variables to the `parser` based on the `filename` specified: 140262395Sbapt 141262395Sbapt- `$FILENAME` - a filename of `ucl` input 142262395Sbapt- `$CURDIR` - a current directory of the input 143262395Sbapt 144262395SbaptFor example, if a `filename` param is `../something.conf` then the variables will have the following values: 145262395Sbapt 146262395Sbapt- `$FILENAME` - "../something.conf" 147262395Sbapt- `$CURDIR` - ".." 148262395Sbapt 149262395Sbaptif `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: 150262395Sbapt 151262395Sbapt- `$FILENAME` - "/etc/something.conf" 152262395Sbapt- `$CURDIR` - "/etc" 153262395Sbapt 154262395Sbapt## Parser usage example 155262395Sbapt 156262395SbaptThe following example loads, parses and extracts `ucl` object from stdin using `libucl` parser functions (the length of input is limited to 8K): 157262395Sbapt 158262395Sbapt~~~C 159262395Sbaptchar inbuf[8192]; 160262395Sbaptstruct ucl_parser *parser = NULL; 161262395Sbaptint ret = 0, r = 0; 162262395Sbaptucl_object_t *obj = NULL; 163262395SbaptFILE *in; 164262395Sbapt 165262395Sbaptin = stdin; 166262395Sbaptparser = ucl_parser_new (0); 167262395Sbaptwhile (!feof (in) && r < (int)sizeof (inbuf)) { 168262395Sbapt r += fread (inbuf + r, 1, sizeof (inbuf) - r, in); 169262395Sbapt} 170262395Sbaptucl_parser_add_chunk (parser, inbuf, r); 171262395Sbaptfclose (in); 172262395Sbapt 173262395Sbaptif (ucl_parser_get_error (parser)) { 174262395Sbapt printf ("Error occured: %s\n", ucl_parser_get_error (parser)); 175262395Sbapt ret = 1; 176262395Sbapt} 177262395Sbaptelse { 178262395Sbapt obj = ucl_parser_get_object (parser); 179262395Sbapt} 180262395Sbapt 181262395Sbaptif (parser != NULL) { 182262395Sbapt ucl_parser_free (parser); 183262395Sbapt} 184262395Sbaptif (obj != NULL) { 185262395Sbapt ucl_object_unref (obj); 186262395Sbapt} 187262395Sbaptreturn ret; 188262395Sbapt~~~ 189262395Sbapt 190262395Sbapt# Emitting functions 191262395Sbapt 192262395SbaptLibucl can transform UCL objects to a number of tectual formats: 193262395Sbapt 194262395Sbapt- configuration (`UCL_EMIT_CONFIG`) - nginx like human readable configuration file where implicit arrays are transformed to the duplicate keys 195262395Sbapt- compact json: `UCL_EMIT_JSON_COMPACT` - single line valid json without spaces 196262395Sbapt- formatted json: `UCL_EMIT_JSON` - pretty formatted JSON with newlines and spaces 197262395Sbapt- compact yaml: `UCL_EMIT_YAML` - compact YAML output 198262395Sbapt 199262395SbaptMoreover, libucl API allows to select a custom set of emitting functions allowing 200262395Sbaptefficent and zero-copy output of libucl objects. Libucl uses the following structure to support this feature: 201262395Sbapt 202262395Sbapt~~~C 203262395Sbaptstruct ucl_emitter_functions { 204262395Sbapt /** Append a single character */ 205262395Sbapt int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud); 206262395Sbapt /** Append a string of a specified length */ 207262395Sbapt int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud); 208262395Sbapt /** Append a 64 bit integer */ 209262395Sbapt int (*ucl_emitter_append_int) (int64_t elt, void *ud); 210262395Sbapt /** Append floating point element */ 211262395Sbapt int (*ucl_emitter_append_double) (double elt, void *ud); 212262395Sbapt /** Opaque userdata pointer */ 213262395Sbapt void *ud; 214262395Sbapt}; 215262395Sbapt~~~ 216262395Sbapt 217262395SbaptThis structure defines the following callbacks: 218262395Sbapt 219262395Sbapt- `ucl_emitter_append_character` - a function that is called to append `nchars` characters equal to `c` 220262395Sbapt- `ucl_emitter_append_len` - used to append a string of length `len` starting from pointer `str` 221262395Sbapt- `ucl_emitter_append_int` - this function applies to integer numbers 222262395Sbapt- `ucl_emitter_append_double` - this function is intended to output floating point variable 223262395Sbapt 224262395SbaptThe set of these functions could be used to output text formats of `UCL` objects to different structures or streams. 225262395Sbapt 226262395SbaptLibucl provides the following functions for emitting UCL objects: 227262395Sbapt 228262395Sbapt### ucl_object_emit 229262395Sbapt 230262395Sbapt~~~C 231262395Sbaptunsigned char *ucl_object_emit (ucl_object_t *obj, enum ucl_emitter emit_type); 232262395Sbapt~~~ 233262395Sbapt 234262395SbaptAllocate 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. 235262395Sbapt 236262395Sbapt### ucl_object_emit_full 237262395Sbapt 238262395Sbapt~~~C 239262395Sbaptbool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type, 240262395Sbapt struct ucl_emitter_functions *emitter); 241262395Sbapt~~~ 242262395Sbapt 243262395SbaptThis 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). 244262395Sbapt 245262395Sbapt# Conversion functions 246262395Sbapt 247262395SbaptConversion functions are used to convert UCL objects to primitive types, such as strings, numbers or boolean values. There are two types of conversion functions: 248262395Sbapt 249262395Sbapt- safe: try to convert an ucl object to a primitive type and fail if such a conversion is not possible 250262395Sbapt- 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) 251262395Sbapt 252262395SbaptAlso 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. 253262395Sbapt 254262395SbaptHere is a list of all conversion functions: 255262395Sbapt 256262395Sbapt- `ucl_object_toint` - returns `int64_t` of UCL object 257262395Sbapt- `ucl_object_todouble` - returns `double` of UCL object 258262395Sbapt- `ucl_object_toboolean` - returns `bool` of UCL object 259262395Sbapt- `ucl_object_tostring` - returns `const char *` of UCL object (this string is NULL terminated) 260262395Sbapt- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string can be not NULL terminated) 261262395Sbapt- `ucl_object_tostring_forced` - returns string representation of any UCL object 262262395Sbapt 263262975SbaptStrings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory. 264262975Sbapt 265262975Sbapt# Generation functions 266262975Sbapt 267262975SbaptIt 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. 268262975Sbapt 269262975Sbapt## ucl_object_new 270262975Sbapt~~~C 271262975Sbaptucl_object_t * ucl_object_new (void) 272262975Sbapt~~~ 273262975Sbapt 274262975SbaptCreates new object of type `UCL_NULL`. This object should be released by caller. 275262975Sbapt 276262975Sbapt## ucl_object_typed_new 277262975Sbapt~~~C 278262975Sbaptucl_object_t * ucl_object_typed_new (unsigned int type) 279262975Sbapt~~~ 280262975Sbapt 281262975SbaptCreate an object of a specified type: 282262975Sbapt- `UCL_OBJECT` - UCL object - key/value pairs 283262975Sbapt- `UCL_ARRAY` - UCL array 284262975Sbapt- `UCL_INT` - integer number 285262975Sbapt- `UCL_FLOAT` - floating point number 286262975Sbapt- `UCL_STRING` - NULL terminated string 287262975Sbapt- `UCL_BOOLEAN` - boolean value 288262975Sbapt- `UCL_TIME` - time value (floating point number of seconds) 289262975Sbapt- `UCL_USERDATA` - opaque userdata pointer (may be used in macros) 290262975Sbapt- `UCL_NULL` - null value 291262975Sbapt 292262975SbaptThis object should be released by caller. 293262975Sbapt 294262975Sbapt## Primitive objects generation 295262975SbaptLibucl provides the functions similar to inverse conversion functions called with the specific C type: 296262975Sbapt- `ucl_object_fromint` - converts `int64_t` to UCL object 297262975Sbapt- `ucl_object_fromdouble` - converts `double` to UCL object 298262975Sbapt- `ucl_object_fromboolean` - converts `bool` to UCL object 299262975Sbapt- `ucl_object_fromstring` - converts `const char *` to UCL object (this string is NULL terminated) 300262975Sbapt- `ucl_object_fromlstring` - converts `const char *` and `size_t` len to UCL object (string can be not NULL terminated) 301262975Sbapt 302262975SbaptAlso there is a function to generate UCL object from a string performing various parsing or conversion operations called `ucl_object_fromstring_common`. 303262975Sbapt 304262975Sbapt## ucl_object_fromstring_common 305262975Sbapt~~~C 306262975Sbaptucl_object_t * ucl_object_fromstring_common (const char *str, 307262975Sbapt size_t len, enum ucl_string_flags flags) 308262975Sbapt~~~ 309262975Sbapt 310262975SbaptThis 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): 311262975Sbapt 312262975Sbapt- `UCL_STRING_ESCAPE` - perform JSON escape 313262975Sbapt- `UCL_STRING_TRIM` - trim leading and trailing whitespaces 314262975Sbapt- `UCL_STRING_PARSE_BOOLEAN` - parse passed string and detect boolean 315262975Sbapt- `UCL_STRING_PARSE_INT` - parse passed string and detect integer number 316262975Sbapt- `UCL_STRING_PARSE_DOUBLE` - parse passed string and detect integer or float number 317262975Sbapt- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float or integer types) 318262975Sbapt- `UCL_STRING_PARSE` - parse passed string (and detect booleans and numbers) 319262975Sbapt- `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 320262975Sbapt 321262975SbaptIf 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. 322262975Sbapt 323262975Sbapt# Iteration function 324262975Sbapt 325262975SbaptIteration 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`. 326262975Sbapt 327262975Sbapt## ucl_iterate_object 328262975Sbapt~~~C 329262975Sbaptucl_object_t* ucl_iterate_object (ucl_object_t *obj, 330262975Sbapt ucl_object_iter_t *iter, bool expand_values); 331262975Sbapt~~~ 332262975Sbapt 333262975SbaptThis 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): 334262975Sbapt 335262975Sbapt~~~C 336262975Sbaptucl_object_iter_t it = NULL, it_obj = NULL; 337262975Sbaptucl_object_t *cur, *tmp; 338262975Sbapt 339262975Sbapt/* Iterate over the object */ 340262975Sbaptwhile ((obj = ucl_iterate_object (top, &it, true))) { 341262975Sbapt printf ("key: \"%s\"\n", ucl_object_key (obj)); 342262975Sbapt /* Iterate over the values of a key */ 343262975Sbapt while ((cur = ucl_iterate_object (obj, &it_obj, false))) { 344262975Sbapt printf ("value: \"%s\"\n", 345262975Sbapt ucl_object_tostring_forced (cur)); 346262975Sbapt } 347262975Sbapt} 348262975Sbapt~~~