Refactor|libdeng2|libgui: Bank uses DotPath ('.' separators) for iden…

…tifiers

Due to the close relationship (Info)Bank has with scripting/Record,
it is better to default to dots ('.') as the separator for item
identifiers. The separator can still be explicitly set, though, to
any character.

doomsday/libdeng2/data.pri

@@ -15,6 +15,7 @@ HEADERS += \
     include/de/Counted \
     include/de/Date \
     include/de/DictionaryValue \
+    include/de/DotPath \
     include/de/FIFO \
     include/de/FixedByteArray \
     include/de/IBlock \

doomsday/libdeng2/include/de/DotPath

@@ -0,0 +1 @@
+#include "data/path.h"

doomsday/libdeng2/include/de/data/bank.h

@@ -23,7 +23,7 @@
 #include <set>
 
 #include "../libdeng2.h"
-#include "../Path"
+#include "../DotPath"
 #include "../PathTree"
 #include "../ISerializable"
 #include "../Observers"
@@ -45,7 +45,8 @@ namespace de {
  *
  * Data items are identified using Paths. Serializable data items can be stored
  * in a persistent cache ("hot storage"), from where they can be deserialized
- * quickly in the future.
+ * quickly in the future. @note Bank uses DotPath, so the path separator is
+ * assumed to be "." unless explicitly specified in the arguments.
  *
  * Data is kept cached on multiple levels: in memory, in hot storage
  * (serialized in a file), or in cold storage (unprocessed source data). When a
@@ -175,13 +176,13 @@ class DENG2_PUBLIC Bank
      * Notified when a data item has been loaded to memory (cache level
      * InMemory). May be called from the background thread, if one is running.
      */
-    DENG2_DEFINE_AUDIENCE(Load, void bankLoaded(Path const &path))
+    DENG2_DEFINE_AUDIENCE(Load, void bankLoaded(DotPath const &path))
 
     /**
      * Notified when a data item's cache level changes (in addition to the Load
      * notification).
      */
-    DENG2_DEFINE_AUDIENCE(CacheLevel, void bankCacheLevelChanged(Path const &path, CacheLevel level))
+    DENG2_DEFINE_AUDIENCE(CacheLevel, void bankCacheLevelChanged(DotPath const &path, CacheLevel level))
 
 public:
     /**
@@ -238,9 +239,9 @@ class DENG2_PUBLIC Bank
      * @param source  Source information that is required for loading the data to
      *                memory. Bank takes ownership.
      */
-    void add(Path const &path, ISource *source);
+    void add(DotPath const &path, ISource *source);
 
-    void remove(Path const &path);
+    void remove(DotPath const &path);
 
     /**
      * Determines whether the Bank contains an item (not a folder).
@@ -249,7 +250,7 @@ class DENG2_PUBLIC Bank
      *
      * @return  @c true or @c false.
      */
-    bool has(Path const &path) const;
+    bool has(DotPath const &path) const;
 
     /**
      * Collects a list of the paths of all items in the bank.
@@ -271,7 +272,7 @@ class DENG2_PUBLIC Bank
      * @param path        Identifier of the data.
      * @param importance  When/how to carry out the load request (with BackgroundThread).
      */
-    void load(Path const &path, Importance importance = Immediately);
+    void load(DotPath const &path, Importance importance = Immediately);
 
     void loadAll();
 
@@ -291,7 +292,7 @@ class DENG2_PUBLIC Bank
      *
      * @return IData instance. Ownership kept by the Bank.
      */
-    IData &data(Path const &path) const;
+    IData &data(DotPath const &path) const;
 
     /**
      * Moves a data item to a lower cache level. When using BackgroundThread,
@@ -301,7 +302,7 @@ class DENG2_PUBLIC Bank
      * @param path     Identifier of the data.
      * @param toLevel  Destination level for the data.
      */
-    void unload(Path const &path, CacheLevel toLevel = InHotStorage);
+    void unload(DotPath const &path, CacheLevel toLevel = InHotStorage);
 
     /**
      * Moves all data items to a lower cache level.
@@ -315,7 +316,7 @@ class DENG2_PUBLIC Bank
      *
      * @param path  Identifier of the data.
      */
-    void clearFromCache(Path const &path);
+    void clearFromCache(DotPath const &path);
 
     /**
      * Moves excess items on each cache level to lower level(s).

doomsday/libdeng2/include/de/data/path.h

@@ -419,6 +419,27 @@ class DENG2_PUBLIC Path : public ISerializable, public LogEntry::Arg::Base
     Instance *d;
 };
 
+/**
+ * Utility class for specifying paths that use a dot (.) as the path separator.
+ */
+class DotPath : public Path
+{
+public:
+    DotPath(String const &path = "")        : Path(path, '.') {}
+    DotPath(QString const &str)             : Path(str, '.') {}
+    DotPath(char const *nullTerminatedCStr) : Path(nullTerminatedCStr, '.') {}
+    DotPath(Path const &other)              : Path(other) {}
+    DotPath(DotPath const &other)           : Path(other.toStringRef(), other.separator()) {}
+
+    bool operator == (DotPath const &other) const {
+        return Path::operator == (other);
+    }
+
+    bool operator != (DotPath const &other) const {
+        return Path::operator != (other);
+    }
+};
+
 } // namespace de
 
 namespace std {

doomsday/libdeng2/include/de/widgets/rulebank.h

@@ -50,7 +50,7 @@ class DENG2_PUBLIC RuleBank : public InfoBank
      *
      * @return  Rule instance.
      */
-    Rule const &rule(Path const &path) const;
+    Rule const &rule(DotPath const &path) const;
 
 protected:
     virtual ISource *newSourceFromInfo(String const &id);

doomsday/libdeng2/src/data/bank.cpp

@@ -145,7 +145,7 @@ DENG2_OBSERVES(Loop, Iteration)
             if(data.get())
             {
                 LOG_DEBUG("Item \"%s\" data cleared from memory (%i bytes)")
-                        << path() << data->sizeInMemory();
+                        << path('.') << data->sizeInMemory();
                 data->aboutToUnload();
                 data.reset();
             }
@@ -158,7 +158,7 @@ DENG2_OBSERVES(Loop, Iteration)
 
             data.reset(newData);
             accessedAt = Time();
-            bank->d->notify(Notification(Notification::Loaded, path()));
+            bank->d->notify(Notification(Notification::Loaded, path('.')));
         }
 
         /// Load the item into memory from its current cache.
@@ -193,7 +193,7 @@ DENG2_OBSERVES(Loop, Iteration)
             // us. This may take an unspecified amount of time.
             QScopedPointer<IData> loaded(bank->loadFromSource(*source));
 
-            LOG_DEBUG("Loaded \"%s\" from source in %.2f seconds") << path() << startedAt.since();
+            LOG_DEBUG("Loaded \"%s\" from source in %.2f seconds") << path('.') << startedAt.since();
 
             if(loaded.data())
             {
@@ -225,14 +225,14 @@ DENG2_OBSERVES(Loop, Iteration)
                     QScopedPointer<IData> blank(bank->newData());
                     reader >> *blank->asSerializable();
                     setData(blank.take());
-                    LOG_DEBUG("Deserialized \"%s\" in %.2f seconds") << path() << startedAt.since();
+                    LOG_DEBUG("Deserialized \"%s\" in %.2f seconds") << path('.') << startedAt.since();
                     return; // Done!
                 }
                 // We cannot use this.
             }
             catch(Error const &er)
             {
-                LOG_WARNING("Failed to deserialize \"%s\":\n") << path() << er.asText();
+                LOG_WARNING("Failed to deserialize \"%s\":\n") << path('.') << er.asText();
             }
 
             // Fallback option.
@@ -301,10 +301,13 @@ DENG2_OBSERVES(Loop, Iteration)
                 fromCache.remove(*this);
                 cache = &toCache;
 
+                // Externally we use dotted paths.
+                Path const itemPath = path('.');
+
                 LOG_DEBUG("Item \"%s\" moved to %s cache")
-                        << path() << Cache::formatAsText(toCache.format());
+                        << itemPath << Cache::formatAsText(toCache.format());
 
-                bank->d->notify(Notification(path(), toCache));
+                bank->d->notify(Notification(itemPath, toCache));
             }
         }
     };
@@ -422,7 +425,7 @@ DENG2_OBSERVES(Loop, Iteration)
         };
 
     public:
-        Job(Bank &bk, Task t, Path p = "")
+        Job(Bank &bk, Task t, Path const &p = Path())
             : _bank(bk), _task(t), _path(p)
         {}
 
@@ -635,7 +638,7 @@ DENG2_OBSERVES(Loop, Iteration)
 
                 if(item.isValidSerialTime(hotTime))
                 {
-                    LOG_DEBUG("Found valid serialized copy of \"%s\"") << item.path();
+                    LOG_DEBUG("Found valid serialized copy of \"%s\"") << item.path('.');
 
                     item.serial = array;
                     best = serialCache;
@@ -774,7 +777,7 @@ void Bank::clear()
     d->clear();
 }
 
-void Bank::add(Path const &path, ISource *source)
+void Bank::add(DotPath const &path, ISource *source)
 {
     LOG_AS("Bank");
 
@@ -789,12 +792,12 @@ void Bank::add(Path const &path, ISource *source)
     d->putInBestCache(item);
 }
 
-void Bank::remove(Path const &path)
+void Bank::remove(DotPath const &path)
 {
     d->items.remove(path, PathTree::NoBranch);
 }
 
-bool Bank::has(Path const &path) const
+bool Bank::has(DotPath const &path) const
 {
     return d->items.has(path);
 }
@@ -816,7 +819,7 @@ PathTree const &Bank::index() const
     return d->items;
 }
 
-void Bank::load(Path const &path, Importance importance)
+void Bank::load(DotPath const &path, Importance importance)
 {
     d->load(path, importance);
 }
@@ -831,7 +834,7 @@ void Bank::loadAll()
     }
 }
 
-Bank::IData &Bank::data(Path const &path) const
+Bank::IData &Bank::data(DotPath const &path) const
 {
     LOG_AS("Bank");
 
@@ -867,7 +870,7 @@ Bank::IData &Bank::data(Path const &path) const
     return *item.data;
 }
 
-void Bank::unload(Path const &path, CacheLevel toLevel)
+void Bank::unload(DotPath const &path, CacheLevel toLevel)
 {
     d->unload(path, toLevel);
 }
@@ -884,7 +887,7 @@ void Bank::unloadAll(CacheLevel maxLevel)
     }
 }
 
-void Bank::clearFromCache(Path const &path)
+void Bank::clearFromCache(DotPath const &path)
 {
     d->unload(path, InColdStorage);
 }

doomsday/libdeng2/src/widgets/rulebank.cpp

@@ -60,7 +60,7 @@ void RuleBank::addFromInfo(File const &file)
     addFromInfoBlocks("rule");
 }
 
-Rule const &RuleBank::rule(Path const &path) const
+Rule const &RuleBank::rule(DotPath const &path) const
 {
     return *static_cast<Instance::RuleData &>(data(path)).rule;
 }

doomsday/libgui/include/de/gui/colorbank.h

@@ -53,7 +53,7 @@ class LIBGUI_PUBLIC ColorBank : public InfoBank
      *
      * @return  Vector with the color values (0...255).
      */
-    Color color(Path const &path) const;
+    Color color(DotPath const &path) const;
 
     /**
      * Finds a specific color.
@@ -62,7 +62,7 @@ class LIBGUI_PUBLIC ColorBank : public InfoBank
      *
      * @return  Vector with the floating-point color values (0...1).
      */
-    Colorf colorf(Path const &path) const;
+    Colorf colorf(DotPath const &path) const;
 
 protected:
     virtual ISource *newSourceFromInfo(String const &id);

doomsday/libgui/include/de/gui/fontbank.h

@@ -49,7 +49,7 @@ class LIBGUI_PUBLIC FontBank : public InfoBank
      *
      * @return  Font instance.
      */
-    Font const &font(Path const &path) const;
+    Font const &font(DotPath const &path) const;
 
 protected:
     virtual ISource *newSourceFromInfo(String const &id);

doomsday/libgui/include/de/gui/glshaderbank.h

@@ -41,7 +41,7 @@ class GLShaderBank : public InfoBank
 
     void addFromInfo(File const &file);
 
-    GLShader &shader(Path const &path, GLShader::Type type) const;
+    GLShader &shader(DotPath const &path, GLShader::Type type) const;
 
     /**
      * Builds a GL program using the defined shaders.
@@ -51,7 +51,7 @@ class GLShaderBank : public InfoBank
      *
      * @return Reference to @a program.
      */
-    GLProgram &build(GLProgram &program, Path const &path) const;
+    GLProgram &build(GLProgram &program, DotPath const &path) const;
 
 protected:
     ISource *newSourceFromInfo(String const &id);

doomsday/libgui/include/de/gui/imagebank.h

@@ -47,10 +47,10 @@ class LIBGUI_PUBLIC ImageBank : public InfoBank
      */
     ImageBank(Flags const &flags = BackgroundThread | DisableHotStorage);
 
-    void add(Path const &path, String const &imageFilePath);
+    void add(DotPath const &path, String const &imageFilePath);
     void addFromInfo(File const &file);
 
-    Image &image(Path const &path) const;
+    Image &image(DotPath const &path) const;
 
 protected:
     ISource *newSourceFromInfo(String const &id);

doomsday/libgui/src/colorbank.cpp

@@ -79,7 +79,7 @@ void ColorBank::addFromInfo(File const &file)
     addFromInfoBlocks("color");
 }
 
-ColorBank::Color ColorBank::color(Path const &path) const
+ColorBank::Color ColorBank::color(DotPath const &path) const
 {
     Colorf col = colorf(path);
     return Color(round<dbyte>(col.x * 255),
@@ -88,7 +88,7 @@ ColorBank::Color ColorBank::color(Path const &path) const
                  round<dbyte>(col.w * 255));
 }
 
-ColorBank::Colorf ColorBank::colorf(Path const &path) const
+ColorBank::Colorf ColorBank::colorf(DotPath const &path) const
 {
     Vector4d clamped = static_cast<Instance::ColorData &>(data(path)).color;
     clamped = clamped.max(Vector4d(0, 0, 0, 0)).min(Vector4d(1, 1, 1, 1));

doomsday/libgui/src/fontbank.cpp

@@ -88,7 +88,7 @@ void FontBank::addFromInfo(File const &file)
     addFromInfoBlocks("font");
 }
 
-Font const &FontBank::font(Path const &path) const
+Font const &FontBank::font(DotPath const &path) const
 {
     return *static_cast<Instance::FontData &>(data(path)).font;
 }

doomsday/libgui/src/glshaderbank.cpp

@@ -147,7 +147,7 @@ void GLShaderBank::addFromInfo(File const &file)
     addFromInfoBlocks("shader");
 }
 
-GLShader &GLShaderBank::shader(Path const &path, GLShader::Type type) const
+GLShader &GLShaderBank::shader(DotPath const &path, GLShader::Type type) const
 {
     Instance::Data &i = static_cast<Instance::Data &>(data(path));
 
@@ -161,7 +161,7 @@ GLShader &GLShaderBank::shader(Path const &path, GLShader::Type type) const
     }
 }
 
-GLProgram &GLShaderBank::build(GLProgram &program, Path const &path) const
+GLProgram &GLShaderBank::build(GLProgram &program, DotPath const &path) const
 {
     Instance::Data &i = static_cast<Instance::Data &>(data(path));
     program.build(i.vertex, i.fragment);