UniConf Class Reference

#include <uniconf.h>

Inheritance diagram for UniConf:

[legend]
List of all members.

Detailed Description

UniConf instances function as handles to subtrees of a UniConf tree and expose a high-level interface for clients.

All operations are marked "const" unless they modify the target of the handle. In effect, this grants UniConf handles the same semantics as pointers where a const pointer may point to a non-const object, which simply means that the pointer cannot be reassigned.

When handles are returned from functions, they are always marked const to guard against accidentally assigning to a temporary by an expression such as cfg["foo"] = cfg["bar"]. Instead this must be written as cfg["foo"].setme(cfg["bar"].getme()) which is slightly less elegant but avoids many subtle mistakes. Also for this reason, unusual cast operators, assignment operators, or copy constructors are not provided. Please do not add any.

Definition at line 62 of file uniconf.h.

Public Member Functions

 UniConf ()
 Creates a NULL UniConf handle, useful for reporting errors.
 UniConf (const UniConf &other)
 Copies a UniConf handle.
virtual ~UniConf ()
 Destroys the UniConf handle.
UniConf root () const
 Returns a handle to the root of the tree.
UniConf parent () const
 Returns a handle to the parent of this node.
UniConfRootrootobj () const
 Returns a pointer to the UniConfRoot that manages this node.
bool isnull () const
 Returns true if the handle is invalid (NULL).
UniConfKey fullkey () const
 Returns the full path of this node, starting at the root.
UniConfKey fullkey (const UniConfKey &k) const
 Returns the full path of this node, starting at the given key.
UniConfKey fullkey (const UniConf &cfg) const
 Returns the full path of this node, starting at the given handle.
UniConfKey key () const
 Returns the path of this node relative to its parent.
const UniConf operator[] (const UniConfKey &key) const
 Returns a handle for a subtree below this key.
const UniConf u (const UniConfKey &key) const
 Return a subtree handle (see operator[]).
UniConfoperator= (const UniConf &other)
 Reassigns the target of this handle to match a different one.
void prefetch (bool recursive) const
 See UniConfGen::prefetch().
WvString getme (WvStringParm defvalue=WvString::null) const
 Fetches the string value for this key from the registry.
WvString operator * () const
 A different way to say cfg.getme(): use *cfg instead.
WvStringStar operator-> () const
 A different way to say cfg.getme().num(): use cfg->num() instead.
WvString xget (WvStringParm key, WvStringParm defvalue=WvString::null) const
 A different way to say cfg[x].getme(y).
int getmeint (int defvalue=0) const
 Fetches the integer value for this key from the registry.
int xgetint (WvStringParm key, int defvalue=0) const
 A different way to say cfg[x].getmeint(y).
bool exists () const
 Without fetching its value, returns true if this key exists.
void setme (WvStringParm value) const
 Stores a string value for this key into the registry.
void setme (WVSTRING_FORMAT_DECL) const
 Stores a string value for this key into the registry.
void xset (WvStringParm key, WvStringParm value) const
 A different way to say cfg[x].setme(y).
void setmeint (int value) const
 Stores an integer value for this key into the registry.
void xsetint (WvStringParm key, int value) const
 A different way to say cfg[x].setme(y).
void move (const UniConf &dst) const
 Equivalent to "mv" in a standard unix filesystem.
void remove () const
 Removes this key and all of its children from the registry.
void copy (const UniConf &dst, bool force) const
 Equivalent to "cp -r" in a standard unix filesystem.
bool refresh () const
 Refreshes information about this key recursively.
void commit () const
 Commits information about this key recursively.
IUniConfGenmount (WvStringParm moniker, bool refresh=true) const
 Mounts a generator at this key using a moniker.
IUniConfGenmountgen (IUniConfGen *gen, bool refresh=true) const
 Mounts a generator at this key.
void unmount (IUniConfGen *gen, bool commit) const
 Unmounts the generator providing this key and destroys it.
bool ismountpoint () const
 Determines if any generators are mounted at this key.
bool isok () const
 Returns true if the generator at this key isok().
IUniConfGenwhichmount (UniConfKey *mountpoint=NULL) const
 Finds the generator that owns this key.
void add_callback (void *cookie, const UniConfCallback &callback, bool recurse=true) const
 Requests notification when any of the keys covered by the recursive depth specification change by invoking a callback.
void del_callback (void *cookie, bool recurse=true) const
 Cancels notification requested using add_callback().
void add_setbool (bool *flag, bool recurse=true) const
 Requests notification when any of the keys covered by the recursive depth specification change by setting a flag.
void del_setbool (bool *flag, bool recurse=true) const
 Cancels notification requested using add_setbool().
void hold_delta ()
 Pauses notifications until matched with a call to unhold_delta().
void unhold_delta ()
 Resumes notifications when each hold_delta() has been matched.
void clear_delta ()
 Clears the list of pending notifications without sending them.
void flush_delta ()
 Flushes the list of pending notifications by sending them.
void dump (WvStream &stream, bool everything=false) const
 Prints the entire contents of this subtree to a stream.
bool haschildren () const
 Returns true if this key has children.
 DeclareWvList (Iter)

Protected Member Functions

 UniConf (UniConfRoot *root, const UniConfKey &fullkey=UniConfKey::EMPTY)
 Creates a handle to the specified subtree of the given root.

Protected Attributes

UniConfRootxroot
UniConfKey xfullkey

Friends

class UniConfRoot

Classes

class  Iter
 This iterator walks through all immediate children of a UniConf node. More...
class  IterBase
 An implementation base class for key iterators. More...
class  RecursiveIter
 This iterator performs depth-first traversal of a subtree. More...
class  SortedIter
 A sorted variant of UniConf::Iter. More...
class  SortedIterBase
 An implementation base class for sorted key iterators. More...
class  SortedRecursiveIter
 A sorted variant of UniConf::RecursiveIter. More...
class  SortedXIter
 A sorted variant of UniConf::XIter. More...
class  XIter
 This iterator walks over all children that match a wildcard pattern. More...


Constructor & Destructor Documentation

UniConf::UniConf UniConfRoot root,
const UniConfKey fullkey = UniConfKey::EMPTY
[protected]
 

Creates a handle to the specified subtree of the given root.

You can't create non-NULL UniConf objects yourself - ask UniConfRoot or another UniConf object to make one for you.

Definition at line 14 of file uniconf.cc.


Member Function Documentation

UniConfRoot* UniConf::rootobj  )  const [inline]
 

Returns a pointer to the UniConfRoot that manages this node.

This may be NULL, to signal an invalid handle.

Definition at line 103 of file uniconf.h.

References xroot.

Referenced by UniConf::Iter::Iter(), UniConf::RecursiveIter::RecursiveIter(), UniUnwrapGen::setinner(), UniUnwrapGen::setv(), and UniUnwrapGen::~UniUnwrapGen().

UniConfKey UniConf::fullkey const UniConfKey k  )  const
 

Returns the full path of this node, starting at the given key.

Assumes that k is an ancestor of fullkey().

Definition at line 42 of file uniconf.cc.

References UniConfKey::subkey(), and xfullkey.

const UniConf UniConf::operator[] const UniConfKey key  )  const [inline]
 

Returns a handle for a subtree below this key.

'key' is the path of the subtree to be appended to the full path of this handle to obtain the full path of the new handle.

Definition at line 139 of file uniconf.h.

References key(), UniConf(), xfullkey, and xroot.

const UniConf UniConf::u const UniConfKey key  )  const [inline]
 

Return a subtree handle (see operator[]).

Mainly to support bindings for languages that can't handle methods named [].

Definition at line 150 of file uniconf.h.

References key().

WvString UniConf::getme WvStringParm  defvalue = WvString::null  )  const
 

Fetches the string value for this key from the registry.

If the key is not found, returns 'defvalue' instead.

Definition at line 66 of file uniconf.cc.

References UniMountGen::get(), WvFastString::isnull(), UniConfRoot::mounts, xfullkey, and xroot.

Referenced by copy(), UniUnwrapGen::get(), getmeint(), operator *(), operator->(), and WvConfigSectionEmu::operator[]().

int UniConf::getmeint int  defvalue = 0  )  const
 

Fetches the integer value for this key from the registry.

If the key is not found, returns 'defvalue' instead. (This is also used to fetch booleans - 'true', 'yes', 'on' and 'enabled' are recognized as 1, 'false', 'no', 'off' and 'disabled' as 0. Note that a nonexistant key is false by default.)

Definition at line 75 of file uniconf.cc.

References getme(), UniConfRoot::mounts, UniConfGen::str2int(), and xroot.

Referenced by WvConfEmu::getint().

bool UniConf::exists  )  const
 

Without fetching its value, returns true if this key exists.

This is provided because it is often more efficient to test existance than to actually retrieve the value.

Definition at line 48 of file uniconf.cc.

References UniMountGen::exists(), UniConfRoot::mounts, xfullkey, and xroot.

Referenced by UniConfDaemonConn::do_subtree(), UniUnwrapGen::exists(), and UniConf::XIter::rewind().

void UniConf::setme WvStringParm  value  )  const
 

Stores a string value for this key into the registry.

If the value is WvString::null, deletes the key and all of its children.

Definition at line 81 of file uniconf.cc.

References UniConfRoot::mounts, UniMountGen::set(), xfullkey, and xroot.

Referenced by copy(), UniConfDaemonConn::do_set(), WvConfigSectionEmu::quick_set(), remove(), WvConfEmu::set(), WvConfigSectionEmu::set(), UniUnwrapGen::set(), setme(), and setmeint().

void UniConf::move const UniConf dst  )  const
 

Equivalent to "mv" in a standard unix filesystem.

This recursively moves a given key and any subkeys to a new point. If the new point exists then the key will be left as a subkey at the new point. Otherwise, the key will also be renamed to the new point (as when using mv).

Don't try to do dumb stuff like making dst a subkey of this one, or vice versa, because we won't try to save you.

Unlike unix mv(), this is *not* currently atomic. It's more like cp-then-rm.

Definition at line 93 of file uniconf.cc.

References copy(), and remove().

void UniConf::copy const UniConf dst,
bool  force
const
 

Equivalent to "cp -r" in a standard unix filesystem.

This recursively copies a given key to a new location. Any keys that already exist at that location will not be overridden unless force is true.

Don't try to do dumb stuff like making dst a subkey of this one, or vice versa, because we won't try to save you.

Definition at line 101 of file uniconf.cc.

References getme(), UniConf::RecursiveIter::next(), UniConf::RecursiveIter::rewind(), and setme().

Referenced by WvConfEmu::load_file(), move(), and WvConfEmu::save().

bool UniConf::refresh  )  const
 

Refreshes information about this key recursively.

May discard uncommitted data. Returns true on success.

Definition at line 117 of file uniconf.cc.

References UniConfRoot::mounts, UniMountGen::refresh(), and xroot.

Referenced by UniConfDaemonConn::do_refresh(), and UniUnwrapGen::refresh().

IUniConfGen * UniConf::mount WvStringParm  moniker,
bool  refresh = true
const
 

Mounts a generator at this key using a moniker.

If 'refresh' is true, automatically refresh()es the generator after mounting.

Returns the mounted generator, or NULL on failure.

Definition at line 129 of file uniconf.cc.

References UniMountGen::mount(), UniConfRoot::mounts, xfullkey, and xroot.

IUniConfGen * UniConf::mountgen IUniConfGen gen,
bool  refresh = true
const
 

Mounts a generator at this key.

Takes ownership of the supplied generator instance.

If 'refresh' is true, automatically refresh()es the generator after mounting.

Returns the mounted generator, or NULL on failure.

Definition at line 135 of file uniconf.cc.

References UniMountGen::mountgen(), UniConfRoot::mounts, xfullkey, and xroot.

Referenced by UniConfPamConn::UniConfPamConn().

IUniConfGen * UniConf::whichmount UniConfKey mountpoint = NULL  )  const
 

Finds the generator that owns this key.

If the key exists, returns the generator that provides its contents. Otherwise returns the generator that would be updated if a value were set.

If non-NULL, 'mountpoint' is set to the actual key where the generator is mounted.

Definition at line 153 of file uniconf.cc.

References UniConfRoot::mounts, UniMountGen::whichmount(), xfullkey, and xroot.

Referenced by UniUnwrapGen::isok(), and isok().

void UniConf::add_callback void *  cookie,
const UniConfCallback callback,
bool  recurse = true
const
 

Requests notification when any of the keys covered by the recursive depth specification change by invoking a callback.

As a programmer, you probably DO NOT want to use this. Use UniWatchList.add() instead. Otherwise, make sure you call del_callback at the appropriate time.

Definition at line 166 of file uniconf.cc.

References UniConfRoot::add_callback(), xfullkey, and xroot.

Referenced by UniConfDaemonConn::addcallback(), UniWatch::UniWatch(), and WvConfEmu::WvConfEmu().

void UniConf::hold_delta  ) 
 

Pauses notifications until matched with a call to unhold_delta().

While paused, notification events are placed into a pending list. Redundant notifications may be discarded.

Use this to safeguard non-reentrant code.

Definition at line 191 of file uniconf.cc.

References UniConfGen::hold_delta(), UniConfRoot::mounts, and xroot.

void UniConf::unhold_delta  ) 
 

Resumes notifications when each hold_delta() has been matched.

On resumption, dispatches all pending notifications except those that were destined to watches that were removed.

Use this to safeguard non-reentrant code.

Definition at line 197 of file uniconf.cc.

References UniConfRoot::mounts, UniConfGen::unhold_delta(), and xroot.

void UniConf::clear_delta  ) 
 

Clears the list of pending notifications without sending them.

Does not affect the hold nesting count.

Definition at line 203 of file uniconf.cc.

References UniConfGen::clear_delta(), UniConfRoot::mounts, and xroot.

void UniConf::flush_delta  ) 
 

Flushes the list of pending notifications by sending them.

Does not affect the hold nesting count.

Definition at line 209 of file uniconf.cc.

References UniConfGen::flush_delta(), UniConfRoot::mounts, and xroot.

void UniConf::dump WvStream stream,
bool  everything = false
const
 

Prints the entire contents of this subtree to a stream.

If 'everything' is true, also prints empty values.

Definition at line 215 of file uniconf.cc.

References UniConf::RecursiveIter::next(), WvStream::print(), and UniConf::RecursiveIter::rewind().

bool UniConf::haschildren  )  const
 

Returns true if this key has children.

This is provided because it is often more efficient to test existance than to actually retrieve the keys.

Definition at line 54 of file uniconf.cc.

References UniMountGen::haschildren(), UniConfRoot::mounts, xfullkey, and xroot.

Referenced by UniConfDaemonConn::do_haschildren(), UniUnwrapGen::haschildren(), and WvConfigSectionEmu::isempty().


The documentation for this class was generated from the following files:
Generated on Thu May 25 21:51:07 2006 for WvStreams by  doxygen 1.4.6