1 /* Copyright (c) 2013, Vsevolod Stakhov
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above copyright
9 * notice, this list of conditions and the following disclaimer in the
10 * documentation and/or other materials provided with the distribution.
12 * THIS SOFTWARE IS PROVIDED ''AS IS'' AND ANY
13 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
14 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
15 * DISCLAIMED. IN NO EVENT SHALL AUTHOR BE LIABLE FOR ANY
16 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
17 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
18 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
19 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
20 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
21 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 # define UCL_EXTERN __declspec(dllexport)
43 * This is a reference manual for UCL API. You may find the description of UCL format by following this
44 * [github repository](https://github.com/vstakhov/libucl).
46 * This manual has several main sections:
55 * @brief UCL parsing and emitting functions
57 * UCL is universal configuration language, which is a form of
58 * JSON with less strict rules that make it more comfortable for
59 * using as a configuration language
65 * Memory allocation utilities
66 * UCL_ALLOC(size) - allocate memory for UCL
67 * UCL_FREE(size, ptr) - free memory of specified size at ptr
68 * Default: malloc and free
71 #define UCL_ALLOC(size) malloc(size)
74 #define UCL_FREE(size, ptr) free(ptr)
77 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
78 #define UCL_WARN_UNUSED_RESULT \
79 __attribute__((warn_unused_result))
81 #define UCL_WARN_UNUSED_RESULT
85 #define UCL_DEPRECATED(func) func __attribute__ ((deprecated))
86 #elif defined(_MSC_VER)
87 #define UCL_DEPRECATED(func) __declspec(deprecated) func
89 #define UCL_DEPRECATED(func) func
93 * @defgroup structures Structures and types
94 * UCL defines several enumeration types used for error reporting or specifying flags and attributes.
100 * The common error codes returned by ucl parser
102 typedef enum ucl_error {
103 UCL_EOK = 0, /**< No error */
104 UCL_ESYNTAX, /**< Syntax error occurred during parsing */
105 UCL_EIO, /**< IO error occurred during parsing */
106 UCL_ESTATE, /**< Invalid state machine state */
107 UCL_ENESTED, /**< Input has too many recursion levels */
108 UCL_EMACRO, /**< Error processing a macro */
109 UCL_EINTERNAL, /**< Internal unclassified error */
110 UCL_ESSL /**< SSL error */
114 * #ucl_object_t may have one of specified types, some types are compatible with each other and some are not.
115 * For example, you can always convert #UCL_TIME to #UCL_FLOAT. Also you can convert #UCL_FLOAT to #UCL_INTEGER
116 * by loosing floating point. Every object may be converted to a string by #ucl_object_tostring_forced() function.
119 typedef enum ucl_type {
120 UCL_OBJECT = 0, /**< UCL object - key/value pairs */
121 UCL_ARRAY, /**< UCL array */
122 UCL_INT, /**< Integer number */
123 UCL_FLOAT, /**< Floating point number */
124 UCL_STRING, /**< Null terminated string */
125 UCL_BOOLEAN, /**< Boolean value */
126 UCL_TIME, /**< Time value (floating point number of seconds) */
127 UCL_USERDATA, /**< Opaque userdata pointer (may be used in macros) */
128 UCL_NULL /**< Null value */
132 * You can use one of these types to serialise #ucl_object_t by using ucl_object_emit().
134 typedef enum ucl_emitter {
135 UCL_EMIT_JSON = 0, /**< Emit fine formatted JSON */
136 UCL_EMIT_JSON_COMPACT, /**< Emit compacted JSON */
137 UCL_EMIT_CONFIG, /**< Emit human readable config format */
138 UCL_EMIT_YAML /**< Emit embedded YAML format */
142 * These flags defines parser behaviour. If you specify #UCL_PARSER_ZEROCOPY you must ensure
143 * that the input memory is not freed if an object is in use. Moreover, if you want to use
144 * zero-terminated keys and string values then you should not use zero-copy mode, as in this case
145 * UCL still has to perform copying implicitly.
147 typedef enum ucl_parser_flags {
148 UCL_PARSER_KEY_LOWERCASE = 0x1, /**< Convert all keys to lower case */
149 UCL_PARSER_ZEROCOPY = 0x2, /**< Parse input in zero-copy mode if possible */
150 UCL_PARSER_NO_TIME = 0x4, /**< Do not parse time and treat time values as strings */
151 UCL_PARSER_NO_IMPLICIT_ARRAYS = 0x8 /** Create explicit arrays instead of implicit ones */
152 } ucl_parser_flags_t;
155 * String conversion flags, that are used in #ucl_object_fromstring_common function.
157 typedef enum ucl_string_flags {
158 UCL_STRING_ESCAPE = 0x1, /**< Perform JSON escape */
159 UCL_STRING_TRIM = 0x2, /**< Trim leading and trailing whitespaces */
160 UCL_STRING_PARSE_BOOLEAN = 0x4, /**< Parse passed string and detect boolean */
161 UCL_STRING_PARSE_INT = 0x8, /**< Parse passed string and detect integer number */
162 UCL_STRING_PARSE_DOUBLE = 0x10, /**< Parse passed string and detect integer or float number */
163 UCL_STRING_PARSE_TIME = 0x20, /**< Parse time strings */
164 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE|UCL_STRING_PARSE_TIME, /**<
165 Parse passed string and detect number */
166 UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER, /**<
167 Parse passed string (and detect booleans and numbers) */
168 UCL_STRING_PARSE_BYTES = 0x40 /**< Treat numbers as bytes */
169 } ucl_string_flags_t;
172 * Basic flags for an object
174 typedef enum ucl_object_flags {
175 UCL_OBJECT_ALLOCATED_KEY = 0x1, /**< An object has key allocated internally */
176 UCL_OBJECT_ALLOCATED_VALUE = 0x2, /**< An object has a string value allocated internally */
177 UCL_OBJECT_NEED_KEY_ESCAPE = 0x4, /**< The key of an object need to be escaped on output */
178 UCL_OBJECT_EPHEMERAL = 0x8, /**< Temporary object that does not need to be freed really */
179 UCL_OBJECT_MULTILINE = 0x10, /**< String should be displayed as multiline string */
180 UCL_OBJECT_MULTIVALUE = 0x20 /**< Object is a key with multiple values */
181 } ucl_object_flags_t;
184 * UCL object structure. Please mention that the most of fields should not be touched by
185 * UCL users. In future, this structure may be converted to private one.
187 typedef struct ucl_object_s {
192 int64_t iv; /**< Int value of an object */
193 const char *sv; /**< String value of an object */
194 double dv; /**< Double value of an object */
195 void *av; /**< Array */
196 void *ov; /**< Object */
197 void* ud; /**< Opaque user data */
199 const char *key; /**< Key of an object */
200 struct ucl_object_s *next; /**< Array handle */
201 struct ucl_object_s *prev; /**< Array handle */
202 uint32_t keylen; /**< Lenght of a key */
203 uint32_t len; /**< Size of an object */
204 uint32_t ref; /**< Reference count */
205 uint16_t flags; /**< Object flags */
206 uint16_t type; /**< Real type */
207 unsigned char* trash_stack[2]; /**< Pointer to allocated chunks */
211 * Destructor type for userdata objects
212 * @param ud user specified data pointer
214 typedef void (*ucl_userdata_dtor)(void *ud);
215 typedef const char* (*ucl_userdata_emitter)(void *ud);
220 * @defgroup utils Utility functions
221 * A number of utility functions simplify handling of UCL objects
226 * Copy and return a key of an object, returned key is zero-terminated
227 * @param obj CL object
228 * @return zero terminated key
230 UCL_EXTERN char* ucl_copy_key_trash (const ucl_object_t *obj);
233 * Copy and return a string value of an object, returned key is zero-terminated
234 * @param obj CL object
235 * @return zero terminated string representation of object value
237 UCL_EXTERN char* ucl_copy_value_trash (const ucl_object_t *obj);
240 * Creates a new object
243 UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT;
246 * Create new object with type specified
247 * @param type type of a new object
250 UCL_EXTERN ucl_object_t* ucl_object_typed_new (ucl_type_t type) UCL_WARN_UNUSED_RESULT;
253 * Create new object with type and priority specified
254 * @param type type of a new object
255 * @param priority priority of an object
258 UCL_EXTERN ucl_object_t* ucl_object_new_full (ucl_type_t type, unsigned priority)
259 UCL_WARN_UNUSED_RESULT;
262 * Create new object with userdata dtor
263 * @param dtor destructor function
266 UCL_EXTERN ucl_object_t* ucl_object_new_userdata (ucl_userdata_dtor dtor,
267 ucl_userdata_emitter emitter) UCL_WARN_UNUSED_RESULT;
270 * Perform deep copy of an object copying everything
271 * @param other object to copy
272 * @return new object with refcount equal to 1
274 UCL_EXTERN ucl_object_t * ucl_object_copy (const ucl_object_t *other)
275 UCL_WARN_UNUSED_RESULT;
278 * Return the type of an object
279 * @return the object type
281 UCL_EXTERN ucl_type_t ucl_object_type (const ucl_object_t *obj);
284 * Convert any string to an ucl object making the specified transformations
285 * @param str fixed size or NULL terminated string
286 * @param len length (if len is zero, than str is treated as NULL terminated)
287 * @param flags conversion flags
290 UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len,
291 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT;
294 * Create a UCL object from the specified string
295 * @param str NULL terminated string, will be json escaped
298 UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str) UCL_WARN_UNUSED_RESULT;
301 * Create a UCL object from the specified string
302 * @param str fixed size string, will be json escaped
303 * @param len length of a string
306 UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str,
307 size_t len) UCL_WARN_UNUSED_RESULT;
310 * Create an object from an integer number
314 UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv) UCL_WARN_UNUSED_RESULT;
317 * Create an object from a float number
321 UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv) UCL_WARN_UNUSED_RESULT;
324 * Create an object from a boolean
325 * @param bv bool value
328 UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv) UCL_WARN_UNUSED_RESULT;
331 * Insert a object 'elt' to the hash 'top' and associate it with key 'key'
332 * @param top destination object (must be of type UCL_OBJECT)
333 * @param elt element to insert (must NOT be NULL)
334 * @param key key to associate with this object (either const or preallocated)
335 * @param keylen length of the key (or 0 for NULL terminated keys)
336 * @param copy_key make an internal copy of key
337 * @return true if key has been inserted
339 UCL_EXTERN bool ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt,
340 const char *key, size_t keylen, bool copy_key);
343 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
344 * if no object has been found this function works like ucl_object_insert_key()
345 * @param top destination object (must be of type UCL_OBJECT)
346 * @param elt element to insert (must NOT be NULL)
347 * @param key key to associate with this object (either const or preallocated)
348 * @param keylen length of the key (or 0 for NULL terminated keys)
349 * @param copy_key make an internal copy of key
350 * @return true if key has been inserted
352 UCL_EXTERN bool ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt,
353 const char *key, size_t keylen, bool copy_key);
356 * Merge the keys from one object to another object. Overwrite on conflict
357 * @param top destination object (must be of type UCL_OBJECT)
358 * @param elt element to insert (must be of type UCL_OBJECT)
359 * @param copy copy rather than reference the elements
360 * @return true if all keys have been merged
362 UCL_EXTERN bool ucl_object_merge (ucl_object_t *top, ucl_object_t *elt, bool copy);
365 * Delete a object associated with key 'key', old object will be unrefered,
367 * @param key key associated to the object to remove
368 * @param keylen length of the key (or 0 for NULL terminated keys)
370 UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top,
371 const char *key, size_t keylen);
374 * Delete a object associated with key 'key', old object will be unrefered,
376 * @param key key associated to the object to remove
378 UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top,
383 * Removes `key` from `top` object, returning the object that was removed. This
384 * object is not released, caller must unref the returned object when it is no
387 * @param key key to remove
388 * @param keylen length of the key (or 0 for NULL terminated keys)
389 * @return removed object or NULL if object has not been found
391 UCL_EXTERN ucl_object_t* ucl_object_pop_keyl (ucl_object_t *top, const char *key,
392 size_t keylen) UCL_WARN_UNUSED_RESULT;
395 * Removes `key` from `top` object returning the object that was removed. This
396 * object is not released, caller must unref the returned object when it is no
399 * @param key key to remove
400 * @return removed object or NULL if object has not been found
402 UCL_EXTERN ucl_object_t* ucl_object_pop_key (ucl_object_t *top, const char *key)
403 UCL_WARN_UNUSED_RESULT;
406 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if
407 * the specified key exist, try to merge its content
408 * @param top destination object (must be of type UCL_OBJECT)
409 * @param elt element to insert (must NOT be NULL)
410 * @param key key to associate with this object (either const or preallocated)
411 * @param keylen length of the key (or 0 for NULL terminated keys)
412 * @param copy_key make an internal copy of key
413 * @return true if key has been inserted
415 UCL_EXTERN bool ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt,
416 const char *key, size_t keylen, bool copy_key);
419 * Append an element to the end of array object
420 * @param top destination object (must NOT be NULL)
421 * @param elt element to append (must NOT be NULL)
422 * @return true if value has been inserted
424 UCL_EXTERN bool ucl_array_append (ucl_object_t *top,
428 * Append an element to the start of array object
429 * @param top destination object (must NOT be NULL)
430 * @param elt element to append (must NOT be NULL)
431 * @return true if value has been inserted
433 UCL_EXTERN bool ucl_array_prepend (ucl_object_t *top,
437 * Merge all elements of second array into the first array
438 * @param top destination array (must be of type UCL_ARRAY)
439 * @param elt array to copy elements from (must be of type UCL_ARRAY)
440 * @param copy copy elements instead of referencing them
441 * @return true if arrays were merged
443 UCL_EXTERN bool ucl_array_merge (ucl_object_t *top, ucl_object_t *elt,
447 * Removes an element `elt` from the array `top`, returning the object that was
448 * removed. This object is not released, caller must unref the returned object
449 * when it is no longer needed.
450 * @param top array ucl object
451 * @param elt element to remove
452 * @return removed element or NULL if `top` is NULL or not an array
454 UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top,
458 * Returns the first element of the array `top`
459 * @param top array ucl object
460 * @return element or NULL if `top` is NULL or not an array
462 UCL_EXTERN const ucl_object_t* ucl_array_head (const ucl_object_t *top);
465 * Returns the last element of the array `top`
466 * @param top array ucl object
467 * @return element or NULL if `top` is NULL or not an array
469 UCL_EXTERN const ucl_object_t* ucl_array_tail (const ucl_object_t *top);
472 * Removes the last element from the array `top`, returning the object that was
473 * removed. This object is not released, caller must unref the returned object
474 * when it is no longer needed.
475 * @param top array ucl object
476 * @return removed element or NULL if `top` is NULL or not an array
478 UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top);
481 * Removes the first element from the array `top`, returning the object that was
482 * removed. This object is not released, caller must unref the returned object
483 * when it is no longer needed.
484 * @param top array ucl object
485 * @return removed element or NULL if `top` is NULL or not an array
487 UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top);
490 * Return object identified by index of the array `top`
491 * @param top object to get a key from (must be of type UCL_ARRAY)
492 * @param index array index to return
493 * @return object at the specified index or NULL if index is not found
495 UCL_EXTERN const ucl_object_t* ucl_array_find_index (const ucl_object_t *top,
499 * Replace an element in an array with a different element, returning the object
500 * that was replaced. This object is not released, caller must unref the
501 * returned object when it is no longer needed.
502 * @param top destination object (must be of type UCL_ARRAY)
503 * @param elt element to append (must NOT be NULL)
504 * @param index array index in destination to overwrite with elt
505 * @return object that was replaced or NULL if index is not found
508 ucl_array_replace_index (ucl_object_t *top, ucl_object_t *elt,
512 * Append a element to another element forming an implicit array
513 * @param head head to append (may be NULL)
514 * @param elt new element
515 * @return the new implicit array
517 UCL_EXTERN ucl_object_t * ucl_elt_append (ucl_object_t *head,
521 * Converts an object to double value
522 * @param obj CL object
523 * @param target target double variable
524 * @return true if conversion was successful
526 UCL_EXTERN bool ucl_object_todouble_safe (const ucl_object_t *obj, double *target);
529 * Unsafe version of \ref ucl_obj_todouble_safe
530 * @param obj CL object
531 * @return double value
533 UCL_EXTERN double ucl_object_todouble (const ucl_object_t *obj);
536 * Converts an object to integer value
537 * @param obj CL object
538 * @param target target integer variable
539 * @return true if conversion was successful
541 UCL_EXTERN bool ucl_object_toint_safe (const ucl_object_t *obj, int64_t *target);
544 * Unsafe version of \ref ucl_obj_toint_safe
545 * @param obj CL object
548 UCL_EXTERN int64_t ucl_object_toint (const ucl_object_t *obj);
551 * Converts an object to boolean value
552 * @param obj CL object
553 * @param target target boolean variable
554 * @return true if conversion was successful
556 UCL_EXTERN bool ucl_object_toboolean_safe (const ucl_object_t *obj, bool *target);
559 * Unsafe version of \ref ucl_obj_toboolean_safe
560 * @param obj CL object
561 * @return boolean value
563 UCL_EXTERN bool ucl_object_toboolean (const ucl_object_t *obj);
566 * Converts an object to string value
567 * @param obj CL object
568 * @param target target string variable, no need to free value
569 * @return true if conversion was successful
571 UCL_EXTERN bool ucl_object_tostring_safe (const ucl_object_t *obj, const char **target);
574 * Unsafe version of \ref ucl_obj_tostring_safe
575 * @param obj CL object
576 * @return string value
578 UCL_EXTERN const char* ucl_object_tostring (const ucl_object_t *obj);
581 * Convert any object to a string in JSON notation if needed
582 * @param obj CL object
583 * @return string value
585 UCL_EXTERN const char* ucl_object_tostring_forced (const ucl_object_t *obj);
588 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
589 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
590 * @param obj CL object
591 * @param target target string variable, no need to free value
592 * @param tlen target length
593 * @return true if conversion was successful
595 UCL_EXTERN bool ucl_object_tolstring_safe (const ucl_object_t *obj,
596 const char **target, size_t *tlen);
599 * Unsafe version of \ref ucl_obj_tolstring_safe
600 * @param obj CL object
601 * @return string value
603 UCL_EXTERN const char* ucl_object_tolstring (const ucl_object_t *obj, size_t *tlen);
606 * Return object identified by a key in the specified object
607 * @param obj object to get a key from (must be of type UCL_OBJECT)
608 * @param key key to search
609 * @return object matching the specified key or NULL if key was not found
611 UCL_EXTERN const ucl_object_t* ucl_object_find_key (const ucl_object_t *obj,
615 * Return object identified by a fixed size key in the specified object
616 * @param obj object to get a key from (must be of type UCL_OBJECT)
617 * @param key key to search
618 * @param klen length of a key
619 * @return object matching the specified key or NULL if key was not found
621 UCL_EXTERN const ucl_object_t* ucl_object_find_keyl (const ucl_object_t *obj,
622 const char *key, size_t klen);
625 * Return object identified by dot notation string
626 * @param obj object to search in
627 * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
628 * @return object matched the specified path or NULL if path is not found
630 UCL_EXTERN const ucl_object_t *ucl_lookup_path (const ucl_object_t *obj,
634 * Returns a key of an object as a NULL terminated string
635 * @param obj CL object
636 * @return key or NULL if there is no key
638 UCL_EXTERN const char* ucl_object_key (const ucl_object_t *obj);
641 * Returns a key of an object as a fixed size string (may be more efficient)
642 * @param obj CL object
643 * @param len target key length
644 * @return key pointer
646 UCL_EXTERN const char* ucl_object_keyl (const ucl_object_t *obj, size_t *len);
649 * Increase reference count for an object
650 * @param obj object to ref
651 * @return the referenced object
653 UCL_EXTERN ucl_object_t* ucl_object_ref (const ucl_object_t *obj);
657 * @param obj ucl object to free
659 UCL_DEPRECATED(UCL_EXTERN void ucl_object_free (ucl_object_t *obj));
662 * Decrease reference count for an object
663 * @param obj object to unref
665 UCL_EXTERN void ucl_object_unref (ucl_object_t *obj);
668 * Compare objects `o1` and `o2`
669 * @param o1 the first object
670 * @param o2 the second object
671 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
672 * The order of comparison:
675 * 3) Content of objects
677 UCL_EXTERN int ucl_object_compare (const ucl_object_t *o1,
678 const ucl_object_t *o2);
681 * Sort UCL array using `cmp` compare function
685 UCL_EXTERN void ucl_object_array_sort (ucl_object_t *ar,
686 int (*cmp)(const ucl_object_t *o1, const ucl_object_t *o2));
689 * Get the priority for specific UCL object
690 * @param obj any ucl object
691 * @return priority of an object
693 UCL_EXTERN unsigned int ucl_object_get_priority (const ucl_object_t *obj);
696 * Set explicit priority of an object.
697 * @param obj any ucl object
698 * @param priority new priroity value (only 4 least significant bits are considred)
700 UCL_EXTERN void ucl_object_set_priority (ucl_object_t *obj,
701 unsigned int priority);
704 * Opaque iterator object
706 typedef void* ucl_object_iter_t;
709 * Get next key from an object
710 * @param obj object to iterate
711 * @param iter opaque iterator, must be set to NULL on the first call:
712 * ucl_object_iter_t it = NULL;
713 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
714 * @return the next object or NULL
716 UCL_EXTERN const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj,
717 ucl_object_iter_t *iter, bool expand_values);
720 * Create new safe iterator for the specified object
721 * @param obj object to iterate
722 * @return new iterator object that should be used with safe iterators API only
724 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_new (const ucl_object_t *obj)
725 UCL_WARN_UNUSED_RESULT;
727 * Reset initialized iterator to a new object
728 * @param obj new object to iterate
729 * @return modified iterator object
731 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_reset (ucl_object_iter_t it,
732 const ucl_object_t *obj);
735 * Get the next object from the `obj`. This fucntion iterates over arrays, objects
736 * and implicit arrays
737 * @param iter safe iterator
738 * @return the next object in sequence
740 UCL_EXTERN const ucl_object_t* ucl_object_iterate_safe (ucl_object_iter_t iter,
744 * Free memory associated with the safe iterator
745 * @param it safe iterator object
747 UCL_EXTERN void ucl_object_iterate_free (ucl_object_iter_t it);
753 * @defgroup parser Parsing functions
754 * These functions are used to parse UCL objects
760 * Macro handler for a parser
761 * @param data the content of macro
762 * @param len the length of content
763 * @param arguments arguments object
764 * @param ud opaque user data
765 * @param err error pointer
766 * @return true if macro has been parsed
768 typedef bool (*ucl_macro_handler) (const unsigned char *data, size_t len,
769 const ucl_object_t *arguments,
776 * Creates new parser object
777 * @param pool pool to allocate memory from
778 * @return new parser object
780 UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags);
783 * Register new handler for a macro
784 * @param parser parser object
785 * @param macro macro name (without leading dot)
786 * @param handler handler (it is called immediately after macro is parsed)
787 * @param ud opaque user data for a handler
789 UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser, const char *macro,
790 ucl_macro_handler handler, void* ud);
793 * Handler to detect unregistered variables
794 * @param data variable data
795 * @param len length of variable
796 * @param replace (out) replace value for variable
797 * @param replace_len (out) replace length for variable
798 * @param need_free (out) UCL will free `dest` after usage
799 * @param ud opaque userdata
800 * @return true if variable
802 typedef bool (*ucl_variable_handler) (const unsigned char *data, size_t len,
803 unsigned char **replace, size_t *replace_len, bool *need_free, void* ud);
806 * Register new parser variable
807 * @param parser parser object
808 * @param var variable name
809 * @param value variable value
811 UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var,
815 * Set handler for unknown variables
816 * @param parser parser structure
817 * @param handler desired handler
818 * @param ud opaque data for the handler
820 UCL_EXTERN void ucl_parser_set_variables_handler (struct ucl_parser *parser,
821 ucl_variable_handler handler, void *ud);
824 * Load new chunk to a parser
825 * @param parser parser structure
826 * @param data the pointer to the beginning of a chunk
827 * @param len the length of a chunk
828 * @return true if chunk has been added and false in case of error
830 UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser,
831 const unsigned char *data, size_t len);
834 * Load new chunk to a parser with the specified priority
835 * @param parser parser structure
836 * @param data the pointer to the beginning of a chunk
837 * @param len the length of a chunk
838 * @param priority the desired priority of a chunk (only 4 least significant bits
839 * are considered for this parameter)
840 * @return true if chunk has been added and false in case of error
842 UCL_EXTERN bool ucl_parser_add_chunk_priority (struct ucl_parser *parser,
843 const unsigned char *data, size_t len, unsigned priority);
846 * Load ucl object from a string
847 * @param parser parser structure
848 * @param data the pointer to the string
849 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
850 * @return true if string has been added and false in case of error
852 UCL_EXTERN bool ucl_parser_add_string (struct ucl_parser *parser,
853 const char *data,size_t len);
856 * Load and add data from a file
857 * @param parser parser structure
858 * @param filename the name of file
859 * @param err if *err is NULL it is set to parser error
860 * @return true if chunk has been added and false in case of error
862 UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser,
863 const char *filename);
866 * Load and add data from a file descriptor
867 * @param parser parser structure
868 * @param filename the name of file
869 * @param err if *err is NULL it is set to parser error
870 * @return true if chunk has been added and false in case of error
872 UCL_EXTERN bool ucl_parser_add_fd (struct ucl_parser *parser,
876 * Get a top object for a parser (refcount is increased)
877 * @param parser parser structure
878 * @param err if *err is NULL it is set to parser error
879 * @return top parser object or NULL
881 UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);
884 * Get the error string if failing
885 * @param parser parser object
887 UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser);
890 * Clear the error in the parser
891 * @param parser parser object
893 UCL_EXTERN void ucl_parser_clear_error(struct ucl_parser *parser);
896 * Free ucl parser object
897 * @param parser parser object
899 UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser);
902 * Add new public key to parser for signatures check
903 * @param parser parser object
904 * @param key PEM representation of a key
905 * @param len length of the key
906 * @param err if *err is NULL it is set to parser error
907 * @return true if a key has been successfully added
909 UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len);
912 * Set FILENAME and CURDIR variables in parser
913 * @param parser parser object
914 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd()
915 * @param need_expand perform realpath() if this variable is true and filename is not NULL
916 * @return true if variables has been set
918 UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename,
924 * @defgroup emitter Emitting functions
925 * These functions are used to serialise UCL objects to some string representation.
930 struct ucl_emitter_context;
932 * Structure using for emitter callbacks
934 struct ucl_emitter_functions {
935 /** Append a single character */
936 int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud);
937 /** Append a string of a specified length */
938 int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud);
939 /** Append a 64 bit integer */
940 int (*ucl_emitter_append_int) (int64_t elt, void *ud);
941 /** Append floating point element */
942 int (*ucl_emitter_append_double) (double elt, void *ud);
944 void (*ucl_emitter_free_func)(void *ud);
945 /** Opaque userdata pointer */
949 struct ucl_emitter_operations {
950 /** Write a primitive element */
951 void (*ucl_emitter_write_elt) (struct ucl_emitter_context *ctx,
952 const ucl_object_t *obj, bool first, bool print_key);
953 /** Start ucl object */
954 void (*ucl_emitter_start_object) (struct ucl_emitter_context *ctx,
955 const ucl_object_t *obj, bool print_key);
956 /** End ucl object */
957 void (*ucl_emitter_end_object) (struct ucl_emitter_context *ctx,
958 const ucl_object_t *obj);
959 /** Start ucl array */
960 void (*ucl_emitter_start_array) (struct ucl_emitter_context *ctx,
961 const ucl_object_t *obj, bool print_key);
962 void (*ucl_emitter_end_array) (struct ucl_emitter_context *ctx,
963 const ucl_object_t *obj);
967 * Structure that defines emitter functions
969 struct ucl_emitter_context {
970 /** Name of emitter (e.g. json, compact_json) */
972 /** Unique id (e.g. UCL_EMIT_JSON for standard emitters */
974 /** A set of output functions */
975 const struct ucl_emitter_functions *func;
976 /** A set of output operations */
977 const struct ucl_emitter_operations *ops;
978 /** Current amount of indent tabs */
980 /** Top level object */
981 const ucl_object_t *top;
982 /** The rest of context */
983 unsigned char data[1];
987 * Emit object to a string
989 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
990 * #UCL_EMIT_CONFIG then emit config like object
991 * @return dump of an object (must be freed after using) or NULL in case of error
993 UCL_EXTERN unsigned char *ucl_object_emit (const ucl_object_t *obj,
994 enum ucl_emitter emit_type);
997 * Emit object to a string
999 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1000 * #UCL_EMIT_CONFIG then emit config like object
1001 * @param emitter a set of emitter functions
1002 * @return dump of an object (must be freed after using) or NULL in case of error
1004 UCL_EXTERN bool ucl_object_emit_full (const ucl_object_t *obj,
1005 enum ucl_emitter emit_type,
1006 struct ucl_emitter_functions *emitter);
1009 * Start streamlined UCL object emitter
1010 * @param obj top UCL object
1011 * @param emit_type emit type
1012 * @param emitter a set of emitter functions
1013 * @return new streamlined context that should be freed by
1014 * `ucl_object_emit_streamline_finish`
1016 UCL_EXTERN struct ucl_emitter_context* ucl_object_emit_streamline_new (
1017 const ucl_object_t *obj, enum ucl_emitter emit_type,
1018 struct ucl_emitter_functions *emitter);
1021 * Start object or array container for the streamlined output
1022 * @param ctx streamlined context
1023 * @param obj container object
1025 UCL_EXTERN void ucl_object_emit_streamline_start_container (
1026 struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1028 * Add a complete UCL object to streamlined output
1029 * @param ctx streamlined context
1030 * @param obj object to output
1032 UCL_EXTERN void ucl_object_emit_streamline_add_object (
1033 struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1035 * End previously added container
1036 * @param ctx streamlined context
1038 UCL_EXTERN void ucl_object_emit_streamline_end_container (
1039 struct ucl_emitter_context *ctx);
1041 * Terminate streamlined container finishing all containers in it
1042 * @param ctx streamlined context
1044 UCL_EXTERN void ucl_object_emit_streamline_finish (
1045 struct ucl_emitter_context *ctx);
1048 * Returns functions to emit object to memory
1049 * @param pmem target pointer (should be freed by caller)
1050 * @return emitter functions structure
1052 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_memory_funcs (
1056 * Returns functions to emit object to FILE *
1057 * @param fp FILE * object
1058 * @return emitter functions structure
1060 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_file_funcs (
1063 * Returns functions to emit object to a file descriptor
1064 * @param fd file descriptor
1065 * @return emitter functions structure
1067 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_fd_funcs (
1071 * Free emitter functions
1072 * @param f pointer to functions
1074 UCL_EXTERN void ucl_object_emit_funcs_free (struct ucl_emitter_functions *f);
1079 * @defgroup schema Schema functions
1080 * These functions are used to validate UCL objects using json schema format
1086 * Used to define UCL schema error
1088 enum ucl_schema_error_code {
1089 UCL_SCHEMA_OK = 0, /**< no error */
1090 UCL_SCHEMA_TYPE_MISMATCH, /**< type of object is incorrect */
1091 UCL_SCHEMA_INVALID_SCHEMA, /**< schema is invalid */
1092 UCL_SCHEMA_MISSING_PROPERTY,/**< one or more missing properties */
1093 UCL_SCHEMA_CONSTRAINT, /**< constraint found */
1094 UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */
1095 UCL_SCHEMA_UNKNOWN /**< generic error */
1099 * Generic ucl schema error
1101 struct ucl_schema_error {
1102 enum ucl_schema_error_code code; /**< error code */
1103 char msg[128]; /**< error message */
1104 const ucl_object_t *obj; /**< object where error occured */
1108 * Validate object `obj` using schema object `schema`.
1109 * @param schema schema object
1110 * @param obj object to validate
1111 * @param err error pointer, if this parameter is not NULL and error has been
1112 * occured, then `err` is filled with the exact error definition.
1113 * @return true if `obj` is valid using `schema`
1115 UCL_EXTERN bool ucl_object_validate (const ucl_object_t *schema,
1116 const ucl_object_t *obj, struct ucl_schema_error *err);
1124 * XXX: Poorly named API functions, need to replace them with the appropriate
1125 * named function. All API functions *must* use naming ucl_object_*. Usage of
1126 * ucl_obj* should be avoided.
1128 #define ucl_obj_todouble_safe ucl_object_todouble_safe
1129 #define ucl_obj_todouble ucl_object_todouble
1130 #define ucl_obj_tostring ucl_object_tostring
1131 #define ucl_obj_tostring_safe ucl_object_tostring_safe
1132 #define ucl_obj_tolstring ucl_object_tolstring
1133 #define ucl_obj_tolstring_safe ucl_object_tolstring_safe
1134 #define ucl_obj_toint ucl_object_toint
1135 #define ucl_obj_toint_safe ucl_object_toint_safe
1136 #define ucl_obj_toboolean ucl_object_toboolean
1137 #define ucl_obj_toboolean_safe ucl_object_toboolean_safe
1138 #define ucl_obj_get_key ucl_object_find_key
1139 #define ucl_obj_get_keyl ucl_object_find_keyl
1140 #define ucl_obj_unref ucl_object_unref
1141 #define ucl_obj_ref ucl_object_ref
1142 #define ucl_obj_free ucl_object_free