Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/properties.h.md

docs/Writerside/topics/properties.h.md

changeset 1231
a9f9c59e0b63
parent 1230
3ec9cce0de01
equal deleted inserted replaced
1230:3ec9cce0de01 1231:a9f9c59e0b63
62 62
63 void cxPropertiesUseStack(CxProperties *prop, 63 void cxPropertiesUseStack(CxProperties *prop,
64 char *buf, size_t capacity); 64 char *buf, size_t capacity);
65 ``` 65 ```
66 66
67 The first step is to initialize a `CxProperties` structure with a call to `cxPropertiesInit()` using the desired config.
68 The shorthand `cxPropertiesInitDefault()` creates a default configuration with the equals sign `'='` as delimiter
69 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config).
70
71 > In a future UCX version, the default `continuation` character will be a backslash `'\'`.
72 > In UCX 3.1 this feature is not implemented, yet.
73
74 The actual parsing is an interleaving invocation of the `cxPropertiesFill()` (or `cxPropertiesFilln()`) and `cxPropertiesNext()` functions.
75 The `cxPropertiesFill()` function is a convenience function, that accepts UCX strings and normal zero-terminated C strings and behaves otherwise like `cxPropertiesFilln()`.
76
77 Filling the input buffer is cost-free if there is no data already in the input buffer.
78 In that case, the input buffer only stores the pointer to the original data without creating a copy.
79 Calling `cxPropertiesNext()` will return with `CX_PROPERTIES_NO_ERROR` (= zero) for each key/value-pair that is successfully parsed,
80 and stores the pointers and lengths for both the key and the value into the structures pointed to by the `key` and `value` arguments.
81
82 > This is all still free of any copies and allocations.
83 > That means, the pointers in `key` and `value` after `cxPropertiesNext()` returns will point into the input buffer.
84 > If you intend to store the key and/or the value somewhere else, it is strongly recommended to create a copy with `cx_strdup()`,
85 > because you will otherwise soon end up with a dangling pointer.
86 > {style="note"}
87
88 If `cxPropertiesNext()` returns `CX_PROPERTIES_INCOMPLETE_DATA` it means that the input buffer is exhausted,
89 but the last line did not contain a full key/value pair.
90 In that case, you can call `cxPropertiesFill()` again to add more data and continue with `cxPropertiesNext()`.
91
92 Note, that adding more data to a non-empty input buffer will lead to an allocation,
93 unless you specified some stack memory with `cxPropertiesUseStack()`.
94 The stack capacity must be large enough to contain the longest line in your data.
95 If the internal buffer is not large enough to contain a single line, it is extended.
96 If that is not possible for some reason, `cxPropertiesNext()` fails and returns `CX_PROPERTIES_BUFFER_ALLOC_FAILED`.
97
98 If you want to reuse a `CxProperties` structure with the same config, you can call `cxPropertiesReset()`, even if the last operation was a failure.
99 Otherwise, you should always call `cxPropertiesDestroy()` when you are done with the parser.
100
101 > It is strongly recommended to always call `cxPropertiesDestroy` when you are done with the parser,
102 > even if you did not expect any allocations because you used `cxPropertiesUseStack()`.
103
67 ### List of Status Codes 104 ### List of Status Codes
105
106 Below is a full list of error codes for `cxPropertiesNext()`.
107
108 | Status Code | Meaning |
109 |-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
110 | CX_PROPERTIES_NO_ERROR | A key/value pair was found and returned. |
111 | CX_PROPERTIES_NO_DATA | The input buffer does not contain more data. |
112 | CX_PROPERTIES_INCOMPLETE_DATA | The input ends unexpectedly. This can happen when the last line does not terminate with a line break, or when the input ends with a parsed key but no value. Use `cxPropertiesFill()` to add more data before retrying. |
113 | CX_PROPERTIES_NULL_INPUT | The input buffer was never initialized. Probably you forgot to call `cxPropertiesFill()` at least once. |
114 | CX_PROPERTIES_INVALID_EMPTY_KEY | Only white-spaces were found on the left hand-side of the delimiter. Keys must not be empty. |
115 | CX_PROPERTIES_INVALID_MISSING_DELIMITER | A line contains data, but no delimiter. |
116 | CX_PROPERTIES_BUFFER_ALLOC_FAILED | More internal buffer was needed, but could not be allocated. |
117
68 118
69 ## Sources and Sinks 119 ## Sources and Sinks
70 120
71 ```C 121 ```C
72 #include <cx/properties.h> 122 #include <cx/properties.h>
88 138
89 CxPropertiesStatus 139 CxPropertiesStatus
90 cxPropertiesLoad(CxProperties *prop, 140 cxPropertiesLoad(CxProperties *prop,
91 CxPropertiesSink sink, CxPropertiesSource source); 141 CxPropertiesSink sink, CxPropertiesSource source);
92 ``` 142 ```
143
144 <warning>
145 TODO: write documentation
146 </warning>
147
148 ### Additional Status Codes
149
150 For sources and sinks there are three additional special status codes,
151 which only appear as return values for `cxPropertiesLoad()`.
152
153 | Status Code | Meaning |
154 |-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
155 | CX_PROPERTIES_READ_INIT_FAILED | Initializing the properties source failed and the `cx_properties_read_init_func` returned non-zero. |
156 | CX_PROPERTIES_READ_FAILED | Reading from a properties source failed and the `cx_properties_read_func` returned non-zero. |
157 | CX_PROPERTIES_SINK_FAILED | Sinking a key/value-pair failed and the `cx_properties_sink_func` returned non-zero. |
158
93 159
94 ### Creating own Sources and Sinks 160 ### Creating own Sources and Sinks
95 161
96 ```C 162 ```C
97 #include <cx/properties.h> 163 #include <cx/properties.h>
122 void *data; 188 void *data;
123 cx_properties_sink_func sink_func; 189 cx_properties_sink_func sink_func;
124 } CxPropertiesSink; 190 } CxPropertiesSink;
125 ``` 191 ```
126 192
193 <warning>
194 TODO: write documentation
195 </warning>
196
127 <seealso> 197 <seealso>
128 <category ref="apidoc"> 198 <category ref="apidoc">
129 <a href="https://ucx.sourceforge.io/api/properties_8h.html">properties.h</a> 199 <a href="https://ucx.sourceforge.io/api/properties_8h.html">properties.h</a>
130 </category> 200 </category>
131 </seealso> 201 </seealso>

Mercurial Repository: ucx

mercurial