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_flags_t;
154 * String conversion flags, that are used in #ucl_object_fromstring_common function.
156 typedef enum ucl_string_flags {
157 UCL_STRING_ESCAPE = 0x1, /**< Perform JSON escape */
158 UCL_STRING_TRIM = 0x2, /**< Trim leading and trailing whitespaces */
159 UCL_STRING_PARSE_BOOLEAN = 0x4, /**< Parse passed string and detect boolean */
160 UCL_STRING_PARSE_INT = 0x8, /**< Parse passed string and detect integer number */
161 UCL_STRING_PARSE_DOUBLE = 0x10, /**< Parse passed string and detect integer or float number */
162 UCL_STRING_PARSE_TIME = 0x20, /**< Parse time strings */
163 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE|UCL_STRING_PARSE_TIME, /**<
164 Parse passed string and detect number */
165 UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER, /**<
166 Parse passed string (and detect booleans and numbers) */
167 UCL_STRING_PARSE_BYTES = 0x40 /**< Treat numbers as bytes */
168 } ucl_string_flags_t;
171 * Basic flags for an object
173 typedef enum ucl_object_flags {
174 UCL_OBJECT_ALLOCATED_KEY = 1, /**< An object has key allocated internally */
175 UCL_OBJECT_ALLOCATED_VALUE = 2, /**< An object has a string value allocated internally */
176 UCL_OBJECT_NEED_KEY_ESCAPE = 4 /**< The key of an object need to be escaped on output */
177 } ucl_object_flags_t;
180 * UCL object structure. Please mention that the most of fields should not be touched by
181 * UCL users. In future, this structure may be converted to private one.
183 typedef struct ucl_object_s {
188 int64_t iv; /**< Int value of an object */
189 const char *sv; /**< String value of an object */
190 double dv; /**< Double value of an object */
191 struct ucl_object_s *av; /**< Array */
192 void *ov; /**< Object */
193 void* ud; /**< Opaque user data */
195 const char *key; /**< Key of an object */
196 struct ucl_object_s *next; /**< Array handle */
197 struct ucl_object_s *prev; /**< Array handle */
198 unsigned char* trash_stack[2]; /**< Pointer to allocated chunks */
199 unsigned keylen; /**< Lenght of a key */
200 unsigned len; /**< Size of an object */
201 enum ucl_type type; /**< Real type */
202 uint16_t ref; /**< Reference count */
203 uint16_t flags; /**< Object flags */
209 * @defgroup utils Utility functions
210 * A number of utility functions simplify handling of UCL objects
215 * Copy and return a key of an object, returned key is zero-terminated
216 * @param obj CL object
217 * @return zero terminated key
219 UCL_EXTERN char* ucl_copy_key_trash (const ucl_object_t *obj);
222 * Copy and return a string value of an object, returned key is zero-terminated
223 * @param obj CL object
224 * @return zero terminated string representation of object value
226 UCL_EXTERN char* ucl_copy_value_trash (const ucl_object_t *obj);
229 * Creates a new object
232 UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT;
235 * Create new object with type specified
236 * @param type type of a new object
239 UCL_EXTERN ucl_object_t* ucl_object_typed_new (ucl_type_t type) UCL_WARN_UNUSED_RESULT;
242 * Return the type of an object
243 * @return the object type
245 UCL_EXTERN ucl_type_t ucl_object_type (const ucl_object_t *obj);
248 * Convert any string to an ucl object making the specified transformations
249 * @param str fixed size or NULL terminated string
250 * @param len length (if len is zero, than str is treated as NULL terminated)
251 * @param flags conversion flags
254 UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len,
255 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT;
258 * Create a UCL object from the specified string
259 * @param str NULL terminated string, will be json escaped
262 UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str) UCL_WARN_UNUSED_RESULT;
265 * Create a UCL object from the specified string
266 * @param str fixed size string, will be json escaped
267 * @param len length of a string
270 UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str,
271 size_t len) UCL_WARN_UNUSED_RESULT;
274 * Create an object from an integer number
278 UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv) UCL_WARN_UNUSED_RESULT;
281 * Create an object from a float number
285 UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv) UCL_WARN_UNUSED_RESULT;
288 * Create an object from a boolean
289 * @param bv bool value
292 UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv) UCL_WARN_UNUSED_RESULT;
295 * Insert a object 'elt' to the hash 'top' and associate it with key 'key'
296 * @param top destination object (will be created automatically if top is NULL)
297 * @param elt element to insert (must NOT be NULL)
298 * @param key key to associate with this object (either const or preallocated)
299 * @param keylen length of the key (or 0 for NULL terminated keys)
300 * @param copy_key make an internal copy of key
301 * @return true if key has been inserted
303 UCL_EXTERN bool ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt,
304 const char *key, size_t keylen, bool copy_key);
307 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
308 * if no object has been found this function works like ucl_object_insert_key()
309 * @param top destination object (will be created automatically if top is NULL)
310 * @param elt element to insert (must NOT be NULL)
311 * @param key key to associate with this object (either const or preallocated)
312 * @param keylen length of the key (or 0 for NULL terminated keys)
313 * @param copy_key make an internal copy of key
314 * @return true if key has been inserted
316 UCL_EXTERN bool ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt,
317 const char *key, size_t keylen, bool copy_key);
320 * Delete a object associated with key 'key', old object will be unrefered,
322 * @param key key associated to the object to remove
323 * @param keylen length of the key (or 0 for NULL terminated keys)
325 UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top,
326 const char *key, size_t keylen);
329 * Delete a object associated with key 'key', old object will be unrefered,
331 * @param key key associated to the object to remove
333 UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top,
338 * Delete key from `top` object returning the object deleted. This object is not
341 * @param key key to remove
342 * @param keylen length of the key (or 0 for NULL terminated keys)
343 * @return removed object or NULL if object has not been found
345 UCL_EXTERN ucl_object_t* ucl_object_pop_keyl (ucl_object_t *top, const char *key,
346 size_t keylen) UCL_WARN_UNUSED_RESULT;
349 * Delete key from `top` object returning the object deleted. This object is not
352 * @param key key to remove
353 * @return removed object or NULL if object has not been found
355 UCL_EXTERN ucl_object_t* ucl_object_pop_key (ucl_object_t *top, const char *key)
356 UCL_WARN_UNUSED_RESULT;
359 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if the specified key exist,
360 * try to merge its content
361 * @param top destination object (will be created automatically if top is NULL)
362 * @param elt element to insert (must NOT be NULL)
363 * @param key key to associate with this object (either const or preallocated)
364 * @param keylen length of the key (or 0 for NULL terminated keys)
365 * @param copy_key make an internal copy of key
366 * @return true if key has been inserted
368 UCL_EXTERN bool ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt,
369 const char *key, size_t keylen, bool copy_key);
372 * Append an element to the front of array object
373 * @param top destination object (will be created automatically if top is NULL)
374 * @param elt element to append (must NOT be NULL)
375 * @return true if value has been inserted
377 UCL_EXTERN bool ucl_array_append (ucl_object_t *top,
381 * Append an element to the start of array object
382 * @param top destination object (will be created automatically if top is NULL)
383 * @param elt element to append (must NOT be NULL)
384 * @return true if value has been inserted
386 UCL_EXTERN bool ucl_array_prepend (ucl_object_t *top,
390 * Removes an element `elt` from the array `top`. Caller must unref the returned object when it is not
392 * @param top array ucl object
393 * @param elt element to remove
394 * @return removed element or NULL if `top` is NULL or not an array
396 UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top,
400 * Returns the first element of the array `top`
401 * @param top array ucl object
402 * @return element or NULL if `top` is NULL or not an array
404 UCL_EXTERN const ucl_object_t* ucl_array_head (const ucl_object_t *top);
407 * Returns the last element of the array `top`
408 * @param top array ucl object
409 * @return element or NULL if `top` is NULL or not an array
411 UCL_EXTERN const ucl_object_t* ucl_array_tail (const ucl_object_t *top);
414 * Removes the last element from the array `top`. Caller must unref the returned object when it is not
416 * @param top array ucl object
417 * @return removed element or NULL if `top` is NULL or not an array
419 UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top);
422 * Return object identified by an index of the array `top`
423 * @param obj object to get a key from (must be of type UCL_ARRAY)
424 * @param index index to return
425 * @return object at the specified index or NULL if index is not found
427 UCL_EXTERN const ucl_object_t* ucl_array_find_index (const ucl_object_t *top,
431 * Removes the first element from the array `top`. Caller must unref the returned object when it is not
433 * @param top array ucl object
434 * @return removed element or NULL if `top` is NULL or not an array
436 UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top);
439 * Append a element to another element forming an implicit array
440 * @param head head to append (may be NULL)
441 * @param elt new element
442 * @return true if element has been inserted
444 UCL_EXTERN ucl_object_t * ucl_elt_append (ucl_object_t *head,
448 * Converts an object to double value
449 * @param obj CL object
450 * @param target target double variable
451 * @return true if conversion was successful
453 UCL_EXTERN bool ucl_object_todouble_safe (const ucl_object_t *obj, double *target);
456 * Unsafe version of \ref ucl_obj_todouble_safe
457 * @param obj CL object
458 * @return double value
460 UCL_EXTERN double ucl_object_todouble (const ucl_object_t *obj);
463 * Converts an object to integer value
464 * @param obj CL object
465 * @param target target integer variable
466 * @return true if conversion was successful
468 UCL_EXTERN bool ucl_object_toint_safe (const ucl_object_t *obj, int64_t *target);
471 * Unsafe version of \ref ucl_obj_toint_safe
472 * @param obj CL object
475 UCL_EXTERN int64_t ucl_object_toint (const ucl_object_t *obj);
478 * Converts an object to boolean value
479 * @param obj CL object
480 * @param target target boolean variable
481 * @return true if conversion was successful
483 UCL_EXTERN bool ucl_object_toboolean_safe (const ucl_object_t *obj, bool *target);
486 * Unsafe version of \ref ucl_obj_toboolean_safe
487 * @param obj CL object
488 * @return boolean value
490 UCL_EXTERN bool ucl_object_toboolean (const ucl_object_t *obj);
493 * Converts an object to string value
494 * @param obj CL object
495 * @param target target string variable, no need to free value
496 * @return true if conversion was successful
498 UCL_EXTERN bool ucl_object_tostring_safe (const ucl_object_t *obj, const char **target);
501 * Unsafe version of \ref ucl_obj_tostring_safe
502 * @param obj CL object
503 * @return string value
505 UCL_EXTERN const char* ucl_object_tostring (const ucl_object_t *obj);
508 * Convert any object to a string in JSON notation if needed
509 * @param obj CL object
510 * @return string value
512 UCL_EXTERN const char* ucl_object_tostring_forced (const ucl_object_t *obj);
515 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
516 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
517 * @param obj CL object
518 * @param target target string variable, no need to free value
519 * @param tlen target length
520 * @return true if conversion was successful
522 UCL_EXTERN bool ucl_object_tolstring_safe (const ucl_object_t *obj,
523 const char **target, size_t *tlen);
526 * Unsafe version of \ref ucl_obj_tolstring_safe
527 * @param obj CL object
528 * @return string value
530 UCL_EXTERN const char* ucl_object_tolstring (const ucl_object_t *obj, size_t *tlen);
533 * Return object identified by a key in the specified object
534 * @param obj object to get a key from (must be of type UCL_OBJECT)
535 * @param key key to search
536 * @return object matched the specified key or NULL if key is not found
538 UCL_EXTERN const ucl_object_t* ucl_object_find_key (const ucl_object_t *obj,
542 * Return object identified by a fixed size key in the specified object
543 * @param obj object to get a key from (must be of type UCL_OBJECT)
544 * @param key key to search
545 * @param klen length of a key
546 * @return object matched the specified key or NULL if key is not found
548 UCL_EXTERN const ucl_object_t* ucl_object_find_keyl (const ucl_object_t *obj,
549 const char *key, size_t klen);
552 * Return object identified by dot notation string
553 * @param obj object to search in
554 * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
555 * @return object matched the specified path or NULL if path is not found
557 UCL_EXTERN const ucl_object_t *ucl_lookup_path (const ucl_object_t *obj,
561 * Returns a key of an object as a NULL terminated string
562 * @param obj CL object
563 * @return key or NULL if there is no key
565 UCL_EXTERN const char* ucl_object_key (const ucl_object_t *obj);
568 * Returns a key of an object as a fixed size string (may be more efficient)
569 * @param obj CL object
570 * @param len target key length
571 * @return key pointer
573 UCL_EXTERN const char* ucl_object_keyl (const ucl_object_t *obj, size_t *len);
576 * Increase reference count for an object
577 * @param obj object to ref
579 UCL_EXTERN ucl_object_t* ucl_object_ref (const ucl_object_t *obj);
583 * @param obj ucl object to free
585 UCL_DEPRECATED(UCL_EXTERN void ucl_object_free (ucl_object_t *obj));
588 * Decrease reference count for an object
589 * @param obj object to unref
591 UCL_EXTERN void ucl_object_unref (ucl_object_t *obj);
594 * Compare objects `o1` and `o2`
595 * @param o1 the first object
596 * @param o2 the second object
597 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
598 * The order of comparison:
601 * 3) Content of objects
603 UCL_EXTERN int ucl_object_compare (const ucl_object_t *o1,
604 const ucl_object_t *o2);
607 * Sort UCL array using `cmp` compare function
611 UCL_EXTERN void ucl_object_array_sort (ucl_object_t *ar,
612 int (*cmp)(const ucl_object_t *o1, const ucl_object_t *o2));
615 * Opaque iterator object
617 typedef void* ucl_object_iter_t;
620 * Get next key from an object
621 * @param obj object to iterate
622 * @param iter opaque iterator, must be set to NULL on the first call:
623 * ucl_object_iter_t it = NULL;
624 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
625 * @return the next object or NULL
627 UCL_EXTERN const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj,
628 ucl_object_iter_t *iter, bool expand_values);
633 * @defgroup parser Parsing functions
634 * These functions are used to parse UCL objects
640 * Macro handler for a parser
641 * @param data the content of macro
642 * @param len the length of content
643 * @param ud opaque user data
644 * @param err error pointer
645 * @return true if macro has been parsed
647 typedef bool (*ucl_macro_handler) (const unsigned char *data, size_t len, void* ud);
653 * Creates new parser object
654 * @param pool pool to allocate memory from
655 * @return new parser object
657 UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags);
660 * Register new handler for a macro
661 * @param parser parser object
662 * @param macro macro name (without leading dot)
663 * @param handler handler (it is called immediately after macro is parsed)
664 * @param ud opaque user data for a handler
666 UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser, const char *macro,
667 ucl_macro_handler handler, void* ud);
670 * Handler to detect unregistered variables
671 * @param data variable data
672 * @param len length of variable
673 * @param replace (out) replace value for variable
674 * @param replace_len (out) replace length for variable
675 * @param need_free (out) UCL will free `dest` after usage
676 * @param ud opaque userdata
677 * @return true if variable
679 typedef bool (*ucl_variable_handler) (const unsigned char *data, size_t len,
680 unsigned char **replace, size_t *replace_len, bool *need_free, void* ud);
683 * Register new parser variable
684 * @param parser parser object
685 * @param var variable name
686 * @param value variable value
688 UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var,
692 * Set handler for unknown variables
693 * @param parser parser structure
694 * @param handler desired handler
695 * @param ud opaque data for the handler
697 UCL_EXTERN void ucl_parser_set_variables_handler (struct ucl_parser *parser,
698 ucl_variable_handler handler, void *ud);
701 * Load new chunk to a parser
702 * @param parser parser structure
703 * @param data the pointer to the beginning of a chunk
704 * @param len the length of a chunk
705 * @param err if *err is NULL it is set to parser error
706 * @return true if chunk has been added and false in case of error
708 UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser,
709 const unsigned char *data, size_t len);
712 * Load ucl object from a string
713 * @param parser parser structure
714 * @param data the pointer to the string
715 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
716 * @return true if string has been added and false in case of error
718 UCL_EXTERN bool ucl_parser_add_string (struct ucl_parser *parser,
719 const char *data,size_t len);
722 * Load and add data from a file
723 * @param parser parser structure
724 * @param filename the name of file
725 * @param err if *err is NULL it is set to parser error
726 * @return true if chunk has been added and false in case of error
728 UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser,
729 const char *filename);
732 * Load and add data from a file descriptor
733 * @param parser parser structure
734 * @param filename the name of file
735 * @param err if *err is NULL it is set to parser error
736 * @return true if chunk has been added and false in case of error
738 UCL_EXTERN bool ucl_parser_add_fd (struct ucl_parser *parser,
742 * Get a top object for a parser (refcount is increased)
743 * @param parser parser structure
744 * @param err if *err is NULL it is set to parser error
745 * @return top parser object or NULL
747 UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);
750 * Get the error string if failing
751 * @param parser parser object
753 UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser);
755 * Free ucl parser object
756 * @param parser parser object
758 UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser);
761 * Add new public key to parser for signatures check
762 * @param parser parser object
763 * @param key PEM representation of a key
764 * @param len length of the key
765 * @param err if *err is NULL it is set to parser error
766 * @return true if a key has been successfully added
768 UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len);
771 * Set FILENAME and CURDIR variables in parser
772 * @param parser parser object
773 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd()
774 * @param need_expand perform realpath() if this variable is true and filename is not NULL
775 * @return true if variables has been set
777 UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename,
783 * @defgroup emitter Emitting functions
784 * These functions are used to serialise UCL objects to some string representation.
790 * Structure using for emitter callbacks
792 struct ucl_emitter_functions {
793 /** Append a single character */
794 int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud);
795 /** Append a string of a specified length */
796 int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud);
797 /** Append a 64 bit integer */
798 int (*ucl_emitter_append_int) (int64_t elt, void *ud);
799 /** Append floating point element */
800 int (*ucl_emitter_append_double) (double elt, void *ud);
801 /** Opaque userdata pointer */
806 * Emit object to a string
808 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
809 * #UCL_EMIT_CONFIG then emit config like object
810 * @return dump of an object (must be freed after using) or NULL in case of error
812 UCL_EXTERN unsigned char *ucl_object_emit (const ucl_object_t *obj,
813 enum ucl_emitter emit_type);
816 * Emit object to a string
818 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
819 * #UCL_EMIT_CONFIG then emit config like object
820 * @return dump of an object (must be freed after using) or NULL in case of error
822 UCL_EXTERN bool ucl_object_emit_full (const ucl_object_t *obj,
823 enum ucl_emitter emit_type,
824 struct ucl_emitter_functions *emitter);
828 * @defgroup schema Schema functions
829 * These functions are used to validate UCL objects using json schema format
835 * Used to define UCL schema error
837 enum ucl_schema_error_code {
838 UCL_SCHEMA_OK = 0, /**< no error */
839 UCL_SCHEMA_TYPE_MISMATCH, /**< type of object is incorrect */
840 UCL_SCHEMA_INVALID_SCHEMA, /**< schema is invalid */
841 UCL_SCHEMA_MISSING_PROPERTY,/**< one or more missing properties */
842 UCL_SCHEMA_CONSTRAINT, /**< constraint found */
843 UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */
844 UCL_SCHEMA_UNKNOWN /**< generic error */
848 * Generic ucl schema error
850 struct ucl_schema_error {
851 enum ucl_schema_error_code code; /**< error code */
852 char msg[128]; /**< error message */
853 const ucl_object_t *obj; /**< object where error occured */
857 * Validate object `obj` using schema object `schema`.
858 * @param schema schema object
859 * @param obj object to validate
860 * @param err error pointer, if this parameter is not NULL and error has been
861 * occured, then `err` is filled with the exact error definition.
862 * @return true if `obj` is valid using `schema`
864 UCL_EXTERN bool ucl_object_validate (const ucl_object_t *schema,
865 const ucl_object_t *obj, struct ucl_schema_error *err);
873 * XXX: Poorly named API functions, need to replace them with the appropriate
874 * named function. All API functions *must* use naming ucl_object_*. Usage of
875 * ucl_obj* should be avoided.
877 #define ucl_obj_todouble_safe ucl_object_todouble_safe
878 #define ucl_obj_todouble ucl_object_todouble
879 #define ucl_obj_tostring ucl_object_tostring
880 #define ucl_obj_tostring_safe ucl_object_tostring_safe
881 #define ucl_obj_tolstring ucl_object_tolstring
882 #define ucl_obj_tolstring_safe ucl_object_tolstring_safe
883 #define ucl_obj_toint ucl_object_toint
884 #define ucl_obj_toint_safe ucl_object_toint_safe
885 #define ucl_obj_toboolean ucl_object_toboolean
886 #define ucl_obj_toboolean_safe ucl_object_toboolean_safe
887 #define ucl_obj_get_key ucl_object_find_key
888 #define ucl_obj_get_keyl ucl_object_find_keyl
889 #define ucl_obj_unref ucl_object_unref
890 #define ucl_obj_ref ucl_object_ref
891 #define ucl_obj_free ucl_object_free