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 #ifndef UCL_REALLOC
77 #define UCL_REALLOC(ptr, size) realloc(ptr, size)
78 #endif
79 #ifndef UCL_STRDUP
ucl_strdup_impl(const char * s)80 static inline char *ucl_strdup_impl(const char *s)
81 {
82 size_t len = strlen(s) + 1;
83 char *p = (char *) UCL_ALLOC(len);
84 if (p) memcpy(p, s, len);
85 return p;
86 }
87 #define UCL_STRDUP(str) ucl_strdup_impl(str)
88 #endif
89
90 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
91 #define UCL_WARN_UNUSED_RESULT \
92 __attribute__((warn_unused_result))
93 #else
94 #define UCL_WARN_UNUSED_RESULT
95 #endif
96
97 #ifdef __GNUC__
98 #define UCL_DEPRECATED(func) func __attribute__((deprecated))
99 #elif defined(_MSC_VER)
100 #define UCL_DEPRECATED(func) __declspec(deprecated) func
101 #else
102 #define UCL_DEPRECATED(func) func
103 #endif
104
105 /**
106 * @defgroup structures Structures and types
107 * UCL defines several enumeration types used for error reporting or specifying flags and attributes.
108 *
109 * @{
110 */
111
112 /**
113 * The common error codes returned by ucl parser
114 */
115 typedef enum ucl_error {
116 UCL_EOK = 0, /**< No error */
117 UCL_ESYNTAX, /**< Syntax error occurred during parsing */
118 UCL_EIO, /**< IO error occurred during parsing */
119 UCL_ESTATE, /**< Invalid state machine state */
120 UCL_ENESTED, /**< Input has too many recursion levels */
121 UCL_EUNPAIRED, /**< Input has too many recursion levels */
122 UCL_EMACRO, /**< Error processing a macro */
123 UCL_EINTERNAL, /**< Internal unclassified error */
124 UCL_ESSL, /**< SSL error */
125 UCL_EMERGE /**< A merge error occurred */
126 } ucl_error_t;
127
128 /**
129 * #ucl_object_t may have one of specified types, some types are compatible with each other and some are not.
130 * For example, you can always convert #UCL_TIME to #UCL_FLOAT. Also you can convert #UCL_FLOAT to #UCL_INTEGER
131 * by loosing floating point. Every object may be converted to a string by #ucl_object_tostring_forced() function.
132 *
133 */
134 typedef enum ucl_type {
135 UCL_OBJECT = 0, /**< UCL object - key/value pairs */
136 UCL_ARRAY, /**< UCL array */
137 UCL_INT, /**< Integer number */
138 UCL_FLOAT, /**< Floating point number */
139 UCL_STRING, /**< Null terminated string */
140 UCL_BOOLEAN, /**< Boolean value */
141 UCL_TIME, /**< Time value (floating point number of seconds) */
142 UCL_USERDATA, /**< Opaque userdata pointer (may be used in macros) */
143 UCL_NULL /**< Null value */
144 } ucl_type_t;
145
146 /**
147 * You can use one of these types to serialise #ucl_object_t by using ucl_object_emit().
148 */
149 typedef enum ucl_emitter {
150 UCL_EMIT_JSON = 0, /**< Emit fine formatted JSON */
151 UCL_EMIT_JSON_COMPACT, /**< Emit compacted JSON */
152 UCL_EMIT_CONFIG, /**< Emit human readable config format */
153 UCL_EMIT_YAML, /**< Emit embedded YAML format */
154 UCL_EMIT_MSGPACK, /**< Emit msgpack output */
155 UCL_EMIT_MAX /**< Unsupported emitter type */
156 } ucl_emitter_t;
157
158 /**
159 * These flags defines parser behaviour. If you specify #UCL_PARSER_ZEROCOPY you must ensure
160 * that the input memory is not freed if an object is in use. Moreover, if you want to use
161 * zero-terminated keys and string values then you should not use zero-copy mode, as in this case
162 * UCL still has to perform copying implicitly.
163 */
164 typedef enum ucl_parser_flags {
165 UCL_PARSER_DEFAULT = 0, /**< No special flags */
166 UCL_PARSER_KEY_LOWERCASE = (1 << 0), /**< Convert all keys to lower case */
167 UCL_PARSER_ZEROCOPY = (1 << 1), /**< Parse input in zero-copy mode if possible */
168 UCL_PARSER_NO_TIME = (1 << 2), /**< Do not parse time and treat time values as strings */
169 UCL_PARSER_NO_IMPLICIT_ARRAYS = (1 << 3), /** Create explicit arrays instead of implicit ones */
170 UCL_PARSER_SAVE_COMMENTS = (1 << 4), /** Save comments in the parser context */
171 UCL_PARSER_DISABLE_MACRO = (1 << 5), /** Treat macros as comments */
172 UCL_PARSER_NO_FILEVARS = (1 << 6) /** Do not set file vars */
173 } ucl_parser_flags_t;
174
175 /**
176 * String conversion flags, that are used in #ucl_object_fromstring_common function.
177 */
178 typedef enum ucl_string_flags {
179 UCL_STRING_RAW = 0x0, /**< Treat string as is */
180 UCL_STRING_ESCAPE = (1 << 0), /**< Perform JSON escape */
181 UCL_STRING_TRIM = (1 << 1), /**< Trim leading and trailing whitespaces */
182 UCL_STRING_PARSE_BOOLEAN = (1 << 2), /**< Parse passed string and detect boolean */
183 UCL_STRING_PARSE_INT = (1 << 3), /**< Parse passed string and detect integer number */
184 UCL_STRING_PARSE_DOUBLE = (1 << 4), /**< Parse passed string and detect integer or float number */
185 UCL_STRING_PARSE_TIME = (1 << 5), /**< Parse time strings */
186 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT | UCL_STRING_PARSE_DOUBLE | UCL_STRING_PARSE_TIME, /**<
187 Parse passed string and detect number */
188 UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN | UCL_STRING_PARSE_NUMBER, /**<
189 Parse passed string (and detect booleans and numbers) */
190 UCL_STRING_PARSE_BYTES = (1 << 6) /**< Treat numbers as bytes */
191 } ucl_string_flags_t;
192
193 /**
194 * Basic flags for an object (can use up to 12 bits as higher 4 bits are used
195 * for priorities)
196 */
197 typedef enum ucl_object_flags {
198 UCL_OBJECT_ALLOCATED_KEY = (1 << 0), /**< An object has key allocated internally */
199 UCL_OBJECT_ALLOCATED_VALUE = (1 << 1), /**< An object has a string value allocated internally */
200 UCL_OBJECT_NEED_KEY_ESCAPE = (1 << 2), /**< The key of an object need to be escaped on output */
201 UCL_OBJECT_EPHEMERAL = (1 << 3), /**< Temporary object that does not need to be freed really */
202 UCL_OBJECT_MULTILINE = (1 << 4), /**< String should be displayed as multiline string */
203 UCL_OBJECT_MULTIVALUE = (1 << 5), /**< Object is a key with multiple values */
204 UCL_OBJECT_INHERITED = (1 << 6), /**< Object has been inherited from another */
205 UCL_OBJECT_BINARY = (1 << 7), /**< Object contains raw binary data */
206 UCL_OBJECT_SQUOTED = (1 << 8) /**< Object has been enclosed in single quotes */
207 } ucl_object_flags_t;
208
209 /**
210 * Duplicate policy types
211 */
212 enum ucl_duplicate_strategy {
213 UCL_DUPLICATE_APPEND = 0, /**< Default policy to merge based on priorities */
214 UCL_DUPLICATE_MERGE, /**< Merge new object with old one */
215 UCL_DUPLICATE_REWRITE, /**< Rewrite old keys */
216 UCL_DUPLICATE_ERROR /**< Stop parsing on duplicate found */
217 };
218
219 /**
220 * Input format type
221 */
222 enum ucl_parse_type {
223 UCL_PARSE_UCL = 0, /**< Default ucl format */
224 UCL_PARSE_MSGPACK, /**< Message pack input format */
225 UCL_PARSE_CSEXP, /**< Canonical S-expressions */
226 UCL_PARSE_AUTO /**< Try to detect parse type */
227 };
228
229 /**
230 * UCL object structure. Please mention that the most of fields should not be touched by
231 * UCL users. In future, this structure may be converted to private one.
232 */
233 typedef struct ucl_object_s {
234 /**
235 * Variant value type
236 */
237 union {
238 int64_t iv; /**< Int value of an object */
239 const char *sv; /**< String value of an object */
240 double dv; /**< Double value of an object */
241 void *av; /**< Array */
242 void *ov; /**< Object */
243 void *ud; /**< Opaque user data */
244 } value;
245 const char *key; /**< Key of an object */
246 struct ucl_object_s *next; /**< Array handle */
247 struct ucl_object_s *prev; /**< Array handle */
248 uint32_t keylen; /**< Length of a key */
249 uint32_t len; /**< Size of an object */
250 uint32_t ref; /**< Reference count */
251 uint16_t flags; /**< Object flags */
252 uint16_t type; /**< Real type */
253 unsigned char *trash_stack[2]; /**< Pointer to allocated chunks */
254 } ucl_object_t;
255
256 /**
257 * Destructor type for userdata objects
258 * @param ud user specified data pointer
259 */
260 typedef void (*ucl_userdata_dtor)(void *ud);
261 typedef const char *(*ucl_userdata_emitter)(void *ud);
262
263 /** @} */
264
265 /**
266 * @defgroup utils Utility functions
267 * A number of utility functions simplify handling of UCL objects
268 *
269 * @{
270 */
271 /**
272 * Copy and return a key of an object, returned key is zero-terminated
273 * @param obj CL object
274 * @return zero terminated key
275 */
276 UCL_EXTERN char *ucl_copy_key_trash(const ucl_object_t *obj);
277
278 /**
279 * Copy and return a string value of an object, returned key is zero-terminated
280 * @param obj CL object
281 * @return zero terminated string representation of object value
282 */
283 UCL_EXTERN char *ucl_copy_value_trash(const ucl_object_t *obj);
284
285 /**
286 * Creates a new object
287 * @return new object
288 */
289 UCL_EXTERN ucl_object_t *ucl_object_new(void) UCL_WARN_UNUSED_RESULT;
290
291 /**
292 * Create new object with type specified
293 * @param type type of a new object
294 * @return new object
295 */
296 UCL_EXTERN ucl_object_t *ucl_object_typed_new(ucl_type_t type) UCL_WARN_UNUSED_RESULT;
297
298 /**
299 * Create new object with type and priority specified
300 * @param type type of a new object
301 * @param priority priority of an object
302 * @return new object
303 */
304 UCL_EXTERN ucl_object_t *ucl_object_new_full(ucl_type_t type, unsigned priority)
305 UCL_WARN_UNUSED_RESULT;
306
307 /**
308 * Create new object with userdata dtor
309 * @param dtor destructor function
310 * @param emitter emitter for userdata
311 * @param ptr opaque pointer
312 * @return new object
313 */
314 UCL_EXTERN ucl_object_t *ucl_object_new_userdata(ucl_userdata_dtor dtor,
315 ucl_userdata_emitter emitter, void *ptr) UCL_WARN_UNUSED_RESULT;
316
317 /**
318 * Perform deep copy of an object copying everything
319 * @param other object to copy
320 * @return new object with refcount equal to 1
321 */
322 UCL_EXTERN ucl_object_t *ucl_object_copy(const ucl_object_t *other)
323 UCL_WARN_UNUSED_RESULT;
324
325 /**
326 * Return the type of an object
327 * @return the object type
328 */
329 UCL_EXTERN ucl_type_t ucl_object_type(const ucl_object_t *obj);
330
331 /**
332 * Converts ucl object type to its string representation
333 * @param type type of object
334 * @return constant string describing type
335 */
336 UCL_EXTERN const char *ucl_object_type_to_string(ucl_type_t type);
337
338 /**
339 * Converts string that represents ucl type to real ucl type enum
340 * @param input C string with name of type
341 * @param res resulting target
342 * @return true if `input` is a name of type stored in `res`
343 */
344 UCL_EXTERN bool ucl_object_string_to_type(const char *input, ucl_type_t *res);
345
346 /**
347 * Convert any string to an ucl object making the specified transformations
348 * @param str fixed size or NULL terminated string
349 * @param len length (if len is zero, than str is treated as NULL terminated)
350 * @param flags conversion flags
351 * @return new object
352 */
353 UCL_EXTERN ucl_object_t *ucl_object_fromstring_common(const char *str, size_t len,
354 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT;
355
356 /**
357 * Create a UCL object from the specified string
358 * @param str NULL terminated string, will be json escaped
359 * @return new object
360 */
361 UCL_EXTERN ucl_object_t *ucl_object_fromstring(const char *str) UCL_WARN_UNUSED_RESULT;
362
363 /**
364 * Create a UCL object from the specified string
365 * @param str fixed size string, will be json escaped
366 * @param len length of a string
367 * @return new object
368 */
369 UCL_EXTERN ucl_object_t *ucl_object_fromlstring(const char *str,
370 size_t len) UCL_WARN_UNUSED_RESULT;
371
372 /**
373 * Create an object from an integer number
374 * @param iv number
375 * @return new object
376 */
377 UCL_EXTERN ucl_object_t *ucl_object_fromint(int64_t iv) UCL_WARN_UNUSED_RESULT;
378
379 /**
380 * Create an object from a float number
381 * @param dv number
382 * @return new object
383 */
384 UCL_EXTERN ucl_object_t *ucl_object_fromdouble(double dv) UCL_WARN_UNUSED_RESULT;
385
386 /**
387 * Create an object from a boolean
388 * @param bv bool value
389 * @return new object
390 */
391 UCL_EXTERN ucl_object_t *ucl_object_frombool(bool bv) UCL_WARN_UNUSED_RESULT;
392
393 /**
394 * Insert a object 'elt' to the hash 'top' and associate it with key 'key'
395 * @param top destination object (must be of type UCL_OBJECT)
396 * @param elt element to insert (must NOT be NULL)
397 * @param key key to associate with this object (either const or preallocated)
398 * @param keylen length of the key (or 0 for NULL terminated keys)
399 * @param copy_key make an internal copy of key
400 * @return true if key has been inserted
401 */
402 UCL_EXTERN bool ucl_object_insert_key(ucl_object_t *top, ucl_object_t *elt,
403 const char *key, size_t keylen, bool copy_key);
404
405 /**
406 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
407 * if no object has been found this function works like ucl_object_insert_key()
408 * @param top destination object (must be of type UCL_OBJECT)
409 * @param elt element to insert (must NOT be NULL)
410 * @param key key to associate with this object (either const or preallocated)
411 * @param keylen length of the key (or 0 for NULL terminated keys)
412 * @param copy_key make an internal copy of key
413 * @return true if key has been inserted
414 */
415 UCL_EXTERN bool ucl_object_replace_key(ucl_object_t *top, ucl_object_t *elt,
416 const char *key, size_t keylen, bool copy_key);
417
418 /**
419 * Merge the keys from one object to another object. Overwrite on conflict
420 * @param top destination object (must be of type UCL_OBJECT)
421 * @param elt element to insert (must be of type UCL_OBJECT)
422 * @param copy copy rather than reference the elements
423 * @return true if all keys have been merged
424 */
425 UCL_EXTERN bool ucl_object_merge(ucl_object_t *top, ucl_object_t *elt, bool copy);
426
427 /**
428 * Delete a object associated with key 'key', old object will be unrefered,
429 * @param top object
430 * @param key key associated to the object to remove
431 * @param keylen length of the key (or 0 for NULL terminated keys)
432 */
433 UCL_EXTERN bool ucl_object_delete_keyl(ucl_object_t *top,
434 const char *key, size_t keylen);
435
436 /**
437 * Delete a object associated with key 'key', old object will be unrefered,
438 * @param top object
439 * @param key key associated to the object to remove
440 */
441 UCL_EXTERN bool ucl_object_delete_key(ucl_object_t *top,
442 const char *key);
443
444
445 /**
446 * Removes `key` from `top` object, returning the object that was removed. This
447 * object is not released, caller must unref the returned object when it is no
448 * longer needed.
449 * @param top object
450 * @param key key to remove
451 * @param keylen length of the key (or 0 for NULL terminated keys)
452 * @return removed object or NULL if object has not been found
453 */
454 UCL_EXTERN ucl_object_t *ucl_object_pop_keyl(ucl_object_t *top, const char *key,
455 size_t keylen) UCL_WARN_UNUSED_RESULT;
456
457 /**
458 * Removes `key` from `top` object returning the object that was removed. This
459 * object is not released, caller must unref the returned object when it is no
460 * longer needed.
461 * @param top object
462 * @param key key to remove
463 * @return removed object or NULL if object has not been found
464 */
465 UCL_EXTERN ucl_object_t *ucl_object_pop_key(ucl_object_t *top, const char *key)
466 UCL_WARN_UNUSED_RESULT;
467
468 /**
469 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if
470 * the specified key exist, try to merge its content
471 * @param top destination object (must be of type UCL_OBJECT)
472 * @param elt element to insert (must NOT be NULL)
473 * @param key key to associate with this object (either const or preallocated)
474 * @param keylen length of the key (or 0 for NULL terminated keys)
475 * @param copy_key make an internal copy of key
476 * @return true if key has been inserted
477 */
478 UCL_EXTERN bool ucl_object_insert_key_merged(ucl_object_t *top, ucl_object_t *elt,
479 const char *key, size_t keylen, bool copy_key);
480
481 /**
482 * Reserve space in ucl array or object for `elt` elements
483 * @param obj object to reserve
484 * @param reserved size to reserve in an object
485 * @return 0 on success, -1 on failure (i.e. ENOMEM)
486 */
487 UCL_EXTERN bool ucl_object_reserve(ucl_object_t *obj, size_t reserved);
488
489 /**
490 * Append an element to the end of array object
491 * @param top destination object (must NOT be NULL)
492 * @param elt element to append (must NOT be NULL)
493 * @return true if value has been inserted
494 */
495 UCL_EXTERN bool ucl_array_append(ucl_object_t *top,
496 ucl_object_t *elt);
497
498 /**
499 * Append an element to the start of array object
500 * @param top destination object (must NOT be NULL)
501 * @param elt element to append (must NOT be NULL)
502 * @return true if value has been inserted
503 */
504 UCL_EXTERN bool ucl_array_prepend(ucl_object_t *top,
505 ucl_object_t *elt);
506
507 /**
508 * Merge all elements of second array into the first array
509 * @param top destination array (must be of type UCL_ARRAY)
510 * @param elt array to copy elements from (must be of type UCL_ARRAY)
511 * @param copy copy elements instead of referencing them
512 * @return true if arrays were merged
513 */
514 UCL_EXTERN bool ucl_array_merge(ucl_object_t *top, ucl_object_t *elt,
515 bool copy);
516
517 /**
518 * Removes an element `elt` from the array `top`, returning the object that was
519 * removed. This object is not released, caller must unref the returned object
520 * when it is no longer needed.
521 * @param top array ucl object
522 * @param elt element to remove
523 * @return removed element or NULL if `top` is NULL or not an array
524 */
525 UCL_EXTERN ucl_object_t *ucl_array_delete(ucl_object_t *top,
526 ucl_object_t *elt);
527
528 /**
529 * Returns the first element of the array `top`
530 * @param top array ucl object
531 * @return element or NULL if `top` is NULL or not an array
532 */
533 UCL_EXTERN const ucl_object_t *ucl_array_head(const ucl_object_t *top);
534
535 /**
536 * Returns the last element of the array `top`
537 * @param top array ucl object
538 * @return element or NULL if `top` is NULL or not an array
539 */
540 UCL_EXTERN const ucl_object_t *ucl_array_tail(const ucl_object_t *top);
541
542 /**
543 * Removes the last element from the array `top`, returning the object that was
544 * removed. This object is not released, caller must unref the returned object
545 * when it is no longer needed.
546 * @param top array ucl object
547 * @return removed element or NULL if `top` is NULL or not an array
548 */
549 UCL_EXTERN ucl_object_t *ucl_array_pop_last(ucl_object_t *top);
550
551 /**
552 * Removes the first element from the array `top`, returning the object that was
553 * removed. This object is not released, caller must unref the returned object
554 * when it is no longer needed.
555 * @param top array ucl object
556 * @return removed element or NULL if `top` is NULL or not an array
557 */
558 UCL_EXTERN ucl_object_t *ucl_array_pop_first(ucl_object_t *top);
559
560 /**
561 * Return size of the array `top`
562 * @param top object to get size from (must be of type UCL_ARRAY)
563 * @return size of the array
564 */
565 UCL_EXTERN unsigned int ucl_array_size(const ucl_object_t *top);
566
567 /**
568 * Return object identified by index of the array `top`
569 * @param top object to get a key from (must be of type UCL_ARRAY)
570 * @param index array index to return
571 * @return object at the specified index or NULL if index is not found
572 */
573 UCL_EXTERN const ucl_object_t *ucl_array_find_index(const ucl_object_t *top,
574 unsigned int index);
575
576 /**
577 * Return the index of `elt` in the array `top`
578 * @param top object to get a key from (must be of type UCL_ARRAY)
579 * @param elt element to find index of (must NOT be NULL)
580 * @return index of `elt` in the array `top or (unsigned int)-1 if `elt` is not found
581 */
582 UCL_EXTERN unsigned int ucl_array_index_of(ucl_object_t *top,
583 ucl_object_t *elt);
584
585 /**
586 * Replace an element in an array with a different element, returning the object
587 * that was replaced. This object is not released, caller must unref the
588 * returned object when it is no longer needed.
589 * @param top destination object (must be of type UCL_ARRAY)
590 * @param elt element to append (must NOT be NULL)
591 * @param index array index in destination to overwrite with elt
592 * @return object that was replaced or NULL if index is not found
593 */
594 ucl_object_t *
595 ucl_array_replace_index(ucl_object_t *top, ucl_object_t *elt,
596 unsigned int index);
597
598 /**
599 * Append a element to another element forming an implicit array
600 * @param head head to append (may be NULL)
601 * @param elt new element
602 * @return the new implicit array
603 */
604 UCL_EXTERN ucl_object_t *ucl_elt_append(ucl_object_t *head,
605 ucl_object_t *elt);
606
607 /**
608 * Converts an object to double value
609 * @param obj CL object
610 * @param target target double variable
611 * @return true if conversion was successful
612 */
613 UCL_EXTERN bool ucl_object_todouble_safe(const ucl_object_t *obj, double *target);
614
615 /**
616 * Unsafe version of \ref ucl_obj_todouble_safe
617 * @param obj CL object
618 * @return double value
619 */
620 UCL_EXTERN double ucl_object_todouble(const ucl_object_t *obj);
621
622 /**
623 * Converts an object to integer value
624 * @param obj CL object
625 * @param target target integer variable
626 * @return true if conversion was successful
627 */
628 UCL_EXTERN bool ucl_object_toint_safe(const ucl_object_t *obj, int64_t *target);
629
630 /**
631 * Unsafe version of \ref ucl_obj_toint_safe
632 * @param obj CL object
633 * @return int value
634 */
635 UCL_EXTERN int64_t ucl_object_toint(const ucl_object_t *obj);
636
637 /**
638 * Converts an object to boolean value
639 * @param obj CL object
640 * @param target target boolean variable
641 * @return true if conversion was successful
642 */
643 UCL_EXTERN bool ucl_object_toboolean_safe(const ucl_object_t *obj, bool *target);
644
645 /**
646 * Unsafe version of \ref ucl_obj_toboolean_safe
647 * @param obj CL object
648 * @return boolean value
649 */
650 UCL_EXTERN bool ucl_object_toboolean(const ucl_object_t *obj);
651
652 /**
653 * Converts an object to string value
654 * @param obj CL object
655 * @param target target string variable, no need to free value
656 * @return true if conversion was successful
657 */
658 UCL_EXTERN bool ucl_object_tostring_safe(const ucl_object_t *obj, const char **target);
659
660 /**
661 * Unsafe version of \ref ucl_obj_tostring_safe
662 * @param obj CL object
663 * @return string value
664 */
665 UCL_EXTERN const char *ucl_object_tostring(const ucl_object_t *obj);
666
667 /**
668 * Convert any object to a string in JSON notation if needed
669 * @param obj CL object
670 * @return string value
671 */
672 UCL_EXTERN const char *ucl_object_tostring_forced(const ucl_object_t *obj);
673
674 /**
675 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
676 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
677 * @param obj CL object
678 * @param target target string variable, no need to free value
679 * @param tlen target length
680 * @return true if conversion was successful
681 */
682 UCL_EXTERN bool ucl_object_tolstring_safe(const ucl_object_t *obj,
683 const char **target, size_t *tlen);
684
685 /**
686 * Unsafe version of \ref ucl_obj_tolstring_safe
687 * @param obj CL object
688 * @return string value
689 */
690 UCL_EXTERN const char *ucl_object_tolstring(const ucl_object_t *obj, size_t *tlen);
691
692 /**
693 * Return object identified by a key in the specified object
694 * @param obj object to get a key from (must be of type UCL_OBJECT)
695 * @param key key to search
696 * @return object matching the specified key or NULL if key was not found
697 */
698 UCL_EXTERN const ucl_object_t *ucl_object_lookup(const ucl_object_t *obj,
699 const char *key);
700 #define ucl_object_find_key ucl_object_lookup
701
702 /**
703 * Return object identified by a key in the specified object, if the first key is
704 * not found then look for the next one. This process is repeated unless
705 * the next argument in the list is not NULL. So, `ucl_object_find_any_key(obj, key, NULL)`
706 * is equal to `ucl_object_find_key(obj, key)`
707 * @param obj object to get a key from (must be of type UCL_OBJECT)
708 * @param key key to search
709 * @param ... list of alternative keys to search (NULL terminated)
710 * @return object matching the specified key or NULL if key was not found
711 */
712 UCL_EXTERN const ucl_object_t *ucl_object_lookup_any(const ucl_object_t *obj,
713 const char *key, ...);
714 #define ucl_object_find_any_key ucl_object_lookup_any
715
716 /**
717 * Return object identified by a fixed size key in the specified object
718 * @param obj object to get a key from (must be of type UCL_OBJECT)
719 * @param key key to search
720 * @param klen length of a key
721 * @return object matching the specified key or NULL if key was not found
722 */
723 UCL_EXTERN const ucl_object_t *ucl_object_lookup_len(const ucl_object_t *obj,
724 const char *key, size_t klen);
725 #define ucl_object_find_keyl ucl_object_lookup_len
726
727 /**
728 * Return object identified by dot notation string
729 * @param obj object to search in
730 * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
731 * @return object matched the specified path or NULL if path is not found
732 */
733 UCL_EXTERN const ucl_object_t *ucl_object_lookup_path(const ucl_object_t *obj,
734 const char *path);
735 #define ucl_lookup_path ucl_object_lookup_path
736
737 /**
738 * Return object identified by object notation string using arbitrary delimiter
739 * @param obj object to search in
740 * @param path dot.notation.path to the path to lookup. May use numeric .index on arrays
741 * @param sep the sepatorator to use in place of . (incase keys have . in them)
742 * @return object matched the specified path or NULL if path is not found
743 */
744 UCL_EXTERN const ucl_object_t *ucl_object_lookup_path_char(const ucl_object_t *obj,
745 const char *path, char sep);
746 #define ucl_lookup_path_char ucl_object_lookup_path_char
747
748 /**
749 * Returns a key of an object as a NULL terminated string
750 * @param obj CL object
751 * @return key or NULL if there is no key
752 */
753 UCL_EXTERN const char *ucl_object_key(const ucl_object_t *obj);
754
755 /**
756 * Returns a key of an object as a fixed size string (may be more efficient)
757 * @param obj CL object
758 * @param len target key length
759 * @return key pointer
760 */
761 UCL_EXTERN const char *ucl_object_keyl(const ucl_object_t *obj, size_t *len);
762
763 /**
764 * Increase reference count for an object
765 * @param obj object to ref
766 * @return the referenced object
767 */
768 UCL_EXTERN ucl_object_t *ucl_object_ref(const ucl_object_t *obj);
769
770 /**
771 * Free ucl object
772 * @param obj ucl object to free
773 */
774 UCL_DEPRECATED(UCL_EXTERN void ucl_object_free(ucl_object_t *obj));
775
776 /**
777 * Decrease reference count for an object
778 * @param obj object to unref
779 */
780 UCL_EXTERN void ucl_object_unref(ucl_object_t *obj);
781
782 /**
783 * Compare objects `o1` and `o2`
784 * @param o1 the first object
785 * @param o2 the second object
786 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
787 * The order of comparison:
788 * 1) Type of objects
789 * 2) Size of objects
790 * 3) Content of objects
791 */
792 UCL_EXTERN int ucl_object_compare(const ucl_object_t *o1,
793 const ucl_object_t *o2);
794
795 /**
796 * Compare objects `o1` and `o2` useful for sorting
797 * @param o1 the first object
798 * @param o2 the second object
799 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
800 * The order of comparison:
801 * 1) Type of objects
802 * 2) Size of objects
803 * 3) Content of objects
804 */
805 UCL_EXTERN int ucl_object_compare_qsort(const ucl_object_t **o1,
806 const ucl_object_t **o2);
807
808 /**
809 * Sort UCL array using `cmp` compare function
810 * @param ar
811 * @param cmp
812 */
813 UCL_EXTERN void ucl_object_array_sort(ucl_object_t *ar,
814 int (*cmp)(const ucl_object_t **o1, const ucl_object_t **o2));
815
816 enum ucl_object_keys_sort_flags {
817 UCL_SORT_KEYS_DEFAULT = 0,
818 UCL_SORT_KEYS_ICASE = (1u << 0u),
819 UCL_SORT_KEYS_RECURSIVE = (1u << 1u),
820 };
821 /***
822 * Sorts keys in object in place
823 * @param obj
824 * @param how
825 */
826 UCL_EXTERN void ucl_object_sort_keys(ucl_object_t *obj,
827 enum ucl_object_keys_sort_flags how);
828
829 /**
830 * Get the priority for specific UCL object
831 * @param obj any ucl object
832 * @return priority of an object
833 */
834 UCL_EXTERN unsigned int ucl_object_get_priority(const ucl_object_t *obj);
835
836 /**
837 * Set explicit priority of an object.
838 * @param obj any ucl object
839 * @param priority new priroity value (only 4 least significant bits are considred)
840 */
841 UCL_EXTERN void ucl_object_set_priority(ucl_object_t *obj,
842 unsigned int priority);
843
844 /**
845 * Opaque iterator object
846 */
847 typedef void *ucl_object_iter_t;
848
849 /**
850 * Get next key from an object
851 * @param obj object to iterate
852 * @param iter opaque iterator, must be set to NULL on the first call:
853 * ucl_object_iter_t it = NULL;
854 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
855 * @param ep pointer record exception (such as ENOMEM), could be NULL
856 * @return the next object or NULL
857 */
858 UCL_EXTERN const ucl_object_t *ucl_object_iterate_with_error(const ucl_object_t *obj,
859 ucl_object_iter_t *iter, bool expand_values, int *ep);
860
861 #define ucl_iterate_object ucl_object_iterate
862 #define ucl_object_iterate(ob, it, ev) ucl_object_iterate_with_error((ob), (it), (ev), NULL)
863
864 /**
865 * Free resources associated with an inline iterator when iteration is
866 * abandoned before completion. Only needed for UCL_OBJECT iteration where
867 * internal heap state is allocated. Safe to call with a NULL iterator or
868 * on non-object types.
869 *
870 * Example usage:
871 * ucl_object_iter_t it = NULL;
872 * while ((cur = ucl_iterate_object(obj, &it, true))) {
873 * if (error) {
874 * ucl_object_iterate_end(obj, &it);
875 * return;
876 * }
877 * }
878 *
879 * @param obj the object being iterated
880 * @param iter pointer to the iterator to free
881 */
882 UCL_EXTERN void ucl_object_iterate_end(const ucl_object_t *obj,
883 ucl_object_iter_t *iter);
884
885 #define ucl_iterate_object_end ucl_object_iterate_end
886
887 /**
888 * Create new safe iterator for the specified object
889 * @param obj object to iterate
890 * @return new iterator object that should be used with safe iterators API only
891 */
892 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_new(const ucl_object_t *obj)
893 UCL_WARN_UNUSED_RESULT;
894 /**
895 * Check safe iterator object after performing some operations on it
896 * (such as ucl_object_iterate_safe()) to see if operation has encountered
897 * fatal exception while performing that operation (e.g. ENOMEM).
898 * @param iter opaque iterator
899 * @return true if exception has occured, false otherwise
900 */
901 UCL_EXTERN bool ucl_object_iter_chk_excpn(ucl_object_iter_t *it);
902
903 /**
904 * Reset initialized iterator to a new object
905 * @param obj new object to iterate
906 * @return modified iterator object
907 */
908 UCL_EXTERN ucl_object_iter_t ucl_object_iterate_reset(ucl_object_iter_t it,
909 const ucl_object_t *obj);
910
911 /**
912 * Get the next object from the `obj`. This function iterates over arrays, objects
913 * and implicit arrays
914 * @param iter safe iterator
915 * @param expand_values expand explicit arrays and objects
916 * @return the next object in sequence
917 */
918 UCL_EXTERN const ucl_object_t *ucl_object_iterate_safe(ucl_object_iter_t iter,
919 bool expand_values);
920 /**
921 * Iteration type enumerator
922 */
923 enum ucl_iterate_type {
924 UCL_ITERATE_EXPLICIT = 1 << 0, /**< Iterate just explicit arrays and objects */
925 UCL_ITERATE_IMPLICIT = 1 << 1, /**< Iterate just implicit arrays */
926 UCL_ITERATE_BOTH = (1 << 0) | (1 << 1), /**< Iterate both explicit and implicit arrays*/
927 };
928
929 /**
930 * Get the next object from the `obj`. This function iterates over arrays, objects
931 * and implicit arrays if needed
932 * @param iter safe iterator
933 * @param
934 * @return the next object in sequence
935 */
936 UCL_EXTERN const ucl_object_t *ucl_object_iterate_full(ucl_object_iter_t iter,
937 enum ucl_iterate_type type);
938
939 /**
940 * Free memory associated with the safe iterator
941 * @param it safe iterator object
942 */
943 UCL_EXTERN void ucl_object_iterate_free(ucl_object_iter_t it);
944
945 /** @} */
946
947
948 /**
949 * @defgroup parser Parsing functions
950 * These functions are used to parse UCL objects
951 *
952 * @{
953 */
954
955 /**
956 * Macro handler for a parser
957 * @param data the content of macro
958 * @param len the length of content
959 * @param arguments arguments object
960 * @param ud opaque user data
961 * @param err error pointer
962 * @return true if macro has been parsed
963 */
964 typedef bool (*ucl_macro_handler)(const unsigned char *data, size_t len,
965 const ucl_object_t *arguments,
966 void *ud);
967
968 /**
969 * Context dependent macro handler for a parser
970 * @param data the content of macro
971 * @param len the length of content
972 * @param arguments arguments object
973 * @param context previously parsed context
974 * @param ud opaque user data
975 * @param err error pointer
976 * @return true if macro has been parsed
977 */
978 typedef bool (*ucl_context_macro_handler)(const unsigned char *data, size_t len,
979 const ucl_object_t *arguments,
980 const ucl_object_t *context,
981 void *ud);
982
983 /* Opaque parser */
984 struct ucl_parser;
985
986 /**
987 * Creates new parser object
988 * @param pool pool to allocate memory from
989 * @return new parser object
990 */
991 UCL_EXTERN struct ucl_parser *ucl_parser_new(int flags);
992
993 /**
994 * Sets the default priority for the parser applied to chunks that do not
995 * specify priority explicitly
996 * @param parser parser object
997 * @param prio default priority (0 .. 16)
998 * @return true if parser's default priority was set
999 */
1000 UCL_EXTERN bool ucl_parser_set_default_priority(struct ucl_parser *parser,
1001 unsigned prio);
1002 /**
1003 * Gets the default priority for the parser applied to chunks that do not
1004 * specify priority explicitly
1005 * @param parser parser object
1006 * @return true default priority (0 .. 16), -1 for failure
1007 */
1008 UCL_EXTERN int ucl_parser_get_default_priority(struct ucl_parser *parser);
1009
1010 /**
1011 * Register new handler for a macro
1012 * @param parser parser object
1013 * @param macro macro name (without leading dot)
1014 * @param handler handler (it is called immediately after macro is parsed)
1015 * @param ud opaque user data for a handler
1016 * @return true on success, false on failure (i.e. ENOMEM)
1017 */
1018 UCL_EXTERN bool ucl_parser_register_macro(struct ucl_parser *parser,
1019 const char *macro,
1020 ucl_macro_handler handler, void *ud);
1021
1022 /**
1023 * Register new context dependent handler for a macro
1024 * @param parser parser object
1025 * @param macro macro name (without leading dot)
1026 * @param handler handler (it is called immediately after macro is parsed)
1027 * @param ud opaque user data for a handler
1028 * @return true on success, false on failure (i.e. ENOMEM)
1029 */
1030 UCL_EXTERN bool ucl_parser_register_context_macro(struct ucl_parser *parser,
1031 const char *macro,
1032 ucl_context_macro_handler handler,
1033 void *ud);
1034
1035 /**
1036 * Handler to detect unregistered variables
1037 * @param data variable data
1038 * @param len length of variable
1039 * @param replace (out) replace value for variable
1040 * @param replace_len (out) replace length for variable
1041 * @param need_free (out) UCL will free `dest` after usage
1042 * @param ud opaque userdata
1043 * @return true if variable
1044 */
1045 typedef bool (*ucl_variable_handler)(const unsigned char *data, size_t len,
1046 unsigned char **replace, size_t *replace_len, bool *need_free, void *ud);
1047
1048 /**
1049 * Register new parser variable
1050 * @param parser parser object
1051 * @param var variable name
1052 * @param value variable value
1053 */
1054 UCL_EXTERN void ucl_parser_register_variable(struct ucl_parser *parser, const char *var,
1055 const char *value);
1056
1057 /**
1058 * Set handler for unknown variables
1059 * @param parser parser structure
1060 * @param handler desired handler
1061 * @param ud opaque data for the handler
1062 */
1063 UCL_EXTERN void ucl_parser_set_variables_handler(struct ucl_parser *parser,
1064 ucl_variable_handler handler, void *ud);
1065
1066 /**
1067 * Load new chunk to a parser
1068 * @param parser parser structure
1069 * @param data the pointer to the beginning of a chunk
1070 * @param len the length of a chunk
1071 * @return true if chunk has been added and false in case of error
1072 */
1073 UCL_EXTERN bool ucl_parser_add_chunk(struct ucl_parser *parser,
1074 const unsigned char *data, size_t len);
1075
1076 /**
1077 * Load new chunk to a parser with the specified priority
1078 * @param parser parser structure
1079 * @param data the pointer to the beginning of a chunk
1080 * @param len the length of a chunk
1081 * @param priority the desired priority of a chunk (only 4 least significant bits
1082 * are considered for this parameter)
1083 * @return true if chunk has been added and false in case of error
1084 */
1085 UCL_EXTERN bool ucl_parser_add_chunk_priority(struct ucl_parser *parser,
1086 const unsigned char *data, size_t len, unsigned priority);
1087
1088 /**
1089 * Insert new chunk to a parser (must have previously processed data with an existing top object)
1090 * @param parser parser structure
1091 * @param data the pointer to the beginning of a chunk
1092 * @param len the length of a chunk
1093 * @return true if chunk has been added and false in case of error
1094 */
1095 UCL_EXTERN bool ucl_parser_insert_chunk(struct ucl_parser *parser,
1096 const unsigned char *data, size_t len);
1097
1098 /**
1099 * Full version of ucl_add_chunk with priority and duplicate strategy
1100 * @param parser parser structure
1101 * @param data the pointer to the beginning of a chunk
1102 * @param len the length of a chunk
1103 * @param priority the desired priority of a chunk (only 4 least significant bits
1104 * are considered for this parameter)
1105 * @param strat duplicates merging strategy
1106 * @param parse_type input format
1107 * @return true if chunk has been added and false in case of error
1108 */
1109 UCL_EXTERN bool ucl_parser_add_chunk_full(struct ucl_parser *parser,
1110 const unsigned char *data, size_t len, unsigned priority,
1111 enum ucl_duplicate_strategy strat, enum ucl_parse_type parse_type);
1112
1113 /**
1114 * Load ucl object from a string
1115 * @param parser parser structure
1116 * @param data the pointer to the string
1117 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
1118 * @return true if string has been added and false in case of error
1119 */
1120 UCL_EXTERN bool ucl_parser_add_string(struct ucl_parser *parser,
1121 const char *data, size_t len);
1122
1123 /**
1124 * Load ucl object from a string
1125 * @param parser parser structure
1126 * @param data the pointer to the string
1127 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string
1128 * @param priority the desired priority of a chunk (only 4 least significant bits
1129 * are considered for this parameter)
1130 * @return true if string has been added and false in case of error
1131 */
1132 UCL_EXTERN bool ucl_parser_add_string_priority(struct ucl_parser *parser,
1133 const char *data, size_t len, unsigned priority);
1134
1135 /**
1136 * Load and add data from a file
1137 * @param parser parser structure
1138 * @param filename the name of file
1139 * @param err if *err is NULL it is set to parser error
1140 * @return true if chunk has been added and false in case of error
1141 */
1142 UCL_EXTERN bool ucl_parser_add_file(struct ucl_parser *parser,
1143 const char *filename);
1144
1145 /**
1146 * Load and add data from a file
1147 * @param parser parser structure
1148 * @param filename the name of file
1149 * @param err if *err is NULL it is set to parser error
1150 * @param priority the desired priority of a chunk (only 4 least significant bits
1151 * are considered for this parameter)
1152 * @return true if chunk has been added and false in case of error
1153 */
1154 UCL_EXTERN bool ucl_parser_add_file_priority(struct ucl_parser *parser,
1155 const char *filename, unsigned priority);
1156
1157 /**
1158 * Load and add data from a file
1159 * @param parser parser structure
1160 * @param filename the name of file
1161 * @param priority the desired priority of a chunk (only 4 least significant bits
1162 * are considered for this parameter)
1163 * @param strat Merge strategy to use while parsing this file
1164 * @param parse_type Parser type to use while parsing this file
1165 * @return true if chunk has been added and false in case of error
1166 */
1167 UCL_EXTERN bool ucl_parser_add_file_full(struct ucl_parser *parser, const char *filename,
1168 unsigned priority, enum ucl_duplicate_strategy strat,
1169 enum ucl_parse_type parse_type);
1170
1171 /**
1172 * Load and add data from a file descriptor
1173 * @param parser parser structure
1174 * @param filename the name of file
1175 * @param err if *err is NULL it is set to parser error
1176 * @return true if chunk has been added and false in case of error
1177 */
1178 UCL_EXTERN bool ucl_parser_add_fd(struct ucl_parser *parser,
1179 int fd);
1180
1181 /**
1182 * Load and add data from a file descriptor
1183 * @param parser parser structure
1184 * @param filename the name of file
1185 * @param err if *err is NULL it is set to parser error
1186 * @param priority the desired priority of a chunk (only 4 least significant bits
1187 * are considered for this parameter)
1188 * @return true if chunk has been added and false in case of error
1189 */
1190 UCL_EXTERN bool ucl_parser_add_fd_priority(struct ucl_parser *parser,
1191 int fd, unsigned priority);
1192
1193 /**
1194 * Load and add data from a file descriptor
1195 * @param parser parser structure
1196 * @param filename the name of file
1197 * @param err if *err is NULL it is set to parser error
1198 * @param priority the desired priority of a chunk (only 4 least significant bits
1199 * are considered for this parameter)
1200 * @param strat Merge strategy to use while parsing this file
1201 * @param parse_type Parser type to use while parsing this file
1202 * @return true if chunk has been added and false in case of error
1203 */
1204 UCL_EXTERN bool ucl_parser_add_fd_full(struct ucl_parser *parser, int fd,
1205 unsigned priority, enum ucl_duplicate_strategy strat,
1206 enum ucl_parse_type parse_type);
1207
1208 /**
1209 * Provide a UCL_ARRAY of paths to search for include files. The object is
1210 * copied so caller must unref the object.
1211 * @param parser parser structure
1212 * @param paths UCL_ARRAY of paths to search
1213 * @return true if the path search array was replaced in the parser
1214 */
1215 UCL_EXTERN bool ucl_set_include_path(struct ucl_parser *parser,
1216 ucl_object_t *paths);
1217
1218 /**
1219 * Get a top object for a parser (refcount is increased)
1220 * @param parser parser structure
1221 * @param err if *err is NULL it is set to parser error
1222 * @return top parser object or NULL
1223 */
1224 UCL_EXTERN ucl_object_t *ucl_parser_get_object(struct ucl_parser *parser);
1225
1226 /**
1227 * Get the current stack object as stack accessor function for use in macro
1228 * functions (refcount is increased)
1229 * @param parser parser object
1230 * @param depth depth of stack to retrieve (top is 0)
1231 * @return current stack object or NULL
1232 */
1233 UCL_EXTERN ucl_object_t *ucl_parser_get_current_stack_object(struct ucl_parser *parser, unsigned int depth);
1234
1235 /**
1236 * Peek at the character at the current chunk position
1237 * @param parser parser structure
1238 * @return current chunk position character
1239 */
1240 UCL_EXTERN unsigned char ucl_parser_chunk_peek(struct ucl_parser *parser);
1241
1242 /**
1243 * Skip the character at the current chunk position
1244 * @param parser parser structure
1245 * @return success boolean
1246 */
1247 UCL_EXTERN bool ucl_parser_chunk_skip(struct ucl_parser *parser);
1248
1249 /**
1250 * Get the error string if parsing has been failed
1251 * @param parser parser object
1252 * @return error description
1253 */
1254 UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser);
1255
1256 /**
1257 * Get the code of the last error
1258 * @param parser parser object
1259 * @return error code
1260 */
1261 UCL_EXTERN int ucl_parser_get_error_code(struct ucl_parser *parser);
1262
1263 /**
1264 * Get the current column number within parser
1265 * @param parser parser object
1266 * @return current column number
1267 */
1268 UCL_EXTERN unsigned ucl_parser_get_column(struct ucl_parser *parser);
1269
1270 /**
1271 * Get the current line number within parser
1272 * @param parser parser object
1273 * @return current line number
1274 */
1275 UCL_EXTERN unsigned ucl_parser_get_linenum(struct ucl_parser *parser);
1276
1277 /**
1278 * Clear the error in the parser
1279 * @param parser parser object
1280 */
1281 UCL_EXTERN void ucl_parser_clear_error(struct ucl_parser *parser);
1282
1283 /**
1284 * Free ucl parser object
1285 * @param parser parser object
1286 */
1287 UCL_EXTERN void ucl_parser_free(struct ucl_parser *parser);
1288
1289 /**
1290 * Get constant opaque pointer to comments structure for this parser. Increase
1291 * refcount to prevent this object to be destroyed on parser's destruction
1292 * @param parser parser structure
1293 * @return ucl comments pointer or NULL
1294 */
1295 UCL_EXTERN const ucl_object_t *ucl_parser_get_comments(struct ucl_parser *parser);
1296
1297 /**
1298 * Utility function to find a comment object for the specified object in the input
1299 * @param comments comments object
1300 * @param srch search object
1301 * @return string comment enclosed in ucl_object_t
1302 */
1303 UCL_EXTERN const ucl_object_t *ucl_comments_find(const ucl_object_t *comments,
1304 const ucl_object_t *srch);
1305
1306 /**
1307 * Move comment from `from` object to `to` object
1308 * @param comments comments object
1309 * @param what source object
1310 * @param with destination object
1311 * @return `true` if `from` has comment and it has been moved to `to`
1312 */
1313 UCL_EXTERN bool ucl_comments_move(ucl_object_t *comments,
1314 const ucl_object_t *from, const ucl_object_t *to);
1315
1316 /**
1317 * Adds a new comment for an object
1318 * @param comments comments object
1319 * @param obj object to add comment to
1320 * @param comment string representation of a comment
1321 */
1322 UCL_EXTERN void ucl_comments_add(ucl_object_t *comments,
1323 const ucl_object_t *obj, const char *comment);
1324
1325 /**
1326 * Add new public key to parser for signatures check
1327 * @param parser parser object
1328 * @param key PEM representation of a key
1329 * @param len length of the key
1330 * @param err if *err is NULL it is set to parser error
1331 * @return true if a key has been successfully added
1332 */
1333 UCL_EXTERN bool ucl_parser_pubkey_add(struct ucl_parser *parser,
1334 const unsigned char *key, size_t len);
1335
1336 /**
1337 * Set FILENAME and CURDIR variables in parser
1338 * @param parser parser object
1339 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd()
1340 * @param need_expand perform realpath() if this variable is true and filename is not NULL
1341 * @return true if variables has been set
1342 */
1343 UCL_EXTERN bool ucl_parser_set_filevars(struct ucl_parser *parser, const char *filename,
1344 bool need_expand);
1345
1346 /**
1347 * Returns current file for the parser
1348 * @param parser parser object
1349 * @return current file or NULL if parsing memory
1350 */
1351 UCL_EXTERN const char *ucl_parser_get_cur_file(struct ucl_parser *parser);
1352
1353 /**
1354 * Defines special handler for certain types of data (identified by magic)
1355 */
1356 typedef bool (*ucl_parser_special_handler_t)(struct ucl_parser *parser,
1357 const unsigned char *source, size_t source_len,
1358 unsigned char **destination, size_t *dest_len,
1359 void *user_data);
1360
1361 /**
1362 * Special handler flags
1363 */
1364 enum ucl_special_handler_flags {
1365 UCL_SPECIAL_HANDLER_DEFAULT = 0,
1366 UCL_SPECIAL_HANDLER_PREPROCESS_ALL = (1u << 0),
1367 };
1368
1369 /**
1370 * Special handler structure
1371 */
1372 struct ucl_parser_special_handler {
1373 const unsigned char *magic;
1374 size_t magic_len;
1375 enum ucl_special_handler_flags flags;
1376 ucl_parser_special_handler_t handler;
1377 void (*free_function)(unsigned char *data, size_t len, void *user_data);
1378 void *user_data;
1379 struct ucl_parser_special_handler *next; /* Used internally */
1380 };
1381
1382 /**
1383 * Add special handler for a parser, handles special sequences identified by magic
1384 * @param parser parser structure
1385 * @param handler handler structure
1386 */
1387 UCL_EXTERN void ucl_parser_add_special_handler(struct ucl_parser *parser,
1388 struct ucl_parser_special_handler *handler);
1389
1390 /**
1391 * Handler for include traces:
1392 * @param parser parser object
1393 * @param parent where include is done from
1394 * @param args arguments to an include
1395 * @param path path of the include
1396 * @param pathlen length of the path
1397 * @param user_data opaque userdata
1398 */
1399 typedef void(ucl_include_trace_func_t)(struct ucl_parser *parser,
1400 const ucl_object_t *parent,
1401 const ucl_object_t *args,
1402 const char *path,
1403 size_t pathlen,
1404 void *user_data);
1405
1406 /**
1407 * Register trace function for an include handler
1408 * @param parser parser object
1409 * @param func function to trace includes
1410 * @param user_data opaque data
1411 */
1412 UCL_EXTERN void ucl_parser_set_include_tracer(struct ucl_parser *parser,
1413 ucl_include_trace_func_t func,
1414 void *user_data);
1415
1416 /** @} */
1417
1418 /**
1419 * @defgroup emitter Emitting functions
1420 * These functions are used to serialise UCL objects to some string representation.
1421 *
1422 * @{
1423 */
1424
1425 struct ucl_emitter_context;
1426 /**
1427 * Structure using for emitter callbacks
1428 */
1429 struct ucl_emitter_functions {
1430 /** Append a single character */
1431 int (*ucl_emitter_append_character)(unsigned char c, size_t nchars, void *ud);
1432 /** Append a string of a specified length */
1433 int (*ucl_emitter_append_len)(unsigned const char *str, size_t len, void *ud);
1434 /** Append a 64 bit integer */
1435 int (*ucl_emitter_append_int)(int64_t elt, void *ud);
1436 /** Append floating point element */
1437 int (*ucl_emitter_append_double)(double elt, void *ud);
1438 /** Free userdata */
1439 void (*ucl_emitter_free_func)(void *ud);
1440 /** Opaque userdata pointer */
1441 void *ud;
1442 };
1443
1444 struct ucl_emitter_operations {
1445 /** Write a primitive element */
1446 void (*ucl_emitter_write_elt)(struct ucl_emitter_context *ctx,
1447 const ucl_object_t *obj, bool first, bool print_key);
1448 /** Start ucl object */
1449 void (*ucl_emitter_start_object)(struct ucl_emitter_context *ctx,
1450 const ucl_object_t *obj, bool first, bool print_key);
1451 /** End ucl object */
1452 void (*ucl_emitter_end_object)(struct ucl_emitter_context *ctx,
1453 const ucl_object_t *obj);
1454 /** Start ucl array */
1455 void (*ucl_emitter_start_array)(struct ucl_emitter_context *ctx,
1456 const ucl_object_t *obj, bool first, bool print_key);
1457 void (*ucl_emitter_end_array)(struct ucl_emitter_context *ctx,
1458 const ucl_object_t *obj);
1459 };
1460
1461 /**
1462 * Structure that defines emitter functions
1463 */
1464 struct ucl_emitter_context {
1465 /** Name of emitter (e.g. json, compact_json) */
1466 const char *name;
1467 /** Unique id (e.g. UCL_EMIT_JSON for standard emitters */
1468 int id;
1469 /** A set of output functions */
1470 const struct ucl_emitter_functions *func;
1471 /** A set of output operations */
1472 const struct ucl_emitter_operations *ops;
1473 /** Current amount of indent tabs */
1474 unsigned int indent;
1475 /** Top level object */
1476 const ucl_object_t *top;
1477 /** Optional comments */
1478 const ucl_object_t *comments;
1479 };
1480
1481 /**
1482 * Emit object to a string
1483 * @param obj object
1484 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1485 * #UCL_EMIT_CONFIG then emit config like object
1486 * @return dump of an object (must be freed after using) or NULL in case of error
1487 */
1488 UCL_EXTERN unsigned char *ucl_object_emit(const ucl_object_t *obj,
1489 enum ucl_emitter emit_type);
1490
1491 /**
1492 * Emit object to a string that can contain `\0` inside
1493 * @param obj object
1494 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1495 * #UCL_EMIT_CONFIG then emit config like object
1496 * @param len the resulting length
1497 * @return dump of an object (must be freed after using) or NULL in case of error
1498 */
1499 UCL_EXTERN unsigned char *ucl_object_emit_len(const ucl_object_t *obj,
1500 enum ucl_emitter emit_type, size_t *len);
1501
1502 /**
1503 * Emit object to a string
1504 * @param obj object
1505 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
1506 * #UCL_EMIT_CONFIG then emit config like object
1507 * @param emitter a set of emitter functions
1508 * @param comments optional comments for the parser
1509 * @return dump of an object (must be freed after using) or NULL in case of error
1510 */
1511 UCL_EXTERN bool ucl_object_emit_full(const ucl_object_t *obj,
1512 enum ucl_emitter emit_type,
1513 struct ucl_emitter_functions *emitter,
1514 const ucl_object_t *comments);
1515
1516 /**
1517 * Start streamlined UCL object emitter
1518 * @param obj top UCL object
1519 * @param emit_type emit type
1520 * @param emitter a set of emitter functions
1521 * @return new streamlined context that should be freed by
1522 * `ucl_object_emit_streamline_finish`
1523 */
1524 UCL_EXTERN struct ucl_emitter_context *ucl_object_emit_streamline_new(
1525 const ucl_object_t *obj, enum ucl_emitter emit_type,
1526 struct ucl_emitter_functions *emitter);
1527
1528 /**
1529 * Start object or array container for the streamlined output
1530 * @param ctx streamlined context
1531 * @param obj container object
1532 */
1533 UCL_EXTERN bool ucl_object_emit_streamline_start_container(
1534 struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1535 /**
1536 * Add a complete UCL object to streamlined output
1537 * @param ctx streamlined context
1538 * @param obj object to output
1539 */
1540 UCL_EXTERN void ucl_object_emit_streamline_add_object(
1541 struct ucl_emitter_context *ctx, const ucl_object_t *obj);
1542 /**
1543 * End previously added container
1544 * @param ctx streamlined context
1545 */
1546 UCL_EXTERN void ucl_object_emit_streamline_end_container(
1547 struct ucl_emitter_context *ctx);
1548 /**
1549 * Terminate streamlined container finishing all containers in it
1550 * @param ctx streamlined context
1551 */
1552 UCL_EXTERN void ucl_object_emit_streamline_finish(
1553 struct ucl_emitter_context *ctx);
1554
1555 /**
1556 * Returns functions to emit object to memory
1557 * @param pmem target pointer (should be freed by caller)
1558 * @return emitter functions structure
1559 */
1560 UCL_EXTERN struct ucl_emitter_functions *ucl_object_emit_memory_funcs(
1561 void **pmem);
1562
1563 /**
1564 * Returns functions to emit object to FILE *
1565 * @param fp FILE * object
1566 * @return emitter functions structure
1567 */
1568 UCL_EXTERN struct ucl_emitter_functions *ucl_object_emit_file_funcs(
1569 FILE *fp);
1570 /**
1571 * Returns functions to emit object to a file descriptor
1572 * @param fd file descriptor
1573 * @return emitter functions structure
1574 */
1575 UCL_EXTERN struct ucl_emitter_functions *ucl_object_emit_fd_funcs(
1576 int fd);
1577
1578 /**
1579 * Free emitter functions
1580 * @param f pointer to functions
1581 */
1582 UCL_EXTERN void ucl_object_emit_funcs_free(struct ucl_emitter_functions *f);
1583
1584 /** @} */
1585
1586 /**
1587 * @defgroup schema Schema functions
1588 * These functions are used to validate UCL objects using json schema format
1589 *
1590 * @{
1591 */
1592
1593 /**
1594 * Used to define UCL schema error
1595 */
1596 enum ucl_schema_error_code {
1597 UCL_SCHEMA_OK = 0, /**< no error */
1598 UCL_SCHEMA_TYPE_MISMATCH, /**< type of object is incorrect */
1599 UCL_SCHEMA_INVALID_SCHEMA, /**< schema is invalid */
1600 UCL_SCHEMA_MISSING_PROPERTY, /**< one or more missing properties */
1601 UCL_SCHEMA_CONSTRAINT, /**< constraint found */
1602 UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */
1603 UCL_SCHEMA_EXTERNAL_REF_MISSING, /**< cannot fetch external ref */
1604 UCL_SCHEMA_EXTERNAL_REF_INVALID, /**< invalid external ref */
1605 UCL_SCHEMA_INTERNAL_ERROR, /**< something bad happened */
1606 UCL_SCHEMA_UNKNOWN /**< generic error */
1607 };
1608
1609 /**
1610 * Generic ucl schema error
1611 */
1612 struct ucl_schema_error {
1613 enum ucl_schema_error_code code; /**< error code */
1614 char msg[128]; /**< error message */
1615 const ucl_object_t *obj; /**< object where error occurred */
1616 };
1617
1618 /**
1619 * Validate object `obj` using schema object `schema`.
1620 * @param schema schema object
1621 * @param obj object to validate
1622 * @param err error pointer, if this parameter is not NULL and error has been
1623 * occurred, then `err` is filled with the exact error definition.
1624 * @return true if `obj` is valid using `schema`
1625 */
1626 UCL_EXTERN bool ucl_object_validate(const ucl_object_t *schema,
1627 const ucl_object_t *obj, struct ucl_schema_error *err);
1628
1629 /**
1630 * Validate object `obj` using schema object `schema` and root schema at `root`.
1631 * @param schema schema object
1632 * @param obj object to validate
1633 * @param root root schema object
1634 * @param err error pointer, if this parameter is not NULL and error has been
1635 * occurred, then `err` is filled with the exact error definition.
1636 * @return true if `obj` is valid using `schema`
1637 */
1638 UCL_EXTERN bool ucl_object_validate_root(const ucl_object_t *schema,
1639 const ucl_object_t *obj,
1640 const ucl_object_t *root,
1641 struct ucl_schema_error *err);
1642
1643 /**
1644 * Validate object `obj` using schema object `schema` and root schema at `root`
1645 * using some external references provided.
1646 * @param schema schema object
1647 * @param obj object to validate
1648 * @param root root schema object
1649 * @param ext_refs external references (might be modified during validation)
1650 * @param err error pointer, if this parameter is not NULL and error has been
1651 * occurred, then `err` is filled with the exact error definition.
1652 * @return true if `obj` is valid using `schema`
1653 */
1654 UCL_EXTERN bool ucl_object_validate_root_ext(const ucl_object_t *schema,
1655 const ucl_object_t *obj,
1656 const ucl_object_t *root,
1657 ucl_object_t *ext_refs,
1658 struct ucl_schema_error *err);
1659
1660 /** @} */
1661
1662 #ifdef __cplusplus
1663 }
1664 #endif
1665 /*
1666 * XXX: Poorly named API functions, need to replace them with the appropriate
1667 * named function. All API functions *must* use naming ucl_object_*. Usage of
1668 * ucl_obj* should be avoided.
1669 */
1670 #define ucl_obj_todouble_safe ucl_object_todouble_safe
1671 #define ucl_obj_todouble ucl_object_todouble
1672 #define ucl_obj_tostring ucl_object_tostring
1673 #define ucl_obj_tostring_safe ucl_object_tostring_safe
1674 #define ucl_obj_tolstring ucl_object_tolstring
1675 #define ucl_obj_tolstring_safe ucl_object_tolstring_safe
1676 #define ucl_obj_toint ucl_object_toint
1677 #define ucl_obj_toint_safe ucl_object_toint_safe
1678 #define ucl_obj_toboolean ucl_object_toboolean
1679 #define ucl_obj_toboolean_safe ucl_object_toboolean_safe
1680 #define ucl_obj_get_key ucl_object_find_key
1681 #define ucl_obj_get_keyl ucl_object_find_keyl
1682 #define ucl_obj_unref ucl_object_unref
1683 #define ucl_obj_ref ucl_object_ref
1684 #define ucl_obj_free ucl_object_free
1685
1686 #define UCL_PRIORITY_MIN 0
1687 #define UCL_PRIORITY_MAX 15
1688
1689 #endif /* UCL_H_ */
1690