comparison: docs/Writerside/topics/properties.h.md
docs/Writerside/topics/properties.h.md
- changeset 1569
- b5d896ad5e75
- parent 1560
- f060ecd65575
equal
deleted
inserted
replaced
| 1568:355066cd9186 | 1569:b5d896ad5e75 |
|---|---|
| 16 key1 = value1 | 16 key1 = value1 |
| 17 key2 = value2 | 17 key2 = value2 |
| 18 # next is a blank line and will be ignored | 18 # next is a blank line and will be ignored |
| 19 | 19 |
| 20 keys_are_trimmed = and_so_are_values # also a comment | 20 keys_are_trimmed = and_so_are_values # also a comment |
| 21 | |
| 22 key3 = value that \ | |
| 23 is continued on the next line | |
| 21 ``` | 24 ``` |
| 22 | 25 |
| 23 > Delimiter and comment characters are configured with the `CxPropertiesConfig` structure. | 26 > Delimiter, line continuation character, and up to three comment characters |
| 24 > There is also a field reserved for `continuation` which will be used as a line continuation character | 27 > can be configured with the `CxPropertiesConfig` structure (see below). |
| 25 > in a future version of UCX. | |
| 26 > In UCX 3.1 this is not implemented. | |
| 27 | 28 |
| 28 ## Basic Parsing | 29 ## Basic Parsing |
| 29 | 30 |
| 30 The following listing shows the properties-parser API. | 31 The following listing shows the properties-parser API. |
| 31 | 32 |
| 40 typedef struct cx_properties_config_s { | 41 typedef struct cx_properties_config_s { |
| 41 char delimiter; | 42 char delimiter; |
| 42 char comment1; | 43 char comment1; |
| 43 char comment2; | 44 char comment2; |
| 44 char comment3; | 45 char comment3; |
| 45 // reserved for future use - not implemented in UCX 3.1 | |
| 46 char continuation; | 46 char continuation; |
| 47 } CxPropertiesConfig; | 47 } CxPropertiesConfig; |
| 48 | 48 |
| 49 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config); | 49 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config); |
| 50 | 50 |
| 75 ``` | 75 ``` |
| 76 | 76 |
| 77 The first step is to initialize a `CxProperties` structure with a call to `cxPropertiesInit()` using the desired config. | 77 The first step is to initialize a `CxProperties` structure with a call to `cxPropertiesInit()` using the desired config. |
| 78 The shorthand `cxPropertiesInitDefault()` creates a default configuration with the equals sign `'='` as delimiter | 78 The shorthand `cxPropertiesInitDefault()` creates a default configuration with the equals sign `'='` as delimiter |
| 79 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config). | 79 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config). |
| 80 | 80 The line continuation symbol is set to `'\'`. |
| 81 > In a future UCX version, the default `continuation` character will be a backslash `'\'`. | 81 Note that leading spaces of a continuing line are ignored. |
| 82 > In UCX 3.1 this feature is not implemented, yet. | |
| 83 | 82 |
| 84 The actual parsing is an interleaving invocation of the `cxPropertiesFill()` (or `cxPropertiesFilln()`) and `cxPropertiesNext()` functions. | 83 The actual parsing is an interleaving invocation of the `cxPropertiesFill()` (or `cxPropertiesFilln()`) and `cxPropertiesNext()` functions. |
| 85 The `cxPropertiesFill()` function is a convenience function, that accepts UCX strings and normal zero-terminated C strings and behaves otherwise like `cxPropertiesFilln()`. | 84 The `cxPropertiesFill()` function is a convenience function, that accepts UCX strings and normal zero-terminated C strings and behaves otherwise like `cxPropertiesFilln()`. |
| 86 | 85 |
| 87 Filling the input buffer is cost-free if there is no data already in the input buffer. | 86 Filling the input buffer is cost-free if there is no data already in the input buffer. |
