config.h File Reference

Interface for a lumiera configuration system (draft). More...

Go to the source code of this file.

Description

Interface for a lumiera configuration system (draft).

This configuration uses ini-style configuration files and supports some simple types. A mechanism for overlay / cascading was planned. After some debate it turned out that we had no clear vision regarding the scope of that effort: should this system also manage (layered) defaults? should it also be able to save user preferences? Anyway, development in that area stalled and never reached the level of just loading and parsing a simple file – yet this was not considered a roadblock and we agreed to revisit the topic when we've gained a better understanding of session storage and management of default values and user preferences.

Todo:

as of 2016, this code is not in any meaningful use

See also

lumiera::BasicSetup simple start-up configuration

http://lumiera.org/documentation/technical/vault/ConfigLoader.html ConfigLoader draft from 2008

Definition in file config.h.

#include "lib/error.h"
#include "lib/mutex.h"
#include "common/config-lookup.h"
#include "common/configitem.h"
#include <nobug.h>
#include <stdio.h>

Macros
#define	LUMIERA_CONFIG_KEY_CHARS   "abcdefghijklmnopqrstuvwxyz0123456789_."
#define	LUMIERA_CONFIG_ENV_CHARS   "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789__"
#define	LUMIERA_CONFIG_TYPES
	Supported high level types: TODO documenting.
#define	LUMIERA_CONFIG_TYPE(name, type)
#define	LUMIERA_CONFIG_TYPE(name, type)

Typedefs
typedef lumiera_config *	LumieraConfig

Classes
struct	lumiera_config

Functions
	LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX)
	LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX_KEY)
	LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX_VALUE)
	LUMIERA_ERROR_DECLARE (CONFIG_NO_ENTRY)
int	lumiera_config_init (const char *path)
	Initialise the configuration subsystem.
void	lumiera_config_destroy ()
	Destroys the configuration subsystem.
int	lumiera_config_load (const char *file)
int	lumiera_config_save ()
int	lumiera_config_purge (const char *filename)
void	lumiera_config_dump (FILE *out)
	Does a diagnostic dump of the whole config database.
const char *	lumiera_config_get (const char *key, const char **value)
const char *	lumiera_config_get_default (const char *key, const char **value)
LumieraConfigitem	lumiera_config_set (const char *key, const char *delim_value)
LumieraConfigitem	lumiera_config_setdefault (const char *line)
	Installs a default value for a config key.
LUMIERA_CONFIG_TYPES const char *	lumiera_config_wordlist_get_nth (const char *key, unsigned nth, const char *delims)
	Wordlists Wordlists are lists of single words delimited by any of " \t,;".
int	lumiera_config_wordlist_find (const char *key, const char *value, const char *delims)
	Find the index of a word in a wordlist.
const char *	lumiera_config_wordlist_replace (const char *key, const char *value, const char *subst1, const char *subst2, const char *delims)
	Universal word replacement function.
const char *	lumiera_config_wordlist_add (const char *key, const char *value, const char *delims)
	Add a word to the end of a wordlist if it doesn't exist already.
LUMIERA_CONFIG_TYPES int	lumiera_config_reset (const char *key)
int	lumiera_config_info (const char *key, const char **filename, unsigned *line)

Typedef Documentation

LumieraConfig

typedef lumiera_config* LumieraConfig

Definition at line 67 of file config.h.

Macro Definition Documentation

LUMIERA_CONFIG_KEY_CHARS

#define LUMIERA_CONFIG_KEY_CHARS   "abcdefghijklmnopqrstuvwxyz0123456789_."

Definition at line 50 of file config.h.

LUMIERA_CONFIG_ENV_CHARS

#define LUMIERA_CONFIG_ENV_CHARS   "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789__"

Definition at line 51 of file config.h.

LUMIERA_CONFIG_TYPES

#define LUMIERA_CONFIG_TYPES

Value:

  LUMIERA_CONFIG_TYPE(link, const char*)        \
  LUMIERA_CONFIG_TYPE(number, long long)        \
  LUMIERA_CONFIG_TYPE(real, long double)        \
  LUMIERA_CONFIG_TYPE(string, const char*)      \
  LUMIERA_CONFIG_TYPE(wordlist, const char*)    \
  LUMIERA_CONFIG_TYPE(word, const char*)        \
  LUMIERA_CONFIG_TYPE(bool, int)

Supported high level types: TODO documenting.

Definition at line 73 of file config.h.

LUMIERA_CONFIG_TYPE [1/2]

#define LUMIERA_CONFIG_TYPE	(		name,
			type
	)

Value:

  const char* \
  lumiera_config_##name##_get (const char* key, type* value);

Definition at line 196 of file config.h.

LUMIERA_CONFIG_TYPE [2/2]

#define LUMIERA_CONFIG_TYPE	(		name,
			type
	)

Value:

  LumieraConfigitem                                             \
  lumiera_config_##name##_set (const char* key, type* value);

Definition at line 196 of file config.h.

---

Class Documentation

lumiera_config_struct

struct lumiera_config_struct

Class Members
lumiera_config_lookup	keys
lumiera_configitem	defaults
lumiera_configitem	files
lumiera_configitem	TODO_unknown
lumiera_mutex	lock

Collaboration diagram for lumiera_config:

Function Documentation

LUMIERA_ERROR_DECLARE() [1/4]

LUMIERA_ERROR_DECLARE

(

CONFIG_SYNTAX

)

LUMIERA_ERROR_DECLARE() [2/4]

LUMIERA_ERROR_DECLARE

(

CONFIG_SYNTAX_KEY

)

LUMIERA_ERROR_DECLARE() [3/4]

LUMIERA_ERROR_DECLARE

(

CONFIG_SYNTAX_VALUE

)

LUMIERA_ERROR_DECLARE() [4/4]

LUMIERA_ERROR_DECLARE

(

CONFIG_NO_ENTRY

)

lumiera_config_init()

int lumiera_config_init

(

const char *

path

)

Initialise the configuration subsystem.

Parameters

path	search path for config files. Must be called only once

Definition at line 77 of file config.c.

References lumiera_config_defaults, lumiera_config_lookup_init(), lumiera_config_setdefault(), lumiera_configitem_init(), lumiera_global_config, lumiera_malloc(), lumiera_mutex_init(), and lumiera_tmpbuf_snprintf().

Referenced by Config::Config().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_destroy()

void lumiera_config_destroy

(

)

Destroys the configuration subsystem.

Subsequent calls are no-ops.

Definition at line 105 of file config.c.

References lumiera_config_lookup_destroy(), lumiera_configitem_destroy(), lumiera_free(), lumiera_global_config, lumiera_mutex_destroy(), and NULL.

Referenced by Config::~Config(), TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_load()

int lumiera_config_load

(

const char *

file

)

Definition at line 124 of file config.c.

lumiera_config_save()

int lumiera_config_save

(

)

Definition at line 134 of file config.c.

lumiera_config_purge()

int lumiera_config_purge

(

const char *

filename

)

Definition at line 143 of file config.c.

lumiera_config_dump()

void lumiera_config_dump

(

FILE *

out

)

Does a diagnostic dump of the whole config database.

Definition at line 303 of file config.c.

References LLIST_FOREACH, and lumiera_global_config.

lumiera_config_get()

const char * lumiera_config_get	(	const char *	key,
		const char **	value
	)

Definition at line 154 of file config.c.

References LUMIERA_CONFIG_ENV_CHARS, LUMIERA_CONFIG_KEY_CHARS, lumiera_config_lookup_item_find(), LUMIERA_ERROR_SET, LUMIERA_ERROR_SET_WARNING, lumiera_global_config, lumiera_tmpbuf_snprintf(), lumiera_tmpbuf_tr(), and NULL.

Referenced by lumiera_config_number_get(), lumiera_config_string_get(), lumiera_config_word_get(), lumiera_config_wordlist_add(), lumiera_config_wordlist_get(), lumiera_config_wordlist_replace(), TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_get_default()

const char * lumiera_config_get_default	(	const char *	key,
		const char **	value
	)

Definition at line 201 of file config.c.

References lumiera_config_lookup_item_tail_find(), lumiera_global_config, and NULL.

Here is the call graph for this function:

lumiera_config_set()

LumieraConfigitem lumiera_config_set	(	const char *	key,
		const char *	delim_value
	)

Parameters

key
delim_value	delimiter (= or <) followed by the value to be set

Definition at line 223 of file config.c.

References llist_insert_tail, lumiera_config_lookup_insert(), lumiera_config_lookup_item_find(), lumiera_configitem_new(), lumiera_configitem_set_value(), lumiera_global_config, and lumiera_tmpbuf_snprintf().

Referenced by lumiera_config_number_set(), lumiera_config_string_set(), lumiera_config_word_set(), lumiera_config_wordlist_add(), lumiera_config_wordlist_replace(), lumiera_config_wordlist_set(), TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_setdefault()

LumieraConfigitem lumiera_config_setdefault

(

const char *

line

)

Installs a default value for a config key.

Any key might have an associated default value which is used when no other configuration is available, this can be set once. Any subsequent call will be a no-op. This function locks the config system.

Parameters

line	line with key, delimiter and value to store as default value

Returns

NULL in case of an error, else a pointer to the default configitem

Definition at line 265 of file config.c.

References llist_insert_head, LUMIERA_CONFIG_KEY_CHARS, lumiera_config_lookup_insert(), lumiera_config_lookup_item_find(), lumiera_configitem_new(), lumiera_global_config, LUMIERA_MUTEX_SECTION, lumiera_tmpbuf_strndup(), and NULL.

Referenced by lumiera_config_init(), LUMIERA_EXPORT(), lumiera_plugin_discover(), TEST(), TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_wordlist_get_nth()

LUMIERA_CONFIG_TYPES const char * lumiera_config_wordlist_get_nth	(	const char *	key,
		unsigned	nth,
		const char *	delims
	)

Wordlists Wordlists are lists of single words delimited by any of " \t,;".

They can be used to store groups of keys and other kinds of simple references into the config system. Here are some functions to manipulate single word entries in a wordlist. Get nth word of a wordlist.

Parameters

key	key under which this wordlist is stored
nth	index of the word to get, starting with 0
delims	a string literal listing all characters which are treated as delimiters

Returns

pointer to a tempbuf holding the nth word or NULL in case of error

Wordlists Wordlists are lists of single words delimited by any of " \t,;".

Definition at line 38 of file config-wordlist.c.

References lumiera_config_wordlist_get(), lumiera_tmpbuf_strndup(), and NULL.

Referenced by lumiera_plugin_discover(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_wordlist_find()

int lumiera_config_wordlist_find	(	const char *	key,
		const char *	value,
		const char *	delims
	)

Find the index of a word in a wordlist.

Parameters

key	key under which this wordlist is stored
value	word to find
delims	a string literal listing all characters which are treated as delimiters

Returns

index of the first occurrence of the word or -1 in case of failure

Definition at line 65 of file config-wordlist.c.

References lumiera_config_wordlist_get().

Referenced by TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_wordlist_replace()

const char * lumiera_config_wordlist_replace	(	const char *	key,
		const char *	value,
		const char *	subst1,
		const char *	subst2,
		const char *	delims
	)

Universal word replacement function.

Replaces a word with up to two new words. This can be used to delete a word (no replacements), insert a new word before an existing word (giving the new word as subst1 and the old word as subst2) insert a new word after an existing word (giving the old word as subst1 and the new word as subst2) or simply give 2 new words.

Parameters

key	key under which this wordlist is stored
value	word to be replaced
subst1	first replacement word
subst2	second replacement word
delims	a string literal listing all characters which are treated as delimiters

Returns

internal representation of the wordlist in a tmpbuf or NULL in case of an error

Definition at line 88 of file config-wordlist.c.

References lumiera_config_get(), lumiera_config_set(), lumiera_global_config, LUMIERA_MUTEX_SECTION, lumiera_tmpbuf_snprintf(), and NULL.

Referenced by TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_wordlist_add()

const char * lumiera_config_wordlist_add	(	const char *	key,
		const char *	value,
		const char *	delims
	)

Add a word to the end of a wordlist if it doesn't exist already.

Parameters

key	key under which this wordlist is stored
value	new word to add
delims	a string literal listing all characters which are treated as delimiters

Returns

internal representation of the wordlist in a tmpbuf or NULL in case of an error

Definition at line 143 of file config-wordlist.c.

References lumiera_config_get(), lumiera_config_set(), lumiera_global_config, LUMIERA_MUTEX_SECTION, lumiera_tmpbuf_snprintf(), and NULL.

Referenced by TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

lumiera_config_reset()

LUMIERA_CONFIG_TYPES int lumiera_config_reset

(

const char *

key

)

Definition at line 322 of file config.c.

lumiera_config_info()

int lumiera_config_info	(	const char *	key,
		const char **	filename,
		unsigned *	line
	)

Definition at line 332 of file config.c.