contrib/libucl/include/ucl.h

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