docs/Writerside/topics/properties.h.md

# Properties

The UCX properties parser can be used to parse line based key/value strings. 

<warning>
New Feature - documentation work in progress!
</warning>

## Supported Syntax

Key/value pairs must be line based and separated by a single character delimter.
The parser supports up to three different characters which introduce comments.
All characters starting with a comment character up to the end of the line are ignored.
Blank lines are also ignored.

An example properties file looks like this:

```properties
# Comment line at start of file
key1 = value1
key2 = value2
# next is a blank line and will be ignored

  keys_are_trimmed  =    and_so_are_values   # also a comment
```

> Delimiter and comment characters are configured with the  `CxPropertiesConfig` structure.
> There is also a field reserved for `continuation` which will be used as a line continuation character
> in a future version of UCX.
> In UCX 3.1 this is not implemented.

## Basic Parsing

```C
#include <cx/properties.h>

typedef struct cx_properties_config_s {
    char delimiter;
    char comment1;
    char comment2;
    char comment3;
    // reserved for future use - not implemented in UCX 3.1
    char continuation;
} CxPropertiesConfig;

void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);

void cxPropertiesInitDefault(CxProperties *prop);

void cxPropertiesDestroy(CxProperties *prop);

void cxPropertiesReset(CxProperties *prop);

int cxPropertiesFilln(CxProperties *prop,
        const char *buf, size_t len);

// where S is one of cxstring, cxmutstr, char*, const char*
int cxPropertiesFill(CxProperties *prop, S string);

CxPropertiesStatus cxPropertiesNext(CxProperties *prop,
        cxstring *key, cxstring *value);
        
void cxPropertiesUseStack(CxProperties *prop,
        char *buf, size_t capacity);
```

### List of Status Codes

## Sources and Sinks

```C
#include <cx/properties.h>

CxPropertiesSource
cxPropertiesStringSource(cxstring str);

CxPropertiesSource
cxPropertiesCstrSource(const char *str);

CxPropertiesSource
cxPropertiesCstrnSource(const char *str, size_t len);

CxPropertiesSource
cxPropertiesFileSource(FILE *file, size_t chunk_size);
        
CxPropertiesSink
cxPropertiesMapSink(CxMap *map);

CxPropertiesStatus
cxPropertiesLoad(CxProperties *prop,
        CxPropertiesSink sink, CxPropertiesSource source);
```

### Creating own Sources and Sinks

```C
#include <cx/properties.h>

typedef int(*cx_properties_read_init_func)(CxProperties *prop,
        CxPropertiesSource *src);

typedef int(*cx_properties_read_func)(CxProperties *prop,
        CxPropertiesSource *src, cxstring *target);

typedef void(*cx_properties_read_clean_func)(CxProperties *prop,
        CxPropertiesSource *src);

typedef int(*cx_properties_sink_func)(CxProperties *prop,
        CxPropertiesSink *sink, cxstring key, cxstring value);

typedef struct cx_properties_source_s {
    void *src;
    void *data_ptr;
    size_t data_size;
    cx_properties_read_func read_func;
    cx_properties_read_init_func read_init_func;
    cx_properties_read_clean_func read_clean_func;
} CxPropertiesSource;

typedef struct cx_properties_sink_s {
    void *sink;
    void *data;
    cx_properties_sink_func sink_func;
} CxPropertiesSink;
```

<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/properties_8h.html">properties.h</a>
</category>
</seealso>