Refactor: Renamed ResourceRecord to ResourceManifest, cleaned up the …

…interface

Improved the API usability and made it more consistent with libdeng2
practices.

doomsday/engine/include/game.h

@@ -57,7 +57,7 @@ struct gamedef_s;
 
 namespace de {
 
-class ResourceRecord;
+class ResourceManifest;
 class File1;
 class GameCollection;
 
@@ -70,7 +70,7 @@ class GameCollection;
 class Game
 {
 public:
-    typedef QMultiMap<resourceclassid_t, ResourceRecord*> Resources;
+    typedef QMultiMap<resourceclassid_t, ResourceManifest*> Resources;
 
 public:
     /**
@@ -118,7 +118,7 @@ class Game
      *
      * @param record  ResourceRecord to add.
      */
-    Game& addResource(ResourceRecord& record);
+    Game& addResource(ResourceManifest& record);
 
     bool allStartupResourcesFound() const;
 

doomsday/engine/include/resource/resourcerecord.h

@@ -1,9 +1,6 @@
 /**
- * @file resourcerecord.h
- *
- * Resource Record.
- *
- * @ingroup resource
+ * @file resourcemanifest.h
+ * Manifest of a resource. @ingroup resource
  *
  * @author Copyright &copy; 2010-2012 Daniel Swanson <danij@dengine.net>
  *
@@ -17,9 +14,8 @@
  * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
  * Public License for more details. You should have received a copy of the GNU
- * General Public License along with this program; if not, write to the Free
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA</small>
+ * General Public License along with this program; if not, see:
+ * http://www.gnu.org/licenses</small>
  */
 
 #ifndef LIBDENG_RESOURCERECORD_H
@@ -35,79 +31,102 @@
 namespace de
 {
     /**
-     * Stores high-level metadata for and manages a logical resource.
+     * Stores metadata about a resource and provides a way to locate the actual
+     * file(s) containing the resource. @ingroup resource
+     *
+     * Resources are identified both by identity keys and names:
+     * - identity key might be <tt>PLAYPAL>=2048</tt>, or <tt>E1M1</tt>
+     * - name might be <tt>doom.wad</tt> (the containing file)
+     *
+     * @todo The definition and usage of identity key and name are too
+     * WAD container centric. Some more generic should be used instead,
+     * perhaps URI-related/based?
      *
-     * @ingroup core
+     * @see The term @em manifest is used with this meaning:
+     * http://en.wikipedia.org/wiki/Manifest_file
      */
-    class ResourceRecord
+    class ResourceManifest
     {
     public:
         /**
+         * Construct a new resource manifest.
+         *
          * @param rClass    Class of resource.
          * @param rFlags    @ref resourceFlags
          * @param name      An expected name for the associated resource.
+         *                  The manifest must define at least one name because
+         *                  the resource can be located. Use addName() to
+         *                  define more names.
          */
-        ResourceRecord(resourceclassid_t rClass, int rFlags, String* name = 0);
-        ~ResourceRecord();
+        ResourceManifest(resourceclassid_t rClass, int rFlags, const String& name = String());
+
+        ~ResourceManifest();
 
         /// @return Class of resource.
         resourceclassid_t resourceClass() const;
 
-        /// @return Flags for this resource.
+        /// @return Flags for this resource (see @ref resourceFlags).
         int resourceFlags() const;
 
         /// @return List of "identity keys" used to identify the resource.
-        QStringList const& identityKeys() const;
+        QStringList identityKeys() const;
 
         /// @return List of names for the associated resource.
-        QStringList const& names() const;
+        QStringList names() const;
 
         /**
          * Attempt to locate this resource by systematically resolving and then
          * checking each search path.
          */
-        ResourceRecord& locateResource();
+        void locate();
 
         /**
          * "Forget" the currently located resource if one has been found.
          */
-        ResourceRecord& forgetResource();
+        void forgetLocation();
 
         /**
          * Attempt to resolve a path to (and maybe locate) this resource.
          *
-         * @param tryLocate  Attempt to locate the resource now.
+         * @param tryLocate  @c true, to attempt locating the resource now
+         *                   (by calling locate()).
          *
          * @return Path to the found resource or an empty string.
          *
-         * @see locateResource()
+         * @see locate()
          */
-        String const& resolvedPath(bool tryLocate = true);
+        String resolvedPath(bool tryLocate = true);
 
         /**
-         * Add a new sub-resource identity key to the list for this record.
+         * Add a new resource identity key to the list for this record.
+         * The key is only added if a matching one hasn't been added yet
+         * (duplicates not allowed).
          *
-         * @param newIdentityKey    New identity key (e.g., a lump/file name).
-         * @param didAdd            If not @c =0, the outcome will be written here.
+         * @param newIdentityKey  New identity key (e.g., a lump/file name).
+         *
+         * @return @c true, if the key was added. @c false, if it was invalid
+         * or already present.
          */
-        ResourceRecord& addIdentityKey(String newIdentityKey, bool* didAdd = 0);
+        bool addIdentityKey(String newIdentityKey);
 
         /**
          * Add a new resource name to the list of names for this record.
+         * Duplicate names are not allowed.
+         *
+         * @param newName   New name for this resource. Newer names have precedence.
          *
-         * @param newName       New name for this resource. Newer names have precedence.
-         * @param didAdd        If not @c =0, the outcome will be written here.
+         * @return @c true, if the name was added. @c false, if it was invalid
+         * or already present.
          */
-        ResourceRecord& addName(String newName, bool* didAdd = 0);
+        bool addName(String newName);
 
         /**
-         * Print information about a resource to the console.
+         * Print information about the resource to the console.
          *
-         * @param record        Record for the resource.
          * @param showStatus    @c true = print loaded/located status for the
          *                      associated resource.
          */
-        static void consolePrint(ResourceRecord& record, bool showStatus = true);
+        void print(bool showStatus = true);
 
     private:
         struct Instance;

doomsday/engine/src/dd_games.cpp

@@ -200,12 +200,12 @@ GameCollection& GameCollection::locateStartupResources(Game& game)
 
     DENG2_FOR_EACH_CONST(Game::Resources, i, game.resources())
     {
-        ResourceRecord& record = **i;
+        ResourceManifest& record = **i;
 
         // We are only interested in startup resources at this time.
         if(!(record.resourceFlags() & RF_STARTUP)) continue;
 
-        record.locateResource();
+        record.locate();
     }
 
     if(d->currentGame != oldGame)

doomsday/engine/src/dd_main.cpp

@@ -370,7 +370,7 @@ boolean DD_ExchangeGamePluginEntryPoints(pluginid_t pluginId)
     return true;
 }
 
-static void loadResource(ResourceRecord& record)
+static void loadResource(ResourceManifest& record)
 {
     DENG_ASSERT(record.resourceClass() == RC_PACKAGE);
 
@@ -457,7 +457,7 @@ static int DD_LoadGameStartupResourcesWorker(void* parameters)
     for(de::Game::Resources::const_iterator i = gameResources.find(RC_PACKAGE);
         i != gameResources.end() && i.key() == RC_PACKAGE; ++i, ++packageIdx)
     {
-        ResourceRecord& record = **i;
+        ResourceManifest& record = **i;
         loadResource(record);
 
         // Update our progress.
@@ -851,7 +851,7 @@ void DD_AddGameResource(gameid_t gameId, resourceclassid_t classId, int rflags,
 
     // Construct and attach the new resource record.
     de::Game& game = games->byId(gameId);
-    ResourceRecord* record = new ResourceRecord(classId, rflags);
+    ResourceManifest* record = new ResourceManifest(classId, rflags);
     game.addResource(*record);
 
     // Add the name list to the resource record.

doomsday/engine/src/def_main.cpp

@@ -849,7 +849,7 @@ static void readAllDefinitions(void)
         for(de::Game::Resources::const_iterator i = gameResources.find(RC_DEFINITION);
             i != gameResources.end() && i.key() == RC_DEFINITION; ++i, ++packageIdx)
         {
-            de::ResourceRecord& record = **i;
+            de::ResourceManifest& record = **i;
             /// Try to locate this resource now.
             QString const& path = record.resolvedPath(true/*try to locate*/);
 

doomsday/engine/src/game.cpp

@@ -84,7 +84,7 @@ struct Game::Instance
     {
         DENG2_FOR_EACH(Game::Resources, i, resources)
         {
-            ResourceRecord* record = *i;
+            ResourceManifest* record = *i;
             delete record;
         }
 
@@ -114,7 +114,7 @@ GameCollection& Game::collection() const
     return *reinterpret_cast<de::GameCollection*>(App_GameCollection());
 }
 
-Game& Game::addResource(ResourceRecord& record)
+Game& Game::addResource(ResourceManifest& record)
 {
     // Ensure we don't add duplicates.
     Resources::const_iterator found = d->resources.find(record.resourceClass(), &record);
@@ -129,7 +129,7 @@ bool Game::allStartupResourcesFound() const
 {
     DENG2_FOR_EACH_CONST(Resources, i, d->resources)
     {
-        ResourceRecord& record = **i;
+        ResourceManifest& record = **i;
         int const flags = record.resourceFlags();
 
         if((flags & RF_STARTUP) && !(flags & RF_FOUND))
@@ -193,7 +193,7 @@ bool Game::isRequiredFile(File1& file)
     for(Resources::const_iterator i = d->resources.find(RC_PACKAGE);
         i != d->resources.end() && i.key() == RC_PACKAGE; ++i)
     {
-        ResourceRecord& record = **i;
+        ResourceManifest& record = **i;
         if(!(record.resourceFlags() & RF_STARTUP)) continue;
 
         if(!record.resolvedPath(true/*try locate*/).compare(absolutePath, Qt::CaseInsensitive))
@@ -230,11 +230,11 @@ void Game::printResources(Game const& game, int rflags, bool printStatus)
         for(Resources::const_iterator i = resources.find(classId);
             i != resources.end() && i.key() == classId; ++i)
         {
-            ResourceRecord& record = **i;
+            ResourceManifest& record = **i;
             if(rflags >= 0 && (rflags & record.resourceFlags()))
             {
-                ResourceRecord::consolePrint(record, printStatus);
-                numPrinted += 1;
+                record.print(printStatus);
+                numPrinted++;
             }
         }
     }
@@ -333,7 +333,7 @@ struct game_s* Game_AddResource(struct game_s* game, struct resourcerecord_s* re
 {
     SELF(game);
     DENG_ASSERT(record);
-    self->addResource(reinterpret_cast<de::ResourceRecord&>(*record));
+    self->addResource(reinterpret_cast<de::ResourceManifest&>(*record));
     return game;
 }