Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

plist::Collection Class Reference

#include <plistCollections.h>

Inheritance diagram for plist::Collection:

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 69 of file plistCollections.h.

List of all members.

Classes

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

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
bool resolveAssignment (const std::string &arg)
 Processes a command of the form 'collection.key = value' or 'collection.array += entry'.
bool resolveAssignment (const std::string &arg, std::ostream &errstream)
 Processes a command of the form 'collection.key = value' or 'collection.array += entry'.
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 setSaveCondensed (bool b)
 set saveCondensed (not automatically recursive)
bool getSaveCondensed () const
 returns saveCondensed
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 saveCondensed
 if true, will skip putting "headline" comments before sub-collections
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

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 75 of file plistCollections.h.

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

Loading SYNCINTERSECTUNIONFIXED
entry not in file
(missing from source)
remove from
collection
remove from
collection
ignoreignore
entry not in collection
(missing from destination)
add to
collection
ignoreadd to
collection
ignore


Saving SYNCINTERSECTUNIONFIXED
entry not in file
(missing from destination)
add to
file
ignoreadd to
file
ignore
entry not in collection
(missing from source)
remove
from file
remove
from file
ignoreignore

Commonly, you'll want to use SYNC (the default) to support dynamically-resized 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 95 of file plistCollections.h.


Constructor & Destructor Documentation

plist::Collection::~Collection (  ) 

destructor

Definition at line 54 of file plistCollections.cc.

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

constructor

Definition at line 158 of file plistCollections.h.

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

constructor

Definition at line 160 of file plistCollections.h.

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

copy constructor (don't assign listeners)

Definition at line 162 of file plistCollections.h.


Member Function Documentation

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

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

Definition at line 153 of file plistCollections.cc.

Referenced by plist::AutoCollectionListener::activate(), and KinematicJoint::ComponentsListener::ComponentsListener().

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

remove all entries in one fell swoop

Implemented in ConvexPolyObstacle, HierarchicalObstacle, plist::DictionaryBase, plist::ArrayBase, and plist::RGBColor< T >.

static const std::string& plist::Collection::emptyStr (  )  [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 181 of file plistCollections.h.

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

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

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

Definition at line 210 of file plistCollections.cc.

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

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, plist::ArrayBase, and plist::RGBColor< T >.

Definition at line 198 of file plistCollections.cc.

std::string plist::Collection::getIndentationPrefix ( xmlNode node  )  [static, protected]
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 235 of file plistCollections.cc.

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

virtual LoadSavePolicy plist::Collection::getLoadPolicy (  )  const [virtual]
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, plist::ArrayBase, and plist::RGBColor< T >.

bool plist::Collection::getSaveCondensed (  )  const

returns saveCondensed

Definition at line 129 of file plistCollections.h.

virtual LoadSavePolicy plist::Collection::getSavePolicy (  )  const [virtual]
bool plist::Collection::getUnusedWarning (  )  const

returns warnUnused

Definition at line 132 of file plistCollections.h.

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

test if l is currently registered as a listener

Definition at line 174 of file plistCollections.cc.

Collection& plist::Collection::operator= ( const Collection d  ) 

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

Definition at line 103 of file plistCollections.h.

static const std::string& plist::Collection::perIndent (  )  [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 187 of file plistCollections.h.

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

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

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

Definition at line 161 of file plistCollections.cc.

Referenced by plist::AutoCollectionListener::deactivate(), and KinematicJoint::ComponentsListener::~ComponentsListener().

bool plist::Collection::resolveAssignment ( const std::string &  arg,
std::ostream &  errstream 
)

Processes a command of the form 'collection.key = value' or 'collection.array += entry'.

Returns whether the assignment was successful, and if an error occurrs, places the error message in errstream

Definition at line 64 of file plistCollections.cc.

bool plist::Collection::resolveAssignment ( const std::string &  arg  ) 

Processes a command of the form 'collection.key = value' or 'collection.array += entry'.

Returns whether the assignment was successful, but does not provide error message (see other version if you want a string to give user)

Definition at line 59 of file plistCollections.cc.

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, plist::ArrayBase, and plist::RGBColor< T >.

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

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

assigns loadPolicy

Definition at line 136 of file plistCollections.h.

Referenced by plist::DictionaryBase::loadXML(), and setLoadSavePolicy().

void plist::Collection::setSaveCondensed ( bool  b  ) 

set saveCondensed (not automatically recursive)

Definition at line 128 of file plistCollections.h.

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

assigns savePolicy

Definition at line 137 of file plistCollections.h.

Referenced by setLoadSavePolicy().

void plist::Collection::setUnusedWarning ( bool  b  ) 
virtual size_t plist::Collection::size (  )  const [pure virtual]

return the size of the collection

Implemented in plist::DictionaryBase, plist::ArrayBase, and plist::RGBColor< T >.

Referenced by ConfigurationEditor::refresh().

static const std::string& plist::Collection::subCollectionSep (  )  [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 142 of file plistCollections.h.

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

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 184 of file plistCollections.cc.

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 183 of file plistCollections.cc.


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 192 of file plistCollections.h.

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

if true, will skip putting "headline" comments before sub-collections

Definition at line 195 of file plistCollections.h.

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

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 197 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 v5.1CVS
Generated Mon May 9 04:59:24 2016 by Doxygen 1.6.3