UCL object structure. Please mention that the most of fields should not be touched by
UCL users. In future, this structure may be converted to private one.
These flags defines parser behaviour. If you specify #UCL_PARSER_ZEROCOPY you must ensure
that the input memory is not freed if an object is in use. Moreover, if you want to use
zero-terminated keys and string values then you should not use zero-copy mode, as in this case
UCL still has to perform copying implicitly.
#ucl_object_t may have one of specified types, some types are compatible with each other and some are not.
For example, you can always convert #UCL_TIME to #UCL_FLOAT. Also you can convert #UCL_FLOAT to #UCL_INTEGER
by loosing floating point. Every object may be converted to a string by #ucl_object_tostring_forced() function.
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
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
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
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
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:
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 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
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
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
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
Context dependent macro handler for a parser
@param data the content of macro
@param len the length of content
@param arguments arguments object
@param context previously parsed context
@param ud opaque user data
@param err error pointer
@return true if macro has been parsed
Macro handler for a parser
@param data the content of macro
@param len the length of content
@param arguments arguments object
@param ud opaque user data
@param err error pointer
@return true if macro has been parsed
Handler to detect unregistered variables
@param data variable data
@param len length of variable
@param replace (out) replace value for variable
@param replace_len (out) replace length for variable
@param need_free (out) UCL will free dest after usage
@param ud opaque userdata
@return true if variable