1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2024 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * @file properties.h
30 * @brief Interface for parsing data from properties files.
31 * @author Mike Becker
32 * @author Olaf Wintermann
33 * @copyright 2-Clause BSD License
34 */
35
36 #ifndef UCX_PROPERTIES_H
37 #define UCX_PROPERTIES_H
38
39 #include "common.h"
40 #include "string.h"
41 #include "map.h"
42 #include "buffer.h"
43
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47
48 /**
49 * Configures the expected characters for the properties parser.
50 */
51 struct cx_properties_config_s {
52 /**
53 * The key/value delimiter that shall be used.
54 * This is '=' by default.
55 */
56 char delimiter;
57
58 /**
59 * The first comment character.
60 * This is '#' by default.
61 */
62 char comment1;
63
64 /**
65 * The second comment character.
66 * This is not set by default.
67 */
68 char comment2;
69
70 /**
71 * The third comment character.
72 * This is not set by default.
73 */
74 char comment3;
75
76 /*
77 * The character, when appearing at the end of a line, continues that line.
78 * This is '\' by default.
79 */
80 char continuation;
81 };
82
83 /**
84 * Typedef for the properties config.
85 */
86 typedef struct cx_properties_config_s CxPropertiesConfig;
87
88 /**
89 * Default properties configuration.
90 */
91 CX_EXPORT extern const CxPropertiesConfig cx_properties_config_default;
92
93 /**
94 * Status codes for the properties interface.
95 */
96 enum cx_properties_status {
97 /**
98 * Everything is fine.
99 */
100 CX_PROPERTIES_NO_ERROR,
101 /**
102 * The input buffer does not contain more data.
103 */
104 CX_PROPERTIES_NO_DATA,
105 /**
106 * The input ends unexpectedly.
107 *
108 * This either happens when the last line does not terminate with a line
109 * break, or when the input ends with a parsed key but no value.
110 */
111 CX_PROPERTIES_INCOMPLETE_DATA,
112 /**
113 * Not used as a status and never returned by any function.
114 *
115 * You can use this enumerator to check for all "good" status results
116 * by checking if the status is less than @c CX_PROPERTIES_OK.
117 *
118 * A "good" status means that you can refill data and continue parsing.
119 */
120 CX_PROPERTIES_OK,
121 /**
122 * Input buffer is @c NULL.
123 */
124 CX_PROPERTIES_NULL_INPUT,
125 /**
126 * The line contains a delimiter but no key.
127 */
128 CX_PROPERTIES_INVALID_EMPTY_KEY,
129 /**
130 * The line contains data but no delimiter.
131 */
132 CX_PROPERTIES_INVALID_MISSING_DELIMITER,
133 /**
134 * More internal buffer was needed, but could not be allocated.
135 */
136 CX_PROPERTIES_BUFFER_ALLOC_FAILED,
137 /**
138 * A file operation failed.
139 * Only for cxPropertiesLoad().
140 * It is system-specific if errno is set.
141 */
142 CX_PROPERTIES_FILE_ERROR,
143 /**
144 * A map operation failed.
145 * Only for cxPropertiesLoad().
146 */
147 CX_PROPERTIES_MAP_ERROR,
148 };
149
150 /**
151 * Typedef for the properties status enum.
152 */
153 typedef enum cx_properties_status CxPropertiesStatus;
154
155 /**
156 * Interface for working with properties data.
157 */
158 struct cx_properties_s {
159 /**
160 * The configuration.
161 */
162 CxPropertiesConfig config;
163
164 /**
165 * The text input buffer.
166 */
167 CxBuffer input;
168
169 /**
170 * Internal buffer.
171 */
172 CxBuffer buffer;
173 };
174
175 /**
176 * Typedef for the properties interface.
177 */
178 typedef struct cx_properties_s CxProperties;
179
180 /**
181 * Initialize a properties interface.
182 *
183 * @param prop the properties interface
184 * @param config the properties configuration
185 * @see cxPropertiesInitDefault()
186 */
187 cx_attr_nonnull
188 CX_EXPORT void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);
189
190 /**
191 * Destroys the properties interface.
192 *
193 * @note Even when you are certain that you did not use the interface in a
194 * way that caused a memory allocation, you should call this function anyway.
195 * Future versions of the library might add features that need additional memory,
196 * and you really don't want to search the entire code where you might need to
197 * add a call to this function.
198 *
199 * @param prop the properties interface
200 */
201 cx_attr_nonnull
202 CX_EXPORT void cxPropertiesDestroy(CxProperties *prop);
203
204 /**
205 * Destroys and re-initializes the properties interface.
206 *
207 * You might want to use this to reset the parser after
208 * encountering a syntax error.
209 *
210 * @param prop the properties interface
211 */
212 cx_attr_nonnull
213 CX_EXPORT void cxPropertiesReset(CxProperties *prop);
214
215 /**
216 * Initialize a properties parser with the default configuration.
217 *
218 * @param prop (@c CxProperties*) the properties interface
219 * @see cxPropertiesInit()
220 */
221 #define cxPropertiesInitDefault(prop) \
222 cxPropertiesInit(prop, cx_properties_config_default)
223
224 /**
225 * Fills the input buffer with data.
226 *
227 * After calling this function, you can parse the data by calling
228 * cxPropertiesNext().
229 *
230 * @remark The properties interface tries to avoid allocations.
231 * When you use this function and cxPropertiesNext() interleaving,
232 * no allocations are performed. However, you must not free the
233 * pointer to the data in that case. When you invoke the fill
234 * function more than once before calling cxPropertiesNext(),
235 * the additional data is appended - inevitably leading to
236 * an allocation of a new buffer and copying the previous contents.
237 *
238 * @param prop the properties interface
239 * @param buf a pointer to the data
240 * @param len the length of the data
241 * @retval zero success
242 * @retval non-zero a memory allocation was necessary but failed
243 * @see cxPropertiesFill()
244 */
245 cx_attr_nonnull cx_attr_access_r(2, 3)
246 CX_EXPORT int cxPropertiesFilln(CxProperties *prop, const char *buf, size_t len);
247
248 /**
249 * Internal function, do not use.
250 *
251 * @param prop the properties interface
252 * @param str the text to fill in
253 * @retval zero success
254 * @retval non-zero a memory allocation was necessary but failed
255 */
256 cx_attr_nonnull
257 CX_INLINE int cx_properties_fill(CxProperties *prop, cxstring str) {
258 return cxPropertiesFilln(prop, str.ptr, str.length);
259 }
260
261 /**
262 * Fills the input buffer with data.
263 *
264 * After calling this function, you can parse the data by calling
265 * cxPropertiesNext().
266 *
267 * @attention The properties interface tries to avoid allocations.
268 * When you use this function and cxPropertiesNext() interleaving,
269 * no allocations are performed. However, you must not free the
270 * pointer to the data in that case. When you invoke the fill
271 * function more than once before calling cxPropertiesNext(),
272 * the additional data is appended - inevitably leading to
273 * an allocation of a new buffer and copying the previous contents.
274 *
275 * @param prop the properties interface
276 * @param str the text to fill in
277 * @retval zero success
278 * @retval non-zero a memory allocation was necessary but failed
279 * @see cxPropertiesFilln()
280 */
281 #define cxPropertiesFill(prop, str) cx_properties_fill(prop, cx_strcast(str))
282
283 /**
284 * Specifies stack memory that shall be used as an internal buffer.
285 *
286 * @param prop the properties interface
287 * @param buf a pointer to stack memory
288 * @param capacity the capacity of the stack memory
289 */
290 cx_attr_nonnull
291 CX_EXPORT void cxPropertiesUseStack(CxProperties *prop, char *buf, size_t capacity);
292
293 /**
294 * Retrieves the next key/value-pair.
295 *
296 * This function returns zero as long as there are key/value-pairs found.
297 * If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
298 *
299 * When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
300 * returned, and you can add more data with #cxPropertiesFill().
301 *
302 * @remark The incomplete line will be stored in an internal buffer, which is
303 * allocated on the heap, by default. If you want to avoid allocations,
304 * you can specify sufficient space with cxPropertiesUseStack() after
305 * initialization with cxPropertiesInit().
306 *
307 * @attention The returned strings will point into a buffer that might not be
308 * available later. It is strongly recommended to copy the strings for further
309 * use.
310 *
311 * @param prop the properties interface
312 * @param key a pointer to the cxstring that shall contain the property name
313 * @param value a pointer to the cxstring that shall contain the property value
314 * @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
315 * @retval CX_PROPERTIES_NO_DATA there is no (more) data in the input buffer
316 * @retval CX_PROPERTIES_INCOMPLETE_DATA the data in the input buffer is incomplete
317 * (fill more data and try again)
318 * @retval CX_PROPERTIES_NULL_INPUT the input buffer was never filled
319 * @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
320 * @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
321 * @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
322 */
323 cx_attr_nonnull cx_attr_nodiscard
324 CX_EXPORT CxPropertiesStatus cxPropertiesNext(CxProperties *prop, cxstring *key, cxstring *value);
325
326 /**
327 * The size of the stack memory that `cxPropertiesLoad()` will reserve with `cxPropertiesUseStack()`.
328 */
329 CX_EXPORT extern const unsigned cx_properties_load_buf_size;
330
331 /**
332 * The size of the stack memory that `cxPropertiesLoad()` will use to read contents from the file.
333 */
334 CX_EXPORT extern const unsigned cx_properties_load_fill_size;
335
336 /**
337 * Internal function - use cxPropertiesLoad() instead.
338 *
339 * @param config the parser config
340 * @param allocator the allocator for the values
341 * @param filename the file name
342 * @param target the target map
343 * @return status code
344 */
345 cx_attr_nonnull_arg(4)
346 CX_EXPORT CxPropertiesStatus cx_properties_load(CxPropertiesConfig config,
347 const CxAllocator *allocator, cxstring filename, CxMap *target);
348
349 /**
350 * Loads properties from a file and inserts them into a map.
351 *
352 * Entries are added to the map, possibly overwriting existing entries.
353 *
354 * The map must either store pointers of type @c char*, or elements of type cxmutstr.
355 * Any other configuration is not supported.
356 *
357 * @note When the parser finds an error, all successfully parsed keys before the error
358 * are added to the map nonetheless.
359 *
360 * @param config the parser config
361 * @param allocator the allocator for the values that will be stored in the map
362 * @param filename (any string) the absolute or relative path to the file
363 * @param target (@c CxMap*) the map where the properties shall be added
364 * @retval CX_PROPERTIES_NO_ERROR (zero) at least one key/value pair was found
365 * @retval CX_PROPERTIES_NO_DATA the file is syntactically OK, but does not contain properties
366 * @retval CX_PROPERTIES_INCOMPLETE_DATA unexpected end of file
367 * @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
368 * @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
369 * @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
370 * @retval CX_PROPERTIES_FILE_ERROR a file operation failed; depending on the system @c errno might be set
371 * @retval CX_PROPERTIES_MAP_ERROR storing a key/value pair in the map failed
372 * @see cxPropertiesLoadDefault()
373 */
374 #define cxPropertiesLoad(config, allocator, filename, target) \
375 cx_properties_load(config, allocator, cx_strcast(filename), target)
376
377 /**
378 * Loads properties from a file and inserts them into a map with a default config.
379 *
380 * Entries are added to the map, possibly overwriting existing entries.
381 *
382 * The map must either store pointers of type @c char*, or elements of type cxmutstr.
383 * Any other configuration is not supported.
384 *
385 * @note When the parser finds an error, all successfully parsed keys before the error
386 * are added to the map nonetheless.
387 *
388 * @param allocator the allocator for the values that will be stored in the map
389 * @param filename (any string) the absolute or relative path to the file
390 * @param target (@c CxMap*) the map where the properties shall be added
391 * @retval CX_PROPERTIES_NO_ERROR (zero) at least one key/value pair was found
392 * @retval CX_PROPERTIES_NO_DATA the file is syntactically OK, but does not contain properties
393 * @retval CX_PROPERTIES_INCOMPLETE_DATA unexpected end of file
394 * @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
395 * @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
396 * @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
397 * @retval CX_PROPERTIES_FILE_ERROR a file operation failed; depending on the system @c errno might be set
398 * @retval CX_PROPERTIES_MAP_ERROR storing a key/value pair in the map failed
399 * @see cxPropertiesLoad()
400 */
401 #define cxPropertiesLoadDefault(allocator, filename, target) \
402 cx_properties_load(cx_properties_config_default, allocator, cx_strcast(filename), target)
403
404
405 #ifdef __cplusplus
406 } // extern "C"
407 #endif
408
409 #endif // UCX_PROPERTIES_H
410