comparison: docs/Writerside/topics/properties.h.md
docs/Writerside/topics/properties.h.md
- changeset 1424
- 563033aa998c
- parent 1420
- c6f55a2b3495
equal
deleted
inserted
replaced
| 1423:9a72258446cd | 1424:563033aa998c |
|---|---|
| 1 # Properties | 1 # Properties |
| 2 | 2 |
| 3 The UCX properties parser can be used to parse line based key/value strings. | 3 The UCX properties parser can be used to parse line-based key/value strings. |
| 4 | 4 |
| 5 ## Supported Syntax | 5 ## Supported Syntax |
| 6 | 6 |
| 7 Key/value pairs must be line-based and separated by a single character delimiter. | 7 Key/value pairs must be line-based and separated by a single character delimiter. |
| 8 The parser supports up to three different characters which introduce comments. | 8 The parser supports up to three different characters which introduce comments. |
| 59 void cxPropertiesUseStack(CxProperties *prop, | 59 void cxPropertiesUseStack(CxProperties *prop, |
| 60 char *buf, size_t capacity); | 60 char *buf, size_t capacity); |
| 61 ``` | 61 ``` |
| 62 | 62 |
| 63 The first step is to initialize a `CxProperties` structure with a call to `cxPropertiesInit()` using the desired config. | 63 The first step is to initialize a `CxProperties` structure with a call to `cxPropertiesInit()` using the desired config. |
| 64 The shorthand `cxPropertiesInitDefault()` creates a default configuration with the equals sign `'='` as delimiter | 64 The shorthand `cxPropertiesInitDefault()` creates a default configuration with the equals sign `'='` as delimiter |
| 65 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config). | 65 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config). |
| 66 | 66 |
| 67 > In a future UCX version, the default `continuation` character will be a backslash `'\'`. | 67 > In a future UCX version, the default `continuation` character will be a backslash `'\'`. |
| 68 > In UCX 3.1 this feature is not implemented, yet. | 68 > In UCX 3.1 this feature is not implemented, yet. |
| 69 | 69 |
| 85 | 85 |
| 86 If `cxPropertiesNext()` returns `CX_PROPERTIES_INCOMPLETE_DATA` it means that the input buffer is exhausted, | 86 If `cxPropertiesNext()` returns `CX_PROPERTIES_INCOMPLETE_DATA` it means that the input buffer is exhausted, |
| 87 but the last line did not contain a full key/value pair. | 87 but the last line did not contain a full key/value pair. |
| 88 In that case, you can call `cxPropertiesFill()` again to add more data and continue with `cxPropertiesNext()`. | 88 In that case, you can call `cxPropertiesFill()` again to add more data and continue with `cxPropertiesNext()`. |
| 89 | 89 |
| 90 Note, that adding more data to a non-empty input buffer will lead to an allocation, | 90 Note that adding more data to a non-empty input buffer will lead to an allocation, |
| 91 unless you specified some stack memory with `cxPropertiesUseStack()`. | 91 unless you specified some stack memory with `cxPropertiesUseStack()`. |
| 92 The stack capacity must be large enough to contain the longest line in your data. | 92 The stack capacity must be large enough to contain the longest line in your data. |
| 93 If the internal buffer is not large enough to contain a single line, it is extended. | 93 If the internal buffer is not large enough to contain a single line, it is extended. |
| 94 If that is not possible for some reason, `cxPropertiesNext()` fails and returns `CX_PROPERTIES_BUFFER_ALLOC_FAILED`. | 94 If that is not possible for some reason, `cxPropertiesNext()` fails and returns `CX_PROPERTIES_BUFFER_ALLOC_FAILED`. |
| 95 | 95 |
| 176 | 176 |
| 177 > The function `cxPropertiesLoad()` should usually not return `CX_PROPERTIES_INCOMPLETE_DATA` because the parser is automatically refilled from the source. | 177 > The function `cxPropertiesLoad()` should usually not return `CX_PROPERTIES_INCOMPLETE_DATA` because the parser is automatically refilled from the source. |
| 178 > If it does, it could mean that the source was unable to provide all the data, or the properties data ended unexpectedly. | 178 > If it does, it could mean that the source was unable to provide all the data, or the properties data ended unexpectedly. |
| 179 > The most expected status code is `CX_PROPERTIES_NO_ERROR` which means that at least one key/value-pair was found. | 179 > The most expected status code is `CX_PROPERTIES_NO_ERROR` which means that at least one key/value-pair was found. |
| 180 > If `cxPropertiesLoad()` returns `CX_PROPERTIES_NO_DATA` it means that the source did not provide any key/value-pair. | 180 > If `cxPropertiesLoad()` returns `CX_PROPERTIES_NO_DATA` it means that the source did not provide any key/value-pair. |
| 181 > There are several special status codes which are documented [below](#additional-status-codes). | 181 > There are several special status codes that are documented [below](#additional-status-codes). |
| 182 | 182 |
| 183 ### Creating own Sources and Sinks | 183 ### Creating own Sources and Sinks |
| 184 | 184 |
| 185 ```C | 185 ```C |
| 186 #include <cx/properties.h> | 186 #include <cx/properties.h> |
