src/settings_parser.c File Reference

Parses and reads setting files (in key=value lines) into an internal linked list. More...

Data Structures
struct	sp_settings_tag
struct	sp_entry_tag
Functions
sp_settings_s *	sp_create_settings (void)
	Creates the initial settings structure file.
void	sp_free_settings (sp_settings_s **settings)
	Frees a sp_settings_s structure and all of its registered keys.
bool	sp_parse_file (sp_settings_s settings, const char path)
	Parses a file into the settings structure.
sp_settings_s *	sp_parse_file_adhoc (const char *path)
	Read a settings file, registering the keys as they're encountered.
sp_entry_s *	sp_register (sp_settings_s settings, const char key, const char defaultValue, sp_value_type_e type, const char comment, bool(validator)(void ))
	Add a key to the specified settings structure.
bool	sp_write_to_file (const sp_settings_s settings, const char path, const char *header)
	Writes a bunch of settings entries to a specified file.
sp_entry_s *	sp_find (sp_settings_s settings, const char key)
	Returns a entry from the settings structure based on the given key.
int	sp_set_value (sp_entry_s entry, const char value)
	Attempt to set the value of the entry based on its type.
const char *	sp_stringize_entry (const sp_entry_s *entry)
	Return the value as a string, regardless of type.
sp_value_type_e	sp_get_entry_type (const sp_entry_s *entry)
	Returns the entry type of the entry.
unsigned long int	sp_entry_as_ulint (const sp_entry_s entry, bool error)
	Returns the value of the entry.
const char *	sp_entry_as_string (const sp_entry_s entry, bool error)
	Returns the value of the entry.
float	sp_entry_as_float (const sp_entry_s entry, bool error)
	Returns the value of the entry.

Detailed Description

Parses and reads setting files (in key=value lines) into an internal linked list.

Date:: 21 Jan 2010

Author:: Zachary Sims <zacs7@users.sourceforge.net>

Module prefix: sp_

Id: settings_parser.c 215 2010-02-10 06:44:30Z zacs7

Function Documentation

sp_settings_s* sp_create_settings ( void )

Creates the initial settings structure file.

This must be called before anything is called on the sp_settings_s structure. The returned value must be freed with sp_free_settings() when done.

See also:: sp_free_settings()

Returns:: A sp_settings_s structure with no keys. On error, NULL is returned.

float sp_entry_as_float	(	const sp_entry_s *	entry,
		bool *	error
	)

Returns the value of the entry.

If the type of the entry is different then error will be set to true.

Parameters:

	entry	The entry to return the value of.
	error	A pointer to an error flag, set to true if the type is wrong. May be NULL.

Returns:: The value of the entry.

const char* sp_entry_as_string	(	const sp_entry_s *	entry,
		bool *	error
	)

Returns the value of the entry.

If the type of the entry is different then error will be set to true.

Parameters:

	entry	The entry to return the value of.
	error	A pointer to an error flag, set to true if the type is wrong. May be NULL.

Returns:: The value of the entry.

unsigned long int sp_entry_as_ulint	(	const sp_entry_s *	entry,
		bool *	error
	)

Returns the value of the entry.

If the type of the entry is different then error will be set to true.

Parameters:

	entry	The entry to return the value of.
	error	A pointer to an error flag, set to true if the type is wrong. May be NULL.

Returns:: The value of the entry.

sp_entry_s* sp_find	(	sp_settings_s *	settings,
		const char *	key
	)

Returns a entry from the settings structure based on the given key.

Note that case of the key is ignored.

See also:: sp_free_settings(); sp_register()

Parameters:

	settings	Settings structure to search.
	key	The key.

Returns:: The entry of the key. Otherwise, NULL is returned if the key couldn't be found.

void sp_free_settings ( sp_settings_s ** settings )

Frees a sp_settings_s structure and all of its registered keys.

See also:: sp_create_settings()

Parameters:

settings

The settings structure to free.

sp_value_type_e sp_get_entry_type ( const sp_entry_s * entry )

Returns the entry type of the entry.

Parameters:

entry

The entry to return the type of.

Returns:: The type of the entry.

bool sp_parse_file	(	sp_settings_s *	settings,
		const char *	path
	)

Parses a file into the settings structure.

The settings entries must have already been registered in the settings argument.

Parameters:

	settings	The settings structure, the keys and default values should be registered already.
	path	A full or relative path to the settings file to parse.

Returns:: true on success. On error, false is returned.

sp_settings_s* sp_parse_file_adhoc ( const char * path )

Read a settings file, registering the keys as they're encountered.

The returned sp_settings_s structure must be freed with sp_free_settings().

See also:: sp_free_settings().

Parameters:

path

A full or relative path to the settings file to parse.

Returns:: Non-NULL on success. On error, NULL is returned.

sp_entry_s* sp_register	(	sp_settings_s *	settings,
		const char *	key,
		const char *	defaultValue,
		sp_value_type_e	type,
		const char *	comment,
		bool()(void )	validator
	)

Add a key to the specified settings structure.

The entry must be freed with free_entry() or the entire sp_settings_s structure with sp_free_settings(). The value is initialy set to the default value.

See also:: free_entry(); sp_free_settings()

Parameters:

	settings	The settings structure to add things to.
	key	The settings key.
	defaultValue	The default value of the setting. Cannot be NULL.
	type	The type of value expected.
	comment	A description of the settings value, cannot be NULL.
	validator	A pointer to the function to use to further validate the value, called in called in addition to range checking. May be NULL. The value is passed as a void pointer to the validator, just cast to the expected type.

Returns:: A valid (Non-NULL) parser entry on success. On error, NULL is returned.

int sp_set_value	(	sp_entry_s *	entry,
		const char *	value
	)

Attempt to set the value of the entry based on its type.

The validator function of the entry is called if it is not NULL. If the validator function returns false then the default value will be used. Do not modify the value passed to the validator.

Parameters:

	entry	The entry.
	value	A string version of the value.

Returns:: On success, zero is returned.; On error, greater than zero is returned if the default value was used.; Otherwise less than zero is returned if the type is unknown.

const char* sp_stringize_entry ( const sp_entry_s * entry )

Return the value as a string, regardless of type.

Warning:: The value returned is not preserved between calls.

Parameters:

entry

The entry to return the stringized value of.

Returns:: A stringized value of the entry. On error, 'unknown type' is returned.

bool sp_write_to_file	(	const sp_settings_s *	settings,
		const char *	path,
		const char *	header
	)

Writes a bunch of settings entries to a specified file.

header is written at the start of the file specified by path.

See also:: sp_parse_file(); sp_create_settings(); sp_free_settings()

Returns:: true on success. On error, false is returned.

src/settings_parser.c File Reference

Data Structures

Functions

Detailed Description

Function Documentation