LibGGZ: Configuration file parsing

Configuration file parsing begins by calling ggz_conf_parse() to open a config file. The file can be created automatically if GGZ_CONF_CREATE is specified. The returned handle uniquely identifies the configuration file, so multiple files can be open at one time.

If the same configuration file is opened multiple times, the original handle will be returned and only one copy will be retained within memory. One use of this feature is that a file may be opened read only initially and later have writing enabled by merely reparsing the file using the same pathname. Note that this feature can be fooled if the same file is opened using different pathnames. Chaos may or may not result in this case, and it is considered a feature not a bug.

Values are stored using a system of section and keys. A key must be unique within a section (you cannot store both an integer and a string under the same key. Section and key names may contain any characters (including whitespace) other than an equals sign. Although keys may not have leading or trailing whitespace, section names may. It is suggested that any whitespace (other than possibly internal spaces) be avoided when specifying section and key names. Alphabetic case is preserved, and must be matched.

An important caveat to remember when using the configuration functions is that writing a value only caches the value in memory. In order to write the values to the physical file, ggz_conf_commit() must be called at some point. This makes writing multiple values in rapid succession more efficient, as the entire file must be regenerated in order to be written to the flat-file format of the configuration file.

The string and list reading functions return dynamically allocated memory to the caller. The user is responsible for calling ggz_free() on this memory when they no longer need the returned values.

All memory used internally by the configuration functions will be released when ggz_conf_cleanup() is called. Note that this does NOT commit any changes made to the configuration files. The user is expected to call this at program termination, but it may be called at any time earlier than termination and new files may be subsequently opened.

Define Documentation

#define GGZ_CONF_DEBUG "ggz_conf"

Debugging type for config-file debugging.

See also:: ggz_debug_enable

Enumeration Type Documentation

enum GGZConfType

Specifies the mode for opening a configuration file.

See also:: ggz_conf_parse()

Enumerator:

GGZ_CONF_RDONLY	Read only.
GGZ_CONF_RDWR	Read and write.
GGZ_CONF_CREATE	Create file.

Function Documentation

void ggz_conf_cleanup ( void )

Closes all open configuration files.

Note:: This does not automatically commit changed values. Any non-committed values written will be lost.

void ggz_conf_close ( int handle )

Closes one configuration file.

Note:: The same warning as for ggz_conf_cleanup() applies here.

int ggz_conf_parse	(	const char *	path,
		const GGZConfType	options
	)

Opens a configuration file and parses the variables so they can be retrieved with the access functions.

Parameters:

	path	A string specifying the filename to be parsed
	options	An or'ed set of GGZConfType option bits

Returns:: An integer configuration file handle or -1 on error

See also:: GGZConfType

int ggz_conf_commit ( int handle )

Commits any changed variables to the configuration file.

The configuration file remains open and may continue to be written to.

Parameters:

handle

A valid handle returned by ggz_conf_parse()

Returns:: 0 if successful, -1 on failure

int ggz_conf_write_string	(	int	handle,
		const char *	section,
		const char *	key,
		const char *	value
	)

Writes a string value to a section and key in an open configuration file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to write to
	key	A string variable key name to write to
	value	The string value to write

Returns:: 0 if successful, -1 on failure

int ggz_conf_write_int	(	int	handle,
		const char *	section,
		const char *	key,
		int	value
	)

Writes an integer value to a section and key in an open configuration file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to write to
	key	A string variable key name to write to
	value	The integer value to write

Returns:: 0 if successful, -1 on failure

int ggz_conf_write_list	(	int	handle,
		const char *	section,
		const char *	key,
		int	argc,
		char **	argv
	)

Writes a list of string values to a section and key in an open configuration file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to write to
	key	A string variable key name to write to
	argc	The number of string array entries in argv
	argv	An array of strings to create a list from

Returns:: 0 if successful, -1 on failure

char* ggz_conf_read_string	(	int	handle,
		const char *	section,
		const char *	key,
		const char *	def
	)

Reads a string value from an open configuration file.

If the section/key combination is not found, the default entry is returned.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to read from
	key	A string variable key name to read from
	def	A value to be returned if the entry does not exist (may be NULL)

Returns:: A dynamically allocated copy of the stored (or default) value or NULL

Note:: The copy is allocated via a standard ggz_malloc() call and the caller is expected to be responsible for calling ggz_free() on the returned value when they no longer need the value. No memory is allocated if a default value of NULL is returned.

int ggz_conf_read_int	(	int	handle,
		const char *	section,
		const char *	key,
		int	def
	)

Reads an integer value from an open configuration file.

If the section/key combination is not found, the default entry is returned.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to read from
	key	A string variable key name to read from
	def	A value to be returned if the entry does not exist

Returns:: The integer value stored in the configuration file, or the default

int ggz_conf_read_list	(	int	handle,
		const char *	section,
		const char *	key,
		int *	argcp,
		char ***	argvp
	)

Reads a list of string values from an open configuration file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to read from
	key	A string variable key name to read from
	argcp	A pointer to an integer which will receive the number of list entries read
	argvp	A pointer to a string array. This will receive a value pointing to a dynamically allocated array of string values. The list will be NULL-terminated.

Returns:: 0 on success, -1 on failure

Note:: The array is allocated via standard ggz_malloc() calls and the caller is expected to be responsible for calling ggz_free() on the string values and the associated array structure when they no longer need the list. If the section/key combination is not found -1 will be returned, *argcp is set to a value of zero, no memory will be allocated, and *argvp will be set to NULL.

int ggz_conf_remove_section	(	int	handle,
		const char *	section
	)

This will remove an entire section and all its associated keys from a configuration file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name to remove

Returns:: 0 on success, -1 on failure

int ggz_conf_remove_key	(	int	handle,
		const char *	section,
		const char *	key
	)

This will remove a single key from a configuration file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name the key is located in
	key	A string key name to remove

Returns:: 0 on success, -1 on failure

int ggz_conf_get_sections	(	int	handle,
		int *	argcp,
		char ***	argvp
	)

This function returns a list of all sections in a config file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	argcp	A pointer to an integer which will receive the number of sections in the configuration file
	argvp	A pointer to a string array. This will receive a value pointing to a dynamically allocated array of string values. This list is NOT NULL terminated.

Returns:: 0 on success, -1 on failure

Note:: The array is allocated via standard ggz_malloc() calls and the caller is expected to be responsible for calling ggz_free() on the string values and the associated array structure when they no longer need the list.

int ggz_conf_get_keys	(	int	handle,
		const char *	section,
		int *	argcp,
		char ***	argvp
	)

This function returns a list of all keys within a section in a config file.

Parameters:

	handle	A valid handle returned by ggz_conf_parse()
	section	A string section name
	argcp	A pointer to an integer which will receive the number of lists within section in the configuration file
	argvp	A pointer to a string array. This will receive a value pointing to a dynamically allocated array of string values. This list is NOT NULL terminated.

Returns:: 0 on success, -1 on failure

Note:: The array is allocated via standard ggz_malloc() calls and the caller is expected to be responsible for calling ggz_free() on the string values and the associated array structure when they no longer need the list.

Configuration file parsing

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation


Defines
#define	GGZ_CONF_DEBUG "ggz_conf"
	Debugging type for config-file debugging.
Enumerations
enum	GGZConfType { GGZ_CONF_RDONLY = ((unsigned char) 0x01), GGZ_CONF_RDWR = ((unsigned char) 0x02), GGZ_CONF_CREATE = ((unsigned char) 0x04) }
	Specifies the mode for opening a configuration file. More...
Functions
void	ggz_conf_cleanup (void)
	Closes all open configuration files.
void	ggz_conf_close (int handle)
	Closes one configuration file.
int	ggz_conf_parse (const char *path, const GGZConfType options)
	Opens a configuration file and parses the variables so they can be retrieved with the access functions.
int	ggz_conf_commit (int handle)
	Commits any changed variables to the configuration file.
int	ggz_conf_write_string (int handle, const char section, const char key, const char *value)
	Writes a string value to a section and key in an open configuration file.
int	ggz_conf_write_int (int handle, const char section, const char key, int value)
	Writes an integer value to a section and key in an open configuration file.
int	ggz_conf_write_list (int handle, const char section, const char key, int argc, char **argv)
	Writes a list of string values to a section and key in an open configuration file.
char *	ggz_conf_read_string (int handle, const char section, const char key, const char *def)
	Reads a string value from an open configuration file.
int	ggz_conf_read_int (int handle, const char section, const char key, int def)
	Reads an integer value from an open configuration file.
int	ggz_conf_read_list (int handle, const char section, const char key, int argcp, char **argvp)
	Reads a list of string values from an open configuration file.
int	ggz_conf_remove_section (int handle, const char *section)
	This will remove an entire section and all its associated keys from a configuration file.
int	ggz_conf_remove_key (int handle, const char section, const char key)
	This will remove a single key from a configuration file.
int	ggz_conf_get_sections (int handle, int argcp, char **argvp)
	This function returns a list of all sections in a config file.
int	ggz_conf_get_keys (int handle, const char section, int argcp, char ***argvp)
	This function returns a list of all keys within a section in a config file.