api.md revision 262398
1Synopsis 2======== 3 4`#include <ucl.h>` 5 6Description 7=========== 8 9Libucl is a parser and `C` API to parse and generate `ucl` objects. Libucl consist of several groups of functions: 10 11### Parser functions 12Used to parse `ucl` files and provide interface to extract `ucl` object 13 14### Emitting functions 15Convert `ucl` objects to some textual or binary representation. 16 17### Conversion functions 18Help to convert `ucl` objects to C types 19 20### Generation functions 21Allow creating of `ucl` objects from C types 22 23### Iteration functions 24Iterate over `ucl` objects 25 26### Utility functions 27Provide basic utilities to manage `ucl` objects 28 29# Parser functions 30 31Parser functions operates with `struct ucl_parser`. 32 33### ucl_parser_new 34 35~~~C 36struct ucl_parser* ucl_parser_new (int flags); 37~~~ 38 39Creates new parser with the specified flags: 40 41- `UCL_PARSER_KEY_LOWERCASE` - lowercase keys parsed 42- `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) 43 44### ucl_parser_register_macro 45 46~~~C 47void ucl_parser_register_macro (struct ucl_parser *parser, 48 const char *macro, ucl_macro_handler handler, void* ud); 49~~~ 50 51Register new macro with name .`macro` parsed by handler `handler` that accepts opaque data pointer `ud`. Macro handler should be of the following type: 52 53~~~C 54bool (*ucl_macro_handler) (const unsigned char *data, 55 size_t len, void* ud);` 56~~~ 57 58Handler 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. 59 60### ucl_parser_register_variable 61 62~~~C 63void ucl_parser_register_variable (struct ucl_parser *parser, 64 const char *var, const char *value); 65~~~ 66 67Register new variable $`var` that should be replaced by the parser to the `value` string. 68 69### ucl_parser_add_chunk 70 71~~~C 72bool ucl_parser_add_chunk (struct ucl_parser *parser, 73 const unsigned char *data, size_t len); 74~~~ 75 76Add 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: 77 78~~~json 79{ "var": "value" } 80~~~ 81 82while this one won't be parsed correctly: 83 84~~~json 85{ "var": 86~~~ 87 88This limitation may possible be removed in future. 89 90### ucl_parser_add_file 91 92~~~C 93bool ucl_parser_add_file (struct ucl_parser *parser, 94 const char *filename); 95~~~ 96 97Load 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. 98 99### ucl_parser_get_object 100 101~~~C 102ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); 103~~~ 104 105If 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. 106 107### ucl_parser_get_error 108 109~~~C 110const char *ucl_parser_get_error(struct ucl_parser *parser); 111~~~ 112 113Returns 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. 114 115### ucl_parser_free 116 117~~~C 118void ucl_parser_free (struct ucl_parser *parser); 119~~~ 120 121Frees 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. 122 123### ucl_pubkey_add 124 125~~~C 126bool ucl_pubkey_add (struct ucl_parser *parser, 127 const unsigned char *key, size_t len); 128~~~ 129 130This 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`. 131 132### ucl_parser_set_filevars 133 134~~~C 135bool ucl_parser_set_filevars (struct ucl_parser *parser, 136 const char *filename, bool need_expand); 137~~~ 138 139Add the standard file variables to the `parser` based on the `filename` specified: 140 141- `$FILENAME` - a filename of `ucl` input 142- `$CURDIR` - a current directory of the input 143 144For example, if a `filename` param is `../something.conf` then the variables will have the following values: 145 146- `$FILENAME` - "../something.conf" 147- `$CURDIR` - ".." 148 149if `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: 150 151- `$FILENAME` - "/etc/something.conf" 152- `$CURDIR` - "/etc" 153 154## Parser usage example 155 156The following example loads, parses and extracts `ucl` object from stdin using `libucl` parser functions (the length of input is limited to 8K): 157 158~~~C 159char inbuf[8192]; 160struct ucl_parser *parser = NULL; 161int ret = 0, r = 0; 162ucl_object_t *obj = NULL; 163FILE *in; 164 165in = stdin; 166parser = ucl_parser_new (0); 167while (!feof (in) && r < (int)sizeof (inbuf)) { 168 r += fread (inbuf + r, 1, sizeof (inbuf) - r, in); 169} 170ucl_parser_add_chunk (parser, inbuf, r); 171fclose (in); 172 173if (ucl_parser_get_error (parser)) { 174 printf ("Error occured: %s\n", ucl_parser_get_error (parser)); 175 ret = 1; 176} 177else { 178 obj = ucl_parser_get_object (parser); 179} 180 181if (parser != NULL) { 182 ucl_parser_free (parser); 183} 184if (obj != NULL) { 185 ucl_object_unref (obj); 186} 187return ret; 188~~~ 189 190# Emitting functions 191 192Libucl can transform UCL objects to a number of tectual formats: 193 194- configuration (`UCL_EMIT_CONFIG`) - nginx like human readable configuration file where implicit arrays are transformed to the duplicate keys 195- compact json: `UCL_EMIT_JSON_COMPACT` - single line valid json without spaces 196- formatted json: `UCL_EMIT_JSON` - pretty formatted JSON with newlines and spaces 197- compact yaml: `UCL_EMIT_YAML` - compact YAML output 198 199Moreover, libucl API allows to select a custom set of emitting functions allowing 200efficent and zero-copy output of libucl objects. Libucl uses the following structure to support this feature: 201 202~~~C 203struct ucl_emitter_functions { 204 /** Append a single character */ 205 int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud); 206 /** Append a string of a specified length */ 207 int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud); 208 /** Append a 64 bit integer */ 209 int (*ucl_emitter_append_int) (int64_t elt, void *ud); 210 /** Append floating point element */ 211 int (*ucl_emitter_append_double) (double elt, void *ud); 212 /** Opaque userdata pointer */ 213 void *ud; 214}; 215~~~ 216 217This structure defines the following callbacks: 218 219- `ucl_emitter_append_character` - a function that is called to append `nchars` characters equal to `c` 220- `ucl_emitter_append_len` - used to append a string of length `len` starting from pointer `str` 221- `ucl_emitter_append_int` - this function applies to integer numbers 222- `ucl_emitter_append_double` - this function is intended to output floating point variable 223 224The set of these functions could be used to output text formats of `UCL` objects to different structures or streams. 225 226Libucl provides the following functions for emitting UCL objects: 227 228### ucl_object_emit 229 230~~~C 231unsigned char *ucl_object_emit (ucl_object_t *obj, enum ucl_emitter emit_type); 232~~~ 233 234Allocate 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. 235 236### ucl_object_emit_full 237 238~~~C 239bool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type, 240 struct ucl_emitter_functions *emitter); 241~~~ 242 243This 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). 244 245# Conversion functions 246 247Conversion functions are used to convert UCL objects to primitive types, such as strings, numbers or boolean values. There are two types of conversion functions: 248 249- safe: try to convert an ucl object to a primitive type and fail if such a conversion is not possible 250- 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) 251 252Also 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. 253 254Here is a list of all conversion functions: 255 256- `ucl_object_toint` - returns `int64_t` of UCL object 257- `ucl_object_todouble` - returns `double` of UCL object 258- `ucl_object_toboolean` - returns `bool` of UCL object 259- `ucl_object_tostring` - returns `const char *` of UCL object (this string is NULL terminated) 260- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string can be not NULL terminated) 261- `ucl_object_tostring_forced` - returns string representation of any UCL object 262 263Strings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory.