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