ucx: comparison src/cx/properties.h

-:71e7e9ba4b97
+:d2d42cb1d59e
 #ifndef UCX_PROPERTIES
 #define UCX_PROPERTIES
 #include "common.h"
 #include "string.h"
+#include "map.h"
 #include "array_list.h"
+#include <stdio.h>
 struct cx_properties_config_s {
 /**
 * The key/value delimiter that shall be used.
 * This is '=' by default.
 * This either happens when the last line does not terminate with a line
 * break, or when the input ends with a parsed key but no value.
 */
 CX_PROPERTIES_INCOMPLETE_DATA,
 /**
+* Not used as a status and never returned by any function.
+*
+* You can use this enumerator to check for all "good" status results
+* by checking if the status is less than \c CX_PROPERTIES_OK.
+*
+* A "good" status means, that you can refill data and continue parsing.
+*/
+CX_PROPERTIES_OK,
+/**
 * Input buffer is \c NULL.
 */
 CX_PROPERTIES_NULL_INPUT,
 /**
 * The line contains a delimiter, but no key.
 CX_PROPERTIES_INVALID_MISSING_DELIMITER,
 /**
 * More internal buffer was needed, but could not be allocated.
 */
 CX_PROPERTIES_BUFFER_ALLOC_FAILED,
+/**
+* Initializing the properties source failed.
+*
+* @see cx_properties_read_init_func
+*/
+CX_PROPERTIES_READ_INIT_FAILED,
+/**
+* Reading from a properties source failed.
+*
+* @see cx_properties_read_func
+*/
+CX_PROPERTIES_READ_FAILED,
+/**
+* Sinking a k/v-pair failed.
+*
+* @see cx_properties_sink_func
+*/
+CX_PROPERTIES_SINK_FAILED,
 };
+/**
+* Typedef for the properties status enum.
+*/
+typedef enum cx_properties_status CxPropertiesStatus;
 /**
 * Interface for working with properties data.
 */
 struct cx_properties_s {
 /**
 * Typedef for the properties interface.
 */
 typedef struct cx_properties_s CxProperties;
+/**
+* Typedef for a properties sink.
+*/
+typedef struct cx_properties_sink_s CxPropertiesSink;
+/**
+* A function that consumes a k/v-pair in a sink.
+*
+* The sink could be e.g. a map and the sink function would be calling
+* a map function to store the k/v-pair.
+*
+* @param prop the properties interface that wants to sink a k/v-pair
+* @param sink the sink
+* @param key the key
+* @param value the value
+* @return zero on success, non-zero when sinking the k/v-pair failed
+*/
+__attribute__((__nonnull__))
+typedef int(*cx_properties_sink_func)(
+CxProperties *prop,
+CxPropertiesSink *sink,
+cxstring key,
+cxstring value
+);
+/**
+* Defines a sink for k/v-pairs.
+*/
+struct cx_properties_sink_s {
+/**
+* The sink object.
+*/
+void *sink;
+/**
+* Optional custom data.
+*/
+void *data;
+/**
+* A function for consuming k/v-pairs into the sink.
+*/
+cx_properties_sink_func sink_func;
+};
+/**
+* Typedef for a properties source.
+*/
+typedef struct cx_properties_source_s CxPropertiesSource;
+/**
+* A function that reads data from a source.
+*
+* When the source is depleted, implementations SHALL provide an empty
+* string in the \p target and return zero.
+* A non-zero return value is only permitted in case of an error.
+*
+* The meaning of the optional parameters is implementation-dependent.
+*
+* @param prop the properties interface that wants to read from the source
+* @param src the source
+* @param target a string buffer where the read data shall be stored
+* @return zero on success, non-zero when reading data failed
+*/
+__attribute__((__nonnull__))
+typedef int(*cx_properties_read_func)(
+CxProperties *prop,
+CxPropertiesSource *src,
+cxstring *target
+);
+/**
+* A function that may initialize additional memory for the source.
+*
+* @param prop the properties interface that wants to read from the source
+* @param src the source
+* @return zero when initialization was successful, non-zero otherwise
+*/
+__attribute__((__nonnull__))
+typedef int(*cx_properties_read_init_func)(
+CxProperties *prop,
+CxPropertiesSource *src
+);
+/**
+* A function that cleans memory initialized by the read_init_func.
+*
+* @param prop the properties interface that wants to read from the source
+* @param src the source
+*/
+__attribute__((__nonnull__))
+typedef void(*cx_properties_read_clean_func)(
+CxProperties *prop,
+CxPropertiesSource *src
+);
+/**
+* Defines a properties source.
+*/
+struct cx_properties_source_s {
+/**
+* The source object.
+*
+* For example a file stream or a string.
+*/
+void *src;
+/**
+* Optional additional data pointer.
+*/
+void *data_ptr;
+/**
+* Optional size information.
+*/
+size_t data_size;
+/**
+* A function that reads data from the source.
+*/
+cx_properties_read_func read_func;
+/**
+* Optional function that may prepare the source for reading data.
+*/
+cx_properties_read_init_func read_init_func;
+/**
+* Optional function that cleans additional memory allocated by the
+* read_init_func.
+*/
+cx_properties_read_clean_func read_clean_func;
+};
 /**
 * Initialize a properties interface.
 *
 * @param prop the properties interface
 *
 * @param prop the properties interface
 * @param buf a pointer to stack memory
 * @param capacity the capacity of the stack memory
 */
+__attribute__((__nonnull__))
 void cxPropertiesUseStack(
 CxProperties *prop,
 char *buf,
 size_t capacity
 );
 * @param key a pointer to the cxstring that shall contain the property name
 * @param value a pointer to the cxstring that shall contain the property value
 * @return the status code as defined above
 * @see cxPropertiesFill()
 */
-enum cx_properties_status cxPropertiesNext(
+__attribute__((__nonnull__, __warn_unused_result__))
+CxPropertiesStatus cxPropertiesNext(
 CxProperties *prop,
 cxstring *key,
 cxstring *value
 );
+/**
+* Creates a properties sink for an UCX map.
+*
+* The values stored in the map will be pointers to strings allocated
+* by #cx_strdup_a().
+* The default stdlib allocator will be used, unless you specify a custom
+* allocator in the optional \c data of the sink.
+*
+* @param map the map that shall consume the k/v-pairs.
+* @return the sink
+* @see cxPropertiesLoad()
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+CxPropertiesSink cxPropertiesMapSink(CxMap *map);
+/**
+* Creates a properties source based on an UCX string.
+*
+* @param str the string
+* @return the properties source
+* @see cxPropertiesLoad()
+*/
+__attribute__((__warn_unused_result__))
+CxPropertiesSource cxPropertiesStringSource(cxstring str);
+/**
+* Creates a properties source based on C string with the specified length.
+*
+* @param str the string
+* @param len the length
+* @return the properties source
+* @see cxPropertiesLoad()
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+CxPropertiesSource cxPropertiesCstrnSource(const char *str, size_t len);
+/**
+* Creates a properties source based on a C string.
+*
+* The length will be determined with strlen(), so the string MUST be
+* zero-terminated.
+*
+* @param str the string
+* @return the properties source
+* @see cxPropertiesLoad()
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+CxPropertiesSource cxPropertiesCstrSource(const char *str);
+/**
+* Creates a properties source based on an FILE.
+*
+* @param file the file
+* @param chunk_size how many bytes may be read in one operation
+*
+* @return the properties source
+* @see cxPropertiesLoad()
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+CxPropertiesSource cxPropertiesFileSource(FILE *file, size_t chunk_size);
+/**
+* Loads properties data from a source and transfers it to a sink.
+*
+* This function tries to read as much data from the source as possible.
+* When the source was completely consumed and at least on k/v-pair was found,
+* the return value will be #CX_PROPERTIES_NO_ERROR.
+* When the source was consumed but no k/v-pairs were found, the return value
+* will be #CX_PROPERTIES_NO_DATA.
+* The other result codes apply, according to their description.
+*
+* @param prop the properties interface
+* @param sink the sink
+* @param source the source
+* @return the status of the last operation
+*/
+__attribute__((__nonnull__))
+CxPropertiesStatus cxPropertiesLoad(
+CxProperties *prop,
+CxPropertiesSink sink,
+CxPropertiesSource source
+);
 #endif // UCX_PROPERTIES

Mercurial > hg > ucx / file comparison

comparison: src/cx/properties.h

src/cx/properties.h