GCC Code Coverage Report

Line	Branch	Exec	Source
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			#include <stdio.h>
45			#include <string.h>
46
47			#ifdef __cplusplus
48			extern "C" {
49			#endif
50
51			/**
52			* Configures the expected characters for the properties parser.
53			*/
54			struct cx_properties_config_s {
55			/**
56			* The key/value delimiter that shall be used.
57			* This is '=' by default.
58			*/
59			char delimiter;
60
61			/**
62			* The first comment character.
63			* This is '#' by default.
64			*/
65			char comment1;
66
67			/**
68			* The second comment character.
69			* This is not set by default.
70			*/
71			char comment2;
72
73			/**
74			* The third comment character.
75			* This is not set by default.
76			*/
77			char comment3;
78
79			/*
80			* The character, when appearing at the end of a line, continues that line.
81			* This is '\' by default.
82			*/
83			/**
84			* Reserved for future use.
85			*/
86			char continuation;
87			};
88
89			/**
90			* Typedef for the properties config.
91			*/
92			typedef struct cx_properties_config_s CxPropertiesConfig;
93
94			/**
95			* Default properties configuration.
96			*/
97			CX_EXPORT extern const CxPropertiesConfig cx_properties_config_default;
98
99			/**
100			* Status codes for the properties interface.
101			*/
102			enum cx_properties_status {
103			/**
104			* Everything is fine.
105			*/
106			CX_PROPERTIES_NO_ERROR,
107			/**
108			* The input buffer does not contain more data.
109			*/
110			CX_PROPERTIES_NO_DATA,
111			/**
112			* The input ends unexpectedly.
113			*
114			* This either happens when the last line does not terminate with a line
115			* break, or when the input ends with a parsed key but no value.
116			*/
117			CX_PROPERTIES_INCOMPLETE_DATA,
118			/**
119			* Not used as a status and never returned by any function.
120			*
121			* You can use this enumerator to check for all "good" status results
122			* by checking if the status is less than @c CX_PROPERTIES_OK.
123			*
124			* A "good" status means that you can refill data and continue parsing.
125			*/
126			CX_PROPERTIES_OK,
127			/**
128			* Input buffer is @c NULL.
129			*/
130			CX_PROPERTIES_NULL_INPUT,
131			/**
132			* The line contains a delimiter but no key.
133			*/
134			CX_PROPERTIES_INVALID_EMPTY_KEY,
135			/**
136			* The line contains data but no delimiter.
137			*/
138			CX_PROPERTIES_INVALID_MISSING_DELIMITER,
139			/**
140			* More internal buffer was needed, but could not be allocated.
141			*/
142			CX_PROPERTIES_BUFFER_ALLOC_FAILED,
143			/**
144			* Initializing the properties source failed.
145			*
146			* @see cx_properties_read_init_func
147			*/
148			CX_PROPERTIES_READ_INIT_FAILED,
149			/**
150			* Reading from a properties source failed.
151			*
152			* @see cx_properties_read_func
153			*/
154			CX_PROPERTIES_READ_FAILED,
155			/**
156			* Sinking a k/v-pair failed.
157			*
158			* @see cx_properties_sink_func
159			*/
160			CX_PROPERTIES_SINK_FAILED,
161			};
162
163			/**
164			* Typedef for the properties status enum.
165			*/
166			typedef enum cx_properties_status CxPropertiesStatus;
167
168			/**
169			* Interface for working with properties data.
170			*/
171			struct cx_properties_s {
172			/**
173			* The configuration.
174			*/
175			CxPropertiesConfig config;
176
177			/**
178			* The text input buffer.
179			*/
180			CxBuffer input;
181
182			/**
183			* Internal buffer.
184			*/
185			CxBuffer buffer;
186			};
187
188			/**
189			* Typedef for the properties interface.
190			*/
191			typedef struct cx_properties_s CxProperties;
192
193
194			/**
195			* Typedef for a properties sink.
196			*/
197			typedef struct cx_properties_sink_s CxPropertiesSink;
198
199			/**
200			* A function that consumes a k/v-pair in a sink.
201			*
202			* The sink could be a map, and the sink function would be calling
203			* a map function to store the k/v-pair.
204			*
205			* @param prop the properties interface that wants to sink a k/v-pair
206			* @param sink the sink
207			* @param key the key
208			* @param value the value
209			* @retval zero success
210			* @retval non-zero sinking the k/v-pair failed
211			*/
212			typedef int(*cx_properties_sink_func)(
213			CxProperties *prop,
214			CxPropertiesSink *sink,
215			cxstring key,
216			cxstring value
217			);
218
219			/**
220			* Defines a sink for k/v-pairs.
221			*/
222			struct cx_properties_sink_s {
223			/**
224			* The sink object.
225			*/
226			void *sink;
227			/**
228			* Optional custom data.
229			*/
230			void *data;
231			/**
232			* A function for consuming k/v-pairs into the sink.
233			*/
234			cx_properties_sink_func sink_func;
235			};
236
237
238			/**
239			* Typedef for a properties source.
240			*/
241			typedef struct cx_properties_source_s CxPropertiesSource;
242
243			/**
244			* A function that reads data from a source.
245			*
246			* When the source is depleted, implementations SHALL provide an empty
247			* string in the @p target and return zero.
248			* A non-zero return value is only permitted in case of an error.
249			*
250			* The meaning of the optional parameters is implementation-dependent.
251			*
252			* @param prop the properties interface that wants to read from the source
253			* @param src the source
254			* @param target a string buffer where the read data shall be stored
255			* @retval zero success
256			* @retval non-zero reading the data failed
257			*/
258			typedef int(*cx_properties_read_func)(
259			CxProperties *prop,
260			CxPropertiesSource *src,
261			cxstring *target
262			);
263
264			/**
265			* A function that may initialize additional memory for the source.
266			*
267			* @param prop the properties interface that wants to read from the source
268			* @param src the source
269			* @retval zero initialization was successful
270			* @retval non-zero otherwise
271			*/
272			typedef int(*cx_properties_read_init_func)(
273			CxProperties *prop,
274			CxPropertiesSource *src
275			);
276
277			/**
278			* A function that cleans memory initialized by the read_init_func.
279			*
280			* @param prop the properties interface that wants to read from the source
281			* @param src the source
282			*/
283			typedef void(*cx_properties_read_clean_func)(
284			CxProperties *prop,
285			CxPropertiesSource *src
286			);
287
288			/**
289			* Defines a properties source.
290			*/
291			struct cx_properties_source_s {
292			/**
293			* The source object.
294			*
295			* For example, a file stream or a string.
296			*/
297			void *src;
298			/**
299			* Optional additional data pointer.
300			*/
301			void *data_ptr;
302			/**
303			* Optional size information.
304			*/
305			size_t data_size;
306			/**
307			* A function that reads data from the source.
308			*/
309			cx_properties_read_func read_func;
310			/**
311			* Optional function that may prepare the source for reading data.
312			*/
313			cx_properties_read_init_func read_init_func;
314			/**
315			* Optional function that cleans additional memory allocated by the
316			* read_init_func.
317			*/
318			cx_properties_read_clean_func read_clean_func;
319			};
320
321			/**
322			* Initialize a properties interface.
323			*
324			* @param prop the properties interface
325			* @param config the properties configuration
326			* @see cxPropertiesInitDefault()
327			*/
328			cx_attr_nonnull
329			CX_EXPORT void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);
330
331			/**
332			* Destroys the properties interface.
333			*
334			* @note Even when you are certain that you did not use the interface in a
335			* way that caused a memory allocation, you should call this function anyway.
336			* Future versions of the library might add features that need additional memory,
337			* and you really don't want to search the entire code where you might need to
338			* add a call to this function.
339			*
340			* @param prop the properties interface
341			*/
342			cx_attr_nonnull
343			CX_EXPORT void cxPropertiesDestroy(CxProperties *prop);
344
345			/**
346			* Destroys and re-initializes the properties interface.
347			*
348			* You might want to use this to reset the parser after
349			* encountering a syntax error.
350			*
351			* @param prop the properties interface
352			*/
353			cx_attr_nonnull
354			CX_EXPORT void cxPropertiesReset(CxProperties *prop);
355
356			/**
357			* Initialize a properties parser with the default configuration.
358			*
359			* @param prop (@c CxProperties*) the properties interface
360			* @see cxPropertiesInit()
361			*/
362			#define cxPropertiesInitDefault(prop) \
363			cxPropertiesInit(prop, cx_properties_config_default)
364
365			/**
366			* Fills the input buffer with data.
367			*
368			* After calling this function, you can parse the data by calling
369			* cxPropertiesNext().
370			*
371			* @remark The properties interface tries to avoid allocations.
372			* When you use this function and cxPropertiesNext() interleaving,
373			* no allocations are performed. However, you must not free the
374			* pointer to the data in that case. When you invoke the fill
375			* function more than once before calling cxPropertiesNext(),
376			* the additional data is appended - inevitably leading to
377			* an allocation of a new buffer and copying the previous contents.
378			*
379			* @param prop the properties interface
380			* @param buf a pointer to the data
381			* @param len the length of the data
382			* @retval zero success
383			* @retval non-zero a memory allocation was necessary but failed
384			* @see cxPropertiesFill()
385			*/
386			cx_attr_nonnull cx_attr_access_r(2, 3)
387			CX_EXPORT int cxPropertiesFilln(CxProperties *prop, const char *buf, size_t len);
388
389			/**
390			* Internal function, do not use.
391			*
392			* @param prop the properties interface
393			* @param str the text to fill in
394			* @retval zero success
395			* @retval non-zero a memory allocation was necessary but failed
396			*/
397			cx_attr_nonnull
398			CX_INLINE int cx_properties_fill(CxProperties *prop, cxstring str) {
399		11	return cxPropertiesFilln(prop, str.ptr, str.length);
400			}
401
402			/**
403			* Fills the input buffer with data.
404			*
405			* After calling this function, you can parse the data by calling
406			* cxPropertiesNext().
407			*
408			* @attention The properties interface tries to avoid allocations.
409			* When you use this function and cxPropertiesNext() interleaving,
410			* no allocations are performed. However, you must not free the
411			* pointer to the data in that case. When you invoke the fill
412			* function more than once before calling cxPropertiesNext(),
413			* the additional data is appended - inevitably leading to
414			* an allocation of a new buffer and copying the previous contents.
415			*
416			* @param prop the properties interface
417			* @param str the text to fill in
418			* @retval zero success
419			* @retval non-zero a memory allocation was necessary but failed
420			* @see cxPropertiesFilln()
421			*/
422			#define cxPropertiesFill(prop, str) cx_properties_fill(prop, cx_strcast(str))
423
424			/**
425			* Specifies stack memory that shall be used as an internal buffer.
426			*
427			* @param prop the properties interface
428			* @param buf a pointer to stack memory
429			* @param capacity the capacity of the stack memory
430			*/
431			cx_attr_nonnull
432			CX_EXPORT void cxPropertiesUseStack(CxProperties *prop, char *buf, size_t capacity);
433
434			/**
435			* Retrieves the next key/value-pair.
436			*
437			* This function returns zero as long as there are key/value-pairs found.
438			* If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
439			*
440			* When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
441			* returned, and you can add more data with #cxPropertiesFill().
442			*
443			* @remark The incomplete line will be stored in an internal buffer, which is
444			* allocated on the heap, by default. If you want to avoid allocations,
445			* you can specify sufficient space with cxPropertiesUseStack() after
446			* initialization with cxPropertiesInit().
447			*
448			* @attention The returned strings will point into a buffer that might not be
449			* available later. It is strongly recommended to copy the strings for further
450			* use.
451			*
452			* @param prop the properties interface
453			* @param key a pointer to the cxstring that shall contain the property name
454			* @param value a pointer to the cxstring that shall contain the property value
455			* @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
456			* @retval CX_PROPERTIES_NO_DATA there is no (more) data in the input buffer
457			* @retval CX_PROPERTIES_INCOMPLETE_DATA the data in the input buffer is incomplete
458			* (fill more data and try again)
459			* @retval CX_PROPERTIES_NULL_INPUT the input buffer was never filled
460			* @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
461			* @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
462			* @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
463			*/
464			cx_attr_nonnull cx_attr_nodiscard
465			CX_EXPORT CxPropertiesStatus cxPropertiesNext(CxProperties *prop, cxstring *key, cxstring *value);
466
467			/**
468			* Creates a properties sink for an UCX map.
469			*
470			* The values stored in the map will be pointers to freshly allocated,
471			* zero-terminated C strings (@c char*), which means the @p map should have been
472			* created with #CX_STORE_POINTERS.
473			*
474			* The cxDefaultAllocator will be used unless you specify a custom
475			* allocator in the optional @c data field of the returned sink.
476			*
477			* @param map the map that shall consume the k/v-pairs.
478			* @return the sink
479			* @see cxPropertiesLoad()
480			*/
481			cx_attr_nonnull cx_attr_nodiscard
482			CX_EXPORT CxPropertiesSink cxPropertiesMapSink(CxMap *map);
483
484			/**
485			* Creates a properties source based on an UCX string.
486			*
487			* @param str the string
488			* @return the properties source
489			* @see cxPropertiesLoad()
490			*/
491			cx_attr_nodiscard
492			CX_EXPORT CxPropertiesSource cxPropertiesStringSource(cxstring str);
493
494			/**
495			* Creates a properties source based on C string with the specified length.
496			*
497			* @param str the string
498			* @param len the length
499			* @return the properties source
500			* @see cxPropertiesLoad()
501			*/
502			cx_attr_nonnull cx_attr_nodiscard cx_attr_access_r(1, 2)
503			CX_EXPORT CxPropertiesSource cxPropertiesCstrnSource(const char *str, size_t len);
504
505			/**
506			* Creates a properties source based on a C string.
507			*
508			* The length will be determined with strlen(), so the string MUST be
509			* zero-terminated.
510			*
511			* @param str the string
512			* @return the properties source
513			* @see cxPropertiesLoad()
514			*/
515			cx_attr_nonnull cx_attr_nodiscard cx_attr_cstr_arg(1)
516			CX_EXPORT CxPropertiesSource cxPropertiesCstrSource(const char *str);
517
518			/**
519			* Creates a properties source based on an FILE.
520			*
521			* @param file the file
522			* @param chunk_size how many bytes may be read in one operation
523			*
524			* @return the properties source
525			* @see cxPropertiesLoad()
526			*/
527			cx_attr_nonnull cx_attr_nodiscard cx_attr_access_r(1)
528			CX_EXPORT CxPropertiesSource cxPropertiesFileSource(FILE *file, size_t chunk_size);
529
530
531			/**
532			* Loads properties data from a source and transfers it to a sink.
533			*
534			* This function tries to read as much data from the source as possible.
535			* When the source was completely consumed and at least on k/v-pair was found,
536			* the return value will be #CX_PROPERTIES_NO_ERROR.
537			* When the source was consumed but no k/v-pairs were found, the return value
538			* will be #CX_PROPERTIES_NO_DATA.
539			* In case the source data ends unexpectedly, the #CX_PROPERTIES_INCOMPLETE_DATA
540			* is returned. In that case you should call this function again with the same
541			* sink and either an updated source or the same source if the source is able to
542			* yield the missing data.
543			*
544			* The other result codes apply, according to their description.
545			*
546			* @param prop the properties interface
547			* @param sink the sink
548			* @param source the source
549			* @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
550			* @retval CX_PROPERTIES_READ_INIT_FAILED initializing the source failed
551			* @retval CX_PROPERTIES_READ_FAILED reading from the source failed
552			* @retval CX_PROPERTIES_SINK_FAILED sinking the properties into the sink failed
553			* @retval CX_PROPERTIES_NO_DATA the source did not provide any key/value pairs
554			* @retval CX_PROPERTIES_INCOMPLETE_DATA the source did not provide enough data
555			* @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
556			* @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
557			* @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
558			*/
559			cx_attr_nonnull
560			CX_EXPORT CxPropertiesStatus cxPropertiesLoad(CxProperties *prop,
561			CxPropertiesSink sink, CxPropertiesSource source);
562
563			#ifdef __cplusplus
564			} // extern "C"
565			#endif
566
567			#endif // UCX_PROPERTIES_H
568