dbutils: comparison ucx/cx/properties.h

-:862ab606ee06
+:04c9f8d8f03b
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 /**
-* \file properties.h
+* @file properties.h
-* \brief Interface for parsing data from properties files.
+* @brief Interface for parsing data from properties files.
-* \author Mike Becker
+* @author Mike Becker
-* \author Olaf Wintermann
+* @author Olaf Wintermann
-* \copyright 2-Clause BSD License
+* @copyright 2-Clause BSD License
 */
 #ifndef UCX_PROPERTIES_H
 #define UCX_PROPERTIES_H
 * This is '=' by default.
 */
 char delimiter;
 /**
+* The first comment character.
+* This is '#' by default.
+*/
+char comment1;
+/**
+* The second comment character.
+* This is not set by default.
+*/
+char comment2;
+/**
+* The third comment character.
+* This is not set by default.
+*/
+char comment3;
+/*
 * The character, when appearing at the end of a line, continues that line.
 * This is '\' by default.
 */
-// char continuation; // TODO: line continuation in properties
+/**
+* Reserved for future use.
-/**
+*/
-* The first comment character.
+char continuation;
-* This is '#' by default.
-*/
-char comment1;
-/**
-* The second comment character.
-* This is not set by default.
-*/
-char comment2;
-/**
-* The third comment character.
-* This is not set by default.
-*/
-char comment3;
 };
 /**
 * Typedef for the properties config.
 */
 typedef struct cx_properties_config_s CxPropertiesConfig;
 /**
 * Default properties configuration.
 */
+cx_attr_export
 extern const CxPropertiesConfig cx_properties_config_default;
 /**
 * Status codes for the properties interface.
 */
 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.
+* 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.
+* Input buffer is @c NULL.
 */
 CX_PROPERTIES_NULL_INPUT,
 /**
 * The line contains a delimiter, but no key.
 */
 *
 * @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
+* @retval zero success
+* @retval non-zero sinking the k/v-pair failed
 */
 cx_attr_nonnull
 typedef int(*cx_properties_sink_func)(
 CxProperties *prop,
 CxPropertiesSink *sink,
 /**
 * 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.
+* 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
+* @retval zero success
+* @retval non-zero reading the data failed
 */
 cx_attr_nonnull
 typedef int(*cx_properties_read_func)(
 CxProperties *prop,
 CxPropertiesSource *src,
 /**
 * 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
+* @retval zero initialization was successful
+* @retval non-zero otherwise
 */
 cx_attr_nonnull
 typedef int(*cx_properties_read_init_func)(
 CxProperties *prop,
 CxPropertiesSource *src
 * @param prop the properties interface
 * @param config the properties configuration
 * @see cxPropertiesInitDefault()
 */
 cx_attr_nonnull
+cx_attr_export
 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);
 /**
 * Destroys the properties interface.
 *
-* \note Even when you are certain that you did not use the interface in a
+* @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
 */
 cx_attr_nonnull
+cx_attr_export
 void cxPropertiesDestroy(CxProperties *prop);
 /**
 * Destroys and re-initializes the properties interface.
 *
 }
 /**
 * Initialize a properties parser with the default configuration.
 *
-* @param prop the properties interface
+* @param prop (@c CxProperties*) the properties interface
 * @see cxPropertiesInit()
 */
 #define cxPropertiesInitDefault(prop) \
 cxPropertiesInit(prop, cx_properties_config_default)
 * an allocation of a new buffer and copying the previous contents.
 *
 * @param prop the properties interface
 * @param buf a pointer to the data
 * @param len the length of the data
-* @return non-zero when a memory allocation was necessary but failed
+* @retval zero success
+* @retval non-zero a memory allocation was necessary but failed
 * @see cxPropertiesFill()
 */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
+cx_attr_export
 int cxPropertiesFilln(
 CxProperties *prop,
 const char *buf,
 size_t len
 );
 * the additional data is appended - inevitably leading to
 * an allocation of a new buffer and copying the previous contents.
 *
 * @param prop the properties interface
 * @param str the text to fill in
-* @return non-zero when a memory allocation was necessary but failed
+* @retval zero success
+* @retval non-zero a memory allocation was necessary but failed
 * @see cxPropertiesFilln()
 */
 #define cxPropertiesFill(prop, str) _Generic((str), \
 cxstring: cx_properties_fill_cxstr,             \
 cxmutstr: cx_properties_fill_mutstr,            \
 * @param prop the properties interface
 * @param buf a pointer to stack memory
 * @param capacity the capacity of the stack memory
 */
 cx_attr_nonnull
+cx_attr_export
 void cxPropertiesUseStack(
 CxProperties *prop,
 char *buf,
 size_t capacity
 );
 * If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
 *
 * When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
 * returned, and you can add more data with #cxPropertiesFill().
 *
-* \remark The incomplete line will be stored in an internal buffer, which is
+* @remark The incomplete line will be stored in an internal buffer, which is
 * allocated on the heap, by default. If you want to avoid allocations,
 * you can specify sufficient space with cxPropertiesUseStack() after
 * initialization with cxPropertiesInit().
 *
-* \attention The returned strings will point into a buffer that might not be
+* @attention The returned strings will point into a buffer that might not be
 * 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 the status code as defined above
+* @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
-* @see cxPropertiesFill()
+* @retval CX_PROPERTIES_NO_DATA there is no (more) data in the input buffer
+* @retval CX_PROPERTIES_INCOMPLETE_DATA the data in the input buffer is incomplete
+* (fill more data and try again)
+* @retval CX_PROPERTIES_NULL_INPUT the input buffer was never filled
+* @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
+* @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
+* @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
 */
 cx_attr_nonnull
 cx_attr_nodiscard
+cx_attr_export
 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.
+* 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()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
+cx_attr_export
 CxPropertiesSink cxPropertiesMapSink(CxMap *map);
 /**
 * Creates a properties source based on an UCX string.
 *
 * @param str the string
 * @return the properties source
 * @see cxPropertiesLoad()
 */
 cx_attr_nodiscard
+cx_attr_export
 CxPropertiesSource cxPropertiesStringSource(cxstring str);
 /**
 * Creates a properties source based on C string with the specified length.
 *
 * @see cxPropertiesLoad()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_access_r(1, 2)
+cx_attr_export
 CxPropertiesSource cxPropertiesCstrnSource(const char *str, size_t len);
 /**
 * Creates a properties source based on a C string.
 *
 * @see cxPropertiesLoad()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_cstr_arg(1)
+cx_attr_export
 CxPropertiesSource cxPropertiesCstrSource(const char *str);
 /**
 * Creates a properties source based on an FILE.
 *
 * @see cxPropertiesLoad()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_access_r(1)
+cx_attr_export
 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.
+* In case the source data ends unexpectedly, the #CX_PROPERTIES_INCOMPLETE_DATA
+* is returned. In that case you should call this function again with the same
+* sink and either an updated source or the same source if the source is able to
+* yield the missing 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
+* @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
-*/
+* @retval CX_PROPERTIES_READ_INIT_FAILED initializing the source failed
-cx_attr_nonnull
+* @retval CX_PROPERTIES_READ_FAILED reading from the source failed
+* @retval CX_PROPERTIES_SINK_FAILED sinking the properties into the sink failed
+* @retval CX_PROPERTIES_NO_DATA the source did not provide any key/value pairs
+* @retval CX_PROPERTIES_INCOMPLETE_DATA the source did not provide enough data
+* @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
+* @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
+* @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
+*/
+cx_attr_nonnull
+cx_attr_export
 CxPropertiesStatus cxPropertiesLoad(
 CxProperties *prop,
 CxPropertiesSink sink,
 CxPropertiesSource source
 );

Mercurial > hg > dbutils / file comparison

comparison: ucx/cx/properties.h

ucx/cx/properties.h