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

#include "common.h"
#include "string.h"
#include "map.h"
#include "buffer.h"

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...

Macros
#define	cxPropertiesInitDefault(prop)
	Initialize a properties parser with the default configuration.

#define	cxPropertiesFill(prop, str)
	Fills the input buffer with data.

#define	cxPropertiesLoad(allocator, filename, target, config)
	Loads properties from a file and inserts them into a map.

#define	cxPropertiesLoadDefault(allocator, filename, target)
	Loads properties from a file and inserts them into a map with a default config.

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.

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_FILE_ERROR , CX_PROPERTIES_MAP_ERROR }
	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.

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 (CxProperties *prop, cxstring str)
	Internal function, do not use.

void	cxPropertiesUseStack (CxProperties prop, char buf, size_t capacity)
	Specifies stack memory that shall be used as an internal buffer.

CxPropertiesStatus	cxPropertiesNext (CxProperties prop, cxstring key, cxstring *value)
	Retrieves the next key/value-pair.

CxPropertiesStatus	cx_properties_load (const CxAllocator allocator, cxstring filename, CxMap target, CxPropertiesConfig config)
	Internal function - use cxPropertiesLoad() instead.

Variables
const CxPropertiesConfig	cx_properties_config_default
	Default properties configuration.

const unsigned	cx_properties_load_buf_size
	The size of the stack memory that `cxPropertiesLoad()` will reserve with `cxPropertiesUseStack()`.

const unsigned	cx_properties_load_fill_size
	The size of the stack memory that `cxPropertiesLoad()` will use to read contents from the file.

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:

cx_properties_fill(prop, cx_strcast(str))

cx_properties_fill

static int cx_properties_fill(CxProperties *prop, cxstring str)

Internal function, do not use.

Definition properties.h:253

cx_strcast

#define cx_strcast(str)

Converts any string to a cxstring.

Definition string.h:393

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 )

Value:

cxPropertiesInit(prop, cx_properties_config_default)

cxPropertiesInit

void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config)

Initialize a properties interface.

cx_properties_config_default

const CxPropertiesConfig cx_properties_config_default

Default properties configuration.

Initialize a properties parser with the default configuration.

Parameters

prop	(`CxProperties*`) the properties interface

See also: cxPropertiesInit()

◆ cxPropertiesLoad

#define cxPropertiesLoad	(	allocator,
		filename,
		target,
		config )

Value:

cx_properties_load(allocator, cx_strcast(filename), target, config)

cx_properties_load

CxPropertiesStatus cx_properties_load(const CxAllocator *allocator, cxstring filename, CxMap *target, CxPropertiesConfig config)

Internal function - use cxPropertiesLoad() instead.

Loads properties from a file and inserts them into a map.

Entries are added to the map, possibly overwriting existing entries.

The map must either store pointers of type char*, or elements of type cxmutstr. Any other configuration is not supported.

Note: When the parser finds an error, all successfully parsed keys before the error are added to the map nonetheless.

Parameters

allocator	the allocator for the values that will be stored in the map
filename	(any string) the absolute or relative path to the file
target	(`CxMap*`) the map where the properties shall be added
config	the parser config

Return values

CX_PROPERTIES_NO_ERROR	(zero) at least one key/value pair was found
CX_PROPERTIES_NO_DATA	the file is syntactically OK, but does not contain properties
CX_PROPERTIES_INCOMPLETE_DATA	unexpected end of file
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
CX_PROPERTIES_FILE_ERROR	a file operation failed; depending on the system `errno` might be set
CX_PROPERTIES_MAP_ERROR	storing a key/value pair in the map failed

See also: cxPropertiesLoadDefault()

◆ cxPropertiesLoadDefault

#define cxPropertiesLoadDefault	(	allocator,
		filename,
		target )

Value:

cx_properties_load(allocator, cx_strcast(filename), target, cx_properties_config_default)

Loads properties from a file and inserts them into a map with a default config.

Entries are added to the map, possibly overwriting existing entries.

The map must either store pointers of type char*, or elements of type cxmutstr. Any other configuration is not supported.

Note: When the parser finds an error, all successfully parsed keys before the error are added to the map nonetheless.

Parameters

allocator	the allocator for the values that will be stored in the map
filename	(any string) the absolute or relative path to the file
target	(`CxMap*`) the map where the properties shall be added

Return values

CX_PROPERTIES_NO_ERROR	(zero) at least one key/value pair was found
CX_PROPERTIES_NO_DATA	the file is syntactically OK, but does not contain properties
CX_PROPERTIES_INCOMPLETE_DATA	unexpected end of file
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
CX_PROPERTIES_FILE_ERROR	a file operation failed; depending on the system `errno` might be set
CX_PROPERTIES_MAP_ERROR	storing a key/value pair in the map failed

See also: cxPropertiesLoad()

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_FILE_ERROR	A file operation failed. Only for cxPropertiesLoad(). It is system-specific if errno is set.
CX_PROPERTIES_MAP_ERROR	A map operation failed. Only for cxPropertiesLoad().

Function Documentation

◆ cx_properties_fill()

static int cx_properties_fill	(	CxProperties *	prop,
		cxstring	str )

inlinestatic

Internal function, do not use.

Parameters

prop	the properties interface
str	the text to fill in

Return values

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

◆ cx_properties_load()

CxPropertiesStatus cx_properties_load	(	const CxAllocator *	allocator,
		cxstring	filename,
		CxMap *	target,
		CxPropertiesConfig	config )

Internal function - use cxPropertiesLoad() instead.

Parameters

allocator	the allocator for the values
filename	the file name
target	the target map
config	the parser config

Returns: status code

◆ 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 to add a call to this function.

Parameters

prop	the properties interface

◆ 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()

◆ 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()

void cxPropertiesReset ( CxProperties * prop )

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

◆ cxPropertiesUseStack()

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

Specifies stack memory that shall be used as an internal buffer.

Parameters

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ cxPropertiesFill

◆ cxPropertiesInitDefault

◆ cxPropertiesLoad

◆ cxPropertiesLoadDefault

Enumeration Type Documentation

◆ cx_properties_status

Function Documentation

◆ cx_properties_fill()

◆ cx_properties_load()

◆ cxPropertiesDestroy()

◆ cxPropertiesFilln()

◆ cxPropertiesInit()

◆ cxPropertiesNext()

◆ cxPropertiesReset()

◆ cxPropertiesUseStack()