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