api.md revision 262395
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 263262395SbaptStrings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory.