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