ucx: comparison src/cx/properties.h

-:45da884269c8
+:3c90dfc35f06
 #ifndef UCX_PROPERTIES
 #define UCX_PROPERTIES
 #include "common.h"
 #include "string.h"
+#include "array_list.h"
 struct cx_properties_config_s {
 /**
 * The key/value delimiter that shall be used.
 * This is '=' by default.
 /**
 * The character, when appearing at the end of a line, continues that line.
 * This is '\' by default.
 */
-char continuation;
+// char continuation; // TODO: line continuation in properties
 /**
 * The first comment character.
 * This is '#' by default.
 */
 CX_PROPERTIES_INCOMPLETE_DATA,
 /**
 * Input buffer is \c NULL.
 */
 CX_PROPERTIES_NULL_INPUT,
+/**
+* The line contains a delimiter, but no key.
+*/
+CX_PROPERTIES_INVALID_EMPTY_KEY,
+/**
+* The line contains data, but no delimiter.
+*/
+CX_PROPERTIES_INVALID_MISSING_DELIMITER,
+/**
+* More internal buffer was needed, but could not be allocated.
+*/
+CX_PROPERTIES_BUFFER_ALLOC_FAILED,
 };
 /**
 * Interface for working with properties data.
 */
 * The text buffer.
 */
 const char *text;
 /**
-* Length of the text buffer.
+* Size of the text buffer.
 */
-size_t text_len;
+size_t text_size;
 /**
 * Position in the text buffer.
 */
 size_t text_pos;
+/**
+* Temporary internal buffer.
+*/
+char *buf;
+/**
+* Size of the internal buffer.
+*/
+size_t buf_size;
+/**
+* Capacity of the internal buffer.
+*/
+size_t buf_capacity;
+/**
+* Internal flags.
+*/
+int flags;
 };
 /**
 * Typedef for the properties interface.
 */
 typedef struct cx_properties_s CxProperties;
 /**
-* Initialize a properties parser.
+* Initialize a properties interface.
 *
 * @param prop the properties interface
 * @param config the properties configuration
 * @see cxPropertiesInitDefault()
 */
 __attribute__((__nonnull__))
-static inline void cxPropertiesInit(
+void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);
-CxProperties *prop,
-CxPropertiesConfig config
+/**
-) {
+* Destroys the properties interface.
-prop->config = config;
+*
-prop->text = NULL;
+* \note Even when you are certain that you did not use the interface in a
-}
+* way that caused a memory allocation, you should call this function anyway.
+* Future versions of the library might add features that need additional memory
+* and you really don't want to search the entire code where you might need
+* add call to this function.
+*
+* @param prop the properties interface
+*/
+__attribute__((__nonnull__))
+void cxPropertiesDestroy(CxProperties *prop);
 /**
 * Initialize a properties parser with the default configuration.
 *
 * @param prop the properties interface
 * @param prop the properties interface
 * @param buf a pointer to data
 * @param len the length of the data
 */
 __attribute__((__nonnull__))
-static inline void cxPropertiesInput(
+void cxPropertiesInput(
 CxProperties *prop,
-const void *buf,
+const char *buf,
 size_t len
-) {
+);
-prop->text = buf;
-prop->text_len = len;
+/**
-prop->text_pos = 0;
+* Sets a new input buffer after copying the current unprocessed data
-}
+* to a temporary buffer.
+*
+* This temporary buffer is allocated on the heap, unless you specified
+* a buffer on the stack with #cxPropertiesUseStack().
+* In that case, the stack buffer is used, until the capacity is not sufficient
+* anymore.
+*
+* When this function is called without any unprocessed data that needs to be
+* copied, it behaves exactly as #cxPropertiesInput().
+*
+* @param prop the properties interface
+* @param buf a pointer to data
+* @param len the length of the data
+* @return non-zero when a memory allocation was necessary but failed
+*/
+__attribute__((__nonnull__))
+int cxPropertiesFill(
+CxProperties *prop,
+const char *buf,
+size_t len
+);
+/**
+* Specifies stack memory that shall be used by #cxPropertiesFill().
+*
+* @param prop the properties interface
+* @param buf a pointer to stack memory
+* @param capacity the capacity of the stack memory
+*/
+void cxPropertiesUseStack(
+CxProperties *prop,
+char *buf,
+size_t capacity
+);
 /**
 * Retrieves the next key/value-pair.
 *
-* This function returns zero as long as there are key/value-pairs
+* This function returns zero as long as there are key/value-pairs found.
-* found. If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA
+* If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
-* is returned. You may refill the input buffer with cxPropertiesInput().
+*
-*
+* When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
-* When an invalid line is encountered, #CX_PROPERTIES_INVALID_LINE is returned
+* returned and the position of the input buffer will be the start of the
-* and the position of the input buffer will be the start of the affected line.
+* affected line. You can then add more data with #cxPropertiesFill().
 *
-* @param prop the properties interface
+* \attention The returned strings will point into a buffer that might not be
-* @param name a pointer to the cxstring that shall contain the property name
+* available later. It is strongly recommended to copy the strings for further
+* use.
+*
+* @param prop the properties interface
+* @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 Nonzero, if a key/value-pair was successfully retrieved
+* @return the status code as defined above
-* @see ucx_properties_fill()
+* @see cxPropertiesFill()
 */
 enum cx_properties_status cxPropertiesNext(
 CxProperties *prop,
-cxstring *name,
+cxstring *key,
 cxstring *value
 );
 #endif // UCX_PROPERTIES

Mercurial > hg > ucx / file comparison

comparison: src/cx/properties.h

src/cx/properties.h