ost::Keydata(3)

📦 version 1.8.1, in ubuntu jammy

💖 ost::Keydata(3) — Library Functions Manual 💖

okay bestie, welcome to the ost::Keydata page! This is the manual for the class that loads and holds config data. It's giving library functions manual energy. Let's go. ✨

✨ 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 current object from the specified config source (a config file/section pair). 💖
  • void loadPrefix (const char *prefix, const char *keypath) — Load additional key values into the current object from the specified 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 the 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 convenient 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 🌈

Okay so, Keydata objects are used to load and hold 'configuration' data for a given application. Periodt.

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 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. So empty, bestie. 💖

ost::Keydata::Keydata (const char * keypath)

Create a new key data object and use the 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 💖

Okay bestie, here's the tea on all the member functions. Every signature is exact, every return value is sacred, and no detail got left on read. ✨

void ost::Keydata::clrValue (const char * sym)

Wipes out every value tied to a given keyword. It does not de-allocate the keyword from memory, though. So the values are gone, but the keyword itself is still chilling in RAM. 💅

Returns: keyword name to clear.

Yes, that's literally what the docs say for the return value. Not me making it up. 💀

static void ost::Keydata::end (void) [static]

A static member that ends keydata i/o allocations. It's the cleanup queen. 👑

Referenced by: ost::endKeydata().

bool ost::Keydata::getBool (const char * key)

Gets a bool value. True or false, no in-between. 🎀

Parameters:

  • sym — keyword name.

Returns: true or false.

The parameter in the docs is called sym, even though the signature says key. Not a typo, just Doxygen being Doxygen. 🙈

int ost::Keydata::getCount (const char * sym)

Gets a count of how many data "values" are associated with a specific keyword. Each value comes from an accumulation of load() requests. So if you loaded it multiple times, they stack up like your unread notifications. 😭

Parameters:

  • sym — keyword symbol name.

Returns: count of values associated with keyword.

unsigned ost::Keydata::getCount (void)

Gets the count of keyword indexes that are actually available, so you can allocate a table to receive getIndex. Basically: how many keywords are in the building? 🏠

Returns: number of keywords found.

double ost::Keydata::getDouble (const char * key, double def = 0.)

Gets a floating value. If it's missing, you can pass a default and it'll use that instead. No drama. 🌸

Parameters:

  • sym — keyword name.
  • default if not set.

Returns: value of key.

Again, the docs call the first one sym while the signature says key. We move. 💅

const char* ost::Keydata::getFirst (const char * sym)

Gets the first data value for a given keyword. This will typically be the /etc set global default. So it's the OG value, the one that was there before your user config started acting up. 👑

Parameters:

  • sym — keyword symbol name.

Returns: first set value for this symbol.

unsigned ost::Keydata::getIndex (char ** data, unsigned max)

Gets an index array of ALL keywords stored by the current keydata object. All of them. The whole squad. 🔥

Returns: number of keywords found.

Parameters:

  • data — pointer of array to hold keyword strings.
  • max — number of entries the array can hold.
Notice how Returns comes before Parameters? That's exactly how the original rolls. We respect the chaos. ✨

const char* ost::Keydata::getLast (const char * sym)

Gets the last (most recently set) value for a given keyword. This is typically the value actually used. So it's the final answer, the one that wins. 🏆

Parameters:

  • sym — keyword symbol name.

Returns: last set value for this symbol.

const char* const* ost::Keydata::getList (const char * sym)

Returns a list of all values set for the given keyword, in order. It's giving chronological receipt energy. 🧾

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)

Gets a long value, with an optional default if it's missing. Because sometimes you just need a big number and a backup plan. 💜

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)

Gets a string value, with an optional default if it's missing. If the key ghosted you, def is there to catch you. 🫶

Parameters:

  • sym — keyword name.
  • default if not present.

Returns: string value of key.

Keysym* ost::Keydata::getSymbol (const char * sym, bool create) [protected]

Protected function. No description in the source. It's giving mysterious main character energy. 👀

bool ost::Keydata::isKey (const char * sym)

Finds out if a given key exists. Like a vibe check but for keywords. 🌈

Parameters:

  • sym — keyword to find.

Returns: true if exists.

void ost::Keydata::load (const char * keypath)

Adds more key values into the current object from the config source you point at (that's a config file/section pair). When matches show up, these values overlay the current keywords. Usually you'd use this in a derived config object class constructor: first load a /etc section, then load a matching user-specific entry from ~/. so the user's settings override the system defaults. It's giving layered customization. 💅

Parameters:

  • keypath — (filepath/section)

void ost::Keydata::load (Define * pairs)

Loads 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. It's the "don't overwrite what's already there" load. Respectful. 🎀

Parameters:

  • pairs — list of NULL terminated default keyword/value pairs.

void ost::Keydata::loadFile (const char * filepath, const char * keys = NULL, const char * pre = NULL)

Loads 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. It's the "I know exactly where the file is" energy. 🔥

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)

Same idea as load(keypath): it adds more key values into the current object from the specified config source (a config file/section pair), and those values overlay the current keywords when matches are found. Typically used in a derived config object class constructor to first load a /etc section, then load a matching user-specific entry from ~/. so user-specific keyword values override system defaults. This variant puts a prefix in front of the key name. So same energy, but with a little prefix bow on top. 🎀

Parameters:

  • prefix
  • keypath — (filepath/section)

const char* ost::Keydata::operator[] (const char * keyword) [inline]

A convenient notation for accessing the keydata as an associative array of keyword/value pairs through the [] operator. So you can do keydata["bestie"] and get your value. Iconic. 💅

void ost::Keydata::setValue (const char * sym, const char * data)

Sets (replaces) 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(). So the old value isn't deleted, just archived. She's still in the group chat history. 😭

Parameters:

  • sym — keyword name to set.
  • data — string to store for the keyword.

Unlinks the keydata object from the cache file stream. This should be used if you plan to keep a 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().

Important! If you don't do this, the cfgFile stream stays open like a tab you forgot to close. Do not leave it on read. 🚨

void endKeydata (void) [friend]

Shuts down the file stream cache. This should be used before detaching a deamon, exec(), fork(), etc.

This is the friend function that comes through when you need to close things properly before your process does a big life change. Don't skip it. 💖

✨ Author ✨

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

So yeah, not a human bestie — it's a robot that read the source and spilled the tea. 🤖💅

This page came from GNU CommonC++ and was generated on Sun Dec 27 2020. Bye bestie, go set some keywords! 🦋💖

📦 where this page comes from