Deleted Added
full compact
ucl.h (262975) ucl.h (263648)
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 */
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 */
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 */
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 */
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 */
153 UCL_STRING_PARSE_NUMBER = UCL_STRING_PARSE_INT|UCL_STRING_PARSE_DOUBLE , /**<
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, /**<
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) */
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) */
157 UCL_STRING_PARSE_BYTES = 0x20 /**< Treat numbers as bytes */
159 UCL_STRING_PARSE_BYTES = 0x40 /**< 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 */
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 */
168 UCL_OBJECT_NEED_KEY_ESCAPE = 4 /**< The key of an object need to be escaped on output */
169} ucl_object_flags_t;
170
171/**
172 * UCL object structure. Please mention that the most of fields should not be touched by
173 * UCL users. In future, this structure may be converted to private one.
174 */
175typedef struct ucl_object_s {
176 /**
177 * Variant value type
178 */
179 union {
180 int64_t iv; /**< Int value of an object */
181 const char *sv; /**< String value of an object */
182 double dv; /**< Double value of an object */
183 struct ucl_object_s *av; /**< Array */
184 void *ov; /**< Object */
185 void* ud; /**< Opaque user data */
186 } value;
187 const char *key; /**< Key of an object */
188 struct ucl_object_s *next; /**< Array handle */
189 struct ucl_object_s *prev; /**< Array handle */
190 unsigned char* trash_stack[2]; /**< Pointer to allocated chunks */
191 unsigned keylen; /**< Lenght of a key */
192 unsigned len; /**< Size of an object */
193 enum ucl_type type; /**< Real type */
194 uint16_t ref; /**< Reference count */
195 uint16_t flags; /**< Object flags */
196} ucl_object_t;
197
198/** @} */
199
200/**
201 * @defgroup utils Utility functions
202 * A number of utility functions simplify handling of UCL objects
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 */
211UCL_EXTERN char* ucl_copy_key_trash (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 */
218UCL_EXTERN char* ucl_copy_value_trash (ucl_object_t *obj);
219
220/**
221 * Creates a new object
222 * @return new object
223 */
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}
224UCL_EXTERN ucl_object_t* ucl_object_new (void) UCL_WARN_UNUSED_RESULT;
235
236/**
237 * Create new object with type specified
238 * @param type type of a new object
239 * @return new object
240 */
225
226/**
227 * Create new object with type specified
228 * @param type type of a new object
229 * @return new object
230 */
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}
231UCL_EXTERN ucl_object_t* ucl_object_typed_new (unsigned int type) UCL_WARN_UNUSED_RESULT;
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 */
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 */
270static inline ucl_object_t *
271ucl_object_fromstring (const char *str)
272{
273 return ucl_object_fromstring_common (str, 0, UCL_STRING_ESCAPE);
274}
248UCL_EXTERN ucl_object_t *ucl_object_fromstring (const char *str);
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 */
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 */
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}
256UCL_EXTERN ucl_object_t *ucl_object_fromlstring (const char *str, size_t len);
287
288/**
289 * Create an object from an integer number
290 * @param iv number
291 * @return new object
292 */
257
258/**
259 * Create an object from an integer number
260 * @param iv number
261 * @return new object
262 */
293static inline ucl_object_t *
294ucl_object_fromint (int64_t iv)
295{
296 ucl_object_t *obj;
263UCL_EXTERN ucl_object_t* ucl_object_fromint (int64_t iv);
297
264
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 */
265/**
266 * Create an object from a float number
267 * @param dv number
268 * @return new object
269 */
312static inline ucl_object_t *
313ucl_object_fromdouble (double dv)
314{
315 ucl_object_t *obj;
270UCL_EXTERN ucl_object_t* ucl_object_fromdouble (double dv);
316
271
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 */
272/**
273 * Create an object from a boolean
274 * @param bv bool value
275 * @return new object
276 */
331static inline ucl_object_t *
332ucl_object_frombool (bool bv)
333{
334 ucl_object_t *obj;
277UCL_EXTERN ucl_object_t* ucl_object_frombool (bool bv);
335
278
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
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
287 */
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;
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 * @return new value of top object
300 */
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;
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 */
310UCL_EXTERN bool ucl_object_delete_keyl (ucl_object_t *top, 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 */
317UCL_EXTERN bool ucl_object_delete_key (ucl_object_t *top, const char *key);
318
319
385/**
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/**
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 */
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 */
404static inline ucl_object_t * ucl_array_append (ucl_object_t *top,
360UCL_EXTERN ucl_object_t* ucl_array_append (ucl_object_t *top,
405 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT;
361 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
362
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 */
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 */
446static inline ucl_object_t * ucl_array_prepend (ucl_object_t *top,
369UCL_EXTERN ucl_object_t* ucl_array_prepend (ucl_object_t *top,
447 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT;
370 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
371
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 */
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 */
489static inline ucl_object_t *
490ucl_array_delete (ucl_object_t *top, ucl_object_t *elt)
491{
492 ucl_object_t *head;
379UCL_EXTERN ucl_object_t* ucl_array_delete (ucl_object_t *top, ucl_object_t *elt);
493
380
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 */
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 */
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}
386UCL_EXTERN ucl_object_t* ucl_array_head (ucl_object_t *top);
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 */
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 */
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}
393UCL_EXTERN ucl_object_t* ucl_array_tail (ucl_object_t *top);
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 */
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 */
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}
401UCL_EXTERN ucl_object_t* ucl_array_pop_last (ucl_object_t *top);
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 */
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 */
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}
409UCL_EXTERN ucl_object_t* ucl_array_pop_first (ucl_object_t *top);
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 */
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 */
580static inline ucl_object_t * ucl_elt_append (ucl_object_t *head,
417UCL_EXTERN ucl_object_t* ucl_elt_append (ucl_object_t *head,
581 ucl_object_t *elt) UCL_WARN_UNUSED_RESULT;
418 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
419
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 */
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 */
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 }
426UCL_EXTERN bool ucl_object_todouble_safe (ucl_object_t *obj, double *target);
624
427
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 */
428/**
429 * Unsafe version of \ref ucl_obj_todouble_safe
430 * @param obj CL object
431 * @return double value
432 */
633static inline double
634ucl_object_todouble (ucl_object_t *obj)
635{
636 double result = 0.;
433UCL_EXTERN double ucl_object_todouble (ucl_object_t *obj);
637
434
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 */
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 */
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 }
441UCL_EXTERN bool ucl_object_toint_safe (ucl_object_t *obj, int64_t *target);
665
442
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 */
443/**
444 * Unsafe version of \ref ucl_obj_toint_safe
445 * @param obj CL object
446 * @return int value
447 */
674static inline int64_t
675ucl_object_toint (ucl_object_t *obj)
676{
677 int64_t result = 0;
448UCL_EXTERN int64_t ucl_object_toint (ucl_object_t *obj);
678
449
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 */
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 */
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 }
456UCL_EXTERN bool ucl_object_toboolean_safe (ucl_object_t *obj, bool *target);
702
457
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 */
458/**
459 * Unsafe version of \ref ucl_obj_toboolean_safe
460 * @param obj CL object
461 * @return boolean value
462 */
711static inline bool
712ucl_object_toboolean (ucl_object_t *obj)
713{
714 bool result = false;
463UCL_EXTERN bool ucl_object_toboolean (ucl_object_t *obj);
715
464
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 */
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 */
726static inline bool
727ucl_object_tostring_safe (ucl_object_t *obj, const char **target)
728{
729 if (obj == NULL) {
730 return false;
731 }
471UCL_EXTERN bool ucl_object_tostring_safe (ucl_object_t *obj, const char **target);
732
472
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 */
473/**
474 * Unsafe version of \ref ucl_obj_tostring_safe
475 * @param obj CL object
476 * @return string value
477 */
749static inline const char *
750ucl_object_tostring (ucl_object_t *obj)
751{
752 const char *result = NULL;
478UCL_EXTERN const char* ucl_object_tostring (ucl_object_t *obj);
753
479
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 */
480/**
481 * Convert any object to a string in JSON notation if needed
482 * @param obj CL object
483 * @return string value
484 */
763static inline const char *
764ucl_object_tostring_forced (ucl_object_t *obj)
765{
766 return ucl_copy_value_trash (obj);
767}
485UCL_EXTERN const char* ucl_object_tostring_forced (ucl_object_t *obj);
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 */
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 */
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 }
495UCL_EXTERN bool ucl_object_tolstring_safe (ucl_object_t *obj,
496 const char **target, size_t *tlen);
791
497
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 */
498/**
499 * Unsafe version of \ref ucl_obj_tolstring_safe
500 * @param obj CL object
501 * @return string value
502 */
800static inline const char *
801ucl_object_tolstring (ucl_object_t *obj, size_t *tlen)
802{
803 const char *result = NULL;
503UCL_EXTERN const char* ucl_object_tolstring (ucl_object_t *obj, size_t *tlen);
804
504
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 */
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 */
815UCL_EXTERN ucl_object_t * ucl_object_find_key (ucl_object_t *obj, const char *key);
511UCL_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 */
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 */
824UCL_EXTERN ucl_object_t *ucl_object_find_keyl (ucl_object_t *obj, const char *key, size_t klen);
520UCL_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 */
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 */
831static inline const char *
832ucl_object_key (ucl_object_t *obj)
833{
834 return ucl_copy_key_trash (obj);
835}
527UCL_EXTERN const char* ucl_object_key (ucl_object_t *obj);
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 */
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 */
843static inline const char *
844ucl_object_keyl (ucl_object_t *obj, size_t *len)
845{
846 *len = obj->keylen;
847 return obj->key;
848}
535UCL_EXTERN const char* ucl_object_keyl (ucl_object_t *obj, size_t *len);
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 */
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 */
860static inline ucl_object_t *
861ucl_object_ref (ucl_object_t *obj) {
862 obj->ref ++;
863 return obj;
864}
547UCL_EXTERN ucl_object_t* ucl_object_ref (ucl_object_t *obj);
865
866/**
867 * Decrease reference count for an object
868 * @param obj object to unref
869 */
548
549/**
550 * Decrease reference count for an object
551 * @param obj object to unref
552 */
870static inline void
871ucl_object_unref (ucl_object_t *obj) {
872 if (obj != NULL && --obj->ref <= 0) {
873 ucl_object_free (obj);
874 }
875}
553UCL_EXTERN void ucl_object_unref (ucl_object_t *obj);
554
876/**
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/**
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 */
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 */
588UCL_EXTERN ucl_object_t* ucl_iterate_object (ucl_object_t *obj, 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 * @{
597 */
598
599/**
600 * Macro handler for a parser
601 * @param data the content of macro
602 * @param len the length of content
603 * @param ud opaque user data
604 * @param err error pointer
605 * @return true if macro has been parsed
606 */
607typedef bool (*ucl_macro_handler) (const unsigned char *data, size_t len, void* ud);
608
609/* Opaque parser */
610struct ucl_parser;
611
612/**
613 * Creates new parser object
614 * @param pool pool to allocate memory from
615 * @return new parser object
616 */
617UCL_EXTERN struct ucl_parser* ucl_parser_new (int flags);
618
619/**
620 * Register new handler for a macro
621 * @param parser parser object
622 * @param macro macro name (without leading dot)
623 * @param handler handler (it is called immediately after macro is parsed)
624 * @param ud opaque user data for a handler
625 */
626UCL_EXTERN void ucl_parser_register_macro (struct ucl_parser *parser, const char *macro,
627 ucl_macro_handler handler, void* ud);
628
629/**
630 * Register new parser variable
631 * @param parser parser object
632 * @param var variable name
633 * @param value variable value
634 */
635UCL_EXTERN void ucl_parser_register_variable (struct ucl_parser *parser, const char *var,
636 const char *value);
637
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 */
947UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser, const unsigned char *data, size_t len);
646UCL_EXTERN bool ucl_parser_add_chunk (struct ucl_parser *parser,
647 const unsigned char *data, size_t len);
948
949/**
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/**
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
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
668/**
669 * Get a top object for a parser
670 * @param parser parser structure
671 * @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 */
680UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser);
681/**
682 * Free ucl parser object
683 * @param parser parser object
684 */
685UCL_EXTERN void ucl_parser_free (struct ucl_parser *parser);
686
687/**
688 * Add new public key to parser for signatures check
689 * @param parser parser object
690 * @param key PEM representation of a key
691 * @param len length of the key
692 * @param err if *err is NULL it is set to parser error
693 * @return true if a key has been successfully added
694 */
695UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len);
696
697/**
698 * Set FILENAME and CURDIR variables in parser
699 * @param parser parser object
700 * @param filename filename to set or NULL to set FILENAME to "undef" and CURDIR to getcwd()
701 * @param need_expand perform realpath() if this variable is true and filename is not NULL
702 * @return true if variables has been set
703 */
704UCL_EXTERN bool ucl_parser_set_filevars (struct ucl_parser *parser, const char *filename,
705 bool need_expand);
706
707/** @} */
708
709/**
710 * @defgroup emitter Emitting functions
711 * These functions are used to serialise UCL objects to some string representation.
712 *
713 * @{
714 */
715
716/**
717 * Structure using for emitter callbacks
718 */
719struct ucl_emitter_functions {
720 /** Append a single character */
721 int (*ucl_emitter_append_character) (unsigned char c, size_t nchars, void *ud);
722 /** Append a string of a specified length */
723 int (*ucl_emitter_append_len) (unsigned const char *str, size_t len, void *ud);
724 /** Append a 64 bit integer */
725 int (*ucl_emitter_append_int) (int64_t elt, void *ud);
726 /** Append floating point element */
727 int (*ucl_emitter_append_double) (double elt, void *ud);
728 /** Opaque userdata pointer */
729 void *ud;
730};
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 */
739UCL_EXTERN unsigned char *ucl_object_emit (ucl_object_t *obj, 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 */
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
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_ */
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 */
802#define ucl_obj_todouble_safe ucl_object_todouble_safe
803#define ucl_obj_todouble ucl_object_todouble
804#define ucl_obj_tostring ucl_object_tostring
805#define ucl_obj_tostring_safe ucl_object_tostring_safe
806#define ucl_obj_tolstring ucl_object_tolstring
807#define ucl_obj_tolstring_safe ucl_object_tolstring_safe
808#define ucl_obj_toint ucl_object_toint
809#define ucl_obj_toint_safe ucl_object_toint_safe
810#define ucl_obj_toboolean ucl_object_toboolean
811#define ucl_obj_toboolean_safe ucl_object_toboolean_safe
812#define ucl_obj_get_key ucl_object_find_key
813#define ucl_obj_get_keyl ucl_object_find_keyl
814#define ucl_obj_unref ucl_object_unref
815#define ucl_obj_ref ucl_object_ref
816#define ucl_obj_free ucl_object_free
817
818#endif /* UCL_H_ */