xref: /freebsd/contrib/libucl/include/ucl.h (revision 1fb62fb074788ca4713551be09d6569966a3abee)
1 /* Copyright (c) 2013-2015, Vsevolod Stakhov
2  * All rights reserved.
3  *
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.
11  *
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.
22  */
23 
24 #ifndef UCL_H_
25 #define UCL_H_
26 
27 #include <string.h>
28 #include <stddef.h>
29 #include <stdlib.h>
30 #include <stdint.h>
31 #include <stdbool.h>
32 #include <stdarg.h>
33 #include <stdio.h>
34 
35 #ifdef _WIN32
36 # define UCL_EXTERN __declspec(dllexport)
37 #else
38 # define UCL_EXTERN
39 #endif
40 
41 /**
42  * @mainpage
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).
45  *
46  * This manual has several main sections:
47  *  - @ref structures
48  *  - @ref utils
49  *  - @ref parser
50  *  - @ref emitter
51  */
52 
53 /**
54  * @file ucl.h
55  * @brief UCL parsing and emitting functions
56  *
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
60  */
61 #ifdef  __cplusplus
62 extern "C" {
63 #endif
64 /*
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
69  */
70 #ifndef UCL_ALLOC
71 #define UCL_ALLOC(size) malloc(size)
72 #endif
73 #ifndef UCL_FREE
74 #define UCL_FREE(size, ptr) free(ptr)
75 #endif
76 
77 #if    __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
78 #define UCL_WARN_UNUSED_RESULT               \
79   __attribute__((warn_unused_result))
80 #else
81 #define UCL_WARN_UNUSED_RESULT
82 #endif
83 
84 #ifdef __GNUC__
85 #define UCL_DEPRECATED(func) func __attribute__ ((deprecated))
86 #elif defined(_MSC_VER)
87 #define UCL_DEPRECATED(func) __declspec(deprecated) func
88 #else
89 #define UCL_DEPRECATED(func) func
90 #endif
91 
92 /**
93  * @defgroup structures Structures and types
94  * UCL defines several enumeration types used for error reporting or specifying flags and attributes.
95  *
96  * @{
97  */
98 
99 /**
100  * The common error codes returned by ucl parser
101  */
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 */
112 } ucl_error_t;
113 
114 /**
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.
118  *
119  */
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 */
130 } ucl_type_t;
131 
132 /**
133  * You can use one of these types to serialise #ucl_object_t by using ucl_object_emit().
134  */
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 */
142 } ucl_emitter_t;
143 
144 /**
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.
149  */
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_flags_t;
159 
160 /**
161  * String conversion flags, that are used in #ucl_object_fromstring_common function.
162  */
163 typedef enum ucl_string_flags {
164 	UCL_STRING_RAW = 0x0,     /**< Treat string as is */
165 	UCL_STRING_ESCAPE = (1 << 0),  /**< Perform JSON escape */
166 	UCL_STRING_TRIM = (1 << 1),    /**< Trim leading and trailing whitespaces */
167 	UCL_STRING_PARSE_BOOLEAN = (1 << 2),    /**< Parse passed string and detect boolean */
168 	UCL_STRING_PARSE_INT = (1 << 3),    /**< Parse passed string and detect integer number */
169 	UCL_STRING_PARSE_DOUBLE = (1 << 4),    /**< Parse passed string and detect integer or float number */
170 	UCL_STRING_PARSE_TIME = (1 << 5), /**< Parse time strings */
171 	UCL_STRING_PARSE_NUMBER =  UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE|UCL_STRING_PARSE_TIME,  /**<
172 									Parse passed string and detect number */
173 	UCL_STRING_PARSE =  UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER,   /**<
174 									Parse passed string (and detect booleans and numbers) */
175 	UCL_STRING_PARSE_BYTES = (1 << 6)  /**< Treat numbers as bytes */
176 } ucl_string_flags_t;
177 
178 /**
179  * Basic flags for an object
180  */
181 typedef enum ucl_object_flags {
182 	UCL_OBJECT_ALLOCATED_KEY = (1 << 0), /**< An object has key allocated internally */
183 	UCL_OBJECT_ALLOCATED_VALUE = (1 << 1), /**< An object has a string value allocated internally */
184 	UCL_OBJECT_NEED_KEY_ESCAPE = (1 << 2), /**< The key of an object need to be escaped on output */
185 	UCL_OBJECT_EPHEMERAL = (1 << 3), /**< Temporary object that does not need to be freed really */
186 	UCL_OBJECT_MULTILINE = (1 << 4), /**< String should be displayed as multiline string */
187 	UCL_OBJECT_MULTIVALUE = (1 << 5), /**< Object is a key with multiple values */
188 	UCL_OBJECT_INHERITED = (1 << 6), /**< Object has been inherited from another */
189 	UCL_OBJECT_BINARY = (1 << 7) /**< Object contains raw binary data */
190 } ucl_object_flags_t;
191 
192 /**
193  * Duplicate policy types
194  */
195 enum ucl_duplicate_strategy {
196 	UCL_DUPLICATE_APPEND = 0, /**< Default policy to merge based on priorities */
197 	UCL_DUPLICATE_MERGE,     /**< Merge new object with old one */
198 	UCL_DUPLICATE_REWRITE,   /**< Rewrite old keys */
199 	UCL_DUPLICATE_ERROR      /**< Stop parsing on duplicate found */
200 };
201 
202 /**
203  * Input format type
204  */
205 enum ucl_parse_type {
206 	UCL_PARSE_UCL = 0, /**< Default ucl format */
207 	UCL_PARSE_MSGPACK, /**< Message pack input format */
208 	UCL_PARSE_CSEXP /**< Canonical S-expressions */
209 };
210 
211 /**
212  * UCL object structure. Please mention that the most of fields should not be touched by
213  * UCL users. In future, this structure may be converted to private one.
214  */
215 typedef struct ucl_object_s {
216 	/**
217 	 * Variant value type
218 	 */
219 	union {
220 		int64_t iv;							/**< Int value of an object */
221 		const char *sv;						/**< String value of an object */
222 		double dv;							/**< Double value of an object */
223 		void *av;							/**< Array					*/
224 		void *ov;							/**< Object					*/
225 		void* ud;							/**< Opaque user data		*/
226 	} value;
227 	const char *key;						/**< Key of an object		*/
228 	struct ucl_object_s *next;				/**< Array handle			*/
229 	struct ucl_object_s *prev;				/**< Array handle			*/
230 	uint32_t keylen;						/**< Lenght of a key		*/
231 	uint32_t len;							/**< Size of an object		*/
232 	uint32_t ref;							/**< Reference count		*/
233 	uint16_t flags;							/**< Object flags			*/
234 	uint16_t type;							/**< Real type				*/
235 	unsigned char* trash_stack[2];			/**< Pointer to allocated chunks */
236 } ucl_object_t;
237 
238 /**
239  * Destructor type for userdata objects
240  * @param ud user specified data pointer
241  */
242 typedef void (*ucl_userdata_dtor)(void *ud);
243 typedef const char* (*ucl_userdata_emitter)(void *ud);
244 
245 /** @} */
246 
247 /**
248  * @defgroup utils Utility functions
249  * A number of utility functions simplify handling of UCL objects
250  *
251  * @{
252  */
253 /**
254  * Copy and return a key of an object, returned key is zero-terminated
255  * @param obj CL object
256  * @return zero terminated key
257  */
258 UCL_EXTERN char* ucl_copy_key_trash (const ucl_object_t *obj);
259 
260 /**
261  * Copy and return a string value of an object, returned key is zero-terminated
262  * @param obj CL object
263  * @return zero terminated string representation of object value
264  */
265 UCL_EXTERN char* ucl_copy_value_trash (const ucl_object_t *obj);
266 
267 /**
268  * Creates a new object
269  * @return new object
270  */
271 UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT;
272 
273 /**
274  * Create new object with type specified
275  * @param type type of a new object
276  * @return new object
277  */
278 UCL_EXTERN ucl_object_t* ucl_object_typed_new (ucl_type_t type) UCL_WARN_UNUSED_RESULT;
279 
280 /**
281  * Create new object with type and priority specified
282  * @param type type of a new object
283  * @param priority priority of an object
284  * @return new object
285  */
286 UCL_EXTERN ucl_object_t* ucl_object_new_full (ucl_type_t type, unsigned priority)
287 	UCL_WARN_UNUSED_RESULT;
288 
289 /**
290  * Create new object with userdata dtor
291  * @param dtor destructor function
292  * @param emitter emitter for userdata
293  * @param ptr opaque pointer
294  * @return new object
295  */
296 UCL_EXTERN ucl_object_t* ucl_object_new_userdata (ucl_userdata_dtor dtor,
297 		ucl_userdata_emitter emitter, void *ptr) UCL_WARN_UNUSED_RESULT;
298 
299 /**
300  * Perform deep copy of an object copying everything
301  * @param other object to copy
302  * @return new object with refcount equal to 1
303  */
304 UCL_EXTERN ucl_object_t * ucl_object_copy (const ucl_object_t *other)
305 	UCL_WARN_UNUSED_RESULT;
306 
307 /**
308  * Return the type of an object
309  * @return the object type
310  */
311 UCL_EXTERN ucl_type_t ucl_object_type (const ucl_object_t *obj);
312 
313 /**
314  * Converts ucl object type to its string representation
315  * @param type type of object
316  * @return constant string describing type
317  */
318 UCL_EXTERN const char * ucl_object_type_to_string (ucl_type_t type);
319 
320 /**
321  * Converts string that represents ucl type to real ucl type enum
322  * @param input C string with name of type
323  * @param res resulting target
324  * @return true if `input` is a name of type stored in `res`
325  */
326 UCL_EXTERN bool ucl_object_string_to_type (const char *input, ucl_type_t *res);
327 
328 /**
329  * Convert any string to an ucl object making the specified transformations
330  * @param str fixed size or NULL terminated string
331  * @param len length (if len is zero, than str is treated as NULL terminated)
332  * @param flags conversion flags
333  * @return new object
334  */
335 UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len,
336 		enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT;
337 
338 /**
339  * Create a UCL object from the specified string
340  * @param str NULL terminated string, will be json escaped
341  * @return new object
342  */
343 UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str) UCL_WARN_UNUSED_RESULT;
344 
345 /**
346  * Create a UCL object from the specified string
347  * @param str fixed size string, will be json escaped
348  * @param len length of a string
349  * @return new object
350  */
351 UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str,
352 		size_t len) UCL_WARN_UNUSED_RESULT;
353 
354 /**
355  * Create an object from an integer number
356  * @param iv number
357  * @return new object
358  */
359 UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv) UCL_WARN_UNUSED_RESULT;
360 
361 /**
362  * Create an object from a float number
363  * @param dv number
364  * @return new object
365  */
366 UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv) UCL_WARN_UNUSED_RESULT;
367 
368 /**
369  * Create an object from a boolean
370  * @param bv bool value
371  * @return new object
372  */
373 UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv) UCL_WARN_UNUSED_RESULT;
374 
375 /**
376  * Insert a object 'elt' to the hash 'top' and associate it with key 'key'
377  * @param top destination object (must be of type UCL_OBJECT)
378  * @param elt element to insert (must NOT be NULL)
379  * @param key key to associate with this object (either const or preallocated)
380  * @param keylen length of the key (or 0 for NULL terminated keys)
381  * @param copy_key make an internal copy of key
382  * @return true if key has been inserted
383  */
384 UCL_EXTERN bool ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt,
385 		const char *key, size_t keylen, bool copy_key);
386 
387 /**
388  * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
389  * if no object has been found this function works like ucl_object_insert_key()
390  * @param top destination object (must be of type UCL_OBJECT)
391  * @param elt element to insert (must NOT be NULL)
392  * @param key key to associate with this object (either const or preallocated)
393  * @param keylen length of the key (or 0 for NULL terminated keys)
394  * @param copy_key make an internal copy of key
395  * @return true if key has been inserted
396  */
397 UCL_EXTERN bool ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt,
398 		const char *key, size_t keylen, bool copy_key);
399 
400 /**
401  * Merge the keys from one object to another object. Overwrite on conflict
402  * @param top destination object (must be of type UCL_OBJECT)
403  * @param elt element to insert (must be of type UCL_OBJECT)
404  * @param copy copy rather than reference the elements
405  * @return true if all keys have been merged
406  */
407 UCL_EXTERN bool ucl_object_merge (ucl_object_t *top, ucl_object_t *elt, bool copy);
408 
409 /**
410  * Delete a object associated with key 'key', old object will be unrefered,
411  * @param top object
412  * @param key key associated to the object to remove
413  * @param keylen length of the key (or 0 for NULL terminated keys)
414  */
415 UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top,
416 		const char *key, size_t keylen);
417 
418 /**
419  * Delete a object associated with key 'key', old object will be unrefered,
420  * @param top object
421  * @param key key associated to the object to remove
422  */
423 UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top,
424 		const char *key);
425 
426 
427 /**
428  * Removes `key` from `top` object, returning the object that was removed. This
429  * object is not released, caller must unref the returned object when it is no
430  * longer needed.
431  * @param top object
432  * @param key key to remove
433  * @param keylen length of the key (or 0 for NULL terminated keys)
434  * @return removed object or NULL if object has not been found
435  */
436 UCL_EXTERN ucl_object_t* ucl_object_pop_keyl (ucl_object_t *top, const char *key,
437 		size_t keylen) UCL_WARN_UNUSED_RESULT;
438 
439 /**
440  * Removes `key` from `top` object returning the object that was removed. This
441  * object is not released, caller must unref the returned object when it is no
442  * longer needed.
443  * @param top object
444  * @param key key to remove
445  * @return removed object or NULL if object has not been found
446  */
447 UCL_EXTERN ucl_object_t* ucl_object_pop_key (ucl_object_t *top, const char *key)
448 	UCL_WARN_UNUSED_RESULT;
449 
450 /**
451  * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if
452  * the specified key exist, try to merge its content
453  * @param top destination object (must be of type UCL_OBJECT)
454  * @param elt element to insert (must NOT be NULL)
455  * @param key key to associate with this object (either const or preallocated)
456  * @param keylen length of the key (or 0 for NULL terminated keys)
457  * @param copy_key make an internal copy of key
458  * @return true if key has been inserted
459  */
460 UCL_EXTERN bool ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt,
461 		const char *key, size_t keylen, bool copy_key);
462 
463 /**
464  * Append an element to the end of array object
465  * @param top destination object (must NOT be NULL)
466  * @param elt element to append (must NOT be NULL)
467  * @return true if value has been inserted
468  */
469 UCL_EXTERN bool ucl_array_append (ucl_object_t *top,
470 		ucl_object_t *elt);
471 
472 /**
473  * Append an element to the start of array object
474  * @param top destination object (must NOT be NULL)
475  * @param elt element to append (must NOT be NULL)
476  * @return true if value has been inserted
477  */
478 UCL_EXTERN bool ucl_array_prepend (ucl_object_t *top,
479 		ucl_object_t *elt);
480 
481 /**
482  * Merge all elements of second array into the first array
483  * @param top destination array (must be of type UCL_ARRAY)
484  * @param elt array to copy elements from (must be of type UCL_ARRAY)
485  * @param copy copy elements instead of referencing them
486  * @return true if arrays were merged
487  */
488 UCL_EXTERN bool ucl_array_merge (ucl_object_t *top, ucl_object_t *elt,
489 		bool copy);
490 
491 /**
492  * Removes an element `elt` from the array `top`, returning the object that was
493  * removed. This object is not released, caller must unref the returned object
494  * when it is no longer needed.
495  * @param top array ucl object
496  * @param elt element to remove
497  * @return removed element or NULL if `top` is NULL or not an array
498  */
499 UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top,
500 		ucl_object_t *elt);
501 
502 /**
503  * Returns the first element of the array `top`
504  * @param top array ucl object
505  * @return element or NULL if `top` is NULL or not an array
506  */
507 UCL_EXTERN const ucl_object_t* ucl_array_head (const ucl_object_t *top);
508 
509 /**
510  * Returns the last element of the array `top`
511  * @param top array ucl object
512  * @return element or NULL if `top` is NULL or not an array
513  */
514 UCL_EXTERN const ucl_object_t* ucl_array_tail (const ucl_object_t *top);
515 
516 /**
517  * Removes the last element from the array `top`, returning the object that was
518  * removed. This object is not released, caller must unref the returned object
519  * when it is no longer needed.
520  * @param top array ucl object
521  * @return removed element or NULL if `top` is NULL or not an array
522  */
523 UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top);
524 
525 /**
526  * Removes the first element from the array `top`, returning the object that was
527  * removed. This object is not released, caller must unref the returned object
528  * when it is no longer needed.
529  * @param top array ucl object
530  * @return removed element or NULL if `top` is NULL or not an array
531  */
532 UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top);
533 
534 /**
535  * Return object identified by index of the array `top`
536  * @param top object to get a key from (must be of type UCL_ARRAY)
537  * @param index array index to return
538  * @return object at the specified index or NULL if index is not found
539  */
540 UCL_EXTERN const ucl_object_t* ucl_array_find_index (const ucl_object_t *top,
541 		unsigned int index);
542 
543 /**
544  * Return the index of `elt` in the array `top`
545  * @param top object to get a key from (must be of type UCL_ARRAY)
546  * @param elt element to find index of (must NOT be NULL)
547  * @return index of `elt` in the array `top or (unsigned int)-1 if `elt` is not found
548  */
549 UCL_EXTERN unsigned int ucl_array_index_of (ucl_object_t *top,
550 		ucl_object_t *elt);
551 
552 /**
553  * Replace an element in an array with a different element, returning the object
554  * that was replaced. This object is not released, caller must unref the
555  * returned object when it is no longer needed.
556  * @param top destination object (must be of type UCL_ARRAY)
557  * @param elt element to append (must NOT be NULL)
558  * @param index array index in destination to overwrite with elt
559  * @return object that was replaced or NULL if index is not found
560  */
561 ucl_object_t *
562 ucl_array_replace_index (ucl_object_t *top, ucl_object_t *elt,
563 	unsigned int index);
564 
565 /**
566  * Append a element to another element forming an implicit array
567  * @param head head to append (may be NULL)
568  * @param elt new element
569  * @return the new implicit array
570  */
571 UCL_EXTERN ucl_object_t * ucl_elt_append (ucl_object_t *head,
572 		ucl_object_t *elt);
573 
574 /**
575  * Converts an object to double value
576  * @param obj CL object
577  * @param target target double variable
578  * @return true if conversion was successful
579  */
580 UCL_EXTERN bool ucl_object_todouble_safe (const ucl_object_t *obj, double *target);
581 
582 /**
583  * Unsafe version of \ref ucl_obj_todouble_safe
584  * @param obj CL object
585  * @return double value
586  */
587 UCL_EXTERN double ucl_object_todouble (const ucl_object_t *obj);
588 
589 /**
590  * Converts an object to integer value
591  * @param obj CL object
592  * @param target target integer variable
593  * @return true if conversion was successful
594  */
595 UCL_EXTERN bool ucl_object_toint_safe (const ucl_object_t *obj, int64_t *target);
596 
597 /**
598  * Unsafe version of \ref ucl_obj_toint_safe
599  * @param obj CL object
600  * @return int value
601  */
602 UCL_EXTERN int64_t ucl_object_toint (const ucl_object_t *obj);
603 
604 /**
605  * Converts an object to boolean value
606  * @param obj CL object
607  * @param target target boolean variable
608  * @return true if conversion was successful
609  */
610 UCL_EXTERN bool ucl_object_toboolean_safe (const ucl_object_t *obj, bool *target);
611 
612 /**
613  * Unsafe version of \ref ucl_obj_toboolean_safe
614  * @param obj CL object
615  * @return boolean value
616  */
617 UCL_EXTERN bool ucl_object_toboolean (const ucl_object_t *obj);
618 
619 /**
620  * Converts an object to string value
621  * @param obj CL object
622  * @param target target string variable, no need to free value
623  * @return true if conversion was successful
624  */
625 UCL_EXTERN bool ucl_object_tostring_safe (const ucl_object_t *obj, const char **target);
626 
627 /**
628  * Unsafe version of \ref ucl_obj_tostring_safe
629  * @param obj CL object
630  * @return string value
631  */
632 UCL_EXTERN const char* ucl_object_tostring (const ucl_object_t *obj);
633 
634 /**
635  * Convert any object to a string in JSON notation if needed
636  * @param obj CL object
637  * @return string value
638  */
639 UCL_EXTERN const char* ucl_object_tostring_forced (const ucl_object_t *obj);
640 
641 /**
642  * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
643  * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
644  * @param obj CL object
645  * @param target target string variable, no need to free value
646  * @param tlen target length
647  * @return true if conversion was successful
648  */
649 UCL_EXTERN bool ucl_object_tolstring_safe (const ucl_object_t *obj,
650 		const char **target, size_t *tlen);
651 
652 /**
653  * Unsafe version of \ref ucl_obj_tolstring_safe
654  * @param obj CL object
655  * @return string value
656  */
657 UCL_EXTERN const char* ucl_object_tolstring (const ucl_object_t *obj, size_t *tlen);
658 
659 /**
660  * Return object identified by a key in the specified object
661  * @param obj object to get a key from (must be of type UCL_OBJECT)
662  * @param key key to search
663  * @return object matching the specified key or NULL if key was not found
664  */
665 UCL_EXTERN const ucl_object_t* ucl_object_lookup (const ucl_object_t *obj,
666 		const char *key);
667 #define ucl_object_find_key ucl_object_lookup
668 
669 /**
670  * Return object identified by a key in the specified object, if the first key is
671  * not found then look for the next one. This process is repeated unless
672  * the next argument in the list is not NULL. So, `ucl_object_find_any_key(obj, key, NULL)`
673  * is equal to `ucl_object_find_key(obj, key)`
674  * @param obj object to get a key from (must be of type UCL_OBJECT)
675  * @param key key to search
676  * @param ... list of alternative keys to search (NULL terminated)
677  * @return object matching the specified key or NULL if key was not found
678  */
679 UCL_EXTERN const ucl_object_t* ucl_object_lookup_any (const ucl_object_t *obj,
680 		const char *key, ...);
681 #define ucl_object_find_any_key ucl_object_lookup_any
682 
683 /**
684  * Return object identified by a fixed size key in the specified object
685  * @param obj object to get a key from (must be of type UCL_OBJECT)
686  * @param key key to search
687  * @param klen length of a key
688  * @return object matching the specified key or NULL if key was not found
689  */
690 UCL_EXTERN const ucl_object_t* ucl_object_lookup_len (const ucl_object_t *obj,
691 		const char *key, size_t klen);
692 #define ucl_object_find_keyl ucl_object_lookup_len
693 
694 /**
695  * Return object identified by dot notation string
696  * @param obj object to search in
697  * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
698  * @return object matched the specified path or NULL if path is not found
699  */
700 UCL_EXTERN const ucl_object_t *ucl_object_lookup_path (const ucl_object_t *obj,
701 		const char *path);
702 #define ucl_lookup_path ucl_object_lookup_path
703 
704 /**
705  * Return object identified by object notation string using arbitrary delimiter
706  * @param obj object to search in
707  * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
708  * @param sep the sepatorator to use in place of . (incase keys have . in them)
709  * @return object matched the specified path or NULL if path is not found
710  */
711 UCL_EXTERN const ucl_object_t *ucl_object_lookup_path_char (const ucl_object_t *obj,
712 		const char *path, char sep);
713 #define ucl_lookup_path_char ucl_object_lookup_path_char
714 
715 /**
716  * Returns a key of an object as a NULL terminated string
717  * @param obj CL object
718  * @return key or NULL if there is no key
719  */
720 UCL_EXTERN const char* ucl_object_key (const ucl_object_t *obj);
721 
722 /**
723  * Returns a key of an object as a fixed size string (may be more efficient)
724  * @param obj CL object
725  * @param len target key length
726  * @return key pointer
727  */
728 UCL_EXTERN const char* ucl_object_keyl (const ucl_object_t *obj, size_t *len);
729 
730 /**
731  * Increase reference count for an object
732  * @param obj object to ref
733  * @return the referenced object
734  */
735 UCL_EXTERN ucl_object_t* ucl_object_ref (const ucl_object_t *obj);
736 
737 /**
738  * Free ucl object
739  * @param obj ucl object to free
740  */
741 UCL_DEPRECATED(UCL_EXTERN void ucl_object_free (ucl_object_t *obj));
742 
743 /**
744  * Decrease reference count for an object
745  * @param obj object to unref
746  */
747 UCL_EXTERN void ucl_object_unref (ucl_object_t *obj);
748 
749 /**
750  * Compare objects `o1` and `o2`
751  * @param o1 the first object
752  * @param o2 the second object
753  * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
754  * The order of comparison:
755  * 1) Type of objects
756  * 2) Size of objects
757  * 3) Content of objects
758  */
759 UCL_EXTERN int ucl_object_compare (const ucl_object_t *o1,
760 		const ucl_object_t *o2);
761 
762 /**
763  * Compare objects `o1` and `o2` useful for sorting
764  * @param o1 the first object
765  * @param o2 the second object
766  * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
767  * The order of comparison:
768  * 1) Type of objects
769  * 2) Size of objects
770  * 3) Content of objects
771  */
772 UCL_EXTERN int ucl_object_compare_qsort (const ucl_object_t **o1,
773 		const ucl_object_t **o2);
774 
775 /**
776  * Sort UCL array using `cmp` compare function
777  * @param ar
778  * @param cmp
779  */
780 UCL_EXTERN void ucl_object_array_sort (ucl_object_t *ar,
781 		int (*cmp)(const ucl_object_t **o1, const ucl_object_t **o2));
782 
783 /**
784  * Get the priority for specific UCL object
785  * @param obj any ucl object
786  * @return priority of an object
787  */
788 UCL_EXTERN unsigned int ucl_object_get_priority (const ucl_object_t *obj);
789 
790 /**
791  * Set explicit priority of an object.
792  * @param obj any ucl object
793  * @param priority new priroity value (only 4 least significant bits are considred)
794  */
795 UCL_EXTERN void ucl_object_set_priority (ucl_object_t *obj,
796 		unsigned int priority);
797 
798 /**
799  * Opaque iterator object
800  */
801 typedef void* ucl_object_iter_t;
802 
803 /**
804  * Get next key from an object
805  * @param obj object to iterate
806  * @param iter opaque iterator, must be set to NULL on the first call:
807  * ucl_object_iter_t it = NULL;
808  * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
809  * @return the next object or NULL
810  */
811 UCL_EXTERN const ucl_object_t* ucl_object_iterate (const ucl_object_t *obj,
812 		ucl_object_iter_t *iter, bool expand_values);
813 #define ucl_iterate_object ucl_object_iterate
814 
815 /**
816  * Create new safe iterator for the specified object
817  * @param obj object to iterate
818  * @return new iterator object that should be used with safe iterators API only
819  */
820 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_new (const ucl_object_t *obj)
821 	UCL_WARN_UNUSED_RESULT;
822 /**
823  * Reset initialized iterator to a new object
824  * @param obj new object to iterate
825  * @return modified iterator object
826  */
827 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_reset (ucl_object_iter_t it,
828 		const ucl_object_t *obj);
829 
830 /**
831  * Get the next object from the `obj`. This fucntion iterates over arrays, objects
832  * and implicit arrays
833  * @param iter safe iterator
834  * @return the next object in sequence
835  */
836 UCL_EXTERN const ucl_object_t* ucl_object_iterate_safe (ucl_object_iter_t iter,
837 		bool expand_values);
838 
839 /**
840  * Free memory associated with the safe iterator
841  * @param it safe iterator object
842  */
843 UCL_EXTERN void ucl_object_iterate_free (ucl_object_iter_t it);
844 
845 /** @} */
846 
847 
848 /**
849  * @defgroup parser Parsing functions
850  * These functions are used to parse UCL objects
851  *
852  * @{
853  */
854 
855 /**
856  * Macro handler for a parser
857  * @param data the content of macro
858  * @param len the length of content
859  * @param arguments arguments object
860  * @param ud opaque user data
861  * @param err error pointer
862  * @return true if macro has been parsed
863  */
864 typedef bool (*ucl_macro_handler) (const unsigned char *data, size_t len,
865 		const ucl_object_t *arguments,
866 		void* ud);
867 
868 /**
869  * Context dependent macro handler for a parser
870  * @param data the content of macro
871  * @param len the length of content
872  * @param arguments arguments object
873  * @param context previously parsed context
874  * @param ud opaque user data
875  * @param err error pointer
876  * @return true if macro has been parsed
877  */
878 typedef bool (*ucl_context_macro_handler) (const unsigned char *data, size_t len,
879 		const ucl_object_t *arguments,
880 		const ucl_object_t *context,
881 		void* ud);
882 
883 /* Opaque parser */
884 struct ucl_parser;
885 
886 /**
887  * Creates new parser object
888  * @param pool pool to allocate memory from
889  * @return new parser object
890  */
891 UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags);
892 
893 /**
894  * Sets the default priority for the parser applied to chunks that does not
895  * specify priority explicitly
896  * @param parser parser object
897  * @param prio default priority (0 .. 16)
898  * @return true if parser's default priority was set
899  */
900 UCL_EXTERN bool ucl_parser_set_default_priority (struct ucl_parser *parser,
901 		unsigned prio);
902 /**
903  * Register new handler for a macro
904  * @param parser parser object
905  * @param macro macro name (without leading dot)
906  * @param handler handler (it is called immediately after macro is parsed)
907  * @param ud opaque user data for a handler
908  */
909 UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser,
910 		const char *macro,
911 		ucl_macro_handler handler, void* ud);
912 
913 /**
914  * Register new context dependent handler for a macro
915  * @param parser parser object
916  * @param macro macro name (without leading dot)
917  * @param handler handler (it is called immediately after macro is parsed)
918  * @param ud opaque user data for a handler
919  */
920 UCL_EXTERN void ucl_parser_register_context_macro (struct ucl_parser *parser,
921 		const char *macro,
922 		ucl_context_macro_handler handler,
923 		void* ud);
924 
925 /**
926  * Handler to detect unregistered variables
927  * @param data variable data
928  * @param len length of variable
929  * @param replace (out) replace value for variable
930  * @param replace_len (out) replace length for variable
931  * @param need_free (out) UCL will free `dest` after usage
932  * @param ud opaque userdata
933  * @return true if variable
934  */
935 typedef bool (*ucl_variable_handler) (const unsigned char *data, size_t len,
936 		unsigned char **replace, size_t *replace_len, bool *need_free, void* ud);
937 
938 /**
939  * Register new parser variable
940  * @param parser parser object
941  * @param var variable name
942  * @param value variable value
943  */
944 UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var,
945 		const char *value);
946 
947 /**
948  * Set handler for unknown variables
949  * @param parser parser structure
950  * @param handler desired handler
951  * @param ud opaque data for the handler
952  */
953 UCL_EXTERN void ucl_parser_set_variables_handler (struct ucl_parser *parser,
954 		ucl_variable_handler handler, void *ud);
955 
956 /**
957  * Load new chunk to a parser
958  * @param parser parser structure
959  * @param data the pointer to the beginning of a chunk
960  * @param len the length of a chunk
961  * @return true if chunk has been added and false in case of error
962  */
963 UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser,
964 		const unsigned char *data, size_t len);
965 
966 /**
967  * Load new chunk to a parser with the specified priority
968  * @param parser parser structure
969  * @param data the pointer to the beginning of a chunk
970  * @param len the length of a chunk
971  * @param priority the desired priority of a chunk (only 4 least significant bits
972  * are considered for this parameter)
973  * @return true if chunk has been added and false in case of error
974  */
975 UCL_EXTERN bool ucl_parser_add_chunk_priority (struct ucl_parser *parser,
976 		const unsigned char *data, size_t len, unsigned priority);
977 
978 /**
979  * Full version of ucl_add_chunk with priority and duplicate strategy
980  * @param parser parser structure
981  * @param data the pointer to the beginning of a chunk
982  * @param len the length of a chunk
983  * @param priority the desired priority of a chunk (only 4 least significant bits
984  * are considered for this parameter)
985  * @param strat duplicates merging strategy
986  * @param parse_type input format
987  * @return true if chunk has been added and false in case of error
988  */
989 UCL_EXTERN bool ucl_parser_add_chunk_full (struct ucl_parser *parser,
990 		const unsigned char *data, size_t len, unsigned priority,
991 		enum ucl_duplicate_strategy strat, enum ucl_parse_type parse_type);
992 
993 /**
994  * Load ucl object from a string
995  * @param parser parser structure
996  * @param data the pointer to the string
997  * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
998  * @return true if string has been added and false in case of error
999  */
1000 UCL_EXTERN bool ucl_parser_add_string (struct ucl_parser *parser,
1001 		const char *data,size_t len);
1002 
1003 /**
1004  * Load ucl object from a string
1005  * @param parser parser structure
1006  * @param data the pointer to the string
1007  * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
1008  * @param priority the desired priority of a chunk (only 4 least significant bits
1009  * are considered for this parameter)
1010  * @return true if string has been added and false in case of error
1011  */
1012 UCL_EXTERN bool ucl_parser_add_string_priority (struct ucl_parser *parser,
1013 		const char *data, size_t len, unsigned priority);
1014 
1015 /**
1016  * Load and add data from a file
1017  * @param parser parser structure
1018  * @param filename the name of file
1019  * @return true if chunk has been added and false in case of error
1020  */
1021 UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser,
1022 		const char *filename);
1023 
1024 /**
1025  * Load and add data from a file
1026  * @param parser parser structure
1027  * @param filename the name of file
1028  * @param priority the desired priority of a chunk (only 4 least significant bits
1029  * are considered for this parameter)
1030  * @return true if chunk has been added and false in case of error
1031  */
1032 UCL_EXTERN bool ucl_parser_add_file_priority (struct ucl_parser *parser,
1033 		const char *filename, unsigned priority);
1034 
1035 /**
1036  * Load and add data from a file
1037  * @param parser parser structure
1038  * @param filename the name of file
1039  * @param priority the desired priority of a chunk (only 4 least significant bits
1040  * are considered for this parameter)
1041  * @param strat Merge strategy to use while parsing this file
1042  * @param parse_type Parser type to use while parsing this file
1043  * @return true if chunk has been added and false in case of error
1044  */
1045 UCL_EXTERN bool ucl_parser_add_file_full (struct ucl_parser *parser, const char *filename,
1046 		unsigned priority, enum ucl_duplicate_strategy strat,
1047 		enum ucl_parse_type parse_type);
1048 
1049 /**
1050  * Load and add data from a file descriptor
1051  * @param parser parser structure
1052  * @param filename the name of file
1053  * @param err if *err is NULL it is set to parser error
1054  * @return true if chunk has been added and false in case of error
1055  */
1056 UCL_EXTERN bool ucl_parser_add_fd (struct ucl_parser *parser,
1057 		int fd);
1058 
1059 /**
1060  * Load and add data from a file descriptor
1061  * @param parser parser structure
1062  * @param filename the name of file
1063  * @param err if *err is NULL it is set to parser error
1064  * @param priority the desired priority of a chunk (only 4 least significant bits
1065  * are considered for this parameter)
1066  * @return true if chunk has been added and false in case of error
1067  */
1068 UCL_EXTERN bool ucl_parser_add_fd_priority (struct ucl_parser *parser,
1069 		int fd, unsigned priority);
1070 
1071 /**
1072  * Provide a UCL_ARRAY of paths to search for include files. The object is
1073  * copied so caller must unref the object.
1074  * @param parser parser structure
1075  * @param paths UCL_ARRAY of paths to search
1076  * @return true if the path search array was replaced in the parser
1077  */
1078 UCL_EXTERN bool ucl_set_include_path (struct ucl_parser *parser,
1079 		ucl_object_t *paths);
1080 
1081 /**
1082  * Get a top object for a parser (refcount is increased)
1083  * @param parser parser structure
1084  * @param err if *err is NULL it is set to parser error
1085  * @return top parser object or NULL
1086  */
1087 UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);
1088 
1089 /**
1090  * Get the error string if parsing has been failed
1091  * @param parser parser object
1092  * @return error description
1093  */
1094 UCL_EXTERN const char *ucl_parser_get_error (struct ucl_parser *parser);
1095 
1096 /**
1097  * Get the code of the last error
1098  * @param parser parser object
1099  * @return error code
1100  */
1101 UCL_EXTERN int ucl_parser_get_error_code (struct ucl_parser *parser);
1102 
1103 /**
1104  * Get the current column number within parser
1105  * @param parser parser object
1106  * @return current column number
1107  */
1108 UCL_EXTERN unsigned ucl_parser_get_column (struct ucl_parser *parser);
1109 
1110 /**
1111  * Get the current line number within parser
1112  * @param parser parser object
1113  * @return current line number
1114  */
1115 UCL_EXTERN unsigned ucl_parser_get_linenum (struct ucl_parser *parser);
1116 
1117 /**
1118  * Clear the error in the parser
1119  * @param parser parser object
1120  */
1121 UCL_EXTERN void ucl_parser_clear_error (struct ucl_parser *parser);
1122 
1123 /**
1124  * Free ucl parser object
1125  * @param parser parser object
1126  */
1127 UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser);
1128 
1129 /**
1130  * Get constant opaque pointer to comments structure for this parser. Increase
1131  * refcount to prevent this object to be destroyed on parser's destruction
1132  * @param parser parser structure
1133  * @return ucl comments pointer or NULL
1134  */
1135 UCL_EXTERN const ucl_object_t * ucl_parser_get_comments (struct ucl_parser *parser);
1136 
1137 /**
1138  * Utility function to find a comment object for the specified object in the input
1139  * @param comments comments object
1140  * @param srch search object
1141  * @return string comment enclosed in ucl_object_t
1142  */
1143 UCL_EXTERN const ucl_object_t * ucl_comments_find (const ucl_object_t *comments,
1144 		const ucl_object_t *srch);
1145 
1146 /**
1147  * Move comment from `from` object to `to` object
1148  * @param comments comments object
1149  * @param what source object
1150  * @param whith destination object
1151  * @return `true` if `from` has comment and it has been moved to `to`
1152  */
1153 UCL_EXTERN bool ucl_comments_move (ucl_object_t *comments,
1154 		const ucl_object_t *from, const ucl_object_t *to);
1155 
1156 /**
1157  * Adds a new comment for an object
1158  * @param comments comments object
1159  * @param obj object to add comment to
1160  * @param comment string representation of a comment
1161  */
1162 UCL_EXTERN void ucl_comments_add (ucl_object_t *comments,
1163 		const ucl_object_t *obj, const char *comment);
1164 
1165 /**
1166  * Add new public key to parser for signatures check
1167  * @param parser parser object
1168  * @param key PEM representation of a key
1169  * @param len length of the key
1170  * @param err if *err is NULL it is set to parser error
1171  * @return true if a key has been successfully added
1172  */
1173 UCL_EXTERN bool ucl_parser_pubkey_add (struct ucl_parser *parser,
1174 		const unsigned char *key, size_t len);
1175 
1176 /**
1177  * Set FILENAME and CURDIR variables in parser
1178  * @param parser parser object
1179  * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd()
1180  * @param need_expand perform realpath() if this variable is true and filename is not NULL
1181  * @return true if variables has been set
1182  */
1183 UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename,
1184 		bool need_expand);
1185 
1186 /** @} */
1187 
1188 /**
1189  * @defgroup emitter Emitting functions
1190  * These functions are used to serialise UCL objects to some string representation.
1191  *
1192  * @{
1193  */
1194 
1195 struct ucl_emitter_context;
1196 /**
1197  * Structure using for emitter callbacks
1198  */
1199 struct ucl_emitter_functions {
1200 	/** Append a single character */
1201 	int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud);
1202 	/** Append a string of a specified length */
1203 	int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud);
1204 	/** Append a 64 bit integer */
1205 	int (*ucl_emitter_append_int) (int64_t elt, void *ud);
1206 	/** Append floating point element */
1207 	int (*ucl_emitter_append_double) (double elt, void *ud);
1208 	/** Free userdata */
1209 	void (*ucl_emitter_free_func)(void *ud);
1210 	/** Opaque userdata pointer */
1211 	void *ud;
1212 };
1213 
1214 struct ucl_emitter_operations {
1215 	/** Write a primitive element */
1216 	void (*ucl_emitter_write_elt) (struct ucl_emitter_context *ctx,
1217 		const ucl_object_t *obj, bool first, bool print_key);
1218 	/** Start ucl object */
1219 	void (*ucl_emitter_start_object) (struct ucl_emitter_context *ctx,
1220 		const ucl_object_t *obj, bool print_key);
1221 	/** End ucl object */
1222 	void (*ucl_emitter_end_object) (struct ucl_emitter_context *ctx,
1223 		const ucl_object_t *obj);
1224 	/** Start ucl array */
1225 	void (*ucl_emitter_start_array) (struct ucl_emitter_context *ctx,
1226 		const ucl_object_t *obj, bool print_key);
1227 	void (*ucl_emitter_end_array) (struct ucl_emitter_context *ctx,
1228 		const ucl_object_t *obj);
1229 };
1230 
1231 /**
1232  * Structure that defines emitter functions
1233  */
1234 struct ucl_emitter_context {
1235 	/** Name of emitter (e.g. json, compact_json) */
1236 	const char *name;
1237 	/** Unique id (e.g. UCL_EMIT_JSON for standard emitters */
1238 	int id;
1239 	/** A set of output functions */
1240 	const struct ucl_emitter_functions *func;
1241 	/** A set of output operations */
1242 	const struct ucl_emitter_operations *ops;
1243 	/** Current amount of indent tabs */
1244 	unsigned int indent;
1245 	/** Top level object */
1246 	const ucl_object_t *top;
1247 	/** Optional comments */
1248 	const ucl_object_t *comments;
1249 };
1250 
1251 /**
1252  * Emit object to a string
1253  * @param obj object
1254  * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1255  * #UCL_EMIT_CONFIG then emit config like object
1256  * @return dump of an object (must be freed after using) or NULL in case of error
1257  */
1258 UCL_EXTERN unsigned char *ucl_object_emit (const ucl_object_t *obj,
1259 		enum ucl_emitter emit_type);
1260 
1261 /**
1262  * Emit object to a string that can contain `\0` inside
1263  * @param obj object
1264  * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1265  * #UCL_EMIT_CONFIG then emit config like object
1266  * @param len the resulting length
1267  * @return dump of an object (must be freed after using) or NULL in case of error
1268  */
1269 UCL_EXTERN unsigned char *ucl_object_emit_len (const ucl_object_t *obj,
1270 		enum ucl_emitter emit_type, size_t *len);
1271 
1272 /**
1273  * Emit object to a string
1274  * @param obj object
1275  * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1276  * #UCL_EMIT_CONFIG then emit config like object
1277  * @param emitter a set of emitter functions
1278  * @param comments optional comments for the parser
1279  * @return dump of an object (must be freed after using) or NULL in case of error
1280  */
1281 UCL_EXTERN bool ucl_object_emit_full (const ucl_object_t *obj,
1282 		enum ucl_emitter emit_type,
1283 		struct ucl_emitter_functions *emitter,
1284 		const ucl_object_t *comments);
1285 
1286 /**
1287  * Start streamlined UCL object emitter
1288  * @param obj top UCL object
1289  * @param emit_type emit type
1290  * @param emitter a set of emitter functions
1291  * @return new streamlined context that should be freed by
1292  * `ucl_object_emit_streamline_finish`
1293  */
1294 UCL_EXTERN struct ucl_emitter_context* ucl_object_emit_streamline_new (
1295 		const ucl_object_t *obj, enum ucl_emitter emit_type,
1296 		struct ucl_emitter_functions *emitter);
1297 
1298 /**
1299  * Start object or array container for the streamlined output
1300  * @param ctx streamlined context
1301  * @param obj container object
1302  */
1303 UCL_EXTERN void ucl_object_emit_streamline_start_container (
1304 		struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1305 /**
1306  * Add a complete UCL object to streamlined output
1307  * @param ctx streamlined context
1308  * @param obj object to output
1309  */
1310 UCL_EXTERN void ucl_object_emit_streamline_add_object (
1311 		struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1312 /**
1313  * End previously added container
1314  * @param ctx streamlined context
1315  */
1316 UCL_EXTERN void ucl_object_emit_streamline_end_container (
1317 		struct ucl_emitter_context *ctx);
1318 /**
1319  * Terminate streamlined container finishing all containers in it
1320  * @param ctx streamlined context
1321  */
1322 UCL_EXTERN void ucl_object_emit_streamline_finish (
1323 		struct ucl_emitter_context *ctx);
1324 
1325 /**
1326  * Returns functions to emit object to memory
1327  * @param pmem target pointer (should be freed by caller)
1328  * @return emitter functions structure
1329  */
1330 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_memory_funcs (
1331 		void **pmem);
1332 
1333 /**
1334  * Returns functions to emit object to FILE *
1335  * @param fp FILE * object
1336  * @return emitter functions structure
1337  */
1338 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_file_funcs (
1339 		FILE *fp);
1340 /**
1341  * Returns functions to emit object to a file descriptor
1342  * @param fd file descriptor
1343  * @return emitter functions structure
1344  */
1345 UCL_EXTERN struct ucl_emitter_functions* ucl_object_emit_fd_funcs (
1346 		int fd);
1347 
1348 /**
1349  * Free emitter functions
1350  * @param f pointer to functions
1351  */
1352 UCL_EXTERN void ucl_object_emit_funcs_free (struct ucl_emitter_functions *f);
1353 
1354 /** @} */
1355 
1356 /**
1357  * @defgroup schema Schema functions
1358  * These functions are used to validate UCL objects using json schema format
1359  *
1360  * @{
1361  */
1362 
1363 /**
1364  * Used to define UCL schema error
1365  */
1366 enum ucl_schema_error_code {
1367 	UCL_SCHEMA_OK = 0,          /**< no error */
1368 	UCL_SCHEMA_TYPE_MISMATCH,   /**< type of object is incorrect */
1369 	UCL_SCHEMA_INVALID_SCHEMA,  /**< schema is invalid */
1370 	UCL_SCHEMA_MISSING_PROPERTY,/**< one or more missing properties */
1371 	UCL_SCHEMA_CONSTRAINT,      /**< constraint found */
1372 	UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */
1373 	UCL_SCHEMA_EXTERNAL_REF_MISSING, /**< cannot fetch external ref */
1374 	UCL_SCHEMA_EXTERNAL_REF_INVALID, /**< invalid external ref */
1375 	UCL_SCHEMA_INTERNAL_ERROR, /**< something bad happened */
1376 	UCL_SCHEMA_UNKNOWN          /**< generic error */
1377 };
1378 
1379 /**
1380  * Generic ucl schema error
1381  */
1382 struct ucl_schema_error {
1383 	enum ucl_schema_error_code code;	/**< error code */
1384 	char msg[128];						/**< error message */
1385 	const ucl_object_t *obj;			/**< object where error occured */
1386 };
1387 
1388 /**
1389  * Validate object `obj` using schema object `schema`.
1390  * @param schema schema object
1391  * @param obj object to validate
1392  * @param err error pointer, if this parameter is not NULL and error has been
1393  * occured, then `err` is filled with the exact error definition.
1394  * @return true if `obj` is valid using `schema`
1395  */
1396 UCL_EXTERN bool ucl_object_validate (const ucl_object_t *schema,
1397 		const ucl_object_t *obj, struct ucl_schema_error *err);
1398 
1399 /**
1400  * Validate object `obj` using schema object `schema` and root schema at `root`.
1401  * @param schema schema object
1402  * @param obj object to validate
1403  * @param root root schema object
1404  * @param err error pointer, if this parameter is not NULL and error has been
1405  * occured, then `err` is filled with the exact error definition.
1406  * @return true if `obj` is valid using `schema`
1407  */
1408 UCL_EXTERN bool ucl_object_validate_root (const ucl_object_t *schema,
1409 		const ucl_object_t *obj,
1410 		const ucl_object_t *root,
1411 		struct ucl_schema_error *err);
1412 
1413 /**
1414  * Validate object `obj` using schema object `schema` and root schema at `root`
1415  * using some external references provided.
1416  * @param schema schema object
1417  * @param obj object to validate
1418  * @param root root schema object
1419  * @param ext_refs external references (might be modified during validation)
1420  * @param err error pointer, if this parameter is not NULL and error has been
1421  * occured, then `err` is filled with the exact error definition.
1422  * @return true if `obj` is valid using `schema`
1423  */
1424 UCL_EXTERN bool ucl_object_validate_root_ext (const ucl_object_t *schema,
1425 		const ucl_object_t *obj,
1426 		const ucl_object_t *root,
1427 		ucl_object_t *ext_refs,
1428 		struct ucl_schema_error *err);
1429 
1430 /** @} */
1431 
1432 #ifdef  __cplusplus
1433 }
1434 #endif
1435 /*
1436  * XXX: Poorly named API functions, need to replace them with the appropriate
1437  * named function. All API functions *must* use naming ucl_object_*. Usage of
1438  * ucl_obj* should be avoided.
1439  */
1440 #define ucl_obj_todouble_safe ucl_object_todouble_safe
1441 #define ucl_obj_todouble ucl_object_todouble
1442 #define ucl_obj_tostring ucl_object_tostring
1443 #define ucl_obj_tostring_safe ucl_object_tostring_safe
1444 #define ucl_obj_tolstring ucl_object_tolstring
1445 #define ucl_obj_tolstring_safe ucl_object_tolstring_safe
1446 #define ucl_obj_toint ucl_object_toint
1447 #define ucl_obj_toint_safe ucl_object_toint_safe
1448 #define ucl_obj_toboolean ucl_object_toboolean
1449 #define ucl_obj_toboolean_safe ucl_object_toboolean_safe
1450 #define ucl_obj_get_key ucl_object_find_key
1451 #define ucl_obj_get_keyl ucl_object_find_keyl
1452 #define ucl_obj_unref ucl_object_unref
1453 #define ucl_obj_ref ucl_object_ref
1454 #define ucl_obj_free ucl_object_free
1455 
1456 #endif /* UCL_H_ */
1457