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 ---
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 ---