.TH "ost::Keydata" 3 "Sun Aug 16 2015" "GNU CommonC++" \" -*- nroff -*- .ad l .nh .SH NAME ost::Keydata \- \fBKeydata\fP objects are used to load and hold 'configuration' data for a given application\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBost::MemPager\fP\&. .SS "Classes" .in +1c .ti -1c .RI "struct \fBDefine\fP" .br .ti -1c .RI "struct \fBKeysym\fP" .br .ti -1c .RI "struct \fBKeyval\fP" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "void \fBload\fP (const char *keypath)" .br .RI "\fILoad additional key values into the currrent object from the specfied config source (a config file/section pair)\&. \fP" .ti -1c .RI "void \fBloadPrefix\fP (const char *prefix, const char *keypath)" .br .RI "\fILoad additional key values into the currrent object from the specfied config source (a config file/section pair)\&. \fP" .ti -1c .RI "void \fBloadFile\fP (const char *filepath, const char *keys=NULL, const char *pre=NULL)" .br .RI "\fILoad additional keys into the current object using a real filename that is directly passed rather than a computed key path\&. \fP" .ti -1c .RI "void \fBload\fP (\fBDefine\fP *pairs)" .br .RI "\fILoad default keywords into the current object\&. \fP" .ti -1c .RI "\fBKeydata\fP ()" .br .RI "\fICreate an empty key data object\&. \fP" .ti -1c .RI "\fBKeydata\fP (const char *keypath)" .br .RI "\fICreate a new key data object and use 'Load' method to load an initial config file section into it\&. \fP" .ti -1c .RI "\fBKeydata\fP (\fBDefine\fP *pairs, const char *keypath=NULL)" .br .RI "\fIAlternate constructor can take a define list and an optional pathfile to parse\&. \fP" .ti -1c .RI "virtual \fB~Keydata\fP ()" .br .RI "\fIDestroy the keydata object and all allocated memory\&. \fP" .ti -1c .RI "void \fBunlink\fP (void)" .br .RI "\fIUnlink the keydata object from the cache file stream\&. \fP" .ti -1c .RI "int \fBgetCount\fP (const char *sym)" .br .RI "\fIGet a count of the number of data 'values' that is associated with a specific keyword\&. \fP" .ti -1c .RI "const char * \fBgetFirst\fP (const char *sym)" .br .RI "\fIGet the first data value for a given keyword\&. \fP" .ti -1c .RI "const char * \fBgetLast\fP (const char *sym)" .br .RI "\fIGet the last (most recently set) value for a given keyword\&. \fP" .ti -1c .RI "bool \fBisKey\fP (const char *sym)" .br .RI "\fIFind if a given key exists\&. \fP" .ti -1c .RI "const char * \fBgetString\fP (const char *sym, const char *def=NULL)" .br .RI "\fIGet a string value, with an optional default if missing\&. \fP" .ti -1c .RI "long \fBgetLong\fP (const char *sym, long def=0)" .br .RI "\fIGet a long value, with an optional default if missing\&. \fP" .ti -1c .RI "bool \fBgetBool\fP (const char *key)" .br .RI "\fIGet a bool value\&. \fP" .ti -1c .RI "double \fBgetDouble\fP (const char *key, double def=0\&.)" .br .RI "\fIGet a floating value\&. \fP" .ti -1c .RI "unsigned \fBgetIndex\fP (char **data, unsigned max)" .br .RI "\fIGet an index array of ALL keywords that are stored by the current keydata object\&. \fP" .ti -1c .RI "unsigned \fBgetCount\fP (void)" .br .RI "\fIGet the count of keyword indexes that are actually available so one can allocate a table to receive getIndex\&. \fP" .ti -1c .RI "void \fBsetValue\fP (const char *sym, const char *data)" .br .RI "\fISet (replace) the value of a given keyword\&. \fP" .ti -1c .RI "const char *const * \fBgetList\fP (const char *sym)" .br .RI "\fIReturn a list of all values set for the given keyword returned in order\&. \fP" .ti -1c .RI "void \fBclrValue\fP (const char *sym)" .br .RI "\fIClear all values associated with a given keyword\&. \fP" .ti -1c .RI "const char * \fBoperator[]\fP (const char *keyword)" .br .RI "\fIA convient notation for accessing the keydata as an associative array of keyword/value pairs through the [] operator\&. \fP" .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "static void \fBend\fP (void)" .br .RI "\fIstatic member to end keydata i/o allocations\&. \fP" .in -1c .SS "Protected Member Functions" .in +1c .ti -1c .RI "\fBKeysym\fP * \fBgetSymbol\fP (const char *sym, bool create)" .br .in -1c .SS "Friends" .in +1c .ti -1c .RI "void \fBendKeydata\fP (void)" .br .RI "\fIShutdown the file stream cache\&. \fP" .in -1c .SH "Detailed Description" .PP \fBKeydata\fP 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: .PP \fC .PP .nf [section_name] key1=value1 key2=value2 .fi .PP \fP .PP 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 \fC/config\fP 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 \fC[smtp]\fP section of that \fC\&.conf\fP file\&. .PP Similarly, something like '~bayonne/smtp' path refers to a '~/\&.bayonnerc' and loads key pairs from the \fC[smtp]\fP section\&. This coercion occurs before the name is passed to the open call\&. .PP 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\&. .PP \fBKeydata\fP 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 \fC/etc/\&.\&.\&.\&.conf\fP and \fC~/\&.confrc\fP segments) into a single object\&. The keys are stored as cumulative (read-only/replacable) config values under a hash index system for quick retrieval\&. .PP \fBKeydata\fP can also load a table of 'initialization' values for keyword pairs that were not found in the external file\&. .PP 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\&. .PP Hence, if I have a '[paths]' section in a '/etc/server\&.conf?' file, I might define something like: .PP \fC .PP .nf class KeyPaths : public \fBKeydata\fP { public: KeyPaths() : \fBKeydata\fP('/server/paths') { static \fBKeydata::Define\fP *defvalues = { {'datafiles', '/var/server'}, {NULL, NULL}}; .fi .PP \fP .PP \fC .PP .nf // override with [paths] from '~/\&.serverrc' if avail\&. .fi .PP \fP .PP \fC .PP .nf load('~server/paths'); load(defvalues); } }; .fi .PP \fP .PP \fC .PP .nf KeyPaths keypaths; .fi .PP \fP .PP \fBAuthor:\fP .RS 4 David Sugar dyfet@ostel.com load text configuration files into keyword pairs\&. .RE .PP .SH "Constructor & Destructor Documentation" .PP .SS "ost::Keydata::Keydata ()" .PP Create an empty key data object\&. .SS "ost::Keydata::Keydata (const char * keypath)" .PP Create a new key data object and use 'Load' method to load an initial config file section into it\&. .PP \fBParameters:\fP .RS 4 \fIkeypath\fP (filepath/section) specifies the home path\&. .RE .PP .SS "ost::Keydata::Keydata (\fBDefine\fP * pairs, const char * keypath = \fCNULL\fP)" .PP Alternate constructor can take a define list and an optional pathfile to parse\&. .PP \fBParameters:\fP .RS 4 \fIpairs\fP of keyword values from a define list .br \fIkeypath\fP of optional file and section to load from .RE .PP .SS "virtual ost::Keydata::~Keydata ()\fC [virtual]\fP" .PP Destroy the keydata object and all allocated memory\&. This may also clear the 'cache' file stream if no other keydata objects currently reference it\&. .SH "Member Function Documentation" .PP .SS "void ost::Keydata::clrValue (const char * sym)" .PP Clear all values associated with a given keyword\&. This does not de-allocate the keyword from memory, however\&. .PP \fBReturns:\fP .RS 4 keyword name to clear\&. .RE .PP .SS "static void ost::Keydata::end (void)\fC [static]\fP" .PP static member to end keydata i/o allocations\&. .PP Referenced by ost::endKeydata()\&. .SS "bool ost::Keydata::getBool (const char * key)" .PP Get a bool value\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword name\&. .RE .PP \fBReturns:\fP .RS 4 true or false\&. .RE .PP .SS "int ost::Keydata::getCount (const char * sym)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword symbol name\&. .RE .PP \fBReturns:\fP .RS 4 count of values associated with keyword\&. .RE .PP .SS "unsigned ost::Keydata::getCount (void)" .PP Get the count of keyword indexes that are actually available so one can allocate a table to receive getIndex\&. .PP \fBReturns:\fP .RS 4 number of keywords found\&. .RE .PP .SS "double ost::Keydata::getDouble (const char * key, double def = \fC0\&.\fP)" .PP Get a floating value\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword name\&. .br \fIdefault\fP if not set\&. .RE .PP \fBReturns:\fP .RS 4 value of key\&. .RE .PP .SS "const char* ost::Keydata::getFirst (const char * sym)" .PP Get the first data value for a given keyword\&. This will typically be the \fC/etc\fP set global default\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword symbol name\&. .RE .PP \fBReturns:\fP .RS 4 first set value for this symbol\&. .RE .PP .SS "unsigned ost::Keydata::getIndex (char ** data, unsigned max)" .PP Get an index array of ALL keywords that are stored by the current keydata object\&. .PP \fBReturns:\fP .RS 4 number of keywords found\&. .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP pointer of array to hold keyword strings\&. .br \fImax\fP number of entries the array can hold\&. .RE .PP .SS "const char* ost::Keydata::getLast (const char * sym)" .PP Get the last (most recently set) value for a given keyword\&. This is typically the value actually used\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword symbol name\&. .RE .PP \fBReturns:\fP .RS 4 last set value for this symbol\&. .RE .PP .SS "const char* const* ost::Keydata::getList (const char * sym)" .PP Return a list of all values set for the given keyword returned in order\&. .PP \fBReturns:\fP .RS 4 list pointer of array holding all keyword values\&. .RE .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword name to fetch\&. .RE .PP .SS "long ost::Keydata::getLong (const char * sym, long def = \fC0\fP)" .PP Get a long value, with an optional default if missing\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword name\&. .br \fIdefault\fP if not present\&. .RE .PP \fBReturns:\fP .RS 4 long value of key\&. .RE .PP .SS "const char* ost::Keydata::getString (const char * sym, const char * def = \fCNULL\fP)" .PP Get a string value, with an optional default if missing\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword name\&. .br \fIdefault\fP if not present\&. .RE .PP \fBReturns:\fP .RS 4 string value of key\&. .RE .PP .SS "\fBKeysym\fP* ost::Keydata::getSymbol (const char * sym, bool create)\fC [protected]\fP" .SS "bool ost::Keydata::isKey (const char * sym)" .PP Find if a given key exists\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword to find\&. .RE .PP \fBReturns:\fP .RS 4 true if exists\&. .RE .PP .SS "void ost::Keydata::load (const char * keypath)" .PP 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 \fC/etc\fP section, and then load a matching user specific entry from \fC~/\&.\fP to override default system values with user specific keyword values\&. .PP \fBParameters:\fP .RS 4 \fIkeypath\fP (filepath/section) .RE .PP .SS "void ost::Keydata::load (\fBDefine\fP * pairs)" .PP 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 \fBKeydata\fP class\&. .PP \fBParameters:\fP .RS 4 \fIpairs\fP list of NULL terminated default keyword/value pairs\&. .RE .PP .SS "void ost::Keydata::loadFile (const char * filepath, const char * keys = \fCNULL\fP, const char * pre = \fCNULL\fP)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fIfilepath\fP to load from .br \fIkeys\fP section to parse from, or NULL to parse from head .br \fIpre\fP optional key prefix .RE .PP .SS "void ost::Keydata::loadPrefix (const char * prefix, const char * keypath)" .PP 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 \fC/etc\fP section, and then load a matching user specific entry from \fC~/\&.\fP to override default system values with user specific keyword values\&. This varient puts a prefix in front of the key name\&. .PP \fBParameters:\fP .RS 4 \fIprefix\fP .br \fIkeypath\fP (filepath/section) .RE .PP .SS "const char* ost::Keydata::operator[] (const char * keyword)\fC [inline]\fP" .PP A convient notation for accessing the keydata as an associative array of keyword/value pairs through the [] operator\&. .SS "void ost::Keydata::setValue (const char * sym, const char * data)" .PP Set (replace) the value of a given keyword\&. This new value will become the value returned from \fBgetLast()\fP, while the prior value will still be stored and found from \fC\fBgetList()\fP\fP\&. .PP \fBParameters:\fP .RS 4 \fIsym\fP keyword name to set\&. .br \fIdata\fP string to store for the keyword\&. .RE .PP .SS "void ost::Keydata::unlink (void)" .PP Unlink the keydata object from the cache file stream\&. This should be used if you plan to keepa \fBKeydata\fP object after it is loaded once all keydata objects have been loaded, otherwise the cfgFile stream will remain open\&. You can also use \fBendKeydata()\fP\&. .SH "Friends And Related Function Documentation" .PP .SS "void endKeydata (void)\fC [friend]\fP" .PP Shutdown the file stream cache\&. This should be used before detaching a deamon, \fCexec()\fP, \fCfork()\fP, etc\&. .SH "Author" .PP Generated automatically by Doxygen for GNU CommonC++ from the source code\&.