Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/properties.h.md	Mon Feb 24 20:39:29 2025 +0100
+++ b/docs/Writerside/topics/properties.h.md	Wed Feb 26 23:01:27 2025 +0100
@@ -1,24 +1,106 @@
 # Properties
 
+The UCX properties parser can be used to parse line-separated key/value strings. 
+
 <warning>
-New Feature - will be documented soon!
+New Feature - documentation work in progress!
 </warning>
 
-<!--
-## Undocumented Symbols (TODO)
-### cx_properties_config_default
-### cxPropertiesCstrnSource
-### cxPropertiesCstrSource
-### cxPropertiesDestroy
-### cxPropertiesFileSource
-### cxPropertiesFilln
-### cxPropertiesInit
-### cxPropertiesLoad
-### cxPropertiesMapSink
-### cxPropertiesNext
-### cxPropertiesStringSource
-### cxPropertiesUseStack
--->
+
+## 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">