Append an element to the end of array object
@param top destination object (must NOT be NULL)
@param elt element to append (must NOT be NULL)
@return true if value has been inserted
Removes an element elt from the array top, returning the object that was
removed. This object is not released, caller must unref the returned object
when it is no longer needed.
@param top array ucl object
@param elt element to remove
@return removed element or NULL if top is NULL or not an array
Return object identified by index of the array top
@param top object to get a key from (must be of type UCL_ARRAY)
@param index array index to return
@return object at the specified index or NULL if index is not found
Returns the first element of the array top
@param top array ucl object
@return element or NULL if top is NULL or not an array
Return the index of elt in the array top
@param top object to get a key from (must be of type UCL_ARRAY)
@param elt element to find index of (must NOT be NULL)
@return index of elt in the array top or (unsigned int)-1 if elt` is not found
Merge all elements of second array into the first array
@param top destination array (must be of type UCL_ARRAY)
@param elt array to copy elements from (must be of type UCL_ARRAY)
@param copy copy elements instead of referencing them
@return true if arrays were merged
Removes the first element from the array top, returning the object that was
removed. This object is not released, caller must unref the returned object
when it is no longer needed.
@param top array ucl object
@return removed element or NULL if top is NULL or not an array
Removes the last element from the array top, returning the object that was
removed. This object is not released, caller must unref the returned object
when it is no longer needed.
@param top array ucl object
@return removed element or NULL if top is NULL or not an array
Append an element to the start of array object
@param top destination object (must NOT be NULL)
@param elt element to append (must NOT be NULL)
@return true if value has been inserted
Replace an element in an array with a different element, returning the object
that was replaced. This object is not released, caller must unref the
returned object when it is no longer needed.
@param top destination object (must be of type UCL_ARRAY)
@param elt element to append (must NOT be NULL)
@param index array index in destination to overwrite with elt
@return object that was replaced or NULL if index is not found
Return size of the array top
@param top object to get size from (must be of type UCL_ARRAY)
@return size of the array
Returns the last element of the array top
@param top array ucl object
@return element or NULL if top is NULL or not an array
Adds a new comment for an object
@param comments comments object
@param obj object to add comment to
@param comment string representation of a comment
Utility function to find a comment object for the specified object in the input
@param comments comments object
@param srch search object
@return string comment enclosed in ucl_object_t
Move comment from from object to to object
@param comments comments object
@param what source object
@param with destination object
@return true if from has comment and it has been moved to to
@defgroup utils Utility functions
A number of utility functions simplify handling of UCL objects
Copy and return a string value of an object, returned key is zero-terminated
@param obj CL object
@return zero terminated string representation of object value
Append a element to another element forming an implicit array
@param head head to append (may be NULL)
@param elt new element
@return the new implicit array
Sort UCL array using cmp compare function
@param ar
@param cmp
Compare objects o1 and o2
@param o1 the first object
@param o2 the second object
@return values >0, 0 and <0 if o1 is more than, equal and less than o2.
The order of comparison:
Compare objects o1 and o2 useful for sorting
@param o1 the first object
@param o2 the second object
@return values >0, 0 and <0 if o1 is more than, equal and less than o2.
The order of comparison:
Perform deep copy of an object copying everything
@param other object to copy
@return new object with refcount equal to 1
Delete a object associated with key ‘key’, old object will be unrefered,
@param top object
@param key key associated to the object to remove
Delete a object associated with key ‘key’, old object will be unrefered,
@param top object
@param key key associated to the object to remove
@param keylen length of the key (or 0 for NULL terminated keys)
Emit object to a string
@param obj object
@param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
#UCL_EMIT_CONFIG then emit config like object
@return dump of an object (must be freed after using) or NULL in case of error
Returns functions to emit object to a file descriptor
@param fd file descriptor
@return emitter functions structure
Emit object to a string
@param obj object
@param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
#UCL_EMIT_CONFIG then emit config like object
@param emitter a set of emitter functions
@param comments optional comments for the parser
@return dump of an object (must be freed after using) or NULL in case of error
Free emitter functions
@param f pointer to functions
Emit object to a string that can contain \0 inside
@param obj object
@param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
#UCL_EMIT_CONFIG then emit config like object
@param len the resulting length
@return dump of an object (must be freed after using) or NULL in case of error
Returns functions to emit object to memory
@param pmem target pointer (should be freed by caller)
@return emitter functions structure
Add a complete UCL object to streamlined output
@param ctx streamlined context
@param obj object to output
End previously added container
@param ctx streamlined context
Terminate streamlined container finishing all containers in it
@param ctx streamlined context
Start streamlined UCL object emitter
@param obj top UCL object
@param emit_type emit type
@param emitter a set of emitter functions
@return new streamlined context that should be freed by
ucl_object_emit_streamline_finish
Start object or array container for the streamlined output
@param ctx streamlined context
@param obj container object
Create an object from a boolean
@param bv bool value
@return new object
Create an object from a float number
@param dv number
@return new object
Create an object from an integer number
@param iv number
@return new object
Create a UCL object from the specified string
@param str fixed size string, will be json escaped
@param len length of a string
@return new object
Create a UCL object from the specified string
@param str NULL terminated string, will be json escaped
@return new object
Convert any string to an ucl object making the specified transformations
@param str fixed size or NULL terminated string
@param len length (if len is zero, than str is treated as NULL terminated)
@param flags conversion flags
@return new object
Get the priority for specific UCL object
@param obj any ucl object
@return priority of an object
Insert a object ‘elt’ to the hash ‘top’ and associate it with key ‘key’
@param top destination object (must be of type UCL_OBJECT)
@param elt element to insert (must NOT be NULL)
@param key key to associate with this object (either const or preallocated)
@param keylen length of the key (or 0 for NULL terminated keys)
@param copy_key make an internal copy of key
@return true if key has been inserted
Insert a object ‘elt’ to the hash ‘top’ and associate it with key ‘key’, if
the specified key exist, try to merge its content
@param top destination object (must be of type UCL_OBJECT)
@param elt element to insert (must NOT be NULL)
@param key key to associate with this object (either const or preallocated)
@param keylen length of the key (or 0 for NULL terminated keys)
@param copy_key make an internal copy of key
@return true if key has been inserted
Get next key from an object
@param obj object to iterate
@param iter opaque iterator, must be set to NULL on the first call:
ucl_object_iter_t it = NULL;
while ((cur = ucl_iterate_object (obj, &it)) != NULL) …
@return the next object or NULL
Free memory associated with the safe iterator
@param it safe iterator object
Get the next object from the obj. This function iterates over arrays, objects
and implicit arrays if needed
@param iter safe iterator
@param
@return the next object in sequence
Create new safe iterator for the specified object
@param obj object to iterate
@return new iterator object that should be used with safe iterators API only
Reset initialized iterator to a new object
@param obj new object to iterate
@return modified iterator object
Get the next object from the obj. This function iterates over arrays, objects
and implicit arrays
@param iter safe iterator
@param expand_values expand explicit arrays and objects
@return the next object in sequence
Returns a key of an object as a NULL terminated string
@param obj CL object
@return key or NULL if there is no key
Returns a key of an object as a fixed size string (may be more efficient)
@param obj CL object
@param len target key length
@return key pointer
Return object identified by a key in the specified object
@param obj object to get a key from (must be of type UCL_OBJECT)
@param key key to search
@return object matching the specified key or NULL if key was not found
Return object identified by a key in the specified object, if the first key is
not found then look for the next one. This process is repeated unless
the next argument in the list is not NULL. So, ucl_object_find_any_key(obj, key, NULL)
is equal to ucl_object_find_key(obj, key)
@param obj object to get a key from (must be of type UCL_OBJECT)
@param key key to search
@param … list of alternative keys to search (NULL terminated)
@return object matching the specified key or NULL if key was not found
Return object identified by a fixed size key in the specified object
@param obj object to get a key from (must be of type UCL_OBJECT)
@param key key to search
@param klen length of a key
@return object matching the specified key or NULL if key was not found
Return object identified by dot notation string
@param obj object to search in
@param path dot.notation.path to the path to lookup. May use numeric .index on arrays
@return object matched the specified path or NULL if path is not found
Return object identified by object notation string using arbitrary delimiter
@param obj object to search in
@param path dot.notation.path to the path to lookup. May use numeric .index on arrays
@param sep the sepatorator to use in place of . (incase keys have . in them)
@return object matched the specified path or NULL if path is not found
Merge the keys from one object to another object. Overwrite on conflict
@param top destination object (must be of type UCL_OBJECT)
@param elt element to insert (must be of type UCL_OBJECT)
@param copy copy rather than reference the elements
@return true if all keys have been merged
Creates a new object
@return new object
Create new object with type and priority specified
@param type type of a new object
@param priority priority of an object
@return new object
Create new object with userdata dtor
@param dtor destructor function
@param emitter emitter for userdata
@param ptr opaque pointer
@return new object
Removes key from top object returning the object that was removed. This
object is not released, caller must unref the returned object when it is no
longer needed.
@param top object
@param key key to remove
@return removed object or NULL if object has not been found
Removes key from top object, returning the object that was removed. This
object is not released, caller must unref the returned object when it is no
longer needed.
@param top object
@param key key to remove
@param keylen length of the key (or 0 for NULL terminated keys)
@return removed object or NULL if object has not been found
Increase reference count for an object
@param obj object to ref
@return the referenced object
Replace a object ‘elt’ to the hash ‘top’ and associate it with key ‘key’, old object will be unrefed,
if no object has been found this function works like ucl_object_insert_key()
@param top destination object (must be of type UCL_OBJECT)
@param elt element to insert (must NOT be NULL)
@param key key to associate with this object (either const or preallocated)
@param keylen length of the key (or 0 for NULL terminated keys)
@param copy_key make an internal copy of key
@return true if key has been inserted
Reserve space in ucl array or object for elt elements
@param obj object to reserve
@param reserved size to reserve in an object
Set explicit priority of an object.
@param obj any ucl object
@param priority new priroity value (only 4 least significant bits are considred)
Converts string that represents ucl type to real ucl type enum
@param input C string with name of type
@param res resulting target
@return true if input is a name of type stored in res
Unsafe version of \ref ucl_obj_toboolean_safe
@param obj CL object
@return boolean value
Converts an object to boolean value
@param obj CL object
@param target target boolean variable
@return true if conversion was successful
Unsafe version of \ref ucl_obj_todouble_safe
@param obj CL object
@return double value
Converts an object to double value
@param obj CL object
@param target target double variable
@return true if conversion was successful
Unsafe version of \ref ucl_obj_toint_safe
@param obj CL object
@return int value
Converts an object to integer value
@param obj CL object
@param target target integer variable
@return true if conversion was successful
Unsafe version of \ref ucl_obj_tolstring_safe
@param obj CL object
@return string value
Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
@param obj CL object
@param target target string variable, no need to free value
@param tlen target length
@return true if conversion was successful
Unsafe version of \ref ucl_obj_tostring_safe
@param obj CL object
@return string value
Convert any object to a string in JSON notation if needed
@param obj CL object
@return string value
Converts an object to string value
@param obj CL object
@param target target string variable, no need to free value
@return true if conversion was successful
Return the type of an object
@return the object type
Converts ucl object type to its string representation
@param type type of object
@return constant string describing type
Create new object with type specified
@param type type of a new object
@return new object
Decrease reference count for an object
@param obj object to unref
Validate object obj using schema object schema.
@param schema schema object
@param obj object to validate
@param err error pointer, if this parameter is not NULL and error has been
occurred, then err is filled with the exact error definition.
@return true if obj is valid using schema
Validate object obj using schema object schema and root schema at root.
@param schema schema object
@param obj object to validate
@param root root schema object
@param err error pointer, if this parameter is not NULL and error has been
occurred, then err is filled with the exact error definition.
@return true if obj is valid using schema
Validate object obj using schema object schema and root schema at root
using some external references provided.
@param schema schema object
@param obj object to validate
@param root root schema object
@param ext_refs external references (might be modified during validation)
@param err error pointer, if this parameter is not NULL and error has been
occurred, then err is filled with the exact error definition.
@return true if obj is valid using schema
Load new chunk to a parser
@param parser parser structure
@param data the pointer to the beginning of a chunk
@param len the length of a chunk
@return true if chunk has been added and false in case of error
Full version of ucl_add_chunk with priority and duplicate strategy
@param parser parser structure
@param data the pointer to the beginning of a chunk
@param len the length of a chunk
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@param strat duplicates merging strategy
@param parse_type input format
@return true if chunk has been added and false in case of error
Load new chunk to a parser with the specified priority
@param parser parser structure
@param data the pointer to the beginning of a chunk
@param len the length of a chunk
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@return true if chunk has been added and false in case of error
Load and add data from a file descriptor
@param parser parser structure
@param filename the name of file
@param err if *err is NULL it is set to parser error
@return true if chunk has been added and false in case of error
Load and add data from a file descriptor
@param parser parser structure
@param filename the name of file
@param err if *err is NULL it is set to parser error
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@param strat Merge strategy to use while parsing this file
@param parse_type Parser type to use while parsing this file
@return true if chunk has been added and false in case of error
Load and add data from a file descriptor
@param parser parser structure
@param filename the name of file
@param err if *err is NULL it is set to parser error
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@return true if chunk has been added and false in case of error
Load and add data from a file
@param parser parser structure
@param filename the name of file
@param err if *err is NULL it is set to parser error
@return true if chunk has been added and false in case of error
Load and add data from a file
@param parser parser structure
@param filename the name of file
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@param strat Merge strategy to use while parsing this file
@param parse_type Parser type to use while parsing this file
@return true if chunk has been added and false in case of error
Load and add data from a file
@param parser parser structure
@param filename the name of file
@param err if *err is NULL it is set to parser error
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@return true if chunk has been added and false in case of error
Load ucl object from a string
@param parser parser structure
@param data the pointer to the string
@param len the length of the string, if len is 0 then data must be zero-terminated string
@return true if string has been added and false in case of error
Load ucl object from a string
@param parser parser structure
@param data the pointer to the string
@param len the length of the string, if len is 0 then data must be zero-terminated string
@param priority the desired priority of a chunk (only 4 least significant bits
are considered for this parameter)
@return true if string has been added and false in case of error
Peek at the character at the current chunk position
@param parser parser structure
@return current chunk position character
Skip the character at the current chunk position
@param parser parser structure
@return success boolean
Clear the error in the parser
@param parser parser object
Free ucl parser object
@param parser parser object
Get the current column number within parser
@param parser parser object
@return current column number
Get constant opaque pointer to comments structure for this parser. Increase
refcount to prevent this object to be destroyed on parser’s destruction
@param parser parser structure
@return ucl comments pointer or NULL
Get the current stack object as stack accessor function for use in macro
functions (refcount is increased)
@param parser parser object
@param depth depth of stack to retrieve (top is 0)
@return current stack object or NULL
Gets the default priority for the parser applied to chunks that do not
specify priority explicitly
@param parser parser object
@return true default priority (0 .. 16), -1 for failure
Get the error string if parsing has been failed
@param parser parser object
@return error description
Get the code of the last error
@param parser parser object
@return error code
Get the current line number within parser
@param parser parser object
@return current line number
Get a top object for a parser (refcount is increased)
@param parser parser structure
@param err if *err is NULL it is set to parser error
@return top parser object or NULL
Insert new chunk to a parser (must have previously processed data with an existing top object)
@param parser parser structure
@param data the pointer to the beginning of a chunk
@param len the length of a chunk
@return true if chunk has been added and false in case of error
Creates new parser object
@param pool pool to allocate memory from
@return new parser object
Add new public key to parser for signatures check
@param parser parser object
@param key PEM representation of a key
@param len length of the key
@param err if *err is NULL it is set to parser error
@return true if a key has been successfully added
Register new context dependent handler for a macro
@param parser parser object
@param macro macro name (without leading dot)
@param handler handler (it is called immediately after macro is parsed)
@param ud opaque user data for a handler
Register new handler for a macro
@param parser parser object
@param macro macro name (without leading dot)
@param handler handler (it is called immediately after macro is parsed)
@param ud opaque user data for a handler
Register new parser variable
@param parser parser object
@param var variable name
@param value variable value
Sets the default priority for the parser applied to chunks that do not
specify priority explicitly
@param parser parser object
@param prio default priority (0 .. 16)
@return true if parser’s default priority was set
Set FILENAME and CURDIR variables in parser
@param parser parser object
@param filename filename to set or NULL to set FILENAME to “undef” and CURDIR to getcwd()
@param need_expand perform realpath() if this variable is true and filename is not NULL
@return true if variables has been set
Set handler for unknown variables
@param parser parser structure
@param handler desired handler
@param ud opaque data for the handler
Provide a UCL_ARRAY of paths to search for include files. The object is
copied so caller must unref the object.
@param parser parser structure
@param paths UCL_ARRAY of paths to search
@return true if the path search array was replaced in the parser