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_ */ 1333