|
|
Keydata objects are used to load and hold "configuration" data for a given application.
This class is used to load and then hold "keyword = value
" pairs parsed from a text
based "config" file that has been divided into "[sections]
". The syntax is:
[section_name]
key1=value1
key2=value2
Essentially, the "path" is a "keypath" into a theoretical namespace of key
pairs, hence one does not use "real" filepaths that may be OS dependent. The "/
" path refers
to "/etc
" prefixed (on UNIX) directories and this is processed within the constructor. It
could refer to the /config
prefix on QNX, or even, gasp, a "C:\WINDOWS
". Hence, a keypath of
"/bayonne.d/vmhost/smtp
" actually resolves to a "/etc/bayonne.d/vmhost.conf
" and loads key
value pairs from the [smtp]
section of that .conf
file.
Similarly, something like "~bayonne/smtp
" path refers to a "~/.bayonnerc
" and loads key pairs
from the [smtp]
section. This coercion occurs before the name is passed to the open call.
I actually use derived keydata based classes as global initialized objects, and they hence automatically load and parse config file entries even before "main" has started.
Keydata can hold multiple values for the same key pair. This can
occur either from storing a "list" of data items in a config file,
or when overlaying multiple config sources (such as /etc/....conf
and
~/.confrc
segments) into a single object. The keys are stored as
cumulative (read-only/replacable) config values under a hash index
system for quick retrieval.
Keydata can also load a table of "initialization" values for keyword pairs that were not found in the external file.
One typically derives an application specific keydata class to load a specific portion of a known config file and initialize it's values. One can then declare a global instance of these objects and have configuration data initialized automatically as the executable is loaded.
Hence, if I have a "[paths]" section in a "/etc/server.conf?
" file, I might
define something like:
class KeyPaths : public Keydata
{
public:
KeyPaths() : Keydata("/server/paths")
{
static KEYDEF *defvalues = {
{"datafiles", "/var/server"},
{NULL, NULL}};
// override with [paths] from "~/.serverrc" if avail.
Load("~server/paths"); Load(defvalues); } };
KeyPaths keypaths;
keysym_t* getSymbol (const char *sym, bool create)
| getSymbol |
[protected]
void Load (const char *keypath,
const char *environment = "CONFIG_KEYDATA")
| Load |
[protected]
Load additional key values into the currrent object from
the specfied config source (a config file/section pair).
These values will overlay the current keywords when matches
are found. This can be used typically in a derived config
object class constructor to first load a /etc
section, and
then load a matching user specific entry from ~/.
to override
default system values with user specific keyword values.
Parameters:
keypath | (filepath/section) |
void Load (KEYDEF *pairs)
| Load |
[protected]
Load default keywords into the current object. This only loads keyword entries which have not already been defined to reduce memory usage. This form of Load is also commonly used in the constructor of a derived Keydata class.
Parameters:
list | of NULL terminated default keyword/value pairs. |
Keydata ()
| Keydata |
Create an empty key data object.
Keydata (const char *keypath, const char *environment="CONFIG_KEYDATA")
| Keydata |
Create a new key data object and use "Load" method to load an initial config file section into it.
Parameters:
keypath | (filepath/section) |
~Keydata ()
| ~Keydata |
[virtual]
Destroy the keydata object and all allocated memory. This may also clear the "cache" file stream if no other keydata objects currently reference it.
void Unlink (void)
| Unlink |
Unlink the keydata object from the cache file stream. This should be used if you plan to keepa Keydata object after it is loaded once all keydata objects have been loaded, otherwise the cfgFile stream will remain open. You can also use endKeydata().
int getCount (const char *sym)
| getCount |
Get a count of the number of data "values" that is associated
with a specific keyword. Each value is from an accumulation of
"load()
" requests.
Parameters:
keyword | symbol name. |
Returns: count of values associated with keyword.
const char* getFirst (const char *sym)
| getFirst |
Get the first data value for a given keyword. This will
typically be the /etc
set global default.
Parameters:
keyword | symbol name. |
Returns: first set value for this symbol.
const char* getLast (const char *sym)
| getLast |
Get the last (most recently set) value for a given keyword. This is typically the value actually used.
Parameters:
keywork | symbol name. |
Returns: last set value for this symbol.
int getIndex (char **data, int max)
| getIndex |
Get an index array of ALL keywords that are stored by the current keydata object.
Parameters:
data | pointer of array to hold keyword strings. |
max | number of entries the array can hold. |
Returns: number of keywords found.
void setValue (const char *sym, const char *data)
| setValue |
Set (replace) the value of a given keyword. This new value
will become the value returned from getLast(), while the
prior value will still be stored and found from getList()
.
Parameters:
keyword | name to set. |
data | string to store for the keyword. |
const char * const* getList (const char *sym)
| getList |
Return a list of all values set for the given keyword returned in order.
Parameters:
keyword | name to fetch. |
Returns: list pointer of array holding all keyword values.
void clrValue (const char *sym)
| clrValue |
Clear all values associated with a given keyword. This does not de-allocate the keyword from memory, however.
Returns: keyword name to clear.
inline const char * operator[] (const char *keyword)
| operator[] |
A convient notation for accessing the keydata as an associative array of keyword/value pairs through the [] operator.
friend void endKeydata (void)
| endKeydata |
Shutdown the file stream cache. This should be used before
detaching a deamon, exec()
, fork()
, etc.