properties.h File Reference

Interface for parsing data from properties files. More...

#include "common.h"
#include "string.h"
#include "map.h"
#include "buffer.h"
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	cx_properties_config_s
	Configures the expected characters for the properties parser. More...
struct	cx_properties_s
	Interface for working with properties data. More...
struct	cx_properties_sink_s
	Defines a sink for k/v-pairs. More...
struct	cx_properties_source_s
	Defines a properties source. More...

Macros
#define	cxPropertiesInitDefault(prop)    cxPropertiesInit(prop, cx_properties_config_default)
	Initialize a properties parser with the default configuration.
#define	cxPropertiesFill(prop, str)
	Fills the input buffer with data.

Typedefs
typedef struct cx_properties_config_s	CxPropertiesConfig
	Typedef for the properties config.
typedef enum cx_properties_status	CxPropertiesStatus
	Typedef for the properties status enum.
typedef struct cx_properties_s	CxProperties
	Typedef for the properties interface.
typedef struct cx_properties_sink_s	CxPropertiesSink
	Typedef for a properties sink.
typedef int(*	cx_properties_sink_func) (CxProperties *prop, CxPropertiesSink *sink, cxstring key, cxstring value)
	A function that consumes a k/v-pair in a sink.
typedef struct cx_properties_source_s	CxPropertiesSource
	Typedef for a properties source.
typedef int(*	cx_properties_read_func) (CxProperties *prop, CxPropertiesSource *src, cxstring *target)
	A function that reads data from a source.
typedef int(*	cx_properties_read_init_func) (CxProperties *prop, CxPropertiesSource *src)
	A function that may initialize additional memory for the source.
typedef void(*	cx_properties_read_clean_func) (CxProperties *prop, CxPropertiesSource *src)
	A function that cleans memory initialized by the read_init_func.

Enumerations
enum	cx_properties_status {   CX_PROPERTIES_NO_ERROR , CX_PROPERTIES_NO_DATA , CX_PROPERTIES_INCOMPLETE_DATA , CX_PROPERTIES_OK ,   CX_PROPERTIES_NULL_INPUT , CX_PROPERTIES_INVALID_EMPTY_KEY , CX_PROPERTIES_INVALID_MISSING_DELIMITER , CX_PROPERTIES_BUFFER_ALLOC_FAILED ,   CX_PROPERTIES_READ_INIT_FAILED , CX_PROPERTIES_READ_FAILED , CX_PROPERTIES_SINK_FAILED }
	Status codes for the properties interface. More...

Functions
void	cxPropertiesInit (CxProperties *prop, CxPropertiesConfig config)
	Initialize a properties interface.
void	cxPropertiesDestroy (CxProperties *prop)
	Destroys the properties interface.
static void	cxPropertiesReset (CxProperties *prop)
	Destroys and re-initializes the properties interface.
int	cxPropertiesFilln (CxProperties *prop, const char *buf, size_t len)
	Fills the input buffer with data.
static int	cx_properties_fill_cxstr (CxProperties *prop, cxstring str)
	Fills the input buffer with data.
static int	cx_properties_fill_mutstr (CxProperties *prop, cxmutstr str)
	Fills the input buffer with data.
static int	cx_properties_fill_str (CxProperties *prop, const char *str)
	Fills the input buffer with data.
void	cxPropertiesUseStack (CxProperties *prop, char *buf, size_t capacity)
	Specifies stack memory that shall be used as internal buffer.
CxPropertiesStatus	cxPropertiesNext (CxProperties *prop, cxstring *key, cxstring *value)
	Retrieves the next key/value-pair.
CxPropertiesSink	cxPropertiesMapSink (CxMap *map)
	Creates a properties sink for an UCX map.
CxPropertiesSource	cxPropertiesStringSource (cxstring str)
	Creates a properties source based on an UCX string.
CxPropertiesSource	cxPropertiesCstrnSource (const char *str, size_t len)
	Creates a properties source based on C string with the specified length.
CxPropertiesSource	cxPropertiesCstrSource (const char *str)
	Creates a properties source based on a C string.
CxPropertiesSource	cxPropertiesFileSource (FILE *file, size_t chunk_size)
	Creates a properties source based on an FILE.
CxPropertiesStatus	cxPropertiesLoad (CxProperties *prop, CxPropertiesSink sink, CxPropertiesSource source)
	Loads properties data from a source and transfers it to a sink.

Variables
const CxPropertiesConfig	cx_properties_config_default
	Default properties configuration.

Detailed Description

Interface for parsing data from properties files.

Author

Mike Becker

Olaf Wintermann

Copyright

2-Clause BSD License

Macro Definition Documentation

cxPropertiesFill

#define cxPropertiesFill	(		prop,
			str )

Value:

    _Generic((str), \
    cxstring: cx_properties_fill_cxstr,             \
    cxmutstr: cx_properties_fill_mutstr,            \
    char*: cx_properties_fill_str,                  \
    const char*: cx_properties_fill_str)            \
    (prop, str)

Fills the input buffer with data.

After calling this function, you can parse the data by calling cxPropertiesNext().

Attention

The properties interface tries to avoid allocations. When you use this function and cxPropertiesNext() interleaving, no allocations are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxPropertiesNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

prop	the properties interface
str	the text to fill in

Return values

zero	success
non-zero	a memory allocation was necessary but failed

See also

cxPropertiesFilln()

cxPropertiesInitDefault

#define cxPropertiesInitDefault

(

prop

)

cxPropertiesInit(prop, cx_properties_config_default)

Initialize a properties parser with the default configuration.

Parameters

prop	(CxProperties*) the properties interface

See also

cxPropertiesInit()

Typedef Documentation

cx_properties_read_clean_func

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

A function that cleans memory initialized by the read_init_func.

Parameters

prop	the properties interface that wants to read from the source
src	the source

cx_properties_read_func

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

A function that reads data from a source.

When the source is depleted, implementations SHALL provide an empty string in the 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.

Parameters

prop	the properties interface that wants to read from the source
src	the source
target	a string buffer where the read data shall be stored

Return values

zero	success
non-zero	reading the data failed

cx_properties_read_init_func

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

A function that may initialize additional memory for the source.

Parameters

prop	the properties interface that wants to read from the source
src	the source

Return values

zero	initialization was successful
non-zero	otherwise

cx_properties_sink_func

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

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.

Parameters

prop	the properties interface that wants to sink a k/v-pair
sink	the sink
key	the key
value	the value

Return values

zero	success
non-zero	sinking the k/v-pair failed

Enumeration Type Documentation

cx_properties_status

enum cx_properties_status

Status codes for the properties interface.

Enumerator
CX_PROPERTIES_NO_ERROR	Everything is fine.
CX_PROPERTIES_NO_DATA	The input buffer does not contain more data.
CX_PROPERTIES_INCOMPLETE_DATA	The input ends unexpectedly. 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_OK	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 CX_PROPERTIES_OK. A "good" status means, that you can refill data and continue parsing.
CX_PROPERTIES_NULL_INPUT	Input buffer is NULL.
CX_PROPERTIES_INVALID_EMPTY_KEY	The line contains a delimiter, but no key.
CX_PROPERTIES_INVALID_MISSING_DELIMITER	The line contains data, but no delimiter.
CX_PROPERTIES_BUFFER_ALLOC_FAILED	More internal buffer was needed, but could not be allocated.
CX_PROPERTIES_READ_INIT_FAILED	Initializing the properties source failed. See also cx_properties_read_init_func
CX_PROPERTIES_READ_FAILED	Reading from a properties source failed. See also cx_properties_read_func
CX_PROPERTIES_SINK_FAILED	Sinking a k/v-pair failed. See also cx_properties_sink_func

Function Documentation

cx_properties_fill_cxstr()

static int cx_properties_fill_cxstr ( CxProperties * prop, cxstring str )

inlinestatic

Fills the input buffer with data.

After calling this function, you can parse the data by calling cxPropertiesNext().

Attention

The properties interface tries to avoid allocations. When you use this function and cxPropertiesNext() interleaving, no allocations are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxPropertiesNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

prop	the properties interface
str	the text to fill in

Return values

zero	success
non-zero	a memory allocation was necessary but failed

See also

cxPropertiesFilln()

cx_properties_fill_mutstr()

static int cx_properties_fill_mutstr ( CxProperties * prop, cxmutstr str )

inlinestatic

Fills the input buffer with data.

After calling this function, you can parse the data by calling cxPropertiesNext().

Attention

The properties interface tries to avoid allocations. When you use this function and cxPropertiesNext() interleaving, no allocations are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxPropertiesNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

prop	the properties interface
str	the text to fill in

Return values

zero	success
non-zero	a memory allocation was necessary but failed

See also

cxPropertiesFilln()

cx_properties_fill_str()

static int cx_properties_fill_str ( CxProperties * prop, const char * str )

inlinestatic

Fills the input buffer with data.

After calling this function, you can parse the data by calling cxPropertiesNext().

Attention

The properties interface tries to avoid allocations. When you use this function and cxPropertiesNext() interleaving, no allocations are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxPropertiesNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

prop	the properties interface
str	the text to fill in

Return values

zero	success
non-zero	a memory allocation was necessary but failed

See also

cxPropertiesFilln()

cxPropertiesCstrnSource()

CxPropertiesSource cxPropertiesCstrnSource	(	const char *	str,
		size_t	len )

Creates a properties source based on C string with the specified length.

Parameters

str	the string
len	the length

Returns

the properties source

See also

cxPropertiesLoad()

cxPropertiesCstrSource()

CxPropertiesSource cxPropertiesCstrSource

(

const char *

str

)

Creates a properties source based on a C string.

The length will be determined with strlen(), so the string MUST be zero-terminated.

Parameters

str	the string

Returns

the properties source

See also

cxPropertiesLoad()

cxPropertiesDestroy()

void cxPropertiesDestroy

(

CxProperties *

prop

)

Destroys the properties interface.

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.

Parameters

prop	the properties interface

cxPropertiesFileSource()

CxPropertiesSource cxPropertiesFileSource	(	FILE *	file,
		size_t	chunk_size )

Creates a properties source based on an FILE.

Parameters

file	the file
chunk_size	how many bytes may be read in one operation

Returns

the properties source

See also

cxPropertiesLoad()

cxPropertiesFilln()

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

Fills the input buffer with data.

After calling this function, you can parse the data by calling cxPropertiesNext().

Remarks

The properties interface tries to avoid allocations. When you use this function and cxPropertiesNext() interleaving, no allocations are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxPropertiesNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

prop	the properties interface
buf	a pointer to the data
len	the length of the data

Return values

zero	success
non-zero	a memory allocation was necessary but failed

See also

cxPropertiesFill()

cxPropertiesInit()

void cxPropertiesInit	(	CxProperties *	prop,
		CxPropertiesConfig	config )

Initialize a properties interface.

Parameters

prop	the properties interface
config	the properties configuration

See also

cxPropertiesInitDefault()

cxPropertiesLoad()

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

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.

Parameters

prop	the properties interface
sink	the sink
source	the source

Return values

CX_PROPERTIES_NO_ERROR	(zero) a key/value pair was found
CX_PROPERTIES_READ_INIT_FAILED	initializing the source failed
CX_PROPERTIES_READ_FAILED	reading from the source failed
CX_PROPERTIES_SINK_FAILED	sinking the properties into the sink failed
CX_PROPERTIES_NO_DATA	the source did not provide any key/value pairs
CX_PROPERTIES_INCOMPLETE_DATA	the source did not provide enough data
CX_PROPERTIES_INVALID_EMPTY_KEY	the properties data contains an illegal empty key
CX_PROPERTIES_INVALID_MISSING_DELIMITER	the properties data contains a line without delimiter
CX_PROPERTIES_BUFFER_ALLOC_FAILED	an internal allocation was necessary but failed

cxPropertiesMapSink()

CxPropertiesSink cxPropertiesMapSink

(

CxMap *

map

)

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 data of the sink.

Parameters

map	the map that shall consume the k/v-pairs.

Returns

the sink

See also

cxPropertiesLoad()

cxPropertiesNext()

CxPropertiesStatus cxPropertiesNext	(	CxProperties *	prop,
		cxstring *	key,
		cxstring *	value )

Retrieves the next key/value-pair.

This function returns zero as long as there are key/value-pairs found. 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().

Remarks

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 available later. It is strongly recommended to copy the strings for further use.

Parameters

prop	the properties interface
key	a pointer to the cxstring that shall contain the property name
value	a pointer to the cxstring that shall contain the property value

Return values

CX_PROPERTIES_NO_ERROR	(zero) a key/value pair was found
CX_PROPERTIES_NO_DATA	there is no (more) data in the input buffer
CX_PROPERTIES_INCOMPLETE_DATA	the data in the input buffer is incomplete (fill more data and try again)
CX_PROPERTIES_NULL_INPUT	the input buffer was never filled
CX_PROPERTIES_INVALID_EMPTY_KEY	the properties data contains an illegal empty key
CX_PROPERTIES_INVALID_MISSING_DELIMITER	the properties data contains a line without delimiter
CX_PROPERTIES_BUFFER_ALLOC_FAILED	an internal allocation was necessary but failed

cxPropertiesReset()

static void cxPropertiesReset ( CxProperties * prop )

inlinestatic

Destroys and re-initializes the properties interface.

You might want to use this, to reset the parser after encountering a syntax error.

Parameters

prop	the properties interface

cxPropertiesStringSource()

CxPropertiesSource cxPropertiesStringSource

(

cxstring

str

)

Creates a properties source based on an UCX string.

Parameters

str	the string

Returns

the properties source

See also

cxPropertiesLoad()

cxPropertiesUseStack()

void cxPropertiesUseStack	(	CxProperties *	prop,
		char *	buf,
		size_t	capacity )

Specifies stack memory that shall be used as internal buffer.

Parameters

prop	the properties interface
buf	a pointer to stack memory
capacity	the capacity of the stack memory