WvStreams
uniconf.h
1 /* -*- Mode: C++ -*-
2  * Worldvisions Weaver Software:
3  * Copyright (C) 1997-2002 Net Integration Technologies, Inc.
4  *
5  * Defines a hierarchical registry abstraction.
6  */
7 #ifndef __UNICONF_H
8 #define __UNICONF_H
9 
10 #include <vector>
11 
12 #include "uniconfgen.h"
13 #include "uniconfkey.h"
14 #include "wvtr1.h"
15 
16 class WvStream;
17 class UniConf;
18 class UniConfRoot;
19 
27 typedef wv::function<void(const UniConf&, const UniConfKey&)> UniConfCallback;
28 
50 class UniConf
51 {
52  friend class UniConfRoot;
53 
54 protected:
55  UniConfRoot *xroot;
56  UniConfKey xfullkey;
57 
65 
66 public:
68  UniConf();
69 
71  UniConf(const UniConf &other);
72 
74  virtual ~UniConf();
75 
76 
77  /***** Handle Manipulation API *****/
78 
80  UniConf root() const
81  { return UniConf(xroot, UniConfKey::EMPTY); }
82 
84  UniConf parent() const
85  { return UniConf(xroot, xfullkey.removelast()); }
86 
92  { return xroot; }
93 
95  bool isnull() const
96  { return xroot == NULL; }
97 
100  { return xfullkey; }
101 
104  UniConfKey fullkey(const UniConfKey &k) const;
105 
107  UniConfKey fullkey(const UniConf &cfg) const
108  { return fullkey(cfg.fullkey()); }
109 
111  UniConfKey key() const
112  { return xfullkey.last(); }
113 
119  const UniConf operator[] (const UniConfKey &key) const
120  { return UniConf(xroot, UniConfKey(xfullkey, key)); }
121 
126  const UniConf u(const UniConfKey &key) const
127  { return (*this)[key]; }
128 
130  UniConf &operator= (const UniConf &other)
131  {
132  xroot = other.xroot;
133  xfullkey = other.xfullkey;
134  return *this;
135  }
136 
137 
138  /***** Key Retrieval API *****/
139 
141  void prefetch(bool recursive) const;
142 
147  WvString getme(WvStringParm defvalue = WvString::null) const;
148 
151  { return getme(); }
152 
155  { return getme(); }
156 
158  WvString xget(WvStringParm key,
159  WvStringParm defvalue = WvString::null) const
160  { return (*this)[key].getme(defvalue); }
161 
169  int getmeint(int defvalue = 0) const;
170 
172  int xgetint(WvStringParm key, int defvalue = 0) const
173  { return (*this)[key].getmeint(defvalue); }
174 
181  bool exists() const;
182 
183 
184  /***** Key Storage API *****/
185 
190  void setme(WvStringParm value) const;
191 
195  void setme(WVSTRING_FORMAT_DECL) const
196  { return setme(WvString(WVSTRING_FORMAT_CALL)); }
197 
199  void xset(WvStringParm key, WvStringParm value) const
200  { (*this)[key].setme(value); }
201 
205  void setmeint(int value) const;
206 
208  void xsetint(WvStringParm key, int value) const
209  { (*this)[key].setmeint(value); }
210 
211 
212  /***** Key Handling API *****/
213 
227  void move(const UniConf &dst) const;
228 
232  void remove() const
233  { setme(WvString::null); }
234 
244  void copy(const UniConf &dst, bool force) const;
245 
246 
247 
248  /***** Key Persistence API *****/
249 
255  bool refresh() const;
256 
260  void commit() const;
261 
262 
263  /***** Generator Mounting API *****/
264 
273  IUniConfGen *mount(WvStringParm moniker, bool refresh = true) const;
274 
285  IUniConfGen *mountgen(IUniConfGen *gen, bool refresh = true) const;
286 
288  void unmount(IUniConfGen *gen, bool commit) const;
289 
291  bool ismountpoint() const;
292 
294  bool isok() const;
295 
306  IUniConfGen *whichmount(UniConfKey *mountpoint = NULL) const;
307 
308 
309  /***** Notification API *****/
310 
319  void add_callback(void *cookie, const UniConfCallback &callback,
320  bool recurse = true) const;
321 
325  void del_callback(void *cookie, bool recurse = true) const;
326 
331  void add_setbool(bool *flag, bool recurse = true) const;
332 
336  void del_setbool(bool *flag, bool recurse = true) const;
337 
346  void hold_delta();
347 
356  void unhold_delta();
357 
362  void clear_delta();
363 
368  void flush_delta();
369 
370 
371  /***** Key Enumeration API *****/
372 
377  void dump(WvStream &stream, bool everything = false) const;
378 
385  bool haschildren() const;
386 
387  /*** Iterators (see comments in class declaration) ***/
388 
389  // internal base class for all of the key iterators
390  class IterBase;
391  // iterates over direct children
392  class Iter;
393  // iterates over all descendents in preorder traversal
394  class RecursiveIter;
395  // iterates over children matching a wildcard
396  class XIter;
397 
398  // internal base class for sorted key iterators
399  class SortedIterBase;
400  // sorted variant of Iter
401  class SortedIter;
402  // sorted variant of RecursiveIter
403  class SortedRecursiveIter;
404  // sorted variant of XIter
405  class SortedXIter;
406 
407  // lists of iterators
408  DeclareWvList(Iter);
409 };
410 
411 
416 {
417 protected:
418  UniConf top;
419  UniConf current;
420 
421  IterBase(const UniConf &_top)
422  : top(_top)
423  { }
424 
425 public:
426  const UniConf *ptr() const
427  { return &current; }
428  WvIterStuff(const UniConf);
429 };
430 
431 
436 {
437  UniConfGen::Iter *it;
438 
439 public:
441  Iter(const UniConf &_top);
442 
443  ~Iter()
444  { delete it; }
445 
446  void rewind()
447  { it->rewind(); }
448  bool next()
449  {
450  if (!it->next())
451  return false;
452  current = top[it->key()];
453  return true;
454  }
455 
456  // FIXME: this is a speed optimization only. Don't use this unless
457  // you're apenwarr. It will change.
458  WvString _value() const
459  { return it->value(); }
460 };
461 
462 
467 {
468  UniConfGen::Iter *it;
469 
470 public:
472  RecursiveIter(const UniConf &_top);
473 
474  ~RecursiveIter()
475  { delete it; }
476 
477  void rewind()
478  { it->rewind(); }
479  bool next()
480  {
481  if (!it->next())
482  return false;
483  current = top[it->key()];
484  return true;
485  }
486 
487  // FIXME: this is a speed optimization only. Don't use this unless
488  // you're apenwarr. It will change.
489  WvString _value() const
490  { return it->value(); }
491 };
492 
493 
512 {
513  UniConfKey pathead;
514  UniConfKey pattail;
515  UniConf::XIter *subit;
516  UniConf::Iter *it;
517  UniConf::RecursiveIter *recit;
518  bool ready;
520 public:
522  XIter(const UniConf &_top, const UniConfKey &pattern);
523  ~XIter();
524 
525  void rewind();
526  bool next();
527 
528 private:
529  void cleanup();
530  bool qnext();
531  void enter(const UniConf &child);
532 };
533 
534 
544 {
545 public:
546  typedef int (*Comparator)(const UniConf &a, const UniConf &b);
547 
549  static int defcomparator(const UniConf &a, const UniConf &b);
550 
551  SortedIterBase(const UniConf &_top, Comparator comparator = defcomparator);
552  ~SortedIterBase();
553 
554  bool next();
555 
556 private:
557  Comparator xcomparator;
558  int index;
559  int count;
560 
561  void _purge();
562  void _rewind();
563 
564 protected:
565  std::vector<UniConf> xkeys;
566 
567  template<class Iter>
568  void populate(Iter &i)
569  {
570  _purge();
571  for (i.rewind(); i.next(); )
572  xkeys.push_back(*i);
573  _rewind();
574  }
575 };
576 
577 
582 {
583  UniConf::Iter i;
584 
585 public:
586  SortedIter(const UniConf &_top, Comparator comparator = defcomparator)
587  : SortedIterBase(_top, comparator), i(_top)
588  { }
589 
590  void rewind()
591  { populate(i); }
592 };
593 
594 
599 {
601 
602 public:
603  SortedRecursiveIter(const UniConf &_top,
604  Comparator comparator = defcomparator)
605  : SortedIterBase(_top, comparator), i(_top)
606  { }
607 
608  void rewind()
609  { populate(i); }
610 };
611 
612 
617 {
618  UniConf::XIter i;
619 
620 public:
621  SortedXIter(const UniConf &_top, const UniConfKey &pattern,
622  Comparator comparator = defcomparator)
623  : SortedIterBase(_top, comparator), i(_top, pattern)
624  { }
625 
626  void rewind()
627  { populate(i); }
628 };
629 
630 #endif // __UNICONF_H
UniConf::IterBase
An implementation base class for key iterators.
Definition: uniconf.h:415
UniConf::refresh
bool refresh() const
Refreshes information about this key recursively.
Definition: uniconf.cc:119
UniConf::commit
void commit() const
Commits information about this key recursively.
Definition: uniconf.cc:125
UniConf::UniConf
UniConf()
Creates a NULL UniConf handle, useful for reporting errors.
Definition: uniconf.cc:23
UniConf::XIter
This iterator walks over all children that match a wildcard pattern.
Definition: uniconf.h:511
UniConf::operator->
WvStringStar operator->() const
A different way to say cfg.getme().num(): use cfg->num() instead.
Definition: uniconf.h:154
UniConfGen::Iter::value
virtual WvString value() const =0
Returns the value of the current key.
UniConf::setmeint
void setmeint(int value) const
Stores an integer value for this key into the registry.
Definition: uniconf.cc:89
UniConf::xgetint
int xgetint(WvStringParm key, int defvalue=0) const
A different way to say cfg[x].getmeint(y).
Definition: uniconf.h:172
UniConf::del_callback
void del_callback(void *cookie, bool recurse=true) const
Cancels notification requested using add_callback().
Definition: uniconf.cc:175
UniConf::Iter::Iter
Iter(const UniConf &_top)
Creates an iterator over the direct children of a branch.
Definition: uniconf.cc:232
UniConf::~UniConf
virtual ~UniConf()
Destroys the UniConf handle.
Definition: uniconf.cc:36
UniConf::operator=
UniConf & operator=(const UniConf &other)
Reassigns the target of this handle to match a different one.
Definition: uniconf.h:130
UniConf::xset
void xset(WvStringParm key, WvStringParm value) const
A different way to say cfg[x].setme(y).
Definition: uniconf.h:199
UniConfKey::removelast
UniConfKey removelast(int n=1) const
Returns the path formed by removing the last n segments of this path.
Definition: uniconfkey.h:346
UniConf::mountgen
IUniConfGen * mountgen(IUniConfGen *gen, bool refresh=true) const
Mounts a generator at this key.
Definition: uniconf.cc:137
UniConf::add_callback
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 inv...
Definition: uniconf.cc:168
UniConf::SortedIterBase
An implementation base class for sorted key iterators.
Definition: uniconf.h:543
UniConf::isok
bool isok() const
Returns true if the generator at this key isok().
Definition: uniconf.cc:161
UniConf::remove
void remove() const
Removes this key and all of its children from the registry.
Definition: uniconf.h:232
UniConf
UniConf instances function as handles to subtrees of a UniConf tree and expose a high-level interface...
Definition: uniconf.h:50
UniConfGen::Iter::key
virtual UniConfKey key() const =0
Returns the current key.
UniConf::setme
void setme(WVSTRING_FORMAT_DECL) const
Stores a string value for this key into the registry.
Definition: uniconf.h:195
UniConf::prefetch
void prefetch(bool recursive) const
See UniConfGen::prefetch().
Definition: uniconf.cc:62
UniConf::root
UniConf root() const
Returns a handle to the root of the tree.
Definition: uniconf.h:80
UniConf::getme
WvString getme(WvStringParm defvalue=WvString::null) const
Fetches the string value for this key from the registry.
Definition: uniconf.cc:68
UniConf::dump
void dump(WvStream &stream, bool everything=false) const
Prints the entire contents of this subtree to a stream.
Definition: uniconf.cc:217
UniConf::unmount
void unmount(IUniConfGen *gen, bool commit) const
Unmounts the generator providing this key and destroys it.
Definition: uniconf.cc:143
UniConf::flush_delta
void flush_delta()
Flushes the list of pending notifications by sending them.
Definition: uniconf.cc:211
UniConf::SortedIterBase::defcomparator
static int defcomparator(const UniConf &a, const UniConf &b)
Default comparator.
Definition: uniconf.cc:424
UniConf::add_setbool
void add_setbool(bool *flag, bool recurse=true) const
Requests notification when any of the keys covered by the recursive depth specification change by set...
Definition: uniconf.cc:181
WvString
WvString is an implementation of a simple and efficient printable-string class.
Definition: wvstring.h:329
UniConf::parent
UniConf parent() const
Returns a handle to the parent of this node.
Definition: uniconf.h:84
IUniConfGen
An abstract data container that backs a UniConf tree.
Definition: uniconfgen.h:39
UniConf::rootobj
UniConfRoot * rootobj() const
Returns a pointer to the UniConfRoot that manages this node.
Definition: uniconf.h:91
UniConfKey
Represents a UniConf key which is a path in a hierarchy structured much like the traditional Unix fil...
Definition: uniconfkey.h:38
UniConf::del_setbool
void del_setbool(bool *flag, bool recurse=true) const
Cancels notification requested using add_setbool().
Definition: uniconf.cc:187
UniConf::copy
void copy(const UniConf &dst, bool force) const
Equivalent to "cp -r" in a standard unix filesystem.
Definition: uniconf.cc:103
UniConf::SortedRecursiveIter
A sorted variant of UniConf::RecursiveIter.
Definition: uniconf.h:598
UniConf::operator*
WvString operator*() const
A different way to say cfg.getme(): use *cfg instead.
Definition: uniconf.h:150
UniConfKey::EMPTY
static UniConfKey EMPTY
Definition: uniconfkey.h:171
UniConf::xsetint
void xsetint(WvStringParm key, int value) const
A different way to say cfg[x].setme(y).
Definition: uniconf.h:208
UniConf::getmeint
int getmeint(int defvalue=0) const
Fetches the integer value for this key from the registry.
Definition: uniconf.cc:77
WvStringStar
A ridiculous class needed because UniConf::operator->() needs to return a pointer,...
Definition: wvstring.h:420
UniConf::setme
void setme(WvStringParm value) const
Stores a string value for this key into the registry.
Definition: uniconf.cc:83
WvStream
Unified support for streams, that is, sequences of bytes that may or may not be ready for read/write ...
Definition: wvstream.h:24
UniConf::xget
WvString xget(WvStringParm key, WvStringParm defvalue=WvString::null) const
A different way to say cfg[x].getme(y).
Definition: uniconf.h:158
UniConf::mount
IUniConfGen * mount(WvStringParm moniker, bool refresh=true) const
Mounts a generator at this key using a moniker.
Definition: uniconf.cc:131
UniConf::RecursiveIter::RecursiveIter
RecursiveIter(const UniConf &_top)
Creates a recursive iterator over a branch.
Definition: uniconf.cc:243
UniConfGen::Iter::rewind
virtual void rewind()=0
Rewinds the iterator.
UniConf::fullkey
UniConfKey fullkey() const
Returns the full path of this node, starting at the root.
Definition: uniconf.h:99
UniConfGen::Iter::next
virtual bool next()=0
Seeks to the next element in the sequence.
UniConf::hold_delta
void hold_delta()
Pauses notifications until matched with a call to unhold_delta().
Definition: uniconf.cc:193
UniConf::XIter::XIter
XIter(const UniConf &_top, const UniConfKey &pattern)
Creates a wildcard iterator.
Definition: uniconf.cc:253
UniConf::SortedXIter
A sorted variant of UniConf::XIter.
Definition: uniconf.h:616
UniConf::haschildren
bool haschildren() const
Returns true if this key has children.
Definition: uniconf.cc:56
UniConf::SortedIter
A sorted variant of UniConf::Iter.
Definition: uniconf.h:581
UniConfKey::last
UniConfKey last(int n=1) const
Returns the path formed by the n last segments of this path.
Definition: uniconfkey.h:324
UniConf::operator[]
const UniConf operator[](const UniConfKey &key) const
Returns a handle for a subtree below this key.
Definition: uniconf.h:119
UniConfRoot
Represents the root of a hierarhical registry consisting of pairs of UniConfKeys and associated strin...
Definition: uniconfroot.h:73
UniConf::ismountpoint
bool ismountpoint() const
Determines if any generators are mounted at this key.
Definition: uniconf.cc:149
UniConf::u
const UniConf u(const UniConfKey &key) const
Return a subtree handle (see operator[]).
Definition: uniconf.h:126
UniConf::move
void move(const UniConf &dst) const
Equivalent to "mv" in a standard unix filesystem.
Definition: uniconf.cc:95
UniConf::fullkey
UniConfKey fullkey(const UniConf &cfg) const
Returns the full path of this node, starting at the given handle.
Definition: uniconf.h:107
UniConf::Iter
This iterator walks through all immediate children of a UniConf node.
Definition: uniconf.h:435
UniConf::exists
bool exists() const
Without fetching its value, returns true if this key exists.
Definition: uniconf.cc:50
UniConf::key
UniConfKey key() const
Returns the path of this node relative to its parent.
Definition: uniconf.h:111
UniConf::clear_delta
void clear_delta()
Clears the list of pending notifications without sending them.
Definition: uniconf.cc:205
UniConf::unhold_delta
void unhold_delta()
Resumes notifications when each hold_delta() has been matched.
Definition: uniconf.cc:199
UniConf::RecursiveIter
This iterator performs depth-first traversal of a subtree.
Definition: uniconf.h:466
UniConf::isnull
bool isnull() const
Returns true if the handle is invalid (NULL).
Definition: uniconf.h:95
UniConf::whichmount
IUniConfGen * whichmount(UniConfKey *mountpoint=NULL) const
Finds the generator that owns this key.
Definition: uniconf.cc:155
UniConfGen::Iter
An abstract iterator over keys and values in a generator.
Definition: uniconfgen.h:323