ucl.h (1709ccf9d38a5753192420ce5fccd93b04ce4d07) ucl.h (b04a7a0baf6523245034b8ccd06cd0176b8a18cf)
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

--- 67 unchanged lines hidden (view full) ---

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

--- 67 unchanged lines hidden (view full) ---

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

--- 111 unchanged lines hidden (view full) ---

203 *
204 * @{
205 */
206/**
207 * Copy and return a key of an object, returned key is zero-terminated
208 * @param obj CL object
209 * @return zero terminated key
210 */
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/**

--- 111 unchanged lines hidden (view full) ---

211 *
212 * @{
213 */
214/**
215 * Copy and return a key of an object, returned key is zero-terminated
216 * @param obj CL object
217 * @return zero terminated key
218 */
211UCL_EXTERN char* ucl_copy_key_trash (ucl_object_t *obj);
219UCL_EXTERN char* ucl_copy_key_trash (const ucl_object_t *obj);
212
213/**
214 * Copy and return a string value of an object, returned key is zero-terminated
215 * @param obj CL object
216 * @return zero terminated string representation of object value
217 */
220
221/**
222 * Copy and return a string value of an object, returned key is zero-terminated
223 * @param obj CL object
224 * @return zero terminated string representation of object value
225 */
218UCL_EXTERN char* ucl_copy_value_trash (ucl_object_t *obj);
226UCL_EXTERN char* ucl_copy_value_trash (const 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/**

--- 13 unchanged lines hidden (view full) ---

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 */
227
228/**
229 * Creates a new object
230 * @return new object
231 */
232UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT;
233
234/**

--- 13 unchanged lines hidden (view full) ---

248UCL_EXTERN ucl_object_t * ucl_object_fromstring_common (const char *str, size_t len,
249 enum ucl_string_flags flags) UCL_WARN_UNUSED_RESULT;
250
251/**
252 * Create a UCL object from the specified string
253 * @param str NULL terminated string, will be json escaped
254 * @return new object
255 */
248UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str);
256UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str) UCL_WARN_UNUSED_RESULT;
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 */
257
258/**
259 * Create a UCL object from the specified string
260 * @param str fixed size string, will be json escaped
261 * @param len length of a string
262 * @return new object
263 */
256UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str, size_t len);
264UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str,
265 size_t len) UCL_WARN_UNUSED_RESULT;
257
258/**
259 * Create an object from an integer number
260 * @param iv number
261 * @return new object
262 */
266
267/**
268 * Create an object from an integer number
269 * @param iv number
270 * @return new object
271 */
263UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv);
272UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv) UCL_WARN_UNUSED_RESULT;
264
265/**
266 * Create an object from a float number
267 * @param dv number
268 * @return new object
269 */
273
274/**
275 * Create an object from a float number
276 * @param dv number
277 * @return new object
278 */
270UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv);
279UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv) UCL_WARN_UNUSED_RESULT;
271
272/**
273 * Create an object from a boolean
274 * @param bv bool value
275 * @return new object
276 */
280
281/**
282 * Create an object from a boolean
283 * @param bv bool value
284 * @return new object
285 */
277UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv);
286UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv) UCL_WARN_UNUSED_RESULT;
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
287
288/**
289 * Insert a object 'elt' to the hash 'top' and associate it with key 'key'
290 * @param top destination object (will be created automatically if top is NULL)
291 * @param elt element to insert (must NOT be NULL)
292 * @param key key to associate with this object (either const or preallocated)
293 * @param keylen length of the key (or 0 for NULL terminated keys)
294 * @param copy_key make an internal copy of key
286 * @return new value of top object
295 * @return true if key has been inserted
287 */
296 */
288UCL_EXTERN ucl_object_t* ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt,
289 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT;
297UCL_EXTERN bool ucl_object_insert_key (ucl_object_t *top, ucl_object_t *elt,
298 const char *key, size_t keylen, bool copy_key);
290
291/**
292 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
293 * if no object has been found this function works like ucl_object_insert_key()
294 * @param top destination object (will be created automatically if top is NULL)
295 * @param elt element to insert (must NOT be NULL)
296 * @param key key to associate with this object (either const or preallocated)
297 * @param keylen length of the key (or 0 for NULL terminated keys)
298 * @param copy_key make an internal copy of key
299
300/**
301 * Replace a object 'elt' to the hash 'top' and associate it with key 'key', old object will be unrefed,
302 * if no object has been found this function works like ucl_object_insert_key()
303 * @param top destination object (will be created automatically if top is NULL)
304 * @param elt element to insert (must NOT be NULL)
305 * @param key key to associate with this object (either const or preallocated)
306 * @param keylen length of the key (or 0 for NULL terminated keys)
307 * @param copy_key make an internal copy of key
299 * @return new value of top object
308 * @return true if key has been inserted
300 */
309 */
301UCL_EXTERN ucl_object_t* ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt,
302 const char *key, size_t keylen, bool copy_key) UCL_WARN_UNUSED_RESULT;
310UCL_EXTERN bool ucl_object_replace_key (ucl_object_t *top, ucl_object_t *elt,
311 const char *key, size_t keylen, bool copy_key);
303
304/**
305 * Delete a object associated with key 'key', old object will be unrefered,
306 * @param top object
307 * @param key key associated to the object to remove
308 * @param keylen length of the key (or 0 for NULL terminated keys)
309 */
312
313/**
314 * Delete a object associated with key 'key', old object will be unrefered,
315 * @param top object
316 * @param key key associated to the object to remove
317 * @param keylen length of the key (or 0 for NULL terminated keys)
318 */
310UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top, const char *key, size_t keylen);
319UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top,
320 const char *key, size_t keylen);
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 */
321
322/**
323 * Delete a object associated with key 'key', old object will be unrefered,
324 * @param top object
325 * @param key key associated to the object to remove
326 */
317UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top, const char *key);
327UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top,
328 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)

--- 15 unchanged lines hidden (view full) ---

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
329
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 * @param keylen length of the key (or 0 for NULL terminated keys)

--- 15 unchanged lines hidden (view full) ---

352/**
353 * Insert a object 'elt' to the hash 'top' and associate it with key 'key', if the specified key exist,
354 * try to merge its content
355 * @param top destination object (will be created automatically if top is NULL)
356 * @param elt element to insert (must NOT be NULL)
357 * @param key key to associate with this object (either const or preallocated)
358 * @param keylen length of the key (or 0 for NULL terminated keys)
359 * @param copy_key make an internal copy of key
349 * @return new value of top object
360 * @return true if key has been inserted
350 */
361 */
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;
362UCL_EXTERN bool ucl_object_insert_key_merged (ucl_object_t *top, ucl_object_t *elt,
363 const char *key, size_t keylen, bool copy_key);
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)
364
365/**
366 * Append an element to the front of array object
367 * @param top destination object (will be created automatically if top is NULL)
368 * @param elt element to append (must NOT be NULL)
358 * @return new value of top object
369 * @return true if value has been inserted
359 */
370 */
360UCL_EXTERN ucl_object_t* ucl_array_append (ucl_object_t *top,
361 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT;
371UCL_EXTERN bool ucl_array_append (ucl_object_t *top,
372 ucl_object_t *elt);
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)
373
374/**
375 * Append an element to the start of array object
376 * @param top destination object (will be created automatically if top is NULL)
377 * @param elt element to append (must NOT be NULL)
367 * @return new value of top object
378 * @return true if value has been inserted
368 */
379 */
369UCL_EXTERN ucl_object_t* ucl_array_prepend (ucl_object_t *top,
370 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT;
380UCL_EXTERN bool ucl_array_prepend (ucl_object_t *top,
381 ucl_object_t *elt);
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 */
382
383/**
384 * Removes an element `elt` from the array `top`. Caller must unref the returned object when it is not
385 * needed.
386 * @param top array ucl object
387 * @param elt element to remove
388 * @return removed element or NULL if `top` is NULL or not an array
389 */
379UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top, ucl_object_t *elt);
390UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top,
391 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 */
392
393/**
394 * Returns the first element of the array `top`
395 * @param top array ucl object
396 * @return element or NULL if `top` is NULL or not an array
397 */
386UCL_EXTERN ucl_object_t* ucl_array_head (ucl_object_t *top);
398UCL_EXTERN const ucl_object_t* ucl_array_head (const 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 */
399
400/**
401 * Returns the last element of the array `top`
402 * @param top array ucl object
403 * @return element or NULL if `top` is NULL or not an array
404 */
393UCL_EXTERN ucl_object_t* ucl_array_tail (ucl_object_t *top);
405UCL_EXTERN const ucl_object_t* ucl_array_tail (const 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);

--- 5 unchanged lines hidden (view full) ---

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
406
407/**
408 * Removes the last element from the array `top`. Caller must unref the returned object when it is not
409 * needed.
410 * @param top array ucl object
411 * @return removed element or NULL if `top` is NULL or not an array
412 */
413UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top);

--- 5 unchanged lines hidden (view full) ---

419 * @return removed element or NULL if `top` is NULL or not an array
420 */
421UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top);
422
423/**
424 * Append a element to another element forming an implicit array
425 * @param head head to append (may be NULL)
426 * @param elt new element
415 * @return new head if applicable
427 * @return true if element has been inserted
416 */
428 */
417UCL_EXTERN ucl_object_t* ucl_elt_append (ucl_object_t *head,
418 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT;
429UCL_EXTERN ucl_object_t * ucl_elt_append (ucl_object_t *head,
430 ucl_object_t *elt);
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 */
431
432/**
433 * Converts an object to double value
434 * @param obj CL object
435 * @param target target double variable
436 * @return true if conversion was successful
437 */
426UCL_EXTERN bool ucl_object_todouble_safe (ucl_object_t *obj, double *target);
438UCL_EXTERN bool ucl_object_todouble_safe (const 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 */
439
440/**
441 * Unsafe version of \ref ucl_obj_todouble_safe
442 * @param obj CL object
443 * @return double value
444 */
433UCL_EXTERN double ucl_object_todouble (ucl_object_t *obj);
445UCL_EXTERN double ucl_object_todouble (const 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 */
446
447/**
448 * Converts an object to integer value
449 * @param obj CL object
450 * @param target target integer variable
451 * @return true if conversion was successful
452 */
441UCL_EXTERN bool ucl_object_toint_safe (ucl_object_t *obj, int64_t *target);
453UCL_EXTERN bool ucl_object_toint_safe (const 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 */
454
455/**
456 * Unsafe version of \ref ucl_obj_toint_safe
457 * @param obj CL object
458 * @return int value
459 */
448UCL_EXTERN int64_t ucl_object_toint (ucl_object_t *obj);
460UCL_EXTERN int64_t ucl_object_toint (const 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 */
461
462/**
463 * Converts an object to boolean value
464 * @param obj CL object
465 * @param target target boolean variable
466 * @return true if conversion was successful
467 */
456UCL_EXTERN bool ucl_object_toboolean_safe (ucl_object_t *obj, bool *target);
468UCL_EXTERN bool ucl_object_toboolean_safe (const 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 */
469
470/**
471 * Unsafe version of \ref ucl_obj_toboolean_safe
472 * @param obj CL object
473 * @return boolean value
474 */
463UCL_EXTERN bool ucl_object_toboolean (ucl_object_t *obj);
475UCL_EXTERN bool ucl_object_toboolean (const 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 */
476
477/**
478 * Converts an object to string value
479 * @param obj CL object
480 * @param target target string variable, no need to free value
481 * @return true if conversion was successful
482 */
471UCL_EXTERN bool ucl_object_tostring_safe (ucl_object_t *obj, const char **target);
483UCL_EXTERN bool ucl_object_tostring_safe (const 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 */
484
485/**
486 * Unsafe version of \ref ucl_obj_tostring_safe
487 * @param obj CL object
488 * @return string value
489 */
478UCL_EXTERN const char* ucl_object_tostring (ucl_object_t *obj);
490UCL_EXTERN const char* ucl_object_tostring (const 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 */
491
492/**
493 * Convert any object to a string in JSON notation if needed
494 * @param obj CL object
495 * @return string value
496 */
485UCL_EXTERN const char* ucl_object_tostring_forced (ucl_object_t *obj);
497UCL_EXTERN const char* ucl_object_tostring_forced (const 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 */
498
499/**
500 * Return string as char * and len, string may be not zero terminated, more efficient that \ref ucl_obj_tostring as it
501 * allows zero-copy (if #UCL_PARSER_ZEROCOPY has been used during parsing)
502 * @param obj CL object
503 * @param target target string variable, no need to free value
504 * @param tlen target length
505 * @return true if conversion was successful
506 */
495UCL_EXTERN bool ucl_object_tolstring_safe (ucl_object_t *obj,
507UCL_EXTERN bool ucl_object_tolstring_safe (const 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 */
508 const char **target, size_t *tlen);
509
510/**
511 * Unsafe version of \ref ucl_obj_tolstring_safe
512 * @param obj CL object
513 * @return string value
514 */
503UCL_EXTERN const char* ucl_object_tolstring (ucl_object_t *obj, size_t *tlen);
515UCL_EXTERN const char* ucl_object_tolstring (const 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 */
516
517/**
518 * Return object identified by a key in the specified object
519 * @param obj object to get a key from (must be of type UCL_OBJECT)
520 * @param key key to search
521 * @return object matched the specified key or NULL if key is not found
522 */
511UCL_EXTERN ucl_object_t* ucl_object_find_key (ucl_object_t *obj, const char *key);
523UCL_EXTERN const ucl_object_t* ucl_object_find_key (const ucl_object_t *obj,
524 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 */
525
526/**
527 * Return object identified by a fixed size key in the specified object
528 * @param obj object to get a key from (must be of type UCL_OBJECT)
529 * @param key key to search
530 * @param klen length of a key
531 * @return object matched the specified key or NULL if key is not found
532 */
520UCL_EXTERN ucl_object_t* ucl_object_find_keyl (ucl_object_t *obj, const char *key, size_t klen);
533UCL_EXTERN const ucl_object_t* ucl_object_find_keyl (const ucl_object_t *obj,
534 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 */
535
536/**
537 * Returns a key of an object as a NULL terminated string
538 * @param obj CL object
539 * @return key or NULL if there is no key
540 */
527UCL_EXTERN const char* ucl_object_key (ucl_object_t *obj);
541UCL_EXTERN const char* ucl_object_key (const 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 */
542
543/**
544 * Returns a key of an object as a fixed size string (may be more efficient)
545 * @param obj CL object
546 * @param len target key length
547 * @return key pointer
548 */
535UCL_EXTERN const char* ucl_object_keyl (ucl_object_t *obj, size_t *len);
549UCL_EXTERN const char* ucl_object_keyl (const ucl_object_t *obj, size_t *len);
536
537/**
550
551/**
538 * Free ucl object
539 * @param obj ucl object to free
552 * Increase reference count for an object
553 * @param obj object to ref
540 */
554 */
541UCL_EXTERN void ucl_object_free (ucl_object_t *obj);
555UCL_EXTERN ucl_object_t* ucl_object_ref (const ucl_object_t *obj);
542
543/**
556
557/**
544 * Increase reference count for an object
545 * @param obj object to ref
558 * Free ucl object
559 * @param obj ucl object to free
546 */
560 */
547UCL_EXTERN ucl_object_t* ucl_object_ref (ucl_object_t *obj);
561UCL_DEPRECATED(UCL_EXTERN void ucl_object_free (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 */
562
563/**
564 * Decrease reference count for an object
565 * @param obj object to unref
566 */
567UCL_EXTERN void ucl_object_unref (ucl_object_t *obj);
568
569/**
570 * Compare objects `o1` and `o2`
571 * @param o1 the first object
572 * @param o2 the second object
573 * @return values >0, 0 and <0 if `o1` is more than, equal and less than `o2`.
574 * The order of comparison:
575 * 1) Type of objects
576 * 2) Size of objects
577 * 3) Content of objects
578 */
565UCL_EXTERN int ucl_object_compare (ucl_object_t *o1, ucl_object_t *o2);
579UCL_EXTERN int ucl_object_compare (const ucl_object_t *o1,
580 const 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,
581
582/**
583 * Sort UCL array using `cmp` compare function
584 * @param ar
585 * @param cmp
586 */
587UCL_EXTERN void ucl_object_array_sort (ucl_object_t *ar,
573 int (*cmp)(ucl_object_t *o1, ucl_object_t *o2));
588 int (*cmp)(const ucl_object_t *o1, const 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:
584 * ucl_object_iter_t it = NULL;
585 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
586 * @return the next object or NULL
587 */
589
590/**
591 * Opaque iterator object
592 */
593typedef void* ucl_object_iter_t;
594
595/**
596 * Get next key from an object
597 * @param obj object to iterate
598 * @param iter opaque iterator, must be set to NULL on the first call:
599 * ucl_object_iter_t it = NULL;
600 * while ((cur = ucl_iterate_object (obj, &it)) != NULL) ...
601 * @return the next object or NULL
602 */
588UCL_EXTERN ucl_object_t* ucl_iterate_object (ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values);
603UCL_EXTERN const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj,
604 ucl_object_iter_t *iter, bool expand_values);
589/** @} */
590
591
592/**
593 * @defgroup parser Parsing functions
594 * These functions are used to parse UCL objects
595 *
596 * @{

--- 61 unchanged lines hidden (view full) ---

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 */
605/** @} */
606
607
608/**
609 * @defgroup parser Parsing functions
610 * These functions are used to parse UCL objects
611 *
612 * @{

--- 61 unchanged lines hidden (view full) ---

674
675/**
676 * Load and add data from a file
677 * @param parser parser structure
678 * @param filename the name of file
679 * @param err if *err is NULL it is set to parser error
680 * @return true if chunk has been added and false in case of error
681 */
666UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser, const char *filename);
682UCL_EXTERN bool ucl_parser_add_file (struct ucl_parser *parser,
683 const char *filename);
667
668/**
684
685/**
669 * Get a top object for a parser
686 * Load and add data from a file descriptor
670 * @param parser parser structure
687 * @param parser parser structure
688 * @param filename the name of file
671 * @param err if *err is NULL it is set to parser error
689 * @param err if *err is NULL it is set to parser error
690 * @return true if chunk has been added and false in case of error
691 */
692UCL_EXTERN bool ucl_parser_add_fd (struct ucl_parser *parser,
693 int fd);
694
695/**
696 * Get a top object for a parser (refcount is increased)
697 * @param parser parser structure
698 * @param err if *err is NULL it is set to parser error
672 * @return top parser object or NULL
673 */
674UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);
675
676/**
677 * Get the error string if failing
678 * @param parser parser object
679 */

--- 51 unchanged lines hidden (view full) ---

731
732/**
733 * Emit object to a string
734 * @param obj object
735 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
736 * #UCL_EMIT_CONFIG then emit config like object
737 * @return dump of an object (must be freed after using) or NULL in case of error
738 */
699 * @return top parser object or NULL
700 */
701UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser);
702
703/**
704 * Get the error string if failing
705 * @param parser parser object
706 */

--- 51 unchanged lines hidden (view full) ---

758
759/**
760 * Emit object to a string
761 * @param obj object
762 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
763 * #UCL_EMIT_CONFIG then emit config like object
764 * @return dump of an object (must be freed after using) or NULL in case of error
765 */
739UCL_EXTERN unsigned char *ucl_object_emit (ucl_object_t *obj, enum ucl_emitter emit_type);
766UCL_EXTERN unsigned char *ucl_object_emit (const ucl_object_t *obj,
767 enum ucl_emitter emit_type);
740
741/**
742 * Emit object to a string
743 * @param obj object
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 */
768
769/**
770 * Emit object to a string
771 * @param obj object
772 * @param emit_type if type is #UCL_EMIT_JSON then emit json, if type is
773 * #UCL_EMIT_CONFIG then emit config like object
774 * @return dump of an object (must be freed after using) or NULL in case of error
775 */
748UCL_EXTERN bool ucl_object_emit_full (ucl_object_t *obj, enum ucl_emitter emit_type,
776UCL_EXTERN bool ucl_object_emit_full (const ucl_object_t *obj,
777 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 * @{

--- 13 unchanged lines hidden (view full) ---

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 struct ucl_emitter_functions *emitter);
779/** @} */
780
781/**
782 * @defgroup schema Schema functions
783 * These functions are used to validate UCL objects using json schema format
784 *
785 * @{

--- 13 unchanged lines hidden (view full) ---

799};
800
801/**
802 * Generic ucl schema error
803 */
804struct ucl_schema_error {
805 enum ucl_schema_error_code code; /**< error code */
806 char msg[128]; /**< error message */
778 ucl_object_t *obj; /**< object where error occured */
807 const 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 */
808};
809
810/**
811 * Validate object `obj` using schema object `schema`.
812 * @param schema schema object
813 * @param obj object to validate
814 * @param err error pointer, if this parameter is not NULL and error has been
815 * occured, then `err` is filled with the exact error definition.
816 * @return true if `obj` is valid using `schema`
817 */
789UCL_EXTERN bool ucl_object_validate (ucl_object_t *schema,
790 ucl_object_t *obj, struct ucl_schema_error *err);
818UCL_EXTERN bool ucl_object_validate (const ucl_object_t *schema,
819 const 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

--- 20 unchanged lines hidden --- 		820
821/** @} */
822
823#ifdef __cplusplus
824}
825#endif
826/*
827 * XXX: Poorly named API functions, need to replace them with the appropriate

--- 20 unchanged lines hidden ---