1 /* Copyright (c) 2013-2015, 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 */
111 UCL_EMERGE /**< A merge error occured */
115 * #ucl_object_t may have one of specified types, some types are compatible with each other and some are not.
116 * For example, you can always convert #UCL_TIME to #UCL_FLOAT. Also you can convert #UCL_FLOAT to #UCL_INTEGER
117 * by loosing floating point. Every object may be converted to a string by #ucl_object_tostring_forced() function.
120 typedef enum ucl_type {
121 UCL_OBJECT = 0, /**< UCL object - key/value pairs */
122 UCL_ARRAY, /**< UCL array */
123 UCL_INT, /**< Integer number */
124 UCL_FLOAT, /**< Floating point number */
125 UCL_STRING, /**< Null terminated string */
126 UCL_BOOLEAN, /**< Boolean value */
127 UCL_TIME, /**< Time value (floating point number of seconds) */
128 UCL_USERDATA, /**< Opaque userdata pointer (may be used in macros) */
129 UCL_NULL /**< Null value */
133 * You can use one of these types to serialise #ucl_object_t by using ucl_object_emit().
135 typedef enum ucl_emitter {
136 UCL_EMIT_JSON = 0, /**< Emit fine formatted JSON */
137 UCL_EMIT_JSON_COMPACT, /**< Emit compacted JSON */
138 UCL_EMIT_CONFIG, /**< Emit human readable config format */
139 UCL_EMIT_YAML, /**< Emit embedded YAML format */
140 UCL_EMIT_MSGPACK, /**< Emit msgpack output */
141 UCL_EMIT_MAX /**< Unsupported emitter type */
145 * These flags defines parser behaviour. If you specify #UCL_PARSER_ZEROCOPY you must ensure
146 * that the input memory is not freed if an object is in use. Moreover, if you want to use
147 * zero-terminated keys and string values then you should not use zero-copy mode, as in this case
148 * UCL still has to perform copying implicitly.
150 typedef enum ucl_parser_flags {
151 UCL_PARSER_DEFAULT = 0, /**< No special flags */
152 UCL_PARSER_KEY_LOWERCASE = (1 << 0), /**< Convert all keys to lower case */
153 UCL_PARSER_ZEROCOPY = (1 << 1), /**< Parse input in zero-copy mode if possible */
154 UCL_PARSER_NO_TIME = (1 << 2), /**< Do not parse time and treat time values as strings */
155 UCL_PARSER_NO_IMPLICIT_ARRAYS = (1 << 3), /** Create explicit arrays instead of implicit ones */
156 UCL_PARSER_SAVE_COMMENTS = (1 << 4), /** Save comments in the parser context */
157 UCL_PARSER_DISABLE_MACRO = (1 << 5), /** Treat macros as comments */
158 UCL_PARSER_NO_FILEVARS = (1 << 6) /** Do not set file vars */
159 } ucl_parser_flags_t;
162 * String conversion flags, that are used in #ucl_object_fromstring_common function.
164 typedef enum ucl_string_flags {
165 UCL_STRING_RAW = 0x0, /**< Treat string as is */
166 UCL_STRING_ESCAPE = (1 << 0), /**< Perform JSON escape */
167 UCL_STRING_TRIM = (1 << 1), /**< Trim leading and trailing whitespaces */
168 UCL_STRING_PARSE_BOOLEAN = (1 << 2), /**< Parse passed string and detect boolean */
169 UCL_STRING_PARSE_INT = (1 << 3), /**< Parse passed string and detect integer number */
170 UCL_STRING_PARSE_DOUBLE = (1 << 4), /**< Parse passed string and detect integer or float number */
171 UCL_STRING_PARSE_TIME = (1 << 5), /**< Parse time strings */
172 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE|UCL_STRING_PARSE_TIME, /**<
173 Parse passed string and detect number */
174 UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER, /**<
175 Parse passed string (and detect booleans and numbers) */
176 UCL_STRING_PARSE_BYTES = (1 << 6) /**< Treat numbers as bytes */
177 } ucl_string_flags_t;
180 * Basic flags for an object
182 typedef enum ucl_object_flags {
183 UCL_OBJECT_ALLOCATED_KEY = (1 << 0), /**< An object has key allocated internally */
184 UCL_OBJECT_ALLOCATED_VALUE = (1 << 1), /**< An object has a string value allocated internally */
185 UCL_OBJECT_NEED_KEY_ESCAPE = (1 << 2), /**< The key of an object need to be escaped on output */
186 UCL_OBJECT_EPHEMERAL = (1 << 3), /**< Temporary object that does not need to be freed really */
187 UCL_OBJECT_MULTILINE = (1 << 4), /**< String should be displayed as multiline string */
188 UCL_OBJECT_MULTIVALUE = (1 << 5), /**< Object is a key with multiple values */
189 UCL_OBJECT_INHERITED = (1 << 6), /**< Object has been inherited from another */
190 UCL_OBJECT_BINARY = (1 << 7) /**< Object contains raw binary data */
191 } ucl_object_flags_t;
194 * Duplicate policy types
196 enum ucl_duplicate_strategy {
197 UCL_DUPLICATE_APPEND = 0, /**< Default policy to merge based on priorities */
198 UCL_DUPLICATE_MERGE, /**< Merge new object with old one */
199 UCL_DUPLICATE_REWRITE, /**< Rewrite old keys */
200 UCL_DUPLICATE_ERROR /**< Stop parsing on duplicate found */
206 enum ucl_parse_type {
207 UCL_PARSE_UCL = 0, /**< Default ucl format */
208 UCL_PARSE_MSGPACK, /**< Message pack input format */
209 UCL_PARSE_CSEXP, /**< Canonical S-expressions */
210 UCL_PARSE_AUTO /**< Try to detect parse type */
214 * UCL object structure. Please mention that the most of fields should not be touched by
215 * UCL users. In future, this structure may be converted to private one.
217 typedef struct ucl_object_s {
222 int64_t iv; /**< Int value of an object */
223 const char *sv; /**< String value of an object */
224 double dv; /**< Double value of an object */
225 void *av; /**< Array */
226 void *ov; /**< Object */
227 void* ud; /**< Opaque user data */
229 const char *key; /**< Key of an object */
230 struct ucl_object_s *next; /**< Array handle */
231 struct ucl_object_s *prev; /**< Array handle */
232 uint32_t keylen; /**< Length of a key */
233 uint32_t len; /**< Size of an object */
234 uint32_t ref; /**< Reference count */
235 uint16_t flags; /**< Object flags */
236 uint16_t type; /**< Real type */
237 unsigned char* trash_stack[2]; /**< Pointer to allocated chunks */
241 * Destructor type for userdata objects
242 * @param ud user specified data pointer
244 typedef void (*ucl_userdata_dtor)(void *ud);
245 typedef const char* (*ucl_userdata_emitter)(void *ud);
250 * @defgroup utils Utility functions
251 * A number of utility functions simplify handling of UCL objects
256 * Copy and return a key of an object, returned key is zero-terminated
257 * @param obj CL object
258 * @return zero terminated key
260 UCL_EXTERN char* ucl_copy_key_trash (const ucl_object_t *obj);
263 * Copy and return a string value of an object, returned key is zero-terminated
264 * @param obj CL object
265 * @return zero terminated string representation of object value
267 UCL_EXTERN char* ucl_copy_value_trash (const ucl_object_t *obj);
270 * Creates a new object
273 UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT;
276 * Create new object with type specified
277 * @param type type of a new object
280 UCL_EXTERN ucl_object_t* ucl_object_typed_new (ucl_type_t type) UCL_WARN_UNUSED_RESULT;
283 * Create new object with type and priority specified
284 * @param type type of a new object
285 * @param priority priority of an object
288 UCL_EXTERN ucl_object_t* ucl_object_new_full (ucl_type_t type, unsigned priority)
289 UCL_WARN_UNUSED_RESULT;
292 * Create new object with userdata dtor
293 * @param dtor destructor function
294 * @param emitter emitter for userdata
295 * @param ptr opaque pointer
298 UCL_EXTERN ucl_object_t* ucl_object_new_userdata (ucl_userdata_dtor dtor,
299 ucl_userdata_emitter emitter, void *ptr) UCL_WARN_UNUSED_RESULT;
302 * Perform deep copy of an object copying everything
303 * @param other object to copy
304 * @return new object with refcount equal to 1
306 UCL_EXTERN ucl_object_t * ucl_object_copy (const ucl_object_t *other)
307 UCL_WARN_UNUSED_RESULT;
310 * Return the type of an object
311 * @return the object type
313 UCL_EXTERN ucl_type_t ucl_object_type (const ucl_object_t *obj);
316 * Converts ucl object type to its string representation
317 * @param type type of object
318 * @return constant string describing type
320 UCL_EXTERN const char * ucl_object_type_to_string (ucl_type_t type);
323 * Converts string that represents ucl type to real ucl type enum
324 * @param input C string with name of type
325 * @param res resulting target
326 * @return true if `input` is a name of type stored in `res`
328 UCL_EXTERN bool ucl_object_string_to_type (const char *input, ucl_type_t *res);
331 * Convert any string to an ucl object making the specified transformations
332 * @param str fixed size or NULL terminated string
333 * @param len length (if len is zero, than str is treated as NULL terminated)
334 * @param flags conversion flags
337 UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len,
338 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT;
341 * Create a UCL object from the specified string
342 * @param str NULL terminated string, will be json escaped
345 UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str) UCL_WARN_UNUSED_RESULT;
348 * Create a UCL object from the specified string
349 * @param str fixed size string, will be json escaped
350 * @param len length of a string
353 UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str,
354 size_t len) UCL_WARN_UNUSED_RESULT;
357 * Create an object from an integer number
361 UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv) UCL_WARN_UNUSED_RESULT;
364 * Create an object from a float number
368 UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv) UCL_WARN_UNUSED_RESULT;
371 * Create an object from a boolean
372 * @param bv bool value
375 UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv) UCL_WARN_UNUSED_RESULT;
378 * Insert a object 'elt' to the hash 'top' and associate it with key 'key'
379 * @param top destination object (must be of type UCL_OBJECT)
380 * @param elt element to insert (must NOT be NULL)
381 * @param key key to associate with this object (either const or preallocated)
382 * @param keylen length of the key (or 0 for NULL terminated keys)
383 * @param copy_key make an internal copy of key
384 * @return true if key has been inserted
386 UCL_EXTERN bool ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt,
387 const char *key, size_t keylen, bool copy_key);
390 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
391 * if no object has been found this function works like ucl_object_insert_key()
392 * @param top destination object (must be of type UCL_OBJECT)
393 * @param elt element to insert (must NOT be NULL)
394 * @param key key to associate with this object (either const or preallocated)
395 * @param keylen length of the key (or 0 for NULL terminated keys)
396 * @param copy_key make an internal copy of key
397 * @return true if key has been inserted
399 UCL_EXTERN bool ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt,
400 const char *key, size_t keylen, bool copy_key);
403 * Merge the keys from one object to another object. Overwrite on conflict
404 * @param top destination object (must be of type UCL_OBJECT)
405 * @param elt element to insert (must be of type UCL_OBJECT)
406 * @param copy copy rather than reference the elements
407 * @return true if all keys have been merged
409 UCL_EXTERN bool ucl_object_merge (ucl_object_t *top, ucl_object_t *elt, bool copy);
412 * Delete a object associated with key 'key', old object will be unrefered,
414 * @param key key associated to the object to remove
415 * @param keylen length of the key (or 0 for NULL terminated keys)
417 UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top,
418 const char *key, size_t keylen);
421 * Delete a object associated with key 'key', old object will be unrefered,
423 * @param key key associated to the object to remove
425 UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top,
430 * Removes `key` from `top` object, returning the object that was removed. This
431 * object is not released, caller must unref the returned object when it is no
434 * @param key key to remove
435 * @param keylen length of the key (or 0 for NULL terminated keys)
436 * @return removed object or NULL if object has not been found
438 UCL_EXTERN ucl_object_t* ucl_object_pop_keyl (ucl_object_t *top, const char *key,
439 size_t keylen) UCL_WARN_UNUSED_RESULT;
442 * Removes `key` from `top` object returning the object that was removed. This
443 * object is not released, caller must unref the returned object when it is no
446 * @param key key to remove
447 * @return removed object or NULL if object has not been found
449 UCL_EXTERN ucl_object_t* ucl_object_pop_key (ucl_object_t *top, const char *key)
450 UCL_WARN_UNUSED_RESULT;
453 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if
454 * the specified key exist, try to merge its content
455 * @param top destination object (must be of type UCL_OBJECT)
456 * @param elt element to insert (must NOT be NULL)
457 * @param key key to associate with this object (either const or preallocated)
458 * @param keylen length of the key (or 0 for NULL terminated keys)
459 * @param copy_key make an internal copy of key
460 * @return true if key has been inserted
462 UCL_EXTERN bool ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt,
463 const char *key, size_t keylen, bool copy_key);
466 * Append an element to the end of array object
467 * @param top destination object (must NOT be NULL)
468 * @param elt element to append (must NOT be NULL)
469 * @return true if value has been inserted
471 UCL_EXTERN bool ucl_array_append (ucl_object_t *top,
475 * Append an element to the start of array object
476 * @param top destination object (must NOT be NULL)
477 * @param elt element to append (must NOT be NULL)
478 * @return true if value has been inserted
480 UCL_EXTERN bool ucl_array_prepend (ucl_object_t *top,
484 * Merge all elements of second array into the first array
485 * @param top destination array (must be of type UCL_ARRAY)
486 * @param elt array to copy elements from (must be of type UCL_ARRAY)
487 * @param copy copy elements instead of referencing them
488 * @return true if arrays were merged
490 UCL_EXTERN bool ucl_array_merge (ucl_object_t *top, ucl_object_t *elt,
494 * Removes an element `elt` from the array `top`, returning the object that was
495 * removed. This object is not released, caller must unref the returned object
496 * when it is no longer needed.
497 * @param top array ucl object
498 * @param elt element to remove
499 * @return removed element or NULL if `top` is NULL or not an array
501 UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top,
505 * Returns the first element of the array `top`
506 * @param top array ucl object
507 * @return element or NULL if `top` is NULL or not an array
509 UCL_EXTERN const ucl_object_t* ucl_array_head (const ucl_object_t *top);
512 * Returns the last element of the array `top`
513 * @param top array ucl object
514 * @return element or NULL if `top` is NULL or not an array
516 UCL_EXTERN const ucl_object_t* ucl_array_tail (const ucl_object_t *top);
519 * Removes the last element from the array `top`, returning the object that was
520 * removed. This object is not released, caller must unref the returned object
521 * when it is no longer needed.
522 * @param top array ucl object
523 * @return removed element or NULL if `top` is NULL or not an array
525 UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top);
528 * Removes the first element from the array `top`, returning the object that was
529 * removed. This object is not released, caller must unref the returned object
530 * when it is no longer needed.
531 * @param top array ucl object
532 * @return removed element or NULL if `top` is NULL or not an array
534 UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top);
537 * Return object identified by index of the array `top`
538 * @param top object to get a key from (must be of type UCL_ARRAY)
539 * @param index array index to return
540 * @return object at the specified index or NULL if index is not found
542 UCL_EXTERN const ucl_object_t* ucl_array_find_index (const ucl_object_t *top,
546 * Return the index of `elt` in the array `top`
547 * @param top object to get a key from (must be of type UCL_ARRAY)
548 * @param elt element to find index of (must NOT be NULL)
549 * @return index of `elt` in the array `top or (unsigned int)-1 if `elt` is not found
551 UCL_EXTERN unsigned int ucl_array_index_of (ucl_object_t *top,
555 * Replace an element in an array with a different element, returning the object
556 * that was replaced. This object is not released, caller must unref the
557 * returned object when it is no longer needed.
558 * @param top destination object (must be of type UCL_ARRAY)
559 * @param elt element to append (must NOT be NULL)
560 * @param index array index in destination to overwrite with elt
561 * @return object that was replaced or NULL if index is not found
564 ucl_array_replace_index (ucl_object_t *top, ucl_object_t *elt,
568 * Append a element to another element forming an implicit array
569 * @param head head to append (may be NULL)
570 * @param elt new element
571 * @return the new implicit array
573 UCL_EXTERN ucl_object_t * ucl_elt_append (ucl_object_t *head,
577 * Converts an object to double value
578 * @param obj CL object
579 * @param target target double variable
580 * @return true if conversion was successful
582 UCL_EXTERN bool ucl_object_todouble_safe (const ucl_object_t *obj, double *target);
585 * Unsafe version of \ref ucl_obj_todouble_safe
586 * @param obj CL object
587 * @return double value
589 UCL_EXTERN double ucl_object_todouble (const ucl_object_t *obj);
592 * Converts an object to integer value
593 * @param obj CL object
594 * @param target target integer variable
595 * @return true if conversion was successful
597 UCL_EXTERN bool ucl_object_toint_safe (const ucl_object_t *obj, int64_t *target);
600 * Unsafe version of \ref ucl_obj_toint_safe
601 * @param obj CL object
604 UCL_EXTERN int64_t ucl_object_toint (const ucl_object_t *obj);
607 * Converts an object to boolean value
608 * @param obj CL object
609 * @param target target boolean variable
610 * @return true if conversion was successful
612 UCL_EXTERN bool ucl_object_toboolean_safe (const ucl_object_t *obj, bool *target);
615 * Unsafe version of \ref ucl_obj_toboolean_safe
616 * @param obj CL object
617 * @return boolean value
619 UCL_EXTERN bool ucl_object_toboolean (const ucl_object_t *obj);
622 * Converts an object to string value
623 * @param obj CL object
624 * @param target target string variable, no need to free value
625 * @return true if conversion was successful
627 UCL_EXTERN bool ucl_object_tostring_safe (const ucl_object_t *obj, const char **target);
630 * Unsafe version of \ref ucl_obj_tostring_safe
631 * @param obj CL object
632 * @return string value
634 UCL_EXTERN const char* ucl_object_tostring (const ucl_object_t *obj);
637 * Convert any object to a string in JSON notation if needed
638 * @param obj CL object
639 * @return string value
641 UCL_EXTERN const char* ucl_object_tostring_forced (const ucl_object_t *obj);
644 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
645 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
646 * @param obj CL object
647 * @param target target string variable, no need to free value
648 * @param tlen target length
649 * @return true if conversion was successful
651 UCL_EXTERN bool ucl_object_tolstring_safe (const ucl_object_t *obj,
652 const char **target, size_t *tlen);
655 * Unsafe version of \ref ucl_obj_tolstring_safe
656 * @param obj CL object
657 * @return string value
659 UCL_EXTERN const char* ucl_object_tolstring (const ucl_object_t *obj, size_t *tlen);
662 * Return object identified by a key in the specified object
663 * @param obj object to get a key from (must be of type UCL_OBJECT)
664 * @param key key to search
665 * @return object matching the specified key or NULL if key was not found
667 UCL_EXTERN const ucl_object_t* ucl_object_lookup (const ucl_object_t *obj,
669 #define ucl_object_find_key ucl_object_lookup
672 * Return object identified by a key in the specified object, if the first key is
673 * not found then look for the next one. This process is repeated unless
674 * the next argument in the list is not NULL. So, `ucl_object_find_any_key(obj, key, NULL)`
675 * is equal to `ucl_object_find_key(obj, key)`
676 * @param obj object to get a key from (must be of type UCL_OBJECT)
677 * @param key key to search
678 * @param ... list of alternative keys to search (NULL terminated)
679 * @return object matching the specified key or NULL if key was not found
681 UCL_EXTERN const ucl_object_t* ucl_object_lookup_any (const ucl_object_t *obj,
682 const char *key, ...);
683 #define ucl_object_find_any_key ucl_object_lookup_any
686 * Return object identified by a fixed size key in the specified object
687 * @param obj object to get a key from (must be of type UCL_OBJECT)
688 * @param key key to search
689 * @param klen length of a key
690 * @return object matching the specified key or NULL if key was not found
692 UCL_EXTERN const ucl_object_t* ucl_object_lookup_len (const ucl_object_t *obj,
693 const char *key, size_t klen);
694 #define ucl_object_find_keyl ucl_object_lookup_len
697 * Return object identified by dot notation string
698 * @param obj object to search in
699 * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
700 * @return object matched the specified path or NULL if path is not found
702 UCL_EXTERN const ucl_object_t *ucl_object_lookup_path (const ucl_object_t *obj,
704 #define ucl_lookup_path ucl_object_lookup_path
707 * Return object identified by object notation string using arbitrary delimiter
708 * @param obj object to search in
709 * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
710 * @param sep the sepatorator to use in place of . (incase keys have . in them)
711 * @return object matched the specified path or NULL if path is not found
713 UCL_EXTERN const ucl_object_t *ucl_object_lookup_path_char (const ucl_object_t *obj,
714 const char *path, char sep);
715 #define ucl_lookup_path_char ucl_object_lookup_path_char
718 * Returns a key of an object as a NULL terminated string
719 * @param obj CL object
720 * @return key or NULL if there is no key
722 UCL_EXTERN const char* ucl_object_key (const ucl_object_t *obj);
725 * Returns a key of an object as a fixed size string (may be more efficient)
726 * @param obj CL object
727 * @param len target key length
728 * @return key pointer
730 UCL_EXTERN const char* ucl_object_keyl (const ucl_object_t *obj, size_t *len);
733 * Increase reference count for an object
734 * @param obj object to ref
735 * @return the referenced object
737 UCL_EXTERN ucl_object_t* ucl_object_ref (const ucl_object_t *obj);
741 * @param obj ucl object to free
743 UCL_DEPRECATED(UCL_EXTERN void ucl_object_free (ucl_object_t *obj));
746 * Decrease reference count for an object
747 * @param obj object to unref
749 UCL_EXTERN void ucl_object_unref (ucl_object_t *obj);
752 * Compare objects `o1` and `o2`
753 * @param o1 the first object
754 * @param o2 the second object
755 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
756 * The order of comparison:
759 * 3) Content of objects
761 UCL_EXTERN int ucl_object_compare (const ucl_object_t *o1,
762 const ucl_object_t *o2);
765 * Compare objects `o1` and `o2` useful for sorting
766 * @param o1 the first object
767 * @param o2 the second object
768 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
769 * The order of comparison:
772 * 3) Content of objects
774 UCL_EXTERN int ucl_object_compare_qsort (const ucl_object_t **o1,
775 const ucl_object_t **o2);
778 * Sort UCL array using `cmp` compare function
782 UCL_EXTERN void ucl_object_array_sort (ucl_object_t *ar,
783 int (*cmp)(const ucl_object_t **o1, const ucl_object_t **o2));
786 * Get the priority for specific UCL object
787 * @param obj any ucl object
788 * @return priority of an object
790 UCL_EXTERN unsigned int ucl_object_get_priority (const ucl_object_t *obj);
793 * Set explicit priority of an object.
794 * @param obj any ucl object
795 * @param priority new priroity value (only 4 least significant bits are considred)
797 UCL_EXTERN void ucl_object_set_priority (ucl_object_t *obj,
798 unsigned int priority);
801 * Opaque iterator object
803 typedef void* ucl_object_iter_t;
806 * Get next key from an object
807 * @param obj object to iterate
808 * @param iter opaque iterator, must be set to NULL on the first call:
809 * ucl_object_iter_t it = NULL;
810 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
811 * @return the next object or NULL
813 UCL_EXTERN const ucl_object_t* ucl_object_iterate (const ucl_object_t *obj,
814 ucl_object_iter_t *iter, bool expand_values);
815 #define ucl_iterate_object ucl_object_iterate
818 * Create new safe iterator for the specified object
819 * @param obj object to iterate
820 * @return new iterator object that should be used with safe iterators API only
822 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_new (const ucl_object_t *obj)
823 UCL_WARN_UNUSED_RESULT;
825 * Reset initialized iterator to a new object
826 * @param obj new object to iterate
827 * @return modified iterator object
829 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_reset (ucl_object_iter_t it,
830 const ucl_object_t *obj);
833 * Get the next object from the `obj`. This fucntion iterates over arrays, objects
834 * and implicit arrays
835 * @param iter safe iterator
836 * @param expand_values expand explicit arrays and objects
837 * @return the next object in sequence
839 UCL_EXTERN const ucl_object_t* ucl_object_iterate_safe (ucl_object_iter_t iter,
842 * Iteration type enumerator
844 enum ucl_iterate_type {
845 UCL_ITERATE_EXPLICIT = 1 << 0, /**< Iterate just explicit arrays and objects */
846 UCL_ITERATE_IMPLICIT = 1 << 1, /**< Iterate just implicit arrays */
847 UCL_ITERATE_BOTH = (1 << 0) | (1 << 1), /**< Iterate both explicit and implicit arrays*/
851 * Get the next object from the `obj`. This fucntion iterates over arrays, objects
852 * and implicit arrays if needed
853 * @param iter safe iterator
855 * @return the next object in sequence
857 UCL_EXTERN const ucl_object_t* ucl_object_iterate_full (ucl_object_iter_t iter,
858 enum ucl_iterate_type type);
861 * Free memory associated with the safe iterator
862 * @param it safe iterator object
864 UCL_EXTERN void ucl_object_iterate_free (ucl_object_iter_t it);
870 * @defgroup parser Parsing functions
871 * These functions are used to parse UCL objects
877 * Macro handler for a parser
878 * @param data the content of macro
879 * @param len the length of content
880 * @param arguments arguments object
881 * @param ud opaque user data
882 * @param err error pointer
883 * @return true if macro has been parsed
885 typedef bool (*ucl_macro_handler) (const unsigned char *data, size_t len,
886 const ucl_object_t *arguments,
890 * Context dependent macro handler for a parser
891 * @param data the content of macro
892 * @param len the length of content
893 * @param arguments arguments object
894 * @param context previously parsed context
895 * @param ud opaque user data
896 * @param err error pointer
897 * @return true if macro has been parsed
899 typedef bool (*ucl_context_macro_handler) (const unsigned char *data, size_t len,
900 const ucl_object_t *arguments,
901 const ucl_object_t *context,
908 * Creates new parser object
909 * @param pool pool to allocate memory from
910 * @return new parser object
912 UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags);
915 * Sets the default priority for the parser applied to chunks that does not
916 * specify priority explicitly
917 * @param parser parser object
918 * @param prio default priority (0 .. 16)
919 * @return true if parser's default priority was set
921 UCL_EXTERN bool ucl_parser_set_default_priority (struct ucl_parser *parser,
924 * Register new handler for a macro
925 * @param parser parser object
926 * @param macro macro name (without leading dot)
927 * @param handler handler (it is called immediately after macro is parsed)
928 * @param ud opaque user data for a handler
930 UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser,
932 ucl_macro_handler handler, void* ud);
935 * Register new context dependent handler for a macro
936 * @param parser parser object
937 * @param macro macro name (without leading dot)
938 * @param handler handler (it is called immediately after macro is parsed)
939 * @param ud opaque user data for a handler
941 UCL_EXTERN void ucl_parser_register_context_macro (struct ucl_parser *parser,
943 ucl_context_macro_handler handler,
947 * Handler to detect unregistered variables
948 * @param data variable data
949 * @param len length of variable
950 * @param replace (out) replace value for variable
951 * @param replace_len (out) replace length for variable
952 * @param need_free (out) UCL will free `dest` after usage
953 * @param ud opaque userdata
954 * @return true if variable
956 typedef bool (*ucl_variable_handler) (const unsigned char *data, size_t len,
957 unsigned char **replace, size_t *replace_len, bool *need_free, void* ud);
960 * Register new parser variable
961 * @param parser parser object
962 * @param var variable name
963 * @param value variable value
965 UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var,
969 * Set handler for unknown variables
970 * @param parser parser structure
971 * @param handler desired handler
972 * @param ud opaque data for the handler
974 UCL_EXTERN void ucl_parser_set_variables_handler (struct ucl_parser *parser,
975 ucl_variable_handler handler, void *ud);
978 * Load new chunk to a parser
979 * @param parser parser structure
980 * @param data the pointer to the beginning of a chunk
981 * @param len the length of a chunk
982 * @return true if chunk has been added and false in case of error
984 UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser,
985 const unsigned char *data, size_t len);
988 * Load new chunk to a parser with the specified priority
989 * @param parser parser structure
990 * @param data the pointer to the beginning of a chunk
991 * @param len the length of a chunk
992 * @param priority the desired priority of a chunk (only 4 least significant bits
993 * are considered for this parameter)
994 * @return true if chunk has been added and false in case of error
996 UCL_EXTERN bool ucl_parser_add_chunk_priority (struct ucl_parser *parser,
997 const unsigned char *data, size_t len, unsigned priority);
1000 * Full version of ucl_add_chunk with priority and duplicate strategy
1001 * @param parser parser structure
1002 * @param data the pointer to the beginning of a chunk
1003 * @param len the length of a chunk
1004 * @param priority the desired priority of a chunk (only 4 least significant bits
1005 * are considered for this parameter)
1006 * @param strat duplicates merging strategy
1007 * @param parse_type input format
1008 * @return true if chunk has been added and false in case of error
1010 UCL_EXTERN bool ucl_parser_add_chunk_full (struct ucl_parser *parser,
1011 const unsigned char *data, size_t len, unsigned priority,
1012 enum ucl_duplicate_strategy strat, enum ucl_parse_type parse_type);
1015 * Load ucl object from a string
1016 * @param parser parser structure
1017 * @param data the pointer to the string
1018 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
1019 * @return true if string has been added and false in case of error
1021 UCL_EXTERN bool ucl_parser_add_string (struct ucl_parser *parser,
1022 const char *data,size_t len);
1025 * Load ucl object from a string
1026 * @param parser parser structure
1027 * @param data the pointer to the string
1028 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
1029 * @param priority the desired priority of a chunk (only 4 least significant bits
1030 * are considered for this parameter)
1031 * @return true if string has been added and false in case of error
1033 UCL_EXTERN bool ucl_parser_add_string_priority (struct ucl_parser *parser,
1034 const char *data, size_t len, unsigned priority);
1037 * Load and add data from a file
1038 * @param parser parser structure
1039 * @param filename the name of file
1040 * @param err if *err is NULL it is set to parser error
1041 * @return true if chunk has been added and false in case of error
1043 UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser,
1044 const char *filename);
1047 * Load and add data from a file
1048 * @param parser parser structure
1049 * @param filename the name of file
1050 * @param err if *err is NULL it is set to parser error
1051 * @param priority the desired priority of a chunk (only 4 least significant bits
1052 * are considered for this parameter)
1053 * @return true if chunk has been added and false in case of error
1055 UCL_EXTERN bool ucl_parser_add_file_priority (struct ucl_parser *parser,
1056 const char *filename, unsigned priority);
1059 * Load and add data from a file
1060 * @param parser parser structure
1061 * @param filename the name of file
1062 * @param priority the desired priority of a chunk (only 4 least significant bits
1063 * are considered for this parameter)
1064 * @param strat Merge strategy to use while parsing this file
1065 * @param parse_type Parser type to use while parsing this file
1066 * @return true if chunk has been added and false in case of error
1068 UCL_EXTERN bool ucl_parser_add_file_full (struct ucl_parser *parser, const char *filename,
1069 unsigned priority, enum ucl_duplicate_strategy strat,
1070 enum ucl_parse_type parse_type);
1073 * Load and add data from a file descriptor
1074 * @param parser parser structure
1075 * @param filename the name of file
1076 * @param err if *err is NULL it is set to parser error
1077 * @return true if chunk has been added and false in case of error
1079 UCL_EXTERN bool ucl_parser_add_fd (struct ucl_parser *parser,
1083 * Load and add data from a file descriptor
1084 * @param parser parser structure
1085 * @param filename the name of file
1086 * @param err if *err is NULL it is set to parser error
1087 * @param priority the desired priority of a chunk (only 4 least significant bits
1088 * are considered for this parameter)
1089 * @return true if chunk has been added and false in case of error
1091 UCL_EXTERN bool ucl_parser_add_fd_priority (struct ucl_parser *parser,
1092 int fd, unsigned priority);
1095 * Load and add data from a file descriptor
1096 * @param parser parser structure
1097 * @param filename the name of file
1098 * @param err if *err is NULL it is set to parser error
1099 * @param priority the desired priority of a chunk (only 4 least significant bits
1100 * are considered for this parameter)
1101 * @param strat Merge strategy to use while parsing this file
1102 * @param parse_type Parser type to use while parsing this file
1103 * @return true if chunk has been added and false in case of error
1105 UCL_EXTERN bool ucl_parser_add_fd_full (struct ucl_parser *parser, int fd,
1106 unsigned priority, enum ucl_duplicate_strategy strat,
1107 enum ucl_parse_type parse_type);
1110 * Provide a UCL_ARRAY of paths to search for include files. The object is
1111 * copied so caller must unref the object.
1112 * @param parser parser structure
1113 * @param paths UCL_ARRAY of paths to search
1114 * @return true if the path search array was replaced in the parser
1116 UCL_EXTERN bool ucl_set_include_path (struct ucl_parser *parser,
1117 ucl_object_t *paths);
1120 * Get a top object for a parser (refcount is increased)
1121 * @param parser parser structure
1122 * @param err if *err is NULL it is set to parser error
1123 * @return top parser object or NULL
1125 UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);
1128 * Get the error string if parsing has been failed
1129 * @param parser parser object
1130 * @return error description
1132 UCL_EXTERN const char *ucl_parser_get_error (struct ucl_parser *parser);
1135 * Get the code of the last error
1136 * @param parser parser object
1137 * @return error code
1139 UCL_EXTERN int ucl_parser_get_error_code (struct ucl_parser *parser);
1142 * Get the current column number within parser
1143 * @param parser parser object
1144 * @return current column number
1146 UCL_EXTERN unsigned ucl_parser_get_column (struct ucl_parser *parser);
1149 * Get the current line number within parser
1150 * @param parser parser object
1151 * @return current line number
1153 UCL_EXTERN unsigned ucl_parser_get_linenum (struct ucl_parser *parser);
1156 * Clear the error in the parser
1157 * @param parser parser object
1159 UCL_EXTERN void ucl_parser_clear_error (struct ucl_parser *parser);
1162 * Free ucl parser object
1163 * @param parser parser object
1165 UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser);
1168 * Get constant opaque pointer to comments structure for this parser. Increase
1169 * refcount to prevent this object to be destroyed on parser's destruction
1170 * @param parser parser structure
1171 * @return ucl comments pointer or NULL
1173 UCL_EXTERN const ucl_object_t * ucl_parser_get_comments (struct ucl_parser *parser);
1176 * Utility function to find a comment object for the specified object in the input
1177 * @param comments comments object
1178 * @param srch search object
1179 * @return string comment enclosed in ucl_object_t
1181 UCL_EXTERN const ucl_object_t * ucl_comments_find (const ucl_object_t *comments,
1182 const ucl_object_t *srch);
1185 * Move comment from `from` object to `to` object
1186 * @param comments comments object
1187 * @param what source object
1188 * @param whith destination object
1189 * @return `true` if `from` has comment and it has been moved to `to`
1191 UCL_EXTERN bool ucl_comments_move (ucl_object_t *comments,
1192 const ucl_object_t *from, const ucl_object_t *to);
1195 * Adds a new comment for an object
1196 * @param comments comments object
1197 * @param obj object to add comment to
1198 * @param comment string representation of a comment
1200 UCL_EXTERN void ucl_comments_add (ucl_object_t *comments,
1201 const ucl_object_t *obj, const char *comment);
1204 * Add new public key to parser for signatures check
1205 * @param parser parser object
1206 * @param key PEM representation of a key
1207 * @param len length of the key
1208 * @param err if *err is NULL it is set to parser error
1209 * @return true if a key has been successfully added
1211 UCL_EXTERN bool ucl_parser_pubkey_add (struct ucl_parser *parser,
1212 const unsigned char *key, size_t len);
1215 * Set FILENAME and CURDIR variables in parser
1216 * @param parser parser object
1217 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd()
1218 * @param need_expand perform realpath() if this variable is true and filename is not NULL
1219 * @return true if variables has been set
1221 UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename,
1227 * @defgroup emitter Emitting functions
1228 * These functions are used to serialise UCL objects to some string representation.
1233 struct ucl_emitter_context;
1235 * Structure using for emitter callbacks
1237 struct ucl_emitter_functions {
1238 /** Append a single character */
1239 int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud);
1240 /** Append a string of a specified length */
1241 int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud);
1242 /** Append a 64 bit integer */
1243 int (*ucl_emitter_append_int) (int64_t elt, void *ud);
1244 /** Append floating point element */
1245 int (*ucl_emitter_append_double) (double elt, void *ud);
1246 /** Free userdata */
1247 void (*ucl_emitter_free_func)(void *ud);
1248 /** Opaque userdata pointer */
1252 struct ucl_emitter_operations {
1253 /** Write a primitive element */
1254 void (*ucl_emitter_write_elt) (struct ucl_emitter_context *ctx,
1255 const ucl_object_t *obj, bool first, bool print_key);
1256 /** Start ucl object */
1257 void (*ucl_emitter_start_object) (struct ucl_emitter_context *ctx,
1258 const ucl_object_t *obj, bool print_key);
1259 /** End ucl object */
1260 void (*ucl_emitter_end_object) (struct ucl_emitter_context *ctx,
1261 const ucl_object_t *obj);
1262 /** Start ucl array */
1263 void (*ucl_emitter_start_array) (struct ucl_emitter_context *ctx,
1264 const ucl_object_t *obj, bool print_key);
1265 void (*ucl_emitter_end_array) (struct ucl_emitter_context *ctx,
1266 const ucl_object_t *obj);
1270 * Structure that defines emitter functions
1272 struct ucl_emitter_context {
1273 /** Name of emitter (e.g. json, compact_json) */
1275 /** Unique id (e.g. UCL_EMIT_JSON for standard emitters */
1277 /** A set of output functions */
1278 const struct ucl_emitter_functions *func;
1279 /** A set of output operations */
1280 const struct ucl_emitter_operations *ops;
1281 /** Current amount of indent tabs */
1282 unsigned int indent;
1283 /** Top level object */
1284 const ucl_object_t *top;
1285 /** Optional comments */
1286 const ucl_object_t *comments;
1290 * Emit object to a string
1292 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1293 * #UCL_EMIT_CONFIG then emit config like object
1294 * @return dump of an object (must be freed after using) or NULL in case of error
1296 UCL_EXTERN unsigned char *ucl_object_emit (const ucl_object_t *obj,
1297 enum ucl_emitter emit_type);
1300 * Emit object to a string that can contain `\0` inside
1302 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1303 * #UCL_EMIT_CONFIG then emit config like object
1304 * @param len the resulting length
1305 * @return dump of an object (must be freed after using) or NULL in case of error
1307 UCL_EXTERN unsigned char *ucl_object_emit_len (const ucl_object_t *obj,
1308 enum ucl_emitter emit_type, size_t *len);
1311 * Emit object to a string
1313 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1314 * #UCL_EMIT_CONFIG then emit config like object
1315 * @param emitter a set of emitter functions
1316 * @param comments optional comments for the parser
1317 * @return dump of an object (must be freed after using) or NULL in case of error
1319 UCL_EXTERN bool ucl_object_emit_full (const ucl_object_t *obj,
1320 enum ucl_emitter emit_type,
1321 struct ucl_emitter_functions *emitter,
1322 const ucl_object_t *comments);
1325 * Start streamlined UCL object emitter
1326 * @param obj top UCL object
1327 * @param emit_type emit type
1328 * @param emitter a set of emitter functions
1329 * @return new streamlined context that should be freed by
1330 * `ucl_object_emit_streamline_finish`
1332 UCL_EXTERN struct ucl_emitter_context* ucl_object_emit_streamline_new (
1333 const ucl_object_t *obj, enum ucl_emitter emit_type,
1334 struct ucl_emitter_functions *emitter);
1337 * Start object or array container for the streamlined output
1338 * @param ctx streamlined context
1339 * @param obj container object
1341 UCL_EXTERN void ucl_object_emit_streamline_start_container (
1342 struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1344 * Add a complete UCL object to streamlined output
1345 * @param ctx streamlined context
1346 * @param obj object to output
1348 UCL_EXTERN void ucl_object_emit_streamline_add_object (
1349 struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1351 * End previously added container
1352 * @param ctx streamlined context
1354 UCL_EXTERN void ucl_object_emit_streamline_end_container (
1355 struct ucl_emitter_context *ctx);
1357 * Terminate streamlined container finishing all containers in it
1358 * @param ctx streamlined context
1360 UCL_EXTERN void ucl_object_emit_streamline_finish (
1361 struct ucl_emitter_context *ctx);
1364 * Returns functions to emit object to memory
1365 * @param pmem target pointer (should be freed by caller)
1366 * @return emitter functions structure
1368 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_memory_funcs (
1372 * Returns functions to emit object to FILE *
1373 * @param fp FILE * object
1374 * @return emitter functions structure
1376 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_file_funcs (
1379 * Returns functions to emit object to a file descriptor
1380 * @param fd file descriptor
1381 * @return emitter functions structure
1383 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_fd_funcs (
1387 * Free emitter functions
1388 * @param f pointer to functions
1390 UCL_EXTERN void ucl_object_emit_funcs_free (struct ucl_emitter_functions *f);
1395 * @defgroup schema Schema functions
1396 * These functions are used to validate UCL objects using json schema format
1402 * Used to define UCL schema error
1404 enum ucl_schema_error_code {
1405 UCL_SCHEMA_OK = 0, /**< no error */
1406 UCL_SCHEMA_TYPE_MISMATCH, /**< type of object is incorrect */
1407 UCL_SCHEMA_INVALID_SCHEMA, /**< schema is invalid */
1408 UCL_SCHEMA_MISSING_PROPERTY,/**< one or more missing properties */
1409 UCL_SCHEMA_CONSTRAINT, /**< constraint found */
1410 UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */
1411 UCL_SCHEMA_EXTERNAL_REF_MISSING, /**< cannot fetch external ref */
1412 UCL_SCHEMA_EXTERNAL_REF_INVALID, /**< invalid external ref */
1413 UCL_SCHEMA_INTERNAL_ERROR, /**< something bad happened */
1414 UCL_SCHEMA_UNKNOWN /**< generic error */
1418 * Generic ucl schema error
1420 struct ucl_schema_error {
1421 enum ucl_schema_error_code code; /**< error code */
1422 char msg[128]; /**< error message */
1423 const ucl_object_t *obj; /**< object where error occured */
1427 * Validate object `obj` using schema object `schema`.
1428 * @param schema schema object
1429 * @param obj object to validate
1430 * @param err error pointer, if this parameter is not NULL and error has been
1431 * occured, then `err` is filled with the exact error definition.
1432 * @return true if `obj` is valid using `schema`
1434 UCL_EXTERN bool ucl_object_validate (const ucl_object_t *schema,
1435 const ucl_object_t *obj, struct ucl_schema_error *err);
1438 * Validate object `obj` using schema object `schema` and root schema at `root`.
1439 * @param schema schema object
1440 * @param obj object to validate
1441 * @param root root schema object
1442 * @param err error pointer, if this parameter is not NULL and error has been
1443 * occured, then `err` is filled with the exact error definition.
1444 * @return true if `obj` is valid using `schema`
1446 UCL_EXTERN bool ucl_object_validate_root (const ucl_object_t *schema,
1447 const ucl_object_t *obj,
1448 const ucl_object_t *root,
1449 struct ucl_schema_error *err);
1452 * Validate object `obj` using schema object `schema` and root schema at `root`
1453 * using some external references provided.
1454 * @param schema schema object
1455 * @param obj object to validate
1456 * @param root root schema object
1457 * @param ext_refs external references (might be modified during validation)
1458 * @param err error pointer, if this parameter is not NULL and error has been
1459 * occured, then `err` is filled with the exact error definition.
1460 * @return true if `obj` is valid using `schema`
1462 UCL_EXTERN bool ucl_object_validate_root_ext (const ucl_object_t *schema,
1463 const ucl_object_t *obj,
1464 const ucl_object_t *root,
1465 ucl_object_t *ext_refs,
1466 struct ucl_schema_error *err);
1474 * XXX: Poorly named API functions, need to replace them with the appropriate
1475 * named function. All API functions *must* use naming ucl_object_*. Usage of
1476 * ucl_obj* should be avoided.
1478 #define ucl_obj_todouble_safe ucl_object_todouble_safe
1479 #define ucl_obj_todouble ucl_object_todouble
1480 #define ucl_obj_tostring ucl_object_tostring
1481 #define ucl_obj_tostring_safe ucl_object_tostring_safe
1482 #define ucl_obj_tolstring ucl_object_tolstring
1483 #define ucl_obj_tolstring_safe ucl_object_tolstring_safe
1484 #define ucl_obj_toint ucl_object_toint
1485 #define ucl_obj_toint_safe ucl_object_toint_safe
1486 #define ucl_obj_toboolean ucl_object_toboolean
1487 #define ucl_obj_toboolean_safe ucl_object_toboolean_safe
1488 #define ucl_obj_get_key ucl_object_find_key
1489 #define ucl_obj_get_keyl ucl_object_find_keyl
1490 #define ucl_obj_unref ucl_object_unref
1491 #define ucl_obj_ref ucl_object_ref
1492 #define ucl_obj_free ucl_object_free