WvStreams
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | Friends
UniConf Class Reference

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

#include <uniconf.h>

Inheritance diagram for UniConf:
Inheritance graph
[legend]

List of all members.

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

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

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 50 of file uniconf.h.


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 16 of file uniconf.cc.

Creates a NULL UniConf handle, useful for reporting errors.

Definition at line 23 of file uniconf.cc.

Referenced by operator[](), parent(), and root().

UniConf::UniConf ( const UniConf other)

Copies a UniConf handle.

Definition at line 29 of file uniconf.cc.

UniConf::~UniConf ( ) [virtual]

Destroys the UniConf handle.

Definition at line 36 of file uniconf.cc.


Member Function Documentation

UniConf UniConf::root ( ) const [inline]

Returns a handle to the root of the tree.

Definition at line 80 of file uniconf.h.

References UniConfKey::EMPTY, and UniConf().

UniConf UniConf::parent ( ) const [inline]

Returns a handle to the parent of this node.

Definition at line 84 of file uniconf.h.

References UniConfKey::removelast(), and UniConf().

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 91 of file uniconf.h.

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

bool UniConf::isnull ( ) const [inline]

Returns true if the handle is invalid (NULL).

Definition at line 95 of file uniconf.h.

UniConfKey UniConf::fullkey ( ) const [inline]

Returns the full path of this node, starting at the root.

Definition at line 99 of file uniconf.h.

Referenced by UniConf::SortedIterBase::defcomparator(), fullkey(), UniConf::Iter::Iter(), and UniConf::RecursiveIter::RecursiveIter().

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 44 of file uniconf.cc.

References UniConfKey::subkey().

UniConfKey UniConf::fullkey ( const UniConf cfg) const [inline]

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

Definition at line 107 of file uniconf.h.

References fullkey().

Referenced by fullkey().

UniConfKey UniConf::key ( ) const [inline]

Returns the path of this node relative to its parent.

Definition at line 111 of file uniconf.h.

References UniConfKey::last().

Referenced by u(), xget(), xgetint(), xset(), and xsetint().

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 119 of file uniconf.h.

References UniConf().

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 126 of file uniconf.h.

References key().

UniConf& UniConf::operator= ( const UniConf other) [inline]

Reassigns the target of this handle to match a different one.

Definition at line 130 of file uniconf.h.

void UniConf::prefetch ( bool  recursive) const

See UniConfGen::prefetch().

Definition at line 62 of file uniconf.cc.

Referenced by UniUnwrapGen::prefetch().

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 68 of file uniconf.cc.

References WvFastString::isnull().

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

WvString UniConf::operator* ( ) const [inline]

A different way to say cfg.getme(): use *cfg instead.

Definition at line 150 of file uniconf.h.

References getme().

WvStringStar UniConf::operator-> ( ) const [inline]

A different way to say cfg.getme().num(): use cfg->num() instead.

Definition at line 154 of file uniconf.h.

References getme().

WvString UniConf::xget ( WvStringParm  key,
WvStringParm  defvalue = WvString::null 
) const [inline]

A different way to say cfg[x].getme(y).

Definition at line 158 of file uniconf.h.

References key().

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 77 of file uniconf.cc.

References getme().

int UniConf::xgetint ( WvStringParm  key,
int  defvalue = 0 
) const [inline]

A different way to say cfg[x].getmeint(y).

Definition at line 172 of file uniconf.h.

References key().

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 50 of file uniconf.cc.

Referenced by UniUnwrapGen::exists().

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 83 of file uniconf.cc.

Referenced by copy(), remove(), UniUnwrapGen::set(), and setmeint().

void UniConf::xset ( WvStringParm  key,
WvStringParm  value 
) const [inline]

A different way to say cfg[x].setme(y).

Definition at line 199 of file uniconf.h.

References key().

void UniConf::xsetint ( WvStringParm  key,
int  value 
) const [inline]

A different way to say cfg[x].setme(y).

Definition at line 208 of file uniconf.h.

References key().

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 95 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 103 of file uniconf.cc.

References getme(), WvFastString::isnull(), and setme().

Referenced by move().

bool UniConf::refresh ( ) const

Refreshes information about this key recursively.

May discard uncommitted data. Returns true on success.

Definition at line 119 of file uniconf.cc.

Referenced by 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 131 of file uniconf.cc.

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 137 of file uniconf.cc.

void UniConf::unmount ( IUniConfGen gen,
bool  commit 
) const

Unmounts the generator providing this key and destroys it.

Definition at line 143 of file uniconf.cc.

bool UniConf::ismountpoint ( ) const

Determines if any generators are mounted at this key.

Definition at line 149 of file uniconf.cc.

bool UniConf::isok ( ) const

Returns true if the generator at this key isok().

Definition at line 161 of file uniconf.cc.

References IUniConfGen::isok(), and whichmount().

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 155 of file uniconf.cc.

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 168 of file uniconf.cc.

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 193 of file uniconf.cc.

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 199 of file uniconf.cc.

Clears the list of pending notifications without sending them.

Does not affect the hold nesting count.

Definition at line 205 of file uniconf.cc.

Flushes the list of pending notifications by sending them.

Does not affect the hold nesting count.

Definition at line 211 of file uniconf.cc.

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 217 of file uniconf.cc.

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 56 of file uniconf.cc.

Referenced by UniUnwrapGen::haschildren().


The documentation for this class was generated from the following files: