API: Added M_ReadFileIntoString()

A convenient method of reading a file or WAD lump into a string.

doomsday/api/api_filesys.h

@@ -68,6 +68,17 @@ DENG_API_TYPEDEF(F)
     const char*     (*PrettyPath)(const char* path);
 
     size_t          (*ReadFile)(const char* path, char** buffer);
+
+    /**
+     * Attempt to read a file on the specified @a path into a text string.
+     *
+     * @param path      Path to search for the file on.
+     * @param isCustom  If not @c 0, the @em is-custom status of the found file is
+     *                  written here (i.e., @c true= the file was @em not loaded
+     *                  from some resource of the current game).
+     */
+    AutoStr*        (*ReadFileIntoString)(Str const *path, dd_bool *isCustom);
+
     dd_bool         (*WriteFile)(const char* path, const char* source, size_t length);
 }
 DENG_API_T(F);
@@ -83,6 +94,7 @@ DENG_API_T(F);
 #define F_TranslatePath         _api_F.TranslatePath
 #define F_PrettyPath            _api_F.PrettyPath
 #define M_ReadFile              _api_F.ReadFile
+#define M_ReadFileIntoString    _api_F.ReadFileIntoString
 #define M_WriteFile             _api_F.WriteFile
 #endif
 

doomsday/api/apis.h

@@ -79,7 +79,8 @@ enum {
     DE_API_DEFINITIONS          = DE_API_DEFINITIONS_v1,
 
     DE_API_FILE_SYSTEM_v1       = 600,     // 1.10
-    DE_API_FILE_SYSTEM          = DE_API_FILE_SYSTEM_v1,
+    DE_API_FILE_SYSTEM_v2       = 601,     // 1.14
+    DE_API_FILE_SYSTEM          = DE_API_FILE_SYSTEM_v2,
 
     DE_API_FONT_RENDER_v1       = 700,     // 1.10
     DE_API_FONT_RENDER          = DE_API_FONT_RENDER_v1,

doomsday/client/src/filesys/fs_main.cpp

@@ -1676,6 +1676,7 @@ extern const char* F_PrettyPath(char const *path);
 
 // m_misc.c
 DENG_EXTERN_C size_t M_ReadFile(char const *name, char **buffer);
+DENG_EXTERN_C AutoStr* M_ReadFileIntoString(ddstring_t const *path, dd_bool *isCustom);
 DENG_EXTERN_C dd_bool M_WriteFile(char const *name, char const *source, size_t length);
 
 DENG_DECLARE_API(F) =
@@ -1692,5 +1693,6 @@ DENG_DECLARE_API(F) =
     F_TranslatePath,
     F_PrettyPath,
     M_ReadFile,
+    M_ReadFileIntoString,
     M_WriteFile
 };

doomsday/client/src/m_misc.cpp

@@ -1,4 +1,4 @@
-/** @file m_misc.cpp
+/** @file m_misc.cpp  Miscellanous utility routines.
  *
  * @authors Copyright © 2003-2013 Jaakko Keränen <jaakko.keranen@iki.fi>
  * @authors Copyright © 2006-2013 Daniel Swanson <danij@dengine.net>
@@ -17,11 +17,7 @@
  * http://www.gnu.org/licenses</small>
  */
 
-/**
- * Miscellanous Routines.
- */
-
-// HEADER FILES ------------------------------------------------------------
+#define DENG_NO_API_MACROS_FILESYS
 
 #include "de_platform.h"
 
@@ -45,10 +41,6 @@
 #  define O_BINARY 0
 #endif
 
-#include <stdlib.h>
-#include <ctype.h>
-#include <math.h>
-
 #include "de_base.h"
 #include "de_console.h"
 #include "de_system.h"
@@ -59,11 +51,14 @@
 
 #include "lzss.h"
 
+#include <de/str.h>
+#include <cstdlib>
+#include <cctype>
+#include <cmath>
+
 #undef M_WriteFile
 #undef M_ReadFile
 
-// MACROS ------------------------------------------------------------------
-
 #define SLOPERANGE      2048
 #define SLOPEBITS       11
 #define DBITS           (FRACBITS-SLOPEBITS)
@@ -74,26 +69,10 @@
 #define write _write
 #endif
 
-// TYPES -------------------------------------------------------------------
-
-// EXTERNAL FUNCTION PROTOTYPES --------------------------------------------
-
-// PUBLIC FUNCTION PROTOTYPES ----------------------------------------------
-
-// PRIVATE FUNCTION PROTOTYPES ---------------------------------------------
-
 static size_t FileReader(char const* name, char** buffer);
 
-// EXTERNAL DATA DECLARATIONS ----------------------------------------------
-
 extern int tantoangle[SLOPERANGE + 1];  // get from tables.c
 
-// PUBLIC DATA DEFINITIONS -------------------------------------------------
-
-// PRIVATE DATA DEFINITIONS ------------------------------------------------
-
-// CODE --------------------------------------------------------------------
-
 void M_ReadLine(char* buffer, size_t len, FileHandle* file)
 {
     size_t p;
@@ -284,6 +263,47 @@ DENG_EXTERN_C size_t M_ReadFile(const char* name, char** buffer)
     return FileReader(name, buffer);
 }
 
+DENG_EXTERN_C AutoStr* M_ReadFileIntoString(ddstring_t const *path, dd_bool *isCustom)
+{
+    if(isCustom) *isCustom = false;
+
+    if(Str_StartsWith(path, "Lumps:"))
+    {
+        lumpnum_t lumpNum = W_CheckLumpNumForName(Str_Text(path) + 6);
+        if(lumpNum < 0) return 0;
+
+        if(isCustom) *isCustom = W_LumpIsCustom(lumpNum);
+
+        // Ignore zero-length scripts.
+        size_t lumpLen = W_LumpLength(lumpNum);
+        if(!lumpLen) return 0;
+
+        // Ensure the resulting string is terminated.
+        AutoStr *string = Str_PartAppend(AutoStr_New(), (char *)W_CacheLump(lumpNum), 0, lumpLen);
+        W_UnlockLump(lumpNum);
+
+        if(Str_IsEmpty(string))
+            return 0;
+
+        return string;
+    }
+
+    char *readBuf = 0;
+    if(size_t bytesRead = M_ReadFile(Str_Text(path), &readBuf))
+    {
+        // Ensure the resulting string is terminated.
+        AutoStr *string = Str_PartAppend(AutoStr_New(), readBuf, 0, int(bytesRead));
+        Z_Free(readBuf);
+
+        if(Str_IsEmpty(string))
+            return 0;
+
+        return string;
+    }
+
+    return 0;
+}
+
 static size_t FileReader(const char* name, char** buffer)
 {
     struct stat fileinfo;