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 --- 124 unchanged lines hidden (view full) --- 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_NO_TIME = 0x4 /**< Do not parse time and treat time values as strings */ |
143} ucl_parser_flags_t; 144 145/** 146 * String conversion flags, that are used in #ucl_object_fromstring_common function. 147 */ 148typedef enum ucl_string_flags { 149 UCL_STRING_ESCAPE = 0x1, /**< Perform JSON escape */ 150 UCL_STRING_TRIM = 0x2, /**< Trim leading and trailing whitespaces */ 151 UCL_STRING_PARSE_BOOLEAN = 0x4, /**< Parse passed string and detect boolean */ 152 UCL_STRING_PARSE_INT = 0x8, /**< Parse passed string and detect integer number */ 153 UCL_STRING_PARSE_DOUBLE = 0x10, /**< Parse passed string and detect integer or float number */ |
154 UCL_STRING_PARSE_TIME = 0x20, /**< Parse time strings */ 155 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE|UCL_STRING_PARSE_TIME, /**< |
156 Parse passed string and detect number */ 157 UCL_STRING_PARSE = UCL_STRING_PARSE_BOOLEAN|UCL_STRING_PARSE_NUMBER, /**< 158 Parse passed string (and detect booleans and numbers) */ |
159 UCL_STRING_PARSE_BYTES = 0x40 /**< Treat numbers as bytes */ |
160} ucl_string_flags_t; 161 162/** 163 * Basic flags for an object 164 */ 165typedef enum ucl_object_flags { 166 UCL_OBJECT_ALLOCATED_KEY = 1, /**< An object has key allocated internally */ 167 UCL_OBJECT_ALLOCATED_VALUE = 2, /**< An object has a string value allocated internally */ --- 48 unchanged lines hidden (view full) --- 216 * @return zero terminated string representation of object value 217 */ 218UCL_EXTERN char* ucl_copy_value_trash (ucl_object_t *obj); 219 220/** 221 * Creates a new object 222 * @return new object 223 */ |
224UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT; |
225 226/** 227 * Create new object with type specified 228 * @param type type of a new object 229 * @return new object 230 */ |
231UCL_EXTERN ucl_object_t* ucl_object_typed_new (unsigned int type) UCL_WARN_UNUSED_RESULT; |
232 233/** 234 * Convert any string to an ucl object making the specified transformations 235 * @param str fixed size or NULL terminated string 236 * @param len length (if len is zero, than str is treated as NULL terminated) 237 * @param flags conversion flags 238 * @return new object 239 */ 240UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len, 241 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT; 242 243/** 244 * Create a UCL object from the specified string 245 * @param str NULL terminated string, will be json escaped 246 * @return new object 247 */ |
248UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str); |
249 250/** 251 * Create a UCL object from the specified string 252 * @param str fixed size string, will be json escaped 253 * @param len length of a string 254 * @return new object 255 */ |
256UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str, size_t len); |
257 258/** 259 * Create an object from an integer number 260 * @param iv number 261 * @return new object 262 */ |
263UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv); |
264 |
265/** 266 * Create an object from a float number 267 * @param dv number 268 * @return new object 269 */ |
270UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv); |
271 |
272/** 273 * Create an object from a boolean 274 * @param bv bool value 275 * @return new object 276 */ |
277UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv); |
278 |
279/** 280 * Insert a object 'elt' to the hash 'top' and associate it with key 'key' 281 * @param top destination object (will be created automatically if top is NULL) 282 * @param elt element to insert (must NOT be NULL) 283 * @param key key to associate with this object (either const or preallocated) 284 * @param keylen length of the key (or 0 for NULL terminated keys) 285 * @param copy_key make an internal copy of key 286 * @return new value of top object --- 24 unchanged lines hidden (view full) --- 311 312/** 313 * Delete a object associated with key 'key', old object will be unrefered, 314 * @param top object 315 * @param key key associated to the object to remove 316 */ 317UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top, const char *key); 318 |
319 |
320/** |
321 * Delete key from `top` object returning the object deleted. This object is not 322 * released 323 * @param top object 324 * @param key key to remove 325 * @param keylen length of the key (or 0 for NULL terminated keys) 326 * @return removed object or NULL if object has not been found 327 */ 328UCL_EXTERN ucl_object_t* ucl_object_pop_keyl (ucl_object_t *top, const char *key, 329 size_t keylen) UCL_WARN_UNUSED_RESULT; 330 331/** 332 * Delete key from `top` object returning the object deleted. This object is not 333 * released 334 * @param top object 335 * @param key key to remove 336 * @return removed object or NULL if object has not been found 337 */ 338UCL_EXTERN ucl_object_t* ucl_object_pop_key (ucl_object_t *top, const char *key) 339 UCL_WARN_UNUSED_RESULT; 340 341/** |
342 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if the specified key exist, 343 * try to merge its content 344 * @param top destination object (will be created automatically if top is NULL) 345 * @param elt element to insert (must NOT be NULL) 346 * @param key key to associate with this object (either const or preallocated) 347 * @param keylen length of the key (or 0 for NULL terminated keys) 348 * @param copy_key make an internal copy of key 349 * @return new value of top object 350 */ 351UCL_EXTERN ucl_object_t* ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt, 352 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT; 353 354/** 355 * Append an element to the front of array object 356 * @param top destination object (will be created automatically if top is NULL) 357 * @param elt element to append (must NOT be NULL) 358 * @return new value of top object 359 */ |
360UCL_EXTERN ucl_object_t* ucl_array_append (ucl_object_t *top, |
361 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT; |
362 |
363/** 364 * Append an element to the start of array object 365 * @param top destination object (will be created automatically if top is NULL) 366 * @param elt element to append (must NOT be NULL) 367 * @return new value of top object 368 */ |
369UCL_EXTERN ucl_object_t* ucl_array_prepend (ucl_object_t *top, |
370 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT; |
371 |
372/** 373 * Removes an element `elt` from the array `top`. Caller must unref the returned object when it is not 374 * needed. 375 * @param top array ucl object 376 * @param elt element to remove 377 * @return removed element or NULL if `top` is NULL or not an array 378 */ |
379UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top, ucl_object_t *elt); |
380 |
381/** 382 * Returns the first element of the array `top` 383 * @param top array ucl object 384 * @return element or NULL if `top` is NULL or not an array 385 */ |
386UCL_EXTERN ucl_object_t* ucl_array_head (ucl_object_t *top); |
387 388/** 389 * Returns the last element of the array `top` 390 * @param top array ucl object 391 * @return element or NULL if `top` is NULL or not an array 392 */ |
393UCL_EXTERN ucl_object_t* ucl_array_tail (ucl_object_t *top); |
394 395/** 396 * Removes the last element from the array `top`. Caller must unref the returned object when it is not 397 * needed. 398 * @param top array ucl object 399 * @return removed element or NULL if `top` is NULL or not an array 400 */ |
401UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top); |
402 403/** 404 * Removes the first element from the array `top`. Caller must unref the returned object when it is not 405 * needed. 406 * @param top array ucl object 407 * @return removed element or NULL if `top` is NULL or not an array 408 */ |
409UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top); |
410 411/** 412 * Append a element to another element forming an implicit array 413 * @param head head to append (may be NULL) 414 * @param elt new element 415 * @return new head if applicable 416 */ |
417UCL_EXTERN ucl_object_t* ucl_elt_append (ucl_object_t *head, |
418 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT; |
419 |
420/** 421 * Converts an object to double value 422 * @param obj CL object 423 * @param target target double variable 424 * @return true if conversion was successful 425 */ |
426UCL_EXTERN bool ucl_object_todouble_safe (ucl_object_t *obj, double *target); |
427 |
428/** 429 * Unsafe version of \ref ucl_obj_todouble_safe 430 * @param obj CL object 431 * @return double value 432 */ |
433UCL_EXTERN double ucl_object_todouble (ucl_object_t *obj); |
434 |
435/** 436 * Converts an object to integer value 437 * @param obj CL object 438 * @param target target integer variable 439 * @return true if conversion was successful 440 */ |
441UCL_EXTERN bool ucl_object_toint_safe (ucl_object_t *obj, int64_t *target); |
442 |
443/** 444 * Unsafe version of \ref ucl_obj_toint_safe 445 * @param obj CL object 446 * @return int value 447 */ |
448UCL_EXTERN int64_t ucl_object_toint (ucl_object_t *obj); |
449 |
450/** 451 * Converts an object to boolean value 452 * @param obj CL object 453 * @param target target boolean variable 454 * @return true if conversion was successful 455 */ |
456UCL_EXTERN bool ucl_object_toboolean_safe (ucl_object_t *obj, bool *target); |
457 |
458/** 459 * Unsafe version of \ref ucl_obj_toboolean_safe 460 * @param obj CL object 461 * @return boolean value 462 */ |
463UCL_EXTERN bool ucl_object_toboolean (ucl_object_t *obj); |
464 |
465/** 466 * Converts an object to string value 467 * @param obj CL object 468 * @param target target string variable, no need to free value 469 * @return true if conversion was successful 470 */ |
471UCL_EXTERN bool ucl_object_tostring_safe (ucl_object_t *obj, const char **target); |
472 |
473/** 474 * Unsafe version of \ref ucl_obj_tostring_safe 475 * @param obj CL object 476 * @return string value 477 */ |
478UCL_EXTERN const char* ucl_object_tostring (ucl_object_t *obj); |
479 |
480/** 481 * Convert any object to a string in JSON notation if needed 482 * @param obj CL object 483 * @return string value 484 */ |
485UCL_EXTERN const char* ucl_object_tostring_forced (ucl_object_t *obj); |
486 487/** 488 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it 489 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing) 490 * @param obj CL object 491 * @param target target string variable, no need to free value 492 * @param tlen target length 493 * @return true if conversion was successful 494 */ |
495UCL_EXTERN bool ucl_object_tolstring_safe (ucl_object_t *obj, 496 const char **target, size_t *tlen); |
497 |
498/** 499 * Unsafe version of \ref ucl_obj_tolstring_safe 500 * @param obj CL object 501 * @return string value 502 */ |
503UCL_EXTERN const char* ucl_object_tolstring (ucl_object_t *obj, size_t *tlen); |
504 |
505/** 506 * Return object identified by a key in the specified object 507 * @param obj object to get a key from (must be of type UCL_OBJECT) 508 * @param key key to search 509 * @return object matched the specified key or NULL if key is not found 510 */ |
511UCL_EXTERN ucl_object_t* ucl_object_find_key (ucl_object_t *obj, const char *key); |
512 513/** 514 * Return object identified by a fixed size key in the specified object 515 * @param obj object to get a key from (must be of type UCL_OBJECT) 516 * @param key key to search 517 * @param klen length of a key 518 * @return object matched the specified key or NULL if key is not found 519 */ |
520UCL_EXTERN ucl_object_t* ucl_object_find_keyl (ucl_object_t *obj, const char *key, size_t klen); |
521 522/** 523 * Returns a key of an object as a NULL terminated string 524 * @param obj CL object 525 * @return key or NULL if there is no key 526 */ |
527UCL_EXTERN const char* ucl_object_key (ucl_object_t *obj); |
528 529/** 530 * Returns a key of an object as a fixed size string (may be more efficient) 531 * @param obj CL object 532 * @param len target key length 533 * @return key pointer 534 */ |
535UCL_EXTERN const char* ucl_object_keyl (ucl_object_t *obj, size_t *len); |
536 537/** 538 * Free ucl object 539 * @param obj ucl object to free 540 */ 541UCL_EXTERN void ucl_object_free (ucl_object_t *obj); 542 543/** 544 * Increase reference count for an object 545 * @param obj object to ref 546 */ |
547UCL_EXTERN ucl_object_t* ucl_object_ref (ucl_object_t *obj); |
548 549/** 550 * Decrease reference count for an object 551 * @param obj object to unref 552 */ |
553UCL_EXTERN void ucl_object_unref (ucl_object_t *obj); 554 |
555/** |
556 * Compare objects `o1` and `o2` 557 * @param o1 the first object 558 * @param o2 the second object 559 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`. 560 * The order of comparison: 561 * 1) Type of objects 562 * 2) Size of objects 563 * 3) Content of objects 564 */ 565UCL_EXTERN int ucl_object_compare (ucl_object_t *o1, ucl_object_t *o2); 566 567/** 568 * Sort UCL array using `cmp` compare function 569 * @param ar 570 * @param cmp 571 */ 572UCL_EXTERN void ucl_object_array_sort (ucl_object_t *ar, 573 int (*cmp)(ucl_object_t *o1, ucl_object_t *o2)); 574 575/** |
576 * Opaque iterator object 577 */ 578typedef void* ucl_object_iter_t; 579 580/** 581 * Get next key from an object 582 * @param obj object to iterate 583 * @param iter opaque iterator, must be set to NULL on the first call: --- 54 unchanged lines hidden (view full) --- 638/** 639 * Load new chunk to a parser 640 * @param parser parser structure 641 * @param data the pointer to the beginning of a chunk 642 * @param len the length of a chunk 643 * @param err if *err is NULL it is set to parser error 644 * @return true if chunk has been added and false in case of error 645 */ |
646UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser, 647 const unsigned char *data, size_t len); |
648 649/** |
650 * Load ucl object from a string 651 * @param parser parser structure 652 * @param data the pointer to the string 653 * @param len the length of the string, if `len` is 0 then `data` must be zero-terminated string 654 * @return true if string has been added and false in case of error 655 */ 656UCL_EXTERN bool ucl_parser_add_string (struct ucl_parser *parser, 657 const char *data,size_t len); 658 659/** |
660 * Load and add data from a file 661 * @param parser parser structure 662 * @param filename the name of file 663 * @param err if *err is NULL it is set to parser error 664 * @return true if chunk has been added and false in case of error 665 */ 666UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser, const char *filename); 667 --- 76 unchanged lines hidden (view full) --- 744 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is 745 * #UCL_EMIT_CONFIG then emit config like object 746 * @return dump of an object (must be freed after using) or NULL in case of error 747 */ 748UCL_EXTERN bool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type, 749 struct ucl_emitter_functions *emitter); 750/** @} */ 751 |
752/** 753 * @defgroup schema Schema functions 754 * These functions are used to validate UCL objects using json schema format 755 * 756 * @{ 757 */ 758 759/** 760 * Used to define UCL schema error 761 */ 762enum ucl_schema_error_code { 763 UCL_SCHEMA_OK = 0, /**< no error */ 764 UCL_SCHEMA_TYPE_MISMATCH, /**< type of object is incorrect */ 765 UCL_SCHEMA_INVALID_SCHEMA, /**< schema is invalid */ 766 UCL_SCHEMA_MISSING_PROPERTY,/**< one or more missing properties */ 767 UCL_SCHEMA_CONSTRAINT, /**< constraint found */ 768 UCL_SCHEMA_MISSING_DEPENDENCY, /**< missing dependency */ 769 UCL_SCHEMA_UNKNOWN /**< generic error */ 770}; 771 772/** 773 * Generic ucl schema error 774 */ 775struct ucl_schema_error { 776 enum ucl_schema_error_code code; /**< error code */ 777 char msg[128]; /**< error message */ 778 ucl_object_t *obj; /**< object where error occured */ 779}; 780 781/** 782 * Validate object `obj` using schema object `schema`. 783 * @param schema schema object 784 * @param obj object to validate 785 * @param err error pointer, if this parameter is not NULL and error has been 786 * occured, then `err` is filled with the exact error definition. 787 * @return true if `obj` is valid using `schema` 788 */ 789UCL_EXTERN bool ucl_object_validate (ucl_object_t *schema, 790 ucl_object_t *obj, struct ucl_schema_error *err); 791 792/** @} */ 793 |
794#ifdef __cplusplus 795} 796#endif 797/* 798 * XXX: Poorly named API functions, need to replace them with the appropriate 799 * named function. All API functions *must* use naming ucl_object_*. Usage of 800 * ucl_obj* should be avoided. 801 */ --- 17 unchanged lines hidden --- |