NAME
ost::Keydata -
Keydata objects are used to load and hold ’configuration’ data for a
given application.
SYNOPSIS
#include <misc.h>
Inherits ost::MemPager.
Classes
struct Define
struct Keysym
struct Keyval
Public Member Functions
void load (const char *keypath)
Load additional key values into the currrent object from the
specfied config source (a config file/section pair).
void loadPrefix (const char *prefix, const char *keypath)
Load additional key values into the currrent object from the
specfied config source (a config file/section pair).
void loadFile (const char *filepath, const char *keys=NULL, const char
*pre=NULL)
Load additional keys into the current object using a real filename
that is directly passed rather than a computed key path.
void load (Define *pairs)
Load default keywords into the current object.
Keydata ()
Create an empty key data object.
Keydata (const char *keypath)
Create a new key data object and use Load method to load an
initial config file section into it.
Keydata (Define *pairs, const char *keypath=NULL)
Alternate constructor can take a define list and an optional
pathfile to parse.
virtual ~Keydata ()
Destroy the keydata object and all allocated memory.
void unlink (void)
Unlink the keydata object from the cache file stream.
int getCount (const char *sym)
Get a count of the number of data values that is associated with
a specific keyword.
const char * getFirst (const char *sym)
Get the first data value for a given keyword.
const char * getLast (const char *sym)
Get the last (most recently set) value for a given keyword.
bool isKey (const char *sym)
Find if a given key exists.
const char * getString (const char *sym, const char *def=NULL)
Get a string value, with an optional default if missing.
long getLong (const char *sym, long def=0)
Get a long value, with an optional default if missing.
bool getBool (const char *key)
Get a bool value.
double getDouble (const char *key, double def=0.)
Get a floating value.
unsigned getIndex (char **data, unsigned max)
Get an index array of ALL keywords that are stored by the current
keydata object.
unsigned getCount (void)
Get the count of keyword indexes that are actually available so one
can allocate a table to receive getIndex.
void setValue (const char *sym, const char *data)
Set (replace) the value of a given keyword.
const char *const * getList (const char *sym)
Return a list of all values set for the given keyword returned in
order.
void clrValue (const char *sym)
Clear all values associated with a given keyword.
const char * operator[] (const char *keyword)
A convient notation for accessing the keydata as an associative
array of keyword/value pairs through the [] operator.
Static Public Member Functions
static void end (void)
static member to end keydata i/o allocations.
Protected Member Functions
Keysym * getSymbol (const char *sym, bool create)
Friends
void endKeydata (void)
Shutdown the file stream cache.
Detailed Description
Keydata objects are used to load and hold ’configuration’ data for a
given application.
This class is used to load and then hold ’<code>keyword = value</code>’
pairs parsed from a text based ’config’ file that has been divided into
’<code>[sections]</code>’. 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 ’<code>/</code>’ path refers to ’<code>/etc</code>’
prefixed (on UNIX) directories and this is processed within the
constructor. It could refer to the /config prefix on QNX, or even,
gasp, a ’<code>C:\WINDOWS</code>’. Hence, a keypath of
’<code>/bayonne.d/vmhost/smtp</code>’ actually resolves to a
’<code>/etc/bayonne.d/vmhost.conf</code>’ and loads key value pairs
from the [smtp] section of that .conf file.
Similarly, something like ’<code>~bayonne/smtp</code>’ path refers to a
’<code>~/.bayonnerc</code>’ 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
’<code>/etc/server.conf?</code>’ file, I might define something like:
class KeyPaths : public Keydata
{
public:
KeyPaths() : Keydata(’/server/paths’)
{
static Keydata::Define *defvalues = {
{’datafiles’, ’/var/server’},
{NULL, NULL}};
// override with [paths] from ’~/.serverrc’ if avail.
load(’~server/paths’);
load(defvalues);
}
};
KeyPaths keypaths;
Author:
David Sugar <dyfet@ostel.com> load text configuration files into
keyword pairs.
Constructor & Destructor Documentation
ost::Keydata::Keydata ()
Create an empty key data object.
ost::Keydata::Keydata (const char * keypath)
Create a new key data object and use ’Load’ method to load an initial
config file section into it. Parameters:
keypath (filepath/section) specifies the home path.
ost::Keydata::Keydata (Define * pairs, const char * keypath = NULL)
Alternate constructor can take a define list and an optional pathfile
to parse. Parameters:
pairs of keyword values from a define list
keypath of optional file and section to load from
virtual ost::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.
Member Function Documentation
void ost::Keydata::clrValue (const char * sym)
Clear all values associated with a given keyword. This does not de-
allocate the keyword from memory, however.
Returns:
keyword name to clear.
static void ost::Keydata::end (void) [static]
static member to end keydata i/o allocations.
Referenced by ost::endKeydata().
bool ost::Keydata::getBool (const char * key)
Get a bool value. Parameters:
sym keyword name.
Returns:
true or false.
unsigned ost::Keydata::getCount (void)
Get the count of keyword indexes that are actually available so one can
allocate a table to receive getIndex. Returns:
number of keywords found.
int ost::Keydata::getCount (const char * sym)
Get a count of the number of data ’values’ that is associated with a
specific keyword. Each value is from an accumulation of
’<code>load()</code>’ requests.
Parameters:
sym keyword symbol name.
Returns:
count of values associated with keyword.
double ost::Keydata::getDouble (const char * key, double def = 0.)
Get a floating value. Parameters:
sym keyword name.
default if not set.
Returns:
value of key.
const char* ost::Keydata::getFirst (const char * sym)
Get the first data value for a given keyword. This will typically be
the /etc set global default.
Parameters:
sym keyword symbol name.
Returns:
first set value for this symbol.
unsigned ost::Keydata::getIndex (char ** data, unsigned max)
Get an index array of ALL keywords that are stored by the current
keydata object. Returns:
number of keywords found.
Parameters:
data pointer of array to hold keyword strings.
max number of entries the array can hold.
const char* ost::Keydata::getLast (const char * sym)
Get the last (most recently set) value for a given keyword. This is
typically the value actually used.
Parameters:
sym keyword symbol name.
Returns:
last set value for this symbol.
const char* const* ost::Keydata::getList (const char * sym)
Return a list of all values set for the given keyword returned in
order. Returns:
list pointer of array holding all keyword values.
Parameters:
sym keyword name to fetch.
long ost::Keydata::getLong (const char * sym, long def = 0)
Get a long value, with an optional default if missing. Parameters:
sym keyword name.
default if not present.
Returns:
long value of key.
const char* ost::Keydata::getString (const char * sym, const char * def =
NULL)
Get a string value, with an optional default if missing. Parameters:
sym keyword name.
default if not present.
Returns:
string value of key.
Keysym* ost::Keydata::getSymbol (const char * sym, bool create) [protected]
bool ost::Keydata::isKey (const char * sym)
Find if a given key exists. Parameters:
sym keyword to find.
Returns:
true if exists.
void ost::Keydata::load (Define * pairs)
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:
pairs list of NULL terminated default keyword/value pairs.
void ost::Keydata::load (const char * keypath)
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 ost::Keydata::loadFile (const char * filepath, const char * keys =
NULL, const char * pre = NULL)
Load additional keys into the current object using a real filename that
is directly passed rather than a computed key path. This also uses a
[keys] section as passed to the object.
Parameters:
filepath to load from
keys section to parse from, or NULL to parse from head
pre optional key prefix
void ost::Keydata::loadPrefix (const char * prefix, const char * keypath)
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. This
varient puts a prefix in front of the key name.
Parameters:
prefix
keypath (filepath/section)
const char* ost::Keydata::operator[] (const char * keyword) [inline]
A convient notation for accessing the keydata as an associative array
of keyword/value pairs through the [] operator.
void ost::Keydata::setValue (const char * sym, const char * data)
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:
sym keyword name to set.
data string to store for the keyword.
void ost::Keydata::unlink (void)
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().
Friends And Related Function Documentation
void endKeydata (void) [friend]
Shutdown the file stream cache. This should be used before detaching a
deamon, exec(), fork(), etc.
Author
Generated automatically by Doxygen for GNU CommonC++ from the source
code.