Tekkotsu Homepage

Demos

Overview

Downloads

Dev. Resources

Reference

Credits

plistCollections.h Go to the documentation of this file. //-*-c++-*- #ifndef INCLUDED_plistCollections_h_ #define INCLUDED_plistCollections_h_ #include "plistPrimitives.h" #include <map> #include <vector> #include <set> #include <regex.h> namespace plist { ObjectBase* loadXML(xmlNode* node); // defined in plist.h, we need the prototype } namespace plist { //! 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. */ class Collection : public ObjectBase { public: //! Specifies that a collection of collections cannot contain any primitive values template<typename U, typename V> struct conversion_policy { typedef typename U::DeniedValueConversions value_conversion; }; //! used to define values for LoadSavePolicy values so we can test a bit out of the policy value enum LoadSaveActionBitMask { ADDITIONS=1, //!< 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=2 //!< 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 }; //! 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): * <table> * <tr><td>@b Loading</td><td>SYNC</td><td>INTERSECT</td><td>UNION</td><td>FIXED</td></tr> * <tr><td>not in file, in collection</td><td>remove</td><td>remove</td><td>ignore</td><td>ignore</td></tr> * <tr><td>in file, not in collection</td><td>add</td><td>ignore</td><td>add</td><td>ignore</td></tr> * <tr><td>@b Saving</td><td>SYNC</td><td>INTERSECT</td><td>UNION</td><td>FIXED</td></tr> * <tr><td>not in file, in collection</td><td>add</td><td>ignore</td><td>add</td><td>ignore</td></tr> * <tr><td>in file, not in collection</td><td>remove</td><td>remove</td><td>ignore</td><td>ignore</td></tr> * </table> * * 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...)*/ enum LoadSavePolicy { FIXED = 0, //!< destination will have the same entries as before, ignores orphans and only updates entries with matching keys UNION = ADDITIONS, //!< destination will have its current entries, as well as new ones from the source INTERSECT = REMOVALS, //!< destination will only hold entries which are in both locations, removes entries not found in source, ignores new entries SYNC = ADDITIONS|REMOVALS //!< destination will mirror source, new entries are added, missing entries are removed }; //! assignment (don't assign listeners); subclass should call fireEntriesChanged after calling this (and updating its own storage) Collection& operator=(const Collection& d) { if(&d==this) return *this; ObjectBase::operator=(d); return *this; } //! destructor ~Collection(); //! recursively resolves @a path interpreted as a series of collection entry names separated by '.', returns NULL if it doesn't exist virtual ObjectBase* resolveEntry(const std::string& path) const=0; //! remove all entries in one fell swoop virtual void clear()=0; //! return the size of the collection virtual size_t size() const=0; //! get notified of changes; be sure to call removeCollectionListener() before destructing @a l! virtual void addCollectionListener(CollectionListener* l) const; //! no longer take notification of changes to this object's value virtual void removeCollectionListener(CollectionListener* l) const; //! test if @a l is currently registered as a listener virtual bool isCollectionListener(CollectionListener* l) const; void setUnusedWarning(bool b) { warnUnused=b; } //!< set #warnUnused bool getUnusedWarning() const { return warnUnused; } //!< returns #warnUnused virtual LoadSavePolicy getLoadPolicy() const { return loadPolicy; } //!< returns #loadPolicy virtual LoadSavePolicy getSavePolicy() const { return savePolicy; } //!< returns #savePolicy virtual void setLoadPolicy(LoadSavePolicy lp) { loadPolicy=lp; } //!< assigns #loadPolicy virtual void setSavePolicy(LoadSavePolicy sp) { savePolicy=sp; } //!< assigns #savePolicy virtual void setLoadSavePolicy(LoadSavePolicy lp, LoadSavePolicy sp) { setLoadPolicy(lp); setSavePolicy(sp); } //!< assigns #loadPolicy and #savePolicy respectively //! defines separator between sub-collections /*! (defined as a function instead of just a constant member so there's no issues with initialization order) */ static const std::string& subCollectionSep() { static std::string sep(1,'.'); return sep; } //! returns longest key length which matches the regular expression virtual unsigned int getLongestKeyLen(const regex_t* reg=NULL, unsigned int depth=-1) const=0; //! returns true if the Collection subclass allows storage of the argument virtual bool canContain(const ObjectBase& obj)=0; virtual long toLong() const; virtual double toDouble() const; protected: //! constructor Collection() : ObjectBase(), collectionListeners(), warnUnused(true), loadPolicy(SYNC), savePolicy(SYNC) {autoFormat=false;} //! constructor Collection(LoadSavePolicy lp, LoadSavePolicy sp) : ObjectBase(), collectionListeners(), warnUnused(true), loadPolicy(lp), savePolicy(sp) {autoFormat=false;} //! copy constructor (don't assign listeners) Collection(const Collection& d) : ObjectBase(d), collectionListeners(), warnUnused(d.warnUnused), loadPolicy(d.loadPolicy), savePolicy(d.savePolicy) {autoFormat=false;} //! run through #collectionListeners, calling CollectionListener::plistCollectionEntryAdded(*this,val) virtual void fireEntryAdded(ObjectBase& val); //! run through #collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val) virtual void fireEntryRemoved(ObjectBase& val); //! run through #collectionListeners, calling CollectionListener::plistCollectionEntriesChanged(*this) virtual void fireEntriesChanged(); //! stores a list of the current listeners mutable std::set<CollectionListener*>* collectionListeners; //! returns index corresponding to @a name, which should encode an integer value less than or equal to the current size static size_t getIndex(const std::string& name); //! returns a prefix for items within the collection static std::string getIndentationPrefix(xmlNode* node); //! 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) */ static const std::string& emptyStr() { static std::string mt; return mt; } //! 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) */ static const std::string& perIndent() { static std::string pi(1,'\t'); return pi; } //! 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 static const unsigned int KEY_IN_COMMENT_MAX_POS=10; //! 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 bool warnUnused; //! specifies how to handle "orphaned" entries while loading LoadSavePolicy loadPolicy; //! specifies how to handle "orphaned" entries while saving LoadSavePolicy savePolicy; }; //! Maintains a set of (key,value) pairs, see DictionaryOf, and the Dictionary typedef /*! You can add or set entries by a quite a few variations on addEntry(), setEntry(), or addValue(). * Basically these boil down to either: * - pass a pointer to an ObjectBase or directly pass a primitive value (int, float, char, etc.), * in which case the dictionary 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 */ class DictionaryBase : virtual public Collection { friend std::ostream& operator<<(std::ostream& os, const DictionaryBase& d); public: //! shorthand for the type of the storage typedef std::map<std::string,ObjectBase*> storage_t; //! shorthand for iterators to be returned typedef storage_t::iterator iterator; //! shorthand for iterators to be returned typedef storage_t::const_iterator const_iterator; //! Indicates that no value conversions are allowed /*! The actual storage type is still allowed, so technically we could use EntryConstraint<PO> * instead as the conversion policy, but that doesn't gain anything because you would need * to know the PO to test for it. At least with this you can test for DeniedValueConversions as a base * class and then fall back to testing individual PO's if you want. */ struct DeniedValueConversions { virtual ~DeniedValueConversions() {} //!< no-op destructor }; //! This base conversion policy doesn't actually specify any conversions at all -- this serves as a base class to provide the ability to directly add entries of the specified type; the subclasses will add value conversions /*! This class is useless to end users: to use it they would have to know the template type being used, * which if they knew, they could just dynamic_cast to the DictionaryOf type directly. The point of this * class is to provide the abstract functions to the its subclasses, which use them to implement their * various conversions. */ template<typename PO> struct EntryConstraint { virtual ~EntryConstraint() {} //!< no-op destructor //! insert a new entry to the dictionary, with key @a name and value @a val (replaces any previous entry by same name, but can give a warning) virtual void setEntry(const std::string& name, PO& val, bool warnExists=false)=0; //! insert a new entry to the dictionary, with key @a name and value @a val (replaces any previous entry by same name with a warning) virtual void addEntry(const std::string& name, PO& val, const std::string& comment="", bool warnExists=true)=0; //! insert a new entry to the dictionary, with key @a name and value @a val (replaces any previous entry by same name, but can give a warning); control of (de)allocation will be assumed by the dictionary virtual void setEntry(const std::string& name, PO* val, bool warnExists=false)=0; //! insert a new entry to the dictionary, with key @a name and value @a val (replaces any previous entry by same name with a warning); control of (de)allocation will be assumed by the dictionary virtual void addEntry(const std::string& name, PO* val, const std::string& comment="", bool warnExists=true)=0; }; //! Abstract base class to test whether the collection will accept strings (possibly converting to a value type, or storing directly as string depending on concrete type) /*! The point of this class is to handle the situation where you have a DictionaryBase and user input to append, and * you don't want to have to test every combination of template parameters to DictionaryOf to find out if you can * add the data. Instead, test dynamic_cast<plist::DictionaryBase::StringConversion>, and if it is successful, you * can pass the string without having to know the actual value type of the dictionary. */ struct StringConversion { virtual ~StringConversion() {} //!< no-op destructor //! generic addition of value, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, const std::string& val, const std::string& comment="", bool warnExists=true)=0; }; //! Abstract base class to test whether the collection will accept integers (possibly converting to another value type, or storing directly as a [unsigned] long depending on concrete type) /*! The point of this class is to handle the situation where you have a DictionaryBase and user input to append, and * you don't want to have to test every combination of template parameters to DictionaryOf to find out if you can * add the data. Instead, test dynamic_cast<plist::DictionaryBase::IntegerConversion>, and if it is successful, you * can pass the data without having to know the actual value type of the dictionary. */ struct IntegerConversion { virtual ~IntegerConversion() {} //!< no-op destructor //! generic addition of value, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, long val, const std::string& comment="", bool warnExists=true)=0; //! generic addition of value, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, unsigned long val, const std::string& comment="", bool warnExists=true)=0; }; //! Abstract base class to test whether the collection will accept floating point numbers (possibly converting to another value type, or storing directly as a double depending on concrete type) /*! The point of this class is to handle the situation where you have a DictionaryBase and user input to append, and * you don't want to have to test every combination of template parameters to DictionaryOf to find out if you can * add the data. Instead, test dynamic_cast<plist::DictionaryBase::RealConversion>, and if it is successful, you * can pass the data without having to know the actual value type of the dictionary. */ struct RealConversion { virtual ~RealConversion() {} //!< no-op destructor //! generic addition of value, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, double val, const std::string& comment="", bool warnExists=true)=0; }; //! This conversion policy accepts entries of the specified template type, and will try to create new instances of that type constructed from any values which are passed. /*! Use of this conversion policy requires that the template parameter is not abstract, * as the policy will be trying to create new instances directly from the specified type. */ template<typename PO> struct ConversionTo : public StringConversion, public IntegerConversion, public RealConversion, public EntryConstraint<PO> { //! insert a new entry to the map, and corresponding comment; expects @a val to be either a primitive type, like int, float, etc., or one of the variable-sized Collection's, like Array, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary template<typename T> void addValue(const std::string& name, const T& val, const std::string& comment="", bool warnExists=true) { addEntry(name,new PO(val),comment,warnExists); } virtual void addValue(const std::string& name, const std::string& val, const std::string& comment="", bool warnExists=true) { PO * po=new PO; try { po->set(val); } catch(...) { delete po; throw; } addEntry(name,po,comment,warnExists); } //! "specialization" (actually just another override) for handling character arrays as strings, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, char val[], const std::string& comment="", bool warnExists=true) { PO * po=new PO; try { po->set(val); } catch(...) { delete po; throw; } addEntry(name,po,comment,warnExists); } //! "specialization" (actually just another override) for handling character arrays as strings, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, const char val[], const std::string& comment="", bool warnExists=true) { PO * po=new PO; try { po->set(val); } catch(...) { delete po; throw; } addEntry(name,po,comment,warnExists); } virtual void addValue(const std::string& name, long val, const std::string& comment="", bool warnExists=true) { addEntry(name,new PO(val),comment,warnExists); } virtual void addValue(const std::string& name, unsigned long val, const std::string& comment="", bool warnExists=true) { addEntry(name,new PO(val),comment,warnExists); } virtual void addValue(const std::string& name, double val, const std::string& comment="", bool warnExists=true) { addEntry(name,new PO(val),comment,warnExists); } }; //! This conversion policy accepts any entries of the specified template type, values will be directly wrapped as Primitives so no conversion at all is actually performed /*! Use addEntry() to add ObjectBase subclasses -- addValue is for POD types */ template<typename PO> struct WrapValueConversion : public StringConversion, public IntegerConversion, public RealConversion, public EntryConstraint<PO> { //! insert a new entry to the map, and corresponding comment; expects @a val to be either a primitive type, like int, float, etc., control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary template<typename T> void addValue(const std::string& name, const T& val, const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<T>(val),comment,warnExists); } virtual void addValue(const std::string& name, const std::string& val, const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<std::string>(val),comment,warnExists); } //! "specialization" (actually just another override) for handling character arrays as strings, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, char val[], const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<std::string>(val),comment,warnExists); } //! "specialization" (actually just another override) for handling character arrays as strings, control of (de)allocation of corresponding Primitive instance will be assumed by the dictionary virtual void addValue(const std::string& name, const char val[], const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<std::string>(val),comment,warnExists); } virtual void addValue(const std::string& name, long val, const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<long>(val),comment,warnExists); } virtual void addValue(const std::string& name, unsigned long val, const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<unsigned long>(val),comment,warnExists); } virtual void addValue(const std::string& name, double val, const std::string& comment="", bool warnExists=true) { this->addEntry(name,new Primitive<double>(val),comment,warnExists); } }; //! remove the entry with key @a name, returns true if something was actually removed (if false, wasn't there to begin with) virtual bool removeEntry(const std::string& name); //! change the key for an entry from @a oldname to @a newname, returns false if @a oldname didn't exist (thus no change was made) /*! If the collection owns the reference to the object, you have to use this function instead * of a pair of calls to removeEntry/addEntry, otherwise you will wind up with an invalid pointer! */ virtual bool renameEntry(const std::string& oldname, const std::string& newname); //! exchange the values for a pair of keys -- if either key doesn't exist, forwards call to renameEntry() /*! returns true if the swap was successful, only returns false if both keys are invalid */ virtual bool swapEntry(const std::string& a, const std::string& b); //! returns a reference to the entry with the specified name, creating it if it doesn't exist virtual ObjectBase& getEntry(const std::string& name)=0; //! returns a reference to the entry with the specified name, creating it if it doesn't exist virtual ObjectBase& operator[](const std::string& name)=0; //! returns a pointer to entry with the specified 'path', which may recurse through sub-collections virtual ObjectBase* resolveEntry(const std::string& path) const; //! returns an iterator to an entry in the current dictionary const_iterator findEntry(const std::string& name) const { return dict.find(name); } virtual void clear(); //! return an STL const_iterator to the first entry const_iterator begin() const { return dict.begin(); } //! return the one-past-end const_iterator const_iterator end() const { return dict.end(); } //! return the size of the dictionary virtual size_t size() const { return dict.size(); } //! replaces previous comment for @a name, or adds it if it doesn't already exist (can preceed actual entry!) void setComment(const std::string& name, const std::string& comment); //! returns comment retrieved from loaded file, or any subsequent call to setComment const std::string& getComment(const std::string& name) const; virtual void loadXML(xmlNode* node); virtual void saveXML(xmlNode* node) const { std::set<std::string> seen; saveXML(node,!(savePolicy&ADDITIONS),seen); } //! saves the dictionary into the specified node /*! @param[in] node the xml node which should be saved into * @param[in] onlyOverwrite if is true, only saves entries for keys already found in the node (this overrides the current savePolicy value) * @param[in] seen used to keep track of which nodes have been seen in @a node -- may be of particular interest with @a onlyOverride set * * @a seen is not cleared before being used.*/ virtual void saveXML(xmlNode* node, bool onlyOverwrite, std::set<std::string>& seen) const; virtual std::string toString() const; //! returns the length of the longest key, subject to an optional regular expression and max depth virtual unsigned int getLongestKeyLen(const regex_t* reg=NULL, unsigned int depth=-1) const; //! returns true if the specified object will be deallocated when removed from the dictionary bool ownsReference(ObjectBase * val) const { return myRef.find(val)==myRef.end(); } protected: //! constructor explicit DictionaryBase(bool growable) : Collection(growable?UNION:FIXED,SYNC), dict(), myRef(), comments() { setLoadSavePolicy(growable?UNION:FIXED,SYNC); } //! copy constructor (don't assign listeners) DictionaryBase(const DictionaryBase& d) : Collection(d), dict(d.dict), myRef(d.myRef), comments(d.comments) { cloneMyRef(); setLoadSavePolicy(d.getLoadPolicy(),d.getSavePolicy()); } //! assignment (don't assign listeners) DictionaryBase& operator=(const DictionaryBase& d) { Collection::operator=(d); return *this; } //! destructor ~DictionaryBase() { clear(); } //! indicates that the storage implementation should mark this as an externally supplied heap reference, which needs to be deleted on removal/destruction virtual void takeObject(const std::string& name, ObjectBase* obj); virtual void fireEntryRemoved(ObjectBase& val); //! returns an entry matching just the prefix /*! @param[in] name the name being looked up * @param[out] seppos the position of the separator (sub-collections are separated by '.') * @return iterator of the sub entry*/ iterator getSubEntry(const std::string& name, std::string::size_type& seppos); //! returns an entry matching just the prefix /*! @param[in] name the name being looked up * @param[out] seppos the position of the separator (sub-collections are separated by '.') * @return iterator of the sub entry*/ const_iterator getSubEntry(const std::string& name, std::string::size_type& seppos) const; //! called after an assignment or copy to clone the objects in #myRef to perform a deep copy virtual void cloneMyRef(); //! called with each node being loaded so subclass can handle appropriately virtual bool loadXMLNode(const std::string& key, xmlNode* val, const std::string& comment)=0; //! called with each node being saved so subclass can handle appropriately, return true if successful and reset key if changed virtual bool saveOverXMLNode(xmlNode* k, xmlNode* val, const std::string& key, std::string comment, const std::string& indentStr, std::set<std::string>& seen) const; //! called with each node being saved so subclass can handle appropriately, return true if successful and set key virtual void saveXMLNode(xmlNode* node, const std::string& key, const ObjectBase* val, const std::string& indentStr) const; //! storage of entries -- mapping from keys to value pointers storage_t dict; //! objects which have been handed over to the collection for eventual de-allocation std::set<ObjectBase*> myRef; //! shorthand for the type of #comments typedef std::map<std::string,std::string> comments_t; //! storage of entry comments -- mapping from keys to help text comments for manual editing or user feedback /*! not every key necessarily has a comment! */ comments_t comments; }; //! A dictionary which requires all elements to be subtypes of the PO template argument /*! You can add or set entries by a quite a few variations on addEntry(), setEntry(), and addValue (via the Alloc conversion policy) * Basically these boil down to either: * - pass a pointer to an ObjectBase or directly pass a primitive value (int, float, char, etc.), * in which case the dictionary 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 * * You have probably noticed this is a templated class -- you can provide any of the ObjectBase * subclasses to restrict the storage to that particular type, which will make life easier when * retrieving objects since their type will be known. * * However, if you @e want an dictionary of mixed types, you can pass ObjectBase itself for the * template parameter, and you can then insert any combination of the plist types into the * same dictionary. For convenience, a plist::Dictionary typedef is provided which does exactly this. * * So plist::Dictionary can handle any mixture of types, whereas plist::DictionaryOf<PO> will @e only * accept the plist objects of type PO (or their subclasses). The Alloc template argument * allows you to define how new string values will be handled from DictionaryBase. * * The optional conversion policy template specifies a base class for the dictionary which * can control how the dictionary will handle conversions from non-PO-based types. */ template<typename PO, typename Alloc=typename PO::template conversion_policy<DictionaryBase,PO>::value_conversion > class DictionaryOf : public DictionaryBase, public Alloc { /// @cond INTERNAL typedef typename storage_t::const_iterator::iterator_category const_iterator_category; typedef typename std::pair<storage_t::key_type,PO*> const_iterator_value; typedef typename storage_t::const_iterator::difference_type const_iterator_difference; /// @endcond public: //! shorthand for the type of the storage typedef typename DictionaryBase::storage_t storage_t; /// @cond INTERNAL //! iterator implementation which wraps storage_t::const_iterator to transparently dynamic_cast to the PO for client class const_iterator : std::iterator<const_iterator_category, const_iterator_value, const_iterator_difference> { public: const_iterator(const storage_t::const_iterator& sit) : it(sit), tmp() {} const const_iterator_value& operator*() const { return std::make_pair(it->first,dynamic_cast<PO*>(it->second)); } const const_iterator_value* operator->() const { tmp=std::make_pair(it->first,dynamic_cast<PO*>(it->second)); return &tmp; } const_iterator& operator++() { ++it; return *this; } const_iterator operator++(int) { return const_iterator(it++); }