LIBUCL(3)

🦋 LIBUCL(3) 🦋 — the universal configuration library, but make it a whole vibe

okay bestie, welcome to libucl (the universal configuration library) 💖 this page is long so it comes in parts — this is part one, so don't go anywhere, there's more coming. grab a snack, hydrate, and let's get into it 🍓

---

💅 NAME 💅

ucl_parser_new, ucl_parser_register_macro, ucl_parser_register_variable, ucl_parser_add_chunk, ucl_parser_add_string, ucl_parser_add_file, ucl_parser_get_object, ucl_parser_get_error, ucl_parser_free, ucl_pubkey_add, ucl_parser_set_filevars — the universal configuration library parser and its little squad of utility functions 🫶

🌈 LIBRARY 🌈

UCL library (libucl, -lucl). that's the one. link it, love it, periodt ✨

📜 SYNOPSIS 📜

#include <ucl.h>

🎀 DESCRIPTION 🎀

okay so Libucl is a parser and a C API that parses and generates ucl objects. it's giving main character energy fr. Libucl is built out of several groups of functions, and each group has its own job:

💖 Parser functions

these are the ones that parse ucl files and hand you an interface to pull a ucl object out. heads up though: currently libucl can only parse full ucl documents. like, you cannot parse just a piece of a document, which means you cannot use libucl as a streaming parser. sad, i know. 😭 in the future this limitation can be removed. manifesting it ✨

💖 Emitting functions

these convert ucl objects into some textual or binary representation. right now libucl supports these exports:

• JSON — valid json format (can possibly lose some original data, such as implicit arrays) 💀
• Config — human-readable configuration format (lossless, we love a lossless king 👑)
• YAML — embedded yaml format (has the same limitations as json output)

💖 Conversion functions

these help convert ucl objects to C types. they take a ucl_object_t and turn it into C primitive types, like numbers, strings or boolean values. glow up for your data 💅

💖 Generation functions

these let you create ucl objects from C types, and let you build complex ucl objects — like hashes or arrays — out of primitive ucl objects, like numbers or strings. build-a-bear but for data structures 🧸

💖 Iteration functions

these iterate over ucl complex objects, or over a chain of values — for example when a key in an object has multiple values (which can be treated as an implicit array or implicit consolidation). iconic behaviour honestly

💖 Validation functions

these validate some object obj using a json-schema compatible object schema. both the input and the schema have to be UCL objects for the validation to happen. no shortcuts bestie 🌸

💖 Utility functions

basic utilities to manage ucl objects: creating, removing, retaining and releasing reference count, and so on. the chores of the library, but somebody's gotta do them 🫡

---

✨ PARSER FUNCTIONS ✨

parser functions operate with struct ucl_parser. let's meet them one by one:

🌟 ucl_parser_new

struct ucl_parser* ucl_parser_new (int flags);

creates a new parser with the flags you specify. the flags are:

• UCL_PARSER_KEY_LOWERCASE — lowercase keys parsed
• UCL_PARSER_ZEROCOPY — try to use zero-copy mode when reading files. in zero-copy mode the text chunk being parsed is read without copying strings, so it should exist till any object parsed is used. do not let that chunk go out of scope, i am begging 🙈
• UCL_PARSER_NO_TIME — treat time values as strings, without parsing them as floats

🌟 ucl_parser_register_macro

void ucl_parser_register_macro (struct ucl_parser *parser,
    const char *macro, ucl_macro_handler handler, void* ud);

register a new macro with name .macro, parsed by the handler handler, which accepts an opaque data pointer ud. the macro handler should be of this type:

bool (*ucl_macro_handler) (const unsigned char *data,
    size_t len, void* ud);

the handler function accepts macro text data of length len and the opaque pointer ud. if the macro is parsed successfully the handler should return true. returning false indicates parsing failure and the parser can be terminated. so like, no pressure or anything 😅

🌟 ucl_parser_register_variable

void ucl_parser_register_variable (struct ucl_parser *parser,
    const char *var, const char *value);

register a new variable $var that should be replaced by the parser with the value string. cute little find-and-replace moment 💫

🌟 ucl_parser_add_chunk

bool ucl_parser_add_chunk (struct ucl_parser *parser,
    const unsigned char *data, size_t len);

add a new text chunk with data of length len to the parser. at the moment, libucl parser is not a streamlined parser, and the chunk must contain the valid ucl object. for example, this object should be valid:

{ "var": "value" }

while this one won't be parsed correctly:

{ "var":

this limitation may possible be removed in future. fingers crossed 🤞

🌟 ucl_parser_add_string

bool ucl_parser_add_string (struct ucl_parser *parser,
    const char *data, size_t len);

this function acts exactly like ucl_parser_add_chunk does — but, if the len argument is zero, then the string data must be zero-terminated and the actual length is calculated up to the \0 character. so len is optional if your string is a good well-behaved null-terminated girly 💅

🌟 ucl_parser_add_file

bool ucl_parser_add_file (struct ucl_parser *parser,
    const char *filename);

load the file filename and parse it with the specified parser. this function uses the mmap call to load the file, therefore it should not be shrunk during parsing. otherwise libucl can cause memory corruption and terminate the calling application. 💀 not the vibe. this function is also used by the internal handler of the include macro, hence, that macro has the same limitation. so like, keep your files stable while they're being parsed, ok? 🫶

🌟 ucl_parser_get_object

ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);

if the ucl data has been parsed correctly, this function returns the top object for the parser. otherwise, it returns the NULL pointer. 😭 the reference count for the ucl object returned is increased by one, therefore a caller should decrease the reference by using ucl_object_unref to free the object after usage. don't forget to clean up after yourself bestie, we're not messy 🧼

🌟 ucl_parser_get_error

const char *ucl_parser_get_error(struct ucl_parser *parser);

returns 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 — it's not yours, hands off 🙅‍♀️

🌟 ucl_parser_free

void ucl_parser_free (struct ucl_parser *parser);

frees the memory occupied by the parser object. the reference count for the 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. sneaky but correct ✨

🌟 ucl_pubkey_add

bool ucl_pubkey_add (struct ucl_parser *parser,
    const unsigned char *key, size_t len);

this function adds a public key from the text blob key of length len to the parser object. this public key should be in the PEM format and can be used by the .includes macro for checking signatures of files included. Openssl support should be enabled to make this function work. if a key cannot be added (e.g. due to format error), or openssl was not linked to libucl, then this function returns false. secure queen behaviour 🔐

🌟 ucl_parser_set_filevars

bool ucl_parser_set_filevars (struct ucl_parser *parser,
    const char *filename, bool need_expand);

add the standard file variables to the parser, based on the filename specified:

• $FILENAME — a filename of ucl input
• $CURDIR — a current directory of the input

for example, if a filename param is ../something.conf then the variables will have the following values:

• $FILENAME — "../something.conf"
• $CURDIR — ".."

if the need_expand parameter is true then all relative paths are expanded using the realpath call. in this example, if .. is /etc/dir then the variables will have these values:

• $FILENAME — "/etc/something.conf"
• $CURDIR — "/etc"

look at those paths getting glow-ups ✨📁

🧚 Parser usage example

the following example loads, parses and extracts a ucl object from stdin using the libucl parser functions (the length of input is limited to 8K):

char inbuf[8192];
struct ucl_parser *parser = NULL;
int ret = 0, r = 0;
ucl_object_t *obj = NULL;
FILE *in;

in = stdin;
parser = ucl_parser_new (0);
while (!feof (in) && r < (int)sizeof (inbuf)) {
    r += fread (inbuf + r, 1, sizeof (inbuf) - r, in);
}
ucl_parser_add_chunk (parser, inbuf, r);
fclose (in);

if (ucl_parser_get_error (parser)) {
    printf ("Error occurred: %s\n", ucl_parser_get_error (parser));
    ret = 1;
}
else {
    obj = ucl_parser_get_object (parser);
}

if (parser != NULL) {
    ucl_parser_free (parser);
}
if (obj != NULL) {
    ucl_object_unref (obj);
}
return ret;

see? clean, cute, correct. we love to see it 💖

---

🌈 EMITTING FUNCTIONS 🌈

libucl can transform UCL objects into a number of tectual formats (yes, "tectual", we're keeping it 😌):

• configuration (UCL_EMIT_CONFIG) — nginx like human readable configuration file, where implicit arrays are transformed to the duplicate keys
• compact json: UCL_EMIT_JSON_COMPACT — single line valid json without spaces
• formatted json: UCL_EMIT_JSON — pretty formatted JSON with newlines and spaces
• compact yaml: UCL_EMIT_YAML — compact YAML output

moreover, the libucl API lets you select a custom set of emitting functions, which allows efficient and zero-copy output of libucl objects. libucl uses the following structure to support this feature:

struct ucl_emitter_functions {
    /** Append a single character */
    int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud);
    /** Append a string of a specified length */
    int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud);
    /** Append a 64 bit integer */
    int (*ucl_emitter_append_int) (int64_t elt, void *ud);
    /** Append floating point element */
    int (*ucl_emitter_append_double) (double elt, void *ud);
    /** Opaque userdata pointer */
    void *ud;
};

this structure defines the following callbacks:

• ucl_emitter_append_character — a function that is called to append nchars characters equal to c
• ucl_emitter_append_len — used to append a string of length len starting from pointer str
• ucl_emitter_append_int — this function applies to integer numbers
• ucl_emitter_append_double — this function is intended to output a floating point variable

the set of these functions could be used to output text formats of UCL objects to different structures or streams. so you can send your data wherever it needs to go, no cap 🚀

libucl provides the following functions for emitting UCL objects:

🌟 ucl_object_emit

unsigned char *ucl_object_emit (const ucl_object_t *obj, enum ucl_emitter emit_type);

allocate 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. free your strings bestie, the memory is not going to free itself 😭

🌟 ucl_object_emit_full

bool ucl_object_emit_full (const ucl_object_t *obj, enum ucl_emitter emit_type,
        struct ucl_emitter_functions *emitter);

this function is similar to the previous one, 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). fancy 💅

---

okay that's part one bestie, more parts are coming so stay tuned 🦋

✨ CONVERSION FUNCTIONS ✨

ok so conversion functions are literally just the glow-up artists of libucl — they take a UCL object and turn it into a primitive type. strings, numbers, booleans, the whole thing. and there are two flavors bestie:

• safe — tries to convert the ucl object to a primitive type and fails if that conversion just isn't possible
• unsafe — returns the primitive type with zero extra checks, and if the object can't be converted you just get some reasonable default back (NULL for strings, 0 for numbers). no thoughts, head empty 💀

also there's exactly one ucl_object_tostring_forced function that converts any UCL object (including compound types — arrays and objects) into a string representation. for objects, arrays, booleans and numeric types, this function actually performs emitting to a compact json format. slay.

here's the full roster of conversion functions:

• ucl_object_toint — returns int64_t of UCL object
• ucl_object_todouble — returns double of UCL object
• ucl_object_toboolean — returns bool of UCL object
• ucl_object_tostring — returns const char * of UCL object (this string is NULL terminated)
• ucl_object_tolstring — returns const char * and size_t len of UCL object (string does not need to be NULL terminated)
• ucl_object_tostring_forced — returns string representation of any UCL object

heads up bestie: strings returned by these pointers are associated with the UCL object and exist over its lifetime. a caller should not free this memory. do not free it. put the free() down. 🙈

---

🌈 GENERATION FUNCTIONS 🌈

so it's also possible to generate UCL objects from C primitive types. and more than that — libucl lets you create and modify complex UCL objects too, like arrays or associative objects. we're building, we're crafting, we're in our creation era 🎀

ucl_object_new

ucl_object_t * ucl_object_new (void)

creates a new object of type UCL_NULL. this object should be released by caller — that's on you, babes. 💅

ucl_object_typed_new

ucl_object_t * ucl_object_typed_new (unsigned int type)

creates an object of a specified type:

• UCL_OBJECT — UCL object — key/value pairs
• UCL_ARRAY — UCL array
• UCL_INT — integer number
• UCL_FLOAT — floating point number
• UCL_STRING — NULL terminated string
• UCL_BOOLEAN — boolean value
• UCL_TIME — time value (floating point number of seconds)
• UCL_USERDATA — opaque userdata pointer (may be used in macros)
• UCL_NULL — null value

this object should be released by caller, yes again, don't forget, i'm watching 👀

Primitive objects generation

libucl provides the functions similar to inverse conversion functions, but called with the specific C type:

• ucl_object_fromint — converts int64_t to UCL object
• ucl_object_fromdouble — converts double to UCL object
• ucl_object_fromboolean — converts bool to UCL object
• ucl_object_fromstring — converts const char * to UCL object (this string should be NULL terminated)
• ucl_object_fromlstring — converts const char * and size_t len to UCL object (string does not need to be NULL terminated)

also there's a function to generate a UCL object from a string that performs various parsing or conversion operations, and it's called ucl_object_fromstring_common. main character behavior honestly ✨

ucl_object_fromstring_common

ucl_object_t * ucl_object_fromstring_common (const char *str,
    size_t len, enum ucl_string_flags flags)

this 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 str is assumed as NULL-terminated. this function supports the following flags (a set of flags can be specified using logical OR operation):

• UCL_STRING_ESCAPE — perform JSON escape
• UCL_STRING_TRIM — trim leading and trailing whitespaces
• UCL_STRING_PARSE_BOOLEAN — parse passed string and detect boolean
• UCL_STRING_PARSE_INT — parse passed string and detect integer number
• UCL_STRING_PARSE_DOUBLE — parse passed string and detect integer or float number
• UCL_STRING_PARSE_TIME — parse time values as floating point numbers
• UCL_STRING_PARSE_NUMBER — parse passed string and detect number (both float, integer and time types)
• UCL_STRING_PARSE — parse passed string (and detect booleans, numbers and time values)
• 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

if 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. always always. no skipping. 🫶

---

🦋 ITERATION FUNCTIONS 🦋

iterations are used to iterate over UCL compound types: arrays and objects. and plot twist — iterations could also be performed over the keys with multiple values (implicit arrays). there are two types of iterators API: the old and unsafe one via ucl_iterate_object, and the proposed interface of safe iterators. glow up era 💖

ucl_iterate_object

const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj,
    ucl_object_iter_t *iter, bool expand_values)

this function accepts an 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 either — hands off, bestie 🙅‍♀️

expand_values flag specifies 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. it's giving loyalty, iykyk 💅

here's an example of iteration over the objects using libucl API (assuming that top is UCL_OBJECT in this example):

ucl_object_iter_t it = NULL, it_obj = NULL;
const ucl_object_t *cur, *tmp;

/* Iterate over the object */
while ((obj = ucl_iterate_object (top, &it, true))) {
    printf ("key: \"%s\"\n", ucl_object_key (obj));
    /* Iterate over the values of a key */
    while ((cur = ucl_iterate_object (obj, &it_obj, false))) {
        printf ("value: \"%s\"\n",
            ucl_object_tostring_forced (cur));
    }
}

Safe iterators API

safe iterators are defined to clarify iterating over UCL objects and simplify flattening of UCL objects in non-trivial cases. for example, if there's an implicit array that contains another array and a boolean value, it's extremely unclear how to iterate over such an object. like genuinely, what do we even do here 😭

safe iterators are designed to define two sorts of iteration:

1. Iteration over complex objects with expanding all values
2. Iteration over complex objects without expanding of values

the following example demonstrates the difference between these two types of iteration:

key = 1;
key = [2, 3, 4];

Iteration with expansion:

1, 2, 3, 4

Iteration without expansion:

1, [2, 3, 4]

UCL defines the following functions to manage safe iterators:

• ucl_object_iterate_new — creates new safe iterator.
• ucl_object_iterate_reset — resets iterator to a new object.
• ucl_object_iterate_safe — safely iterate the object inside iterator. Note: function may allocate and free memory during its operation. Therefore it returns NULL either while trying to access item after the last one or when exception (such as memory allocation failure) happens.
• ucl_object_iter_chk_excpn — check if the last call to ucl_object_iterate_safe ended up in unrecoverable exception (e.g. ENOMEM).
• ucl_object_iterate_free — free memory associated with the safe iterator.

please note: unlike unsafe iterators, safe iterators must be explicitly initialized and freed. an assert is likely generated if you use uninitialized or NULL iterator in all safe iterators functions. so like, initialize them fr fr 🙏

ucl_object_iter_t it;
const ucl_object_t *cur;

it = ucl_object_iterate_new (obj);

while ((cur = ucl_object_iterate_safe (it, true)) != NULL) {
    /* Do something */
}
/* Check error condition */
if (ucl_object_iter_chk_excpn (it)) {
    ucl_object_iterate_free (it);
    exit (1);
}

/* Switch to another object */
it = ucl_object_iterate_reset (it, another_obj);

while ((cur = ucl_object_iterate_safe (it, true)) != NULL) {
    /* Do something else */
}
/* Check error condition */
if (ucl_object_iter_chk_excpn (it)) {
    ucl_object_iterate_free (it);
    exit (1);
}

ucl_object_iterate_free (it);

---

👑 VALIDATION FUNCTIONS 👑

currently, there is only one validation function and it's called ucl_object_validate. it performs validation of object using the specified schema. this function is defined as following:

ucl_object_validate

bool ucl_object_validate (const ucl_object_t *schema,
    const ucl_object_t *obj, struct ucl_schema_error *err);

this 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. vibe check failed, no details, sorry 💀

Error is the structure defined as following:

struct ucl_schema_error {
    enum ucl_schema_error_code code;    /* error code */
    char msg[128];              /* error message */
    ucl_object_t *obj;          /* object where error occurred */
};

caller may use code field to get a numeric error code:

enum ucl_schema_error_code {
    UCL_SCHEMA_OK = 0,          /* no error */
    UCL_SCHEMA_TYPE_MISMATCH,   /* type of object is incorrect */
    UCL_SCHEMA_INVALID_SCHEMA,  /* schema is invalid */
    UCL_SCHEMA_MISSING_PROPERTY,/* missing properties */
    UCL_SCHEMA_CONSTRAINT,      /* constraint found */
    UCL_SCHEMA_MISSING_DEPENDENCY, /* missing dependency */
    UCL_SCHEMA_UNKNOWN          /* generic error */
};

msg is a string description of an error and obj is an object where error has occurred. the error object is not allocated by libucl, so there is no need to free it after validation (a static object should thus be used). don't free it bestie, it's not yours to free 🎀

---

💜 AUTHORS 💜

Vsevolod Stakhov <vsevolod@highsecure.ru>.

---

and that's the whole page babes!! 🫶 this one came straight out of the Libucl manual, dated 27 December, 2014, and it lives at LIBUCL(3) — iconic, legendary, no notes 💅✨ bye bestie, go write some UCL 💖