IMutableFileSystem::saveFileBlob (#2427)

* #include an absolute path didn't work - because paths were taken to always be relative.

* Remove ref count for Entry in RiffFileSystem.
Free up backing Entry types (to work around Dictionary not doing this).

* Some small improvements to RiffFileSystem.

* Add testing for file systems.

* Split out MemoryFileSystem.

* Add some documentation around different FileSystems.

* Small tiry up - removing unused headers, fixing some comments.
Use StringBlob::moveCreate where appropriate.

* Small improvement to MemoryFileSystem.
Improve documentation comments a little.

* Added PathKind

* * Make MemoryFileSystem not have implicit directories
* Make RelativeFileSystem only allow access to files in file system (kind of like chroot)
* Added Path::simplifyAbsolute
* Special handling for root of MemoryFileSystem
* Improvements around paths for different impls

* More improvements around RelativeFileSystem.
Special case root handling.

* Test archive serialization.
Move testinf from compression.
Remove the implicit directory test -> doesn't work on all file systems.

* Small optimization that removes need for check for a parent unless an item is being *created*.

* Add implicit path testing.

* Add support for saveFileBlob
Add testing for saveFileBlob

* Removed TemporaryFileSet
Added PlatformUtil::outputDebugMessage

* Some small improvements around RelativeFileSystem.

* Split out ImplicitDirectoryCollector so can use without requiring compression systems.

* Split out StringSliceIndexMap into own files.

1 files changed, 59 insertions, 30 deletions

diff --git a/slang.h b/slang.h
index 72d39ec5f..42825f5c4 100644
--- a/slang.h
+++ b/slang.h
@@ -1090,7 +1090,39 @@ extern "C"
     {
         None,                ///< Paths do not map to the file system
         Direct,              ///< Paths map directly to the file system
-        Canonical,           ///< Only canonical paths map to the file system
+        OperatingSystem,     ///< Only paths gained via PathKind::OperatingSystem map to the operating system file system
+    };
+
+    /* Used to determine what kind of path is required from an input path */
+    enum class PathKind
+    {
+            /// Given a path, returns a simplified version of that path.  
+            /// This typically means removing '..' and/or '.' from the path.
+            /// A simplified path must point to the same object as the original.
+        Simplified,             
+
+            /// Given a path, returns a 'canonical path' to the item. 
+            /// This may be the operating system 'canonical path' that is the unique path to the item.
+            /// 
+            /// If the item exists the returned canonical path should always be usable to access the item.
+            /// 
+            /// If the item the path specifies doesn't exist, the canonical path may not be returnable
+            /// or be a path simplification.             
+            /// Not all file systems support canonical paths.
+        Canonical,
+
+            /// Given a path returns a path such that it is suitable to be displayed to the user.
+            /// 
+            /// For example if the file system is a zip file - it might include the path to the zip
+            /// container as well as the path to the specific file.
+            /// 
+            /// NOTE! The display path won't necessarily work on the file system to access the item
+        Display,
+
+            /// Get the path to the item on the *operating system* file system, if available.
+        OperatingSystem,
+
+        CountOf,
     };
 
     /** An extended file system abstraction.
@@ -1161,36 +1193,17 @@ extern "C"
             const char* path, 
             SlangPathType* pathTypeOut) = 0;
 
-        /** Get a simplified path. 
-        Given a path, returns a simplified version of that path - typically removing '..' and/or '.'. A simplified
-        path must point to the same object as the original. 
-       
-        This method is optional, if not implemented return SLANG_E_NOT_IMPLEMENTED.
+        /** Get a path based on the kind.
 
-        @param path
-        @param outSimplifiedPath
+        @param kind The kind of path wanted
+        @param path The input path
+        @param outPath The output path held in a blob
         @returns SLANG_OK if successfully simplified the path (SLANG_E_NOT_IMPLEMENTED if not implemented, or some other error code)
         */
-        virtual SLANG_NO_THROW SlangResult SLANG_MCALL getSimplifiedPath(
+        virtual SLANG_NO_THROW SlangResult SLANG_MCALL getPath(
+            PathKind kind,
             const char* path,
-            ISlangBlob** outSimplifiedPath) = 0;
-
-        /** Get a canonical path identifies an object of the file system.
-
-        Given a path, returns a 'canonicalPath' to the file. This may be a file system 'canonical path' to
-        show where a file was read from. If the file system is say a zip file - it might include the path to the zip
-        container as well as the absolute path to the specific file. The main purpose of the method is to be able
-        to display to uses unambiguously where a file was read from.
-
-        This method is optional, if not implemented return SLANG_E_NOT_IMPLEMENTED.
-
-        @param path
-        @param outCanonicalPath
-        @returns SLANG_OK if successfully canonicalized the path (SLANG_E_NOT_IMPLEMENTED if not implemented, or some other error code)
-        */
-        virtual SLANG_NO_THROW SlangResult SLANG_MCALL getCanonicalPath(
-            const char* path,
-            ISlangBlob** outCanonicalPath) = 0;
+            ISlangBlob** outPath) = 0;
 
         /** Clears any cached information */
         virtual SLANG_NO_THROW void SLANG_MCALL clearCache() = 0;
@@ -1211,7 +1224,7 @@ extern "C"
 
         /** Returns how paths map to the OS file system
         
-        @returns true if this 
+        @returns OSPathKind that describes how paths map to the Operating System file system
         */
         virtual SLANG_NO_THROW OSPathKind SLANG_MCALL getOSPathKind() = 0;
     };
@@ -1222,11 +1235,11 @@ extern "C"
     {
         SLANG_COM_INTERFACE(0xa058675c, 0x1d65, 0x452a, { 0x84, 0x58, 0xcc, 0xde, 0xd1, 0x42, 0x71, 0x5 })
 
-        /** Write the data specified with data and size to the specified path.
+        /** Write data to the specified path.
 
         @param path The path for data to be saved to
         @param data The data to be saved
-        @param size The size of the data
+        @param size The size of the data in bytes
         @returns SLANG_OK if successful (SLANG_E_NOT_IMPLEMENTED if not implemented, or some other error code)
         */
         virtual SLANG_NO_THROW SlangResult SLANG_MCALL saveFile(
@@ -1234,6 +1247,22 @@ extern "C"
             const void* data,
             size_t size) = 0;
 
+        /** Write data in the form of a blob to the specified path.
+
+        Depending on the implementation writing a blob might be faster/use less memory. It is assumed the 
+        blob is *immutable* and that an implementation can reference count it.
+
+        It is not guaranteed loading the same file will return the *same* blob - just a blob with same 
+        contents.
+
+        @param path The path for data to be saved to
+        @param dataBlob The data to be saved
+        @returns SLANG_OK if successful (SLANG_E_NOT_IMPLEMENTED if not implemented, or some other error code)
+        */
+        virtual SLANG_NO_THROW SlangResult SLANG_MCALL saveFileBlob(
+            const char* path,
+            ISlangBlob* dataBlob) = 0;
+
         /** Remove the entry in the path (directory of file). Will only delete an empty directory, if not empty
         will return an error.