plist::Collection Class Reference
#include <plistCollections.h>
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.
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 | |
| Collection & | operator= (const Collection &d) |
| assignment (don't assign listeners); subclass should call fireEntriesChanged after calling this (and updating its own storage) | |
| ~Collection () | |
| destructor | |
| virtual ObjectBase * | resolveEntry (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 | SYNC | INTERSECT | UNION | FIXED |
|---|---|---|---|---|
| entry not in file (missing from source) | remove from collection | remove from collection | ignore | ignore |
| entry not in collection (missing from destination) | add to collection | ignore | add to collection | ignore |
| Saving | SYNC | INTERSECT | UNION | FIXED |
|---|---|---|---|---|
| entry not in file (missing from destination) | add to file | ignore | add to file | ignore |
| entry not in collection (missing from source) | remove from file | remove from file | ignore | ignore |
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:
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 bool plist::Collection::canContain | ( | const ObjectBase & | obj | ) | [pure virtual] |
returns true if the Collection subclass allows storage of the argument
Implemented in plist::DictionaryOf< PO, Alloc >, plist::ArrayOf< PO, Alloc >, plist::RGBColor< T >, plist::DictionaryOf< SinusoidalParameters >, plist::DictionaryOf< plist::Primitive< float > >, plist::DictionaryOf< plist::Primitive< T > >, plist::DictionaryOf< plist::Point >, plist::ArrayOf< ContactPoint >, plist::ArrayOf< plist::ArrayOf< plist::Primitive< float > > >, plist::ArrayOf< LinkComponent >, plist::ArrayOf< SensorInfo >, plist::ArrayOf< plist::Primitive< std::string > >, plist::ArrayOf< KinematicJoint >, plist::ArrayOf< plist::Primitive< float > >, plist::ArrayOf< plist::Primitive< T > >, plist::ArrayOf< plist::Angle >, plist::ArrayOf< LegParameters >, and plist::ArrayOf< plist::Primitive< PLISTREAL > >.
Referenced by ConfigurationEditor::AddCollectionEntry::refresh().
| 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] |
run through collectionListeners, calling CollectionListener::plistCollectionEntryAdded(*this,val)
Definition at line 186 of file plistCollections.cc.
Referenced by plist::ArrayOf< PO, Alloc >::addEntry(), plist::ArrayOf< plist::Primitive< PLISTREAL > >::addEntry(), plist::DictionaryOf< PO, Alloc >::addEntry(), plist::DictionaryOf< plist::Point >::getEntry(), plist::ArrayOf< PO, Alloc >::setEntry(), and plist::DictionaryOf< PO, Alloc >::setEntry().
| 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] |
returns a prefix for items within the collection
Definition at line 222 of file plistCollections.cc.
Referenced by plist::ArrayBase::saveXML(), plist::DictionaryBase::saveXML(), KinematicJoint::saveXML(), KinematicJointSaver::saveXML(), OutputConfig< T >::saveXML(), and Config::saveXML().
| 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] |
returns loadPolicy
Definition at line 134 of file plistCollections.h.
Referenced by plist::ArrayBase::ArrayBase(), and plist::DictionaryBase::DictionaryBase().
| 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] |
returns savePolicy
Definition at line 135 of file plistCollections.h.
Referenced by plist::ArrayBase::ArrayBase(), and plist::DictionaryBase::DictionaryBase().
| 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().
| virtual void plist::Collection::setLoadSavePolicy | ( | LoadSavePolicy | lp, | |
| LoadSavePolicy | sp | |||
| ) | [virtual] |
assigns loadPolicy and savePolicy respectively
Definition at line 138 of file plistCollections.h.
Referenced by plist::ArrayBase::ArrayBase(), plist::DictionaryBase::DictionaryBase(), DriverMessaging::FixedPoints::FixedPoints(), XWalkParameters::init(), OdometrySensor::init(), GPSSensor::init(), SensorFeedback::init(), SensorContact::init(), SensorRangeFinder::init(), SensorInfo::init(), plist::RGBColor< T >::init(), plist::Point::init(), PlannerObstacle< N >::init(), LinkComponent::init(), DynamicRobotState::init(), DriverMessaging::ContactPoint::init(), KinematicJoint::initEntries(), InstanceTypeLoader::InstanceTypeLoader(), XWalkParameters::LegParameters::LegParameters(), DriverMessaging::LoadPrediction::LoadPrediction(), PhysicsWorld::PhysicsWorld(), PIDMotorController::PIDMotorController(), DriverMessaging::SensorPriority::SensorPriority(), XWalkParameters::SinusoidalParameters::SinusoidalParameters(), and WheeledWalkMC::WheeledWalkMC().
| 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 | ) |
set warnUnused
Definition at line 131 of file plistCollections.h.
Referenced by Config::behaviors_config::behaviors_config(), InstanceTypeLoader::InstanceTypeLoader(), and plist::loadXML().
| 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
std::set<CollectionListener*>* plist::Collection::collectionListeners [mutable, protected] |
stores a list of the current listeners
Definition at line 171 of file plistCollections.h.
Referenced by addCollectionListener(), fireEntriesChanged(), fireEntryAdded(), fireEntryRemoved(), isCollectionListener(), removeCollectionListener(), and ~Collection().
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().
LoadSavePolicy plist::Collection::loadPolicy [protected] |
specifies how to handle "orphaned" entries while loading
Definition at line 199 of file plistCollections.h.
Referenced by getLoadPolicy(), plist::ArrayBase::loadXML(), plist::DictionaryBase::loadXML(), plist::ArrayOf< PO, Alloc >::loadXMLNode(), plist::DictionaryOf< PO, Alloc >::loadXMLNode(), plist::ArrayOf< PO, Alloc >::operator=(), plist::DictionaryOf< PO, Alloc >::operator=(), plist::ArrayOf< PO, Alloc >::set(), plist::DictionaryOf< PO, Alloc >::set(), and setLoadPolicy().
bool plist::Collection::saveCondensed [protected] |
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().
LoadSavePolicy plist::Collection::savePolicy [protected] |
specifies how to handle "orphaned" entries while saving
Definition at line 201 of file plistCollections.h.
Referenced by getSavePolicy(), plist::ArrayOf< PO, Alloc >::loadXMLNode(), plist::ArrayOf< PO, Alloc >::operator=(), plist::ArrayBase::saveXML(), plist::DictionaryBase::saveXML(), plist::ArrayOf< PO, Alloc >::set(), and setSavePolicy().
bool plist::Collection::warnUnused [protected] |
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:
