Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

plist::Collection Class Reference

#include <plistCollections.h>

Inheritance diagram for plist::Collection:

List of all members.


Detailed Description

Provides a common base class for the collection-oriented primitives, Dictionary and Array.

When a collection, you can call addEntry() or setEntry() you can either:

  • pass a pointer to an ObjectBase or directly pass a primitive value (int, float, char, etc.), in which case the Array will assume management of the corresponding ObjectBase instance (freeing the memory region when removed)
  • pass a reference to an ObjectBase, in which case you retain control over the object's allocation

This class supports callbacks upon modification through the use of the CollectionListener interface. Note that we only store a pointer to the listener list, which is typically unallocated when no listeners are active. This should ensure minimal memory usage per object, as well as support safe storage of plist objects in inter-process shared memory regions.

If you are using these in a shared memory region, just be sure that only the process with listeners does any and all modifications, and that it unsubscribes before detaching from the region (or else destroys the region itself)

There isn't a callback if entries themselves are modified, only when new entries are added, or old ones removed. If you want to know any time any aspect of any entry is modified, listen for the add and remove callbacks, and then add yourself as a listener to each entry individually.

Definition at line 41 of file plistCollections.h.


Public Types

enum  LoadSaveActionBitMask { ADDITIONS = 1, REMOVALS = 2 }
 used to define values for LoadSavePolicy values so we can test a bit out of the policy value More...
enum  LoadSavePolicy { FIXED = 0, UNION = ADDITIONS, INTERSECT = REMOVALS, SYNC = ADDITIONS|REMOVALS }
 Arguments for setLoadPolicy() and setSavePolicy(), specifies how to handle orphaned entries when loading or saving. More...

Public Member Functions

Collectionoperator= (const Collection &d)
 assignment (don't assign listeners); subclass should call fireEntriesChanged after calling this (and updating its own storage)
 ~Collection ()
 destructor
virtual ObjectBaseresolveEntry (const std::string &path) const =0
 recursively resolves path interpreted as a series of collection entry names separated by '.', returns NULL if it doesn't exist
virtual void clear ()=0
 remove all entries in one fell swoop
virtual size_t size () const =0
 return the size of the collection
virtual void addCollectionListener (CollectionListener *l) const
 get notified of changes; be sure to call removeCollectionListener() before destructing l!
virtual void removeCollectionListener (CollectionListener *l) const
 no longer take notification of changes to this object's value
virtual bool isCollectionListener (CollectionListener *l) const
 test if l is currently registered as a listener
void setUnusedWarning (bool b)
 set warnUnused
bool getUnusedWarning () const
 returns warnUnused
virtual LoadSavePolicy getLoadPolicy () const
 returns loadPolicy
virtual LoadSavePolicy getSavePolicy () const
 returns savePolicy
virtual void setLoadPolicy (LoadSavePolicy lp)
 assigns loadPolicy
virtual void setSavePolicy (LoadSavePolicy sp)
 assigns savePolicy
virtual void setLoadSavePolicy (LoadSavePolicy lp, LoadSavePolicy sp)
 assigns loadPolicy and savePolicy respectively
virtual unsigned int getLongestKeyLen (const regex_t *reg=NULL, unsigned int depth=-1) const =0
 returns longest key length which matches the regular expression
virtual bool canContain (const ObjectBase &obj)=0
 returns true if the Collection subclass allows storage of the argument
virtual long toLong () const
 return current value as an (long) integer (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)
virtual double toDouble () const
 return current value as a double (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)

Static Public Member Functions

static const std::string & subCollectionSep ()
 defines separator between sub-collections

Protected Member Functions

 Collection ()
 constructor
 Collection (LoadSavePolicy lp, LoadSavePolicy sp)
 constructor
 Collection (const Collection &d)
 copy constructor (don't assign listeners)
virtual void fireEntryAdded (ObjectBase &val)
 run through collectionListeners, calling CollectionListener::plistCollectionEntryAdded(*this,val)
virtual void fireEntryRemoved (ObjectBase &val)
 run through collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val)
virtual void fireEntriesChanged ()
 run through collectionListeners, calling CollectionListener::plistCollectionEntriesChanged(*this)

Static Protected Member Functions

static size_t getIndex (const std::string &name)
 returns index corresponding to name, which should encode an integer value less than or equal to the current size
static std::string getIndentationPrefix (xmlNode *node)
 returns a prefix for items within the collection
static const std::string & emptyStr ()
 when an empty string is needed for not found items
static const std::string & perIndent ()
 how much to indent each sub-collection

Protected Attributes

std::set< CollectionListener * > * collectionListeners
 stores a list of the current listeners
bool warnUnused
 if true (the default) loadXML will give warnings using FIXED policy and there are ignored entries in the source while loading or ignored entries in the destination while saving
LoadSavePolicy loadPolicy
 specifies how to handle "orphaned" entries while loading
LoadSavePolicy savePolicy
 specifies how to handle "orphaned" entries while saving

Static Protected Attributes

static const unsigned int KEY_IN_COMMENT_MAX_POS = 10
 when saving comments to file, the key name will automatically be prepended to the comment, unless the key is found within this many characters from the beginning of the comment

Classes

struct  conversion_policy
 Specifies that a collection of collections cannot contain any primitive values. More...

Member Enumeration Documentation

used to define values for LoadSavePolicy values so we can test a bit out of the policy value

Enumerator:
ADDITIONS  if this bit is set in loadPolicy's value, entries not found in the collection will be added, or for savePolicy, entries will be added to the file
REMOVALS  if this bit is set in loadPolicy's value, entries not found in the file will be removed from the collection, or for savePolicy, entries will be removed from the file

Definition at line 47 of file plistCollections.h.

Arguments for setLoadPolicy() and setSavePolicy(), specifies how to handle orphaned entries when loading or saving.

An entry is considered "orphaned" if you are loading or saving into a pre-existing file, and an entry exists in one location (the collection or the file), but not the other. The results look like this... (add/remove refer to the destination i.e. collection if loading, file if saving):
Loading SYNCINTERSECTUNIONFIXED
not in file, in collectionremoveremoveignoreignore
in file, not in collectionaddignoreaddignore
Saving SYNCINTERSECTUNIONFIXED
not in file, in collectionaddignoreaddignore
in file, not in collectionremoveremoveignoreignore

Commonly, you'll want to use SYNC (the default) to support dynamic storage, and FIXED load/SYNC save for configuration settings (or perhaps FIXED load and UNION save to keep 'extra' values in the file...)

Enumerator:
FIXED  destination will have the same entries as before, ignores orphans and only updates entries with matching keys
UNION  destination will have its current entries, as well as new ones from the source
INTERSECT  destination will only hold entries which are in both locations, removes entries not found in source, ignores new entries
SYNC  destination will mirror source, new entries are added, missing entries are removed

Definition at line 67 of file plistCollections.h.


Constructor & Destructor Documentation

plist::Collection::~Collection (  ) 

destructor

Definition at line 11 of file plistCollections.cc.

plist::Collection::Collection (  )  [inline, protected]

constructor

Definition at line 121 of file plistCollections.h.

plist::Collection::Collection ( LoadSavePolicy  lp,
LoadSavePolicy  sp 
) [inline, protected]

constructor

Definition at line 123 of file plistCollections.h.

plist::Collection::Collection ( const Collection d  )  [inline, protected]

copy constructor (don't assign listeners)

Definition at line 125 of file plistCollections.h.


Member Function Documentation

Collection& plist::Collection::operator= ( const Collection d  )  [inline]

assignment (don't assign listeners); subclass should call fireEntriesChanged after calling this (and updating its own storage)

Definition at line 75 of file plistCollections.h.

Referenced by plist::ArrayBase::operator=(), and plist::DictionaryBase::operator=().

virtual ObjectBase* plist::Collection::resolveEntry ( const std::string &  path  )  const [pure virtual]

recursively resolves path interpreted as a series of collection entry names separated by '.', returns NULL if it doesn't exist

Implemented in plist::DictionaryBase, and plist::ArrayBase.

Referenced by ConfigurationEditor::refresh(), plist::ArrayBase::resolveEntry(), plist::DictionaryBase::resolveEntry(), and Config::setValue().

virtual void plist::Collection::clear (  )  [pure virtual]

remove all entries in one fell swoop

Implemented in plist::DictionaryBase, and plist::ArrayBase.

virtual size_t plist::Collection::size (  )  const [pure virtual]

return the size of the collection

Implemented in plist::DictionaryBase, and plist::ArrayBase.

Referenced by ConfigurationEditor::refresh().

void plist::Collection::addCollectionListener ( CollectionListener l  )  const [virtual]

get notified of changes; be sure to call removeCollectionListener() before destructing l!

Definition at line 16 of file plistCollections.cc.

void plist::Collection::removeCollectionListener ( CollectionListener l  )  const [virtual]

no longer take notification of changes to this object's value

Definition at line 24 of file plistCollections.cc.

bool plist::Collection::isCollectionListener ( CollectionListener l  )  const [virtual]

test if l is currently registered as a listener

Definition at line 37 of file plistCollections.cc.

void plist::Collection::setUnusedWarning ( bool  b  )  [inline]

set warnUnused

Definition at line 94 of file plistCollections.h.

Referenced by Config::behaviors_config::behaviors_config().

bool plist::Collection::getUnusedWarning (  )  const [inline]

returns warnUnused

Definition at line 95 of file plistCollections.h.

virtual LoadSavePolicy plist::Collection::getLoadPolicy (  )  const [inline, virtual]

virtual LoadSavePolicy plist::Collection::getSavePolicy (  )  const [inline, virtual]

virtual void plist::Collection::setLoadPolicy ( LoadSavePolicy  lp  )  [inline, virtual]

assigns loadPolicy

Definition at line 99 of file plistCollections.h.

Referenced by setLoadSavePolicy().

virtual void plist::Collection::setSavePolicy ( LoadSavePolicy  sp  )  [inline, virtual]

assigns savePolicy

Definition at line 100 of file plistCollections.h.

Referenced by setLoadSavePolicy().

virtual void plist::Collection::setLoadSavePolicy ( LoadSavePolicy  lp,
LoadSavePolicy  sp 
) [inline, virtual]

static const std::string& plist::Collection::subCollectionSep (  )  [inline, static]

defines separator between sub-collections

(defined as a function instead of just a constant member so there's no issues with initialization order)

Definition at line 105 of file plistCollections.h.

Referenced by plist::filteredDisplay(), plist::ArrayBase::getLongestKeyLen(), plist::DictionaryBase::getLongestKeyLen(), plist::ArrayBase::getSubEntry(), plist::DictionaryBase::getSubEntry(), and ConfigurationEditor::refresh().

virtual unsigned int plist::Collection::getLongestKeyLen ( const regex_t *  reg = NULL,
unsigned int  depth = -1 
) const [pure virtual]

returns longest key length which matches the regular expression

Implemented in plist::DictionaryBase, and plist::ArrayBase.

virtual bool plist::Collection::canContain ( const ObjectBase obj  )  [pure virtual]

long plist::Collection::toLong (  )  const [virtual]

return current value as an (long) integer (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)

Implements plist::ObjectBase.

Definition at line 46 of file plistCollections.cc.

double plist::Collection::toDouble (  )  const [virtual]

return current value as a double (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)

Implements plist::ObjectBase.

Definition at line 47 of file plistCollections.cc.

void plist::Collection::fireEntryAdded ( ObjectBase val  )  [protected, virtual]

void plist::Collection::fireEntryRemoved ( ObjectBase val  )  [protected, virtual]

run through collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val)

Reimplemented in plist::DictionaryBase, and plist::ArrayBase.

Definition at line 61 of file plistCollections.cc.

Referenced by plist::ArrayBase::fireEntryRemoved(), and plist::DictionaryBase::fireEntryRemoved().

void plist::Collection::fireEntriesChanged (  )  [protected, virtual]

run through collectionListeners, calling CollectionListener::plistCollectionEntriesChanged(*this)

Definition at line 73 of file plistCollections.cc.

Referenced by plist::ArrayBase::clear(), plist::DictionaryBase::clear(), plist::DictionaryBase::renameEntry(), plist::ArrayOf< PO, Alloc >::setEntry(), and plist::DictionaryBase::swapEntry().

size_t plist::Collection::getIndex ( const std::string &  name  )  [static, protected]

returns index corresponding to name, which should encode an integer value less than or equal to the current size

Definition at line 98 of file plistCollections.cc.

Referenced by plist::ArrayBase::getSubEntry(), and plist::ArrayBase::resolveEntry().

std::string plist::Collection::getIndentationPrefix ( xmlNode node  )  [static, protected]

returns a prefix for items within the collection

Definition at line 85 of file plistCollections.cc.

Referenced by plist::ArrayBase::saveXML(), plist::DictionaryBase::saveXML(), OutputConfig< T >::saveXML(), and Config::saveXML().

static const std::string& plist::Collection::emptyStr (  )  [inline, static, protected]

when an empty string is needed for not found items

(defined as a function instead of just a constant member so there's no issues with initialization order)

Definition at line 144 of file plistCollections.h.

Referenced by plist::ArrayBase::getComment(), and plist::DictionaryBase::getComment().

static const std::string& plist::Collection::perIndent (  )  [inline, static, protected]

how much to indent each sub-collection

(defined as a function instead of just a constant member so there's no issues with initialization order)

Definition at line 150 of file plistCollections.h.

Referenced by getIndentationPrefix(), plist::ArrayBase::saveXML(), plist::DictionaryBase::saveXML(), and OutputConfig< T >::saveXML().


Member Data Documentation

const unsigned int plist::Collection::KEY_IN_COMMENT_MAX_POS = 10 [static, protected]

when saving comments to file, the key name will automatically be prepended to the comment, unless the key is found within this many characters from the beginning of the comment

Definition at line 155 of file plistCollections.h.

Referenced by plist::DictionaryBase::saveOverXMLNode(), and plist::DictionaryBase::saveXMLNode().

if true (the default) loadXML will give warnings using FIXED policy and there are ignored entries in the source while loading or ignored entries in the destination while saving

Definition at line 158 of file plistCollections.h.

Referenced by getUnusedWarning(), plist::ArrayOf< PO, Alloc >::loadXMLNode(), plist::DictionaryOf< PO, Alloc >::loadXMLNode(), plist::ArrayOf< PO, Alloc >::operator=(), plist::DictionaryOf< PO, Alloc >::operator=(), plist::ArrayBase::saveXML(), plist::DictionaryBase::saveXML(), plist::ArrayOf< PO, Alloc >::set(), plist::DictionaryOf< PO, Alloc >::set(), and setUnusedWarning().


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

Tekkotsu v4.0
Generated Thu Nov 22 00:58:54 2007 by Doxygen 1.5.4