ost::Keydata - Keydata objects are used to load and hold 'configuration' data for a given application.

       Generated automatically by Doxygen for GNU CommonC++ from the source code.

GNU CommonC++                                    Sun Dec 27 2020                                 ost::Keydata(3)

ost::Keydata::Keydata()
       Create an empty key data object.

   ost::Keydata::Keydata(constchar*keypath)
       Create a new key data object and use 'Load' method to load an initial config file section into it.

       Parameterskeypath (filepath/section) specifies the home path.

   ost::Keydata::Keydata(Define*pairs,constchar*keypath=NULL)
       Alternate constructor can take a define list and an optional pathfile to parse.

       Parameterspairs of keyword values from a define list
           keypath of optional file and section to load from

   virtualost::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.

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.

voidendKeydata(void)[friend]
       Shutdown the file stream cache. This should be used before detaching a deamon, exec(), fork(), etc.

voidost::Keydata::clrValue(constchar*sym)
       Clear all values associated with a given keyword. This does not de-allocate the keyword from memory,
       however.

       Returns
           keyword name to clear.

   staticvoidost::Keydata::end(void)[static]
       static member to end keydata i/o allocations.

       Referenced by ost::endKeydata().

   boolost::Keydata::getBool(constchar*key)
       Get a bool value.

       Parameterssym keyword name.

       Returns
           true or false.

   intost::Keydata::getCount(constchar*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.

       Parameterssym keyword symbol name.

       Returns
           count of values associated with keyword.

   unsignedost::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.

   doubleost::Keydata::getDouble(constchar*key,doubledef=0.)
       Get a floating value.

       Parameterssym keyword name.
           default if not set.

       Returns
           value of key.

   constchar*ost::Keydata::getFirst(constchar*sym)
       Get the first data value for a given keyword. This will typically be the /etc set global default.

       Parameterssym keyword symbol name.

       Returns
           first set value for this symbol.

   unsignedost::Keydata::getIndex(char**data,unsignedmax)
       Get an index array of ALL keywords that are stored by the current keydata object.

       Returns
           number of keywords found.

       Parametersdata pointer of array to hold keyword strings.
           max number of entries the array can hold.

   constchar*ost::Keydata::getLast(constchar*sym)
       Get the last (most recently set) value for a given keyword. This is typically the value actually used.

       Parameterssym keyword symbol name.

       Returns
           last set value for this symbol.

   constchar*const*ost::Keydata::getList(constchar*sym)
       Return a list of all values set for the given keyword returned in order.

       Returns
           list pointer of array holding all keyword values.

       Parameterssym keyword name to fetch.

   longost::Keydata::getLong(constchar*sym,longdef=0)
       Get a long value, with an optional default if missing.

       Parameterssym keyword name.
           default if not present.

       Returns
           long value of key.

   constchar*ost::Keydata::getString(constchar*sym,constchar*def=NULL)
       Get a string value, with an optional default if missing.

       Parameterssym keyword name.
           default if not present.

       Returns
           string value of key.

   Keysym*ost::Keydata::getSymbol(constchar*sym,boolcreate)[protected]boolost::Keydata::isKey(constchar*sym)
       Find if a given key exists.

       Parameterssym keyword to find.

       Returns
           true if exists.

   voidost::Keydata::load(constchar*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.

       Parameterskeypath (filepath/section)

   voidost::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.

       Parameterspairs list of NULL terminated default keyword/value pairs.

   voidost::Keydata::loadFile(constchar*filepath,constchar*keys=NULL,constchar*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.

       Parametersfilepath to load from
           keys section to parse from, or NULL to parse from head
           pre optional key prefix

   voidost::Keydata::loadPrefix(constchar*prefix,constchar*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.

       Parametersprefixkeypath (filepath/section)

   constchar*ost::Keydata::operator[](constchar*keyword)[inline]
       A convient notation for accessing the keydata as an associative array of keyword/value pairs through the
       [] operator.

   voidost::Keydata::setValue(constchar*sym,constchar*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().Parameterssym keyword name to set.
           data string to store for the keyword.

   voidost::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().

       ost::Keydata - Keydata objects are used to load and hold 'configuration' data for a given application.

       #include <misc.h>

       Inherits ost::MemPager.

   Classes
       struct Define
       struct Keysym
       struct KeyvalPublicMemberFunctions
       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.

   StaticPublicMemberFunctions
       static void end (void)
           static member to end keydata i/o allocations.

   ProtectedMemberFunctionsKeysym * getSymbol (const char *sym, bool create)

   Friends
       void endKeydata (void)
           Shutdown the file stream cache.