1/* Copyright (c) 2013, 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 62extern "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/** 85 * @defgroup structures Structures and types 86 * UCL defines several enumeration types used for error reporting or specifying flags and attributes. 87 * 88 * @{ 89 */ 90 91/** 92 * The common error codes returned by ucl parser 93 */ 94typedef enum ucl_error { 95 UCL_EOK = 0, /**< No error */ 96 UCL_ESYNTAX, /**< Syntax error occurred during parsing */ 97 UCL_EIO, /**< IO error occurred during parsing */ 98 UCL_ESTATE, /**< Invalid state machine state */ 99 UCL_ENESTED, /**< Input has too many recursion levels */ 100 UCL_EMACRO, /**< Error processing a macro */ 101 UCL_EINTERNAL, /**< Internal unclassified error */ 102 UCL_ESSL /**< SSL error */ 103} ucl_error_t; 104 105/** 106 * #ucl_object_t may have one of specified types, some types are compatible with each other and some are not. 107 * For example, you can always convert #UCL_TIME to #UCL_FLOAT. Also you can convert #UCL_FLOAT to #UCL_INTEGER 108 * by loosing floating point. Every object may be converted to a string by #ucl_object_tostring_forced() function. 109 * 110 */ 111typedef enum ucl_type { 112 UCL_OBJECT = 0, /**< UCL object - key/value pairs */ 113 UCL_ARRAY, /**< UCL array */ 114 UCL_INT, /**< Integer number */ 115 UCL_FLOAT, /**< Floating point number */ 116 UCL_STRING, /**< Null terminated string */ 117 UCL_BOOLEAN, /**< Boolean value */ 118 UCL_TIME, /**< Time value (floating point number of seconds) */ 119 UCL_USERDATA, /**< Opaque userdata pointer (may be used in macros) */ 120 UCL_NULL /**< Null value */ 121} ucl_type_t; 122 123/** 124 * You can use one of these types to serialise #ucl_object_t by using ucl_object_emit(). 125 */ 126typedef enum ucl_emitter { 127 UCL_EMIT_JSON = 0, /**< Emit fine formatted JSON */ 128 UCL_EMIT_JSON_COMPACT, /**< Emit compacted JSON */ 129 UCL_EMIT_CONFIG, /**< Emit human readable config format */ 130 UCL_EMIT_YAML /**< Emit embedded YAML format */ 131} ucl_emitter_t; 132 133/** 134 * These flags defines parser behaviour. If you specify #UCL_PARSER_ZEROCOPY you must ensure 135 * that the input memory is not freed if an object is in use. Moreover, if you want to use 136 * zero-terminated keys and string values then you should not use zero-copy mode, as in this case 137 * UCL still has to perform copying implicitly. 138 */ 139typedef enum ucl_parser_flags { 140 UCL_PARSER_KEY_LOWERCASE = 0x1, /**< Convert all keys to lower case */ 141 UCL_PARSER_ZEROCOPY = 0x2 /**< Parse input in zero-copy mode if possible */ 142} ucl_parser_flags_t; 143 144/** 145 * String conversion flags, that are used in #ucl_object_fromstring_common function. 146 */ 147typedef enum ucl_string_flags { 148 UCL_STRING_ESCAPE = 0x1, /**< Perform JSON escape */ 149 UCL_STRING_TRIM = 0x2, /**< Trim leading and trailing whitespaces */ 150 UCL_STRING_PARSE_BOOLEAN = 0x4, /**< Parse passed string and detect boolean */ 151 UCL_STRING_PARSE_INT = 0x8, /**< Parse passed string and detect integer number */ 152 UCL_STRING_PARSE_DOUBLE = 0x10, /**< Parse passed string and detect integer or float number */ 153 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE , /**< 154 Parse passed string and detect number */ 155 UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER, /**< 156 Parse passed string (and detect booleans and numbers) */ 157 UCL_STRING_PARSE_BYTES = 0x20 /**< Treat numbers as bytes */ 158} ucl_string_flags_t; 159 160/** 161 * Basic flags for an object 162 */ 163typedef enum ucl_object_flags { 164 UCL_OBJECT_ALLOCATED_KEY = 1, /**< An object has key allocated internally */ 165 UCL_OBJECT_ALLOCATED_VALUE = 2, /**< An object has a string value allocated internally */ 166 UCL_OBJECT_NEED_KEY_ESCAPE = 4 /**< The key of an object need to be escaped on output */ 167} ucl_object_flags_t; 168 169/** 170 * UCL object structure. Please mention that the most of fields should not be touched by 171 * UCL users. In future, this structure may be converted to private one. 172 */ 173typedef struct ucl_object_s { 174 /** 175 * Variant value type 176 */ 177 union { 178 int64_t iv; /**< Int value of an object */ 179 const char *sv; /**< String value of an object */ 180 double dv; /**< Double value of an object */ 181 struct ucl_object_s *av; /**< Array */ 182 void *ov; /**< Object */ 183 void* ud; /**< Opaque user data */ 184 } value; 185 const char *key; /**< Key of an object */ 186 struct ucl_object_s *next; /**< Array handle */ 187 struct ucl_object_s *prev; /**< Array handle */ 188 unsigned char* trash_stack[2]; /**< Pointer to allocated chunks */ 189 unsigned keylen; /**< Lenght of a key */ 190 unsigned len; /**< Size of an object */ 191 enum ucl_type type; /**< Real type */ 192 uint16_t ref; /**< Reference count */ 193 uint16_t flags; /**< Object flags */ 194} ucl_object_t; 195 196/** @} */ 197 198/** 199 * @defgroup utils Utility functions 200 * A number of utility functions simplify handling of UCL objects 201 * 202 * @{ 203 */ 204/** 205 * Copy and return a key of an object, returned key is zero-terminated 206 * @param obj CL object 207 * @return zero terminated key 208 */ 209UCL_EXTERN char* ucl_copy_key_trash (ucl_object_t *obj); 210 211/** 212 * Copy and return a string value of an object, returned key is zero-terminated 213 * @param obj CL object 214 * @return zero terminated string representation of object value 215 */ 216UCL_EXTERN char* ucl_copy_value_trash (ucl_object_t *obj); 217 218/** 219 * Creates a new object 220 * @return new object 221 */ 222static inline ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT; 223static inline ucl_object_t * 224ucl_object_new (void) 225{ 226 ucl_object_t *new; 227 new = malloc (sizeof (ucl_object_t)); 228 if (new != NULL) { 229 memset (new, 0, sizeof (ucl_object_t)); 230 new->ref = 1; 231 new->type = UCL_NULL; 232 } 233 return new; 234} 235 236/** 237 * Create new object with type specified 238 * @param type type of a new object 239 * @return new object 240 */ 241static inline ucl_object_t* ucl_object_typed_new (unsigned int type) UCL_WARN_UNUSED_RESULT; 242static inline ucl_object_t * 243ucl_object_typed_new (unsigned int type) 244{ 245 ucl_object_t *new; 246 new = malloc (sizeof (ucl_object_t)); 247 if (new != NULL) { 248 memset (new, 0, sizeof (ucl_object_t)); 249 new->ref = 1; 250 new->type = (type <= UCL_NULL ? type : UCL_NULL); 251 } 252 return new; 253} 254 255/** 256 * Convert any string to an ucl object making the specified transformations 257 * @param str fixed size or NULL terminated string 258 * @param len length (if len is zero, than str is treated as NULL terminated) 259 * @param flags conversion flags 260 * @return new object 261 */ 262UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len, 263 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT; 264 265/** 266 * Create a UCL object from the specified string 267 * @param str NULL terminated string, will be json escaped 268 * @return new object 269 */ 270static inline ucl_object_t * 271ucl_object_fromstring (const char *str) 272{ 273 return ucl_object_fromstring_common (str, 0, UCL_STRING_ESCAPE); 274} 275 276/** 277 * Create a UCL object from the specified string 278 * @param str fixed size string, will be json escaped 279 * @param len length of a string 280 * @return new object 281 */ 282static inline ucl_object_t * 283ucl_object_fromlstring (const char *str, size_t len) 284{ 285 return ucl_object_fromstring_common (str, len, UCL_STRING_ESCAPE); 286} 287 288/** 289 * Create an object from an integer number 290 * @param iv number 291 * @return new object 292 */ 293static inline ucl_object_t * 294ucl_object_fromint (int64_t iv) 295{ 296 ucl_object_t *obj; 297 298 obj = ucl_object_new (); 299 if (obj != NULL) { 300 obj->type = UCL_INT; 301 obj->value.iv = iv; 302 } 303 304 return obj; 305} 306 307/** 308 * Create an object from a float number 309 * @param dv number 310 * @return new object 311 */ 312static inline ucl_object_t * 313ucl_object_fromdouble (double dv) 314{ 315 ucl_object_t *obj; 316 317 obj = ucl_object_new (); 318 if (obj != NULL) { 319 obj->type = UCL_FLOAT; 320 obj->value.dv = dv; 321 } 322 323 return obj; 324} 325 326/** 327 * Create an object from a boolean 328 * @param bv bool value 329 * @return new object 330 */ 331static inline ucl_object_t * 332ucl_object_frombool (bool bv) 333{ 334 ucl_object_t *obj; 335 336 obj = ucl_object_new (); 337 if (obj != NULL) { 338 obj->type = UCL_BOOLEAN; 339 obj->value.iv = bv; 340 } 341 342 return obj; 343} 344 345/** 346 * Insert a object 'elt' to the hash 'top' and associate it with key 'key' 347 * @param top destination object (will be created automatically if top is NULL) 348 * @param elt element to insert (must NOT be NULL) 349 * @param key key to associate with this object (either const or preallocated) 350 * @param keylen length of the key (or 0 for NULL terminated keys) 351 * @param copy_key make an internal copy of key 352 * @return new value of top object 353 */ 354UCL_EXTERN ucl_object_t* ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt, 355 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 356 357/** 358 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed, 359 * if no object has been found this function works like ucl_object_insert_key() 360 * @param top destination object (will be created automatically if top is NULL) 361 * @param elt element to insert (must NOT be NULL) 362 * @param key key to associate with this object (either const or preallocated) 363 * @param keylen length of the key (or 0 for NULL terminated keys) 364 * @param copy_key make an internal copy of key 365 * @return new value of top object 366 */ 367UCL_EXTERN ucl_object_t* ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt, 368 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 369 370/** 371 * Delete a object associated with key 'key', old object will be unrefered, 372 * @param top object 373 * @param key key associated to the object to remove 374 * @param keylen length of the key (or 0 for NULL terminated keys) 375 */ 376UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top, const char *key, size_t keylen); 377 378/** 379 * Delete a object associated with key 'key', old object will be unrefered, 380 * @param top object 381 * @param key key associated to the object to remove 382 */ 383UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top, const char *key); 384 385/** 386 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if the specified key exist, 387 * try to merge its content 388 * @param top destination object (will be created automatically if top is NULL) 389 * @param elt element to insert (must NOT be NULL) 390 * @param key key to associate with this object (either const or preallocated) 391 * @param keylen length of the key (or 0 for NULL terminated keys) 392 * @param copy_key make an internal copy of key 393 * @return new value of top object 394 */ 395UCL_EXTERN ucl_object_t* ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt, 396 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 397 398/** 399 * Append an element to the front of array object 400 * @param top destination object (will be created automatically if top is NULL) 401 * @param elt element to append (must NOT be NULL) 402 * @return new value of top object 403 */ 404static inline ucl_object_t * ucl_array_append (ucl_object_t *top, 405 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT; 406static inline ucl_object_t * 407ucl_array_append (ucl_object_t *top, ucl_object_t *elt) 408{ 409 ucl_object_t *head; 410 411 if (elt == NULL) { 412 return NULL; 413 } 414 415 if (top == NULL) { 416 top = ucl_object_typed_new (UCL_ARRAY); 417 top->value.av = elt; 418 elt->next = NULL; 419 elt->prev = elt; 420 top->len = 1; 421 } 422 else { 423 head = top->value.av; 424 if (head == NULL) { 425 top->value.av = elt; 426 elt->prev = elt; 427 } 428 else { 429 elt->prev = head->prev; 430 head->prev->next = elt; 431 head->prev = elt; 432 } 433 elt->next = NULL; 434 top->len ++; 435 } 436 437 return top; 438} 439 440/** 441 * Append an element to the start of array object 442 * @param top destination object (will be created automatically if top is NULL) 443 * @param elt element to append (must NOT be NULL) 444 * @return new value of top object 445 */ 446static inline ucl_object_t * ucl_array_prepend (ucl_object_t *top, 447 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT; 448static inline ucl_object_t * 449ucl_array_prepend (ucl_object_t *top, ucl_object_t *elt) 450{ 451 ucl_object_t *head; 452 453 if (elt == NULL) { 454 return NULL; 455 } 456 457 if (top == NULL) { 458 top = ucl_object_typed_new (UCL_ARRAY); 459 top->value.av = elt; 460 elt->next = NULL; 461 elt->prev = elt; 462 top->len = 1; 463 } 464 else { 465 head = top->value.av; 466 if (head == NULL) { 467 top->value.av = elt; 468 elt->prev = elt; 469 } 470 else { 471 elt->prev = head->prev; 472 head->prev = elt; 473 } 474 elt->next = head; 475 top->value.av = elt; 476 top->len ++; 477 } 478 479 return top; 480} 481 482/** 483 * Removes an element `elt` from the array `top`. Caller must unref the returned object when it is not 484 * needed. 485 * @param top array ucl object 486 * @param elt element to remove 487 * @return removed element or NULL if `top` is NULL or not an array 488 */ 489static inline ucl_object_t * 490ucl_array_delete (ucl_object_t *top, ucl_object_t *elt) 491{ 492 ucl_object_t *head; 493 494 if (top == NULL || top->type != UCL_ARRAY || top->value.av == NULL) { 495 return NULL; 496 } 497 head = top->value.av; 498 499 if (elt->prev == elt) { 500 top->value.av = NULL; 501 } 502 else if (elt == head) { 503 elt->next->prev = elt->prev; 504 top->value.av = elt->next; 505 } 506 else { 507 elt->prev->next = elt->next; 508 if (elt->next) { 509 elt->next->prev = elt->prev; 510 } 511 else { 512 head->prev = elt->prev; 513 } 514 } 515 elt->next = NULL; 516 elt->prev = elt; 517 top->len --; 518 519 return elt; 520} 521 522/** 523 * Returns the first element of the array `top` 524 * @param top array ucl object 525 * @return element or NULL if `top` is NULL or not an array 526 */ 527static inline ucl_object_t * 528ucl_array_head (ucl_object_t *top) 529{ 530 if (top == NULL || top->type != UCL_ARRAY || top->value.av == NULL) { 531 return NULL; 532 } 533 return top->value.av; 534} 535 536/** 537 * Returns the last element of the array `top` 538 * @param top array ucl object 539 * @return element or NULL if `top` is NULL or not an array 540 */ 541static inline ucl_object_t * 542ucl_array_tail (ucl_object_t *top) 543{ 544 if (top == NULL || top->type != UCL_ARRAY || top->value.av == NULL) { 545 return NULL; 546 } 547 return top->value.av->prev; 548} 549 550/** 551 * Removes the last element from the array `top`. Caller must unref the returned object when it is not 552 * needed. 553 * @param top array ucl object 554 * @return removed element or NULL if `top` is NULL or not an array 555 */ 556static inline ucl_object_t * 557ucl_array_pop_last (ucl_object_t *top) 558{ 559 return ucl_array_delete (top, ucl_array_tail (top)); 560} 561 562/** 563 * Removes the first element from the array `top`. Caller must unref the returned object when it is not 564 * needed. 565 * @param top array ucl object 566 * @return removed element or NULL if `top` is NULL or not an array 567 */ 568static inline ucl_object_t * 569ucl_array_pop_first (ucl_object_t *top) 570{ 571 return ucl_array_delete (top, ucl_array_head (top)); 572} 573 574/** 575 * Append a element to another element forming an implicit array 576 * @param head head to append (may be NULL) 577 * @param elt new element 578 * @return new head if applicable 579 */ 580static inline ucl_object_t * ucl_elt_append (ucl_object_t *head, 581 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT; 582static inline ucl_object_t * 583ucl_elt_append (ucl_object_t *head, ucl_object_t *elt) 584{ 585 586 if (head == NULL) { 587 elt->next = NULL; 588 elt->prev = elt; 589 head = elt; 590 } 591 else { 592 elt->prev = head->prev; 593 head->prev->next = elt; 594 head->prev = elt; 595 elt->next = NULL; 596 } 597 598 return head; 599} 600 601/** 602 * Converts an object to double value 603 * @param obj CL object 604 * @param target target double variable 605 * @return true if conversion was successful 606 */ 607static inline bool 608ucl_object_todouble_safe (ucl_object_t *obj, double *target) 609{ 610 if (obj == NULL) { 611 return false; 612 } 613 switch (obj->type) { 614 case UCL_INT: 615 *target = obj->value.iv; /* Probaly could cause overflow */ 616 break; 617 case UCL_FLOAT: 618 case UCL_TIME: 619 *target = obj->value.dv; 620 break; 621 default: 622 return false; 623 } 624 625 return true; 626} 627 628/** 629 * Unsafe version of \ref ucl_obj_todouble_safe 630 * @param obj CL object 631 * @return double value 632 */ 633static inline double 634ucl_object_todouble (ucl_object_t *obj) 635{ 636 double result = 0.; 637 638 ucl_object_todouble_safe (obj, &result); 639 return result; 640} 641 642/** 643 * Converts an object to integer value 644 * @param obj CL object 645 * @param target target integer variable 646 * @return true if conversion was successful 647 */ 648static inline bool 649ucl_object_toint_safe (ucl_object_t *obj, int64_t *target) 650{ 651 if (obj == NULL) { 652 return false; 653 } 654 switch (obj->type) { 655 case UCL_INT: 656 *target = obj->value.iv; 657 break; 658 case UCL_FLOAT: 659 case UCL_TIME: 660 *target = obj->value.dv; /* Loosing of decimal points */ 661 break; 662 default: 663 return false; 664 } 665 666 return true; 667} 668 669/** 670 * Unsafe version of \ref ucl_obj_toint_safe 671 * @param obj CL object 672 * @return int value 673 */ 674static inline int64_t 675ucl_object_toint (ucl_object_t *obj) 676{ 677 int64_t result = 0; 678 679 ucl_object_toint_safe (obj, &result); 680 return result; 681} 682 683/** 684 * Converts an object to boolean value 685 * @param obj CL object 686 * @param target target boolean variable 687 * @return true if conversion was successful 688 */ 689static inline bool 690ucl_object_toboolean_safe (ucl_object_t *obj, bool *target) 691{ 692 if (obj == NULL) { 693 return false; 694 } 695 switch (obj->type) { 696 case UCL_BOOLEAN: 697 *target = (obj->value.iv == true); 698 break; 699 default: 700 return false; 701 } 702 703 return true; 704} 705 706/** 707 * Unsafe version of \ref ucl_obj_toboolean_safe 708 * @param obj CL object 709 * @return boolean value 710 */ 711static inline bool 712ucl_object_toboolean (ucl_object_t *obj) 713{ 714 bool result = false; 715 716 ucl_object_toboolean_safe (obj, &result); 717 return result; 718} 719 720/** 721 * Converts an object to string value 722 * @param obj CL object 723 * @param target target string variable, no need to free value 724 * @return true if conversion was successful 725 */ 726static inline bool 727ucl_object_tostring_safe (ucl_object_t *obj, const char **target) 728{ 729 if (obj == NULL) { 730 return false; 731 } 732 733 switch (obj->type) { 734 case UCL_STRING: 735 *target = ucl_copy_value_trash (obj); 736 break; 737 default: 738 return false; 739 } 740 741 return true; 742} 743 744/** 745 * Unsafe version of \ref ucl_obj_tostring_safe 746 * @param obj CL object 747 * @return string value 748 */ 749static inline const char * 750ucl_object_tostring (ucl_object_t *obj) 751{ 752 const char *result = NULL; 753 754 ucl_object_tostring_safe (obj, &result); 755 return result; 756} 757 758/** 759 * Convert any object to a string in JSON notation if needed 760 * @param obj CL object 761 * @return string value 762 */ 763static inline const char * 764ucl_object_tostring_forced (ucl_object_t *obj) 765{ 766 return ucl_copy_value_trash (obj); 767} 768 769/** 770 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it 771 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing) 772 * @param obj CL object 773 * @param target target string variable, no need to free value 774 * @param tlen target length 775 * @return true if conversion was successful 776 */ 777static inline bool 778ucl_object_tolstring_safe (ucl_object_t *obj, const char **target, size_t *tlen) 779{ 780 if (obj == NULL) { 781 return false; 782 } 783 switch (obj->type) { 784 case UCL_STRING: 785 *target = obj->value.sv; 786 *tlen = obj->len; 787 break; 788 default: 789 return false; 790 } 791 792 return true; 793} 794 795/** 796 * Unsafe version of \ref ucl_obj_tolstring_safe 797 * @param obj CL object 798 * @return string value 799 */ 800static inline const char * 801ucl_object_tolstring (ucl_object_t *obj, size_t *tlen) 802{ 803 const char *result = NULL; 804 805 ucl_object_tolstring_safe (obj, &result, tlen); 806 return result; 807} 808 809/** 810 * Return object identified by a key in the specified object 811 * @param obj object to get a key from (must be of type UCL_OBJECT) 812 * @param key key to search 813 * @return object matched the specified key or NULL if key is not found 814 */ 815UCL_EXTERN ucl_object_t * ucl_object_find_key (ucl_object_t *obj, const char *key); 816 817/** 818 * Return object identified by a fixed size key in the specified object 819 * @param obj object to get a key from (must be of type UCL_OBJECT) 820 * @param key key to search 821 * @param klen length of a key 822 * @return object matched the specified key or NULL if key is not found 823 */ 824UCL_EXTERN ucl_object_t *ucl_object_find_keyl (ucl_object_t *obj, const char *key, size_t klen); 825 826/** 827 * Returns a key of an object as a NULL terminated string 828 * @param obj CL object 829 * @return key or NULL if there is no key 830 */ 831static inline const char * 832ucl_object_key (ucl_object_t *obj) 833{ 834 return ucl_copy_key_trash (obj); 835} 836 837/** 838 * Returns a key of an object as a fixed size string (may be more efficient) 839 * @param obj CL object 840 * @param len target key length 841 * @return key pointer 842 */ 843static inline const char * 844ucl_object_keyl (ucl_object_t *obj, size_t *len) 845{ 846 *len = obj->keylen; 847 return obj->key; 848} 849 850/** 851 * Free ucl object 852 * @param obj ucl object to free 853 */ 854UCL_EXTERN void ucl_object_free (ucl_object_t *obj); 855 856/** 857 * Increase reference count for an object 858 * @param obj object to ref 859 */ 860static inline ucl_object_t * 861ucl_object_ref (ucl_object_t *obj) { 862 obj->ref ++; 863 return obj; 864} 865 866/** 867 * Decrease reference count for an object 868 * @param obj object to unref 869 */ 870static inline void 871ucl_object_unref (ucl_object_t *obj) { 872 if (obj != NULL && --obj->ref <= 0) { 873 ucl_object_free (obj); 874 } 875} 876/** 877 * Opaque iterator object 878 */ 879typedef void* ucl_object_iter_t; 880 881/** 882 * Get next key from an object 883 * @param obj object to iterate 884 * @param iter opaque iterator, must be set to NULL on the first call: 885 * ucl_object_iter_t it = NULL; 886 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ... 887 * @return the next object or NULL 888 */ 889UCL_EXTERN ucl_object_t* ucl_iterate_object (ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values); 890/** @} */ 891 892 893/** 894 * @defgroup parser Parsing functions 895 * These functions are used to parse UCL objects 896 * 897 * @{ 898 */ 899 900/** 901 * Macro handler for a parser 902 * @param data the content of macro 903 * @param len the length of content 904 * @param ud opaque user data 905 * @param err error pointer 906 * @return true if macro has been parsed 907 */ 908typedef bool (*ucl_macro_handler) (const unsigned char *data, size_t len, void* ud); 909 910/* Opaque parser */ 911struct ucl_parser; 912 913/** 914 * Creates new parser object 915 * @param pool pool to allocate memory from 916 * @return new parser object 917 */ 918UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags); 919 920/** 921 * Register new handler for a macro 922 * @param parser parser object 923 * @param macro macro name (without leading dot) 924 * @param handler handler (it is called immediately after macro is parsed) 925 * @param ud opaque user data for a handler 926 */ 927UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser, const char *macro, 928 ucl_macro_handler handler, void* ud); 929 930/** 931 * Register new parser variable 932 * @param parser parser object 933 * @param var variable name 934 * @param value variable value 935 */ 936UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var, 937 const char *value); 938 939/** 940 * Load new chunk to a parser 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 err if *err is NULL it is set to parser error 945 * @return true if chunk has been added and false in case of error 946 */ 947UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser, const unsigned char *data, size_t len); 948 949/** 950 * Load and add data from a file 951 * @param parser parser structure 952 * @param filename the name of file 953 * @param err if *err is NULL it is set to parser error 954 * @return true if chunk has been added and false in case of error 955 */ 956UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser, const char *filename); 957 958/** 959 * Get a top object for a parser 960 * @param parser parser structure 961 * @param err if *err is NULL it is set to parser error 962 * @return top parser object or NULL 963 */ 964UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); 965 966/** 967 * Get the error string if failing 968 * @param parser parser object 969 */ 970UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser); 971/** 972 * Free ucl parser object 973 * @param parser parser object 974 */ 975UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser); 976 977/** 978 * Add new public key to parser for signatures check 979 * @param parser parser object 980 * @param key PEM representation of a key 981 * @param len length of the key 982 * @param err if *err is NULL it is set to parser error 983 * @return true if a key has been successfully added 984 */ 985UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len); 986 987/** 988 * Set FILENAME and CURDIR variables in parser 989 * @param parser parser object 990 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd() 991 * @param need_expand perform realpath() if this variable is true and filename is not NULL 992 * @return true if variables has been set 993 */ 994UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename, 995 bool need_expand); 996 997/** @} */ 998 999/** 1000 * @defgroup emitter Emitting functions 1001 * These functions are used to serialise UCL objects to some string representation. 1002 * 1003 * @{ 1004 */ 1005 1006/** 1007 * Structure using for emitter callbacks 1008 */ 1009struct ucl_emitter_functions { 1010 /** Append a single character */ 1011 int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud); 1012 /** Append a string of a specified length */ 1013 int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud); 1014 /** Append a 64 bit integer */ 1015 int (*ucl_emitter_append_int) (int64_t elt, void *ud); 1016 /** Append floating point element */ 1017 int (*ucl_emitter_append_double) (double elt, void *ud); 1018 /** Opaque userdata pointer */ 1019 void *ud; 1020}; 1021 1022/** 1023 * Emit object to a string 1024 * @param obj object 1025 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 1026 * #UCL_EMIT_CONFIG then emit config like object 1027 * @return dump of an object (must be freed after using) or NULL in case of error 1028 */ 1029UCL_EXTERN unsigned char *ucl_object_emit (ucl_object_t *obj, enum ucl_emitter emit_type); 1030 1031/** 1032 * Emit object to a string 1033 * @param obj object 1034 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 1035 * #UCL_EMIT_CONFIG then emit config like object 1036 * @return dump of an object (must be freed after using) or NULL in case of error 1037 */ 1038UCL_EXTERN bool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type, 1039 struct ucl_emitter_functions *emitter); 1040/** @} */ 1041 1042#ifdef __cplusplus 1043} 1044#endif 1045/* 1046 * XXX: Poorly named API functions, need to replace them with the appropriate 1047 * named function. All API functions *must* use naming ucl_object_*. Usage of 1048 * ucl_obj* should be avoided. 1049 */ 1050#define ucl_obj_todouble_safe ucl_object_todouble_safe 1051#define ucl_obj_todouble ucl_object_todouble 1052#define ucl_obj_tostring ucl_object_tostring 1053#define ucl_obj_tostring_safe ucl_object_tostring_safe 1054#define ucl_obj_tolstring ucl_object_tolstring 1055#define ucl_obj_tolstring_safe ucl_object_tolstring_safe 1056#define ucl_obj_toint ucl_object_toint 1057#define ucl_obj_toint_safe ucl_object_toint_safe 1058#define ucl_obj_toboolean ucl_object_toboolean 1059#define ucl_obj_toboolean_safe ucl_object_toboolean_safe 1060#define ucl_obj_get_key ucl_object_find_key 1061#define ucl_obj_get_keyl ucl_object_find_keyl 1062#define ucl_obj_unref ucl_object_unref 1063#define ucl_obj_ref ucl_object_ref 1064#define ucl_obj_free ucl_object_free 1065 1066#endif /* UCL_H_ */ 1067