dgamevfs.vfs

  • VFSDir

    Declaration

    abstract class VFSDir;

    A directory in the VFS.

    Discussion

    Provides basic directory information and access to files and subdirectories within the directory.

    Directory names in the VFS can contain any characters except /, which is used as directory separator, and the :: sequence, which is used for explicit package lookup (see ).

    Examples

    1. //Construct the directory (ordinary physical file system directory in this case): VFSDir dir = new FSDir("main", "./user_data/main", Yes.writable); //Print information about the directory: writeln("name: ", dir.name, ", full path: ", dir.path, ", writable: ", dir.writable, ", exists: ", dir.exists); //Access a file. If it does not exist, it will be created when writing: auto file = dir.file("logs/memory.log"); //Access a subdirectory: auto shaders = dir.dir("shaders"); //Create a subdirectory. If the directory exists, nothing happens (no error): auto shaders = dir.dir("does_not_exist").create(); //dirs() and files() methods can be used to get ranges of files and subdirectories: //Print paths of all immediate subdirectories and their files: foreach(subdir; dir.dirs()) { writeln(dir.path, ":"); foreach(file; subdir.files()) { writeln(" ", file.path); } } //Print paths of all subdirectories and their subdirectories, etc. recursively: foreach(subdir; dir.dirs(Yes.deep)) { writeln(dir.path); } //Glob patterns can be used to filter the results: //Print paths of all immediate subdirectories with paths containg "doc": foreach(subdir; dir.dirs(No.deep, "*doc*")) { writeln(dir.path); } //Print paths of all files in the directory and in subdirectories with paths ending with ".txt": foreach(file; dir.files(Yes.deep, "*.txt")) { writeln(file.path); }

    • name

      Declaration

      final const pure nothrow @nogc @property @safe string name();

      Get the name of this directory.

    • path

      Declaration

      final const pure nothrow @property @safe string path();

      Get full path of this directory in the VFS.

    • writable

      Declaration

      const pure nothrow @nogc @property @safe bool writable();

      Is it possible to write to the directory?

    • exists

      Declaration

      const nothrow @property @safe bool exists();

      Does the directory exist?

    • file

      Declaration

      VFSFile file(string path);

      Get file with specified path in the directory.

      Discussion

      The file will be returned even if it does not exist - it will be created when writing into it.

      Parameters

      string path

      Path of the file to get.

      Throws

      if the directory does not exist or the file is in a nonexistent subdirectory.

      if the path is invalid.

      Return Value

      File with specified path.

    • dir

      Declaration

      @safe VFSDir dir(string path);

      Get a subdirectory with specified path in the directory.

      Discussion

      The subdirectory will be returned even if it does not exist - it can be created with the method.

      Parameters

      string path

      Path of the subdirectory to get.

      Throws

      if this VFSDir does not exist or the subdirectory is in a nonexistent subdirectory.

      if the path is invalid.

      Return Value

      Subdirectory with specified path.

    • files

      Declaration

      @safe VFSFiles files(Flag!"deep" deep = No.deep, string glob = null);

      Get a range of files in the directory.

      Parameters

      Flag!"deep" deep

      If true, recursively get files in subdirectories. Otherwise only get files directly in this directory.

      string glob

      Glob pattern used to filter the results. If null (default), all files will be returned. Otherwise only files whose VFS paths within this directory match glob (case sensitive) will be returned. Some characters of glob patterns have special meanings: For instance, *.txt matches any path ending with the .txt extension.

      Return Value

      Range of the files.

      Throws

      if the directory does not exist.

      See Also

      Wikipedia: glob (programming)

    • dirs

      Declaration

      @safe VFSDirs dirs(Flag!"deep" deep = No.deep, string glob = null);

      Get a range of subdirectories.

      Parameters

      Flag!"deep" deep

      If true, recursively get all subdirectories. Otherwise just get subdirectories of this directory.

      string glob

      Glob pattern used to filter the results. If null (default), all subdirectories will be returned. Otherwise only subdirectories whose VFS paths within this directory match glob (case sensitive) will be returned. Some characters of glob patterns have special meanings: For instance, *.txt matches any path ending with the .txt extension.

      Return Value

      Range of the directories.

      Throws

      if the directory does not exist.

    • create

      Declaration

      final @safe void create();

      Create the directory if it does not exist (otherwise do nothing).

      Throws

      if the directory could not be created.

    • remove

      Declaration

      @system void remove();

      Remove the directory if it exists (otherwise do nothing).

      Discussion

      Removes recursively, together with any subdirectories and files.

      Warning: This will make any references to subdirectories or files in this directory invalid.

      Throws

      if the directory could not be removed.

    • this

      Declaration

      protected pure nothrow @nogc @safe this(VFSDir parent, string pathInParent);

      Constructor to initialize state common for implementations.

      Parameters

      VFSDir parent

      Parent directory. If null, this directory has no parent.

      string pathInParent

      Path of the directory within the parent.

    • dirsRange

      Declaration

      protected static @safe VFSDirs dirsRange(VFSDirs.Items dirs);

      Construct a range from a set of directories.

    • filesRange

      Declaration

      protected static @safe VFSFiles filesRange(VFSFiles.Items files);

      Construct a range from a set of files.

    • composePath

      Declaration

      protected const pure nothrow @safe string composePath(const VFSDir child);

      Compose path for a child directory. Used e.g. to allow to set children's paths.

    • create_

      Declaration

      protected @trusted void create_();

      Implementation of . Caller contract guarantees that the directory is writable.

    • copyWithoutParent

      Declaration

      protected @safe VFSDir copyWithoutParent();

      Return a copy of this VFSDir without a parent. Used for mounting.

    • getCopyWithoutParent

      Declaration

      protected final @safe VFSDir getCopyWithoutParent(VFSDir dir);

      Access for derived classes to call copyWithoutParent() of other instances.

  • VFSRange

    Declaration

    struct VFSRange(T) if (is(T == VFSDir) || is(T == VFSFile));

    A bidirectional range of VFS items (files or directories).

    Examples

    1. //VFSDirs is a VFSRange of directories - VFSFiles of files. VFSDirs dirs; //Get the first directory. auto f = dirs.front; //Get the last directory. auto b = dirs.back; //Remove the first directory from the range (this will not remove the directory itself). dirs.popFront(); //Remove the last directory from the range (this will not remove the directory itself). dirs.popBack(); //Are there no files/directories ? bool empty = r.empty;

    • compare

      Declaration

      static bool compare(inout(T) a, inout(T) b);

      Function used to compare items alphabetically.

    • Items

      Declaration

      alias Items = RedBlackTree!(T, compare);

      Type used to store the items.

    • length

      Declaration

      const pure nothrow @nogc @property @safe size_t length();

      Get number of items in the range.

    • popFront

      Declaration

      pure nothrow @nogc @safe void popFront();

      Pop the front element from the range.

    • popBack

      Declaration

      pure nothrow @nogc @safe void popBack();

      Pop the back element from the range.

  • VFSDirs

    Declaration

    alias VFSDirs = VFSRange!(VFSDir).VFSRange;

    A VFSRange of directories.

  • VFSFiles

    Declaration

    alias VFSFiles = VFSRange!(VFSFile).VFSRange;

    A VFSRange of files.

  • VFSFile

    Declaration

    abstract class VFSFile;

    A file in the VFS.

    Discussion

    Provides basic file information and access to I/O.

    File names in the VFS can contain any characters except /, which is used as directory separator, and the :: sequence, which is used for explicit package lookup (see ).

    Examples

    1. VFSDir dir = new FSDir("main", "./user_data/main", Yes.writable); //Get the file from a directory. VFSFile file = dir.file("logs/memory.log"); //Print information about the file (note that we can only get file size of an existing file): writeln("name: ", file.name, ", full path: ", file.path, ", writable: ", file.writable, ", exists: ", file.exists, ", size in bytes: ", file.bytes); //Get access to read from the file: { auto input = file.input; //Simply read the file to a buffer: auto buffer = new ubyte[file.bytes]; input.read(buffer); } //Get access to write to the file: { auto output = file.output; //Simply write a buffer to the file: output.write(cast(const void[])"The answer is 42"); }

    • Mode

      Declaration

      enum Mode: int;

      File mode (used by implementations);

    • name

      Declaration

      final const nothrow @property @safe string name();

      Get name of the file.

    • path

      Declaration

      final const nothrow @property @safe string path();

      Get full path of the file in the VFS.

    • bytes

      Declaration

      const @property @safe ulong bytes();

      Get file size in bytes.

      Throws

      if the file does not exist.

    • exists

      Declaration

      const nothrow @property @safe bool exists();

      Does the file exist?

    • writable

      Declaration

      const nothrow @property @safe bool writable();

      Is it possible to write to this file?

    • open

      Declaration

      const pure nothrow @nogc @property @safe bool open();

      Is the file open?

    • input

      Declaration

      final @property VFSFileInput input();

      Open the file and get reading access.

      Return Value

      providing input access to the file.

      Throws

      if the file does not exist or is already open.

    • output

      Declaration

      final @property VFSFileOutput output(Flag!"append" append = No.append);

      Open the file and get writing access. Must not already be open.

      Return Value

      providing output access to the file.

      Throws

      if the file is not writable or is already open.

    • this

      Declaration

      protected nothrow @safe this(VFSDir parent, string pathInParent);

      Constructor to initialize state common for implementations.

      Parameters

      VFSDir parent

      Parent directory. Must not be null.

      string pathInParent

      Path of the file within the parent.

    • this

      Declaration

      protected nothrow @safe this(string absolutePath);

      Constructor to initialize a without a parent.

      Parameters

      noParent

      Parent directory. Must not be null.

      pathInParent

      Path of the file within the parent.

    • openRead

      Declaration

      protected void openRead();

      Open the file for reading.

    • openWrite

      Declaration

      protected void openWrite(Flag!"append" append);

      Open the file for writing/appending.

    • read

      Declaration

      protected void[] read(void[] target);

      Read up to bytes to target from current file position.

      Parameters

      void[] target

      Buffer to read to.

      Return Value

      Slice of target containing the read data.

    • write

      Declaration

      protected void write(in void[] data);

      Write bytes to file from current file position.

    • seek

      Declaration

      protected void seek(long offset, Seek origin);

      Seek offset bytes from origin within the file.

    • close

      Declaration

      protected void close();

      Close the file, finalizing any file operations.

    • openReadProxy

      Declaration

      protected static void openReadProxy(VFSFile file);
      protected static void openWriteProxy(VFSFile file, Flag!"append" append);
      protected static void[] readProxy(VFSFile file, void[] target);
      protected static void writeProxy(VFSFile file, const void[] data);
      protected static void seekProxy(VFSFile file, long offset, Seek origin);
      protected static void closeProxy(VFSFile file);

      Proxies to for derived VFSFiles to call protected members of other VFSFiles.

  • Seek

    Declaration

    enum Seek: int;

    File seeking positions.

    • Set

      Declaration

      Set

      Beginning of file.

    • Current

      Declaration

      Current

      Current file position.

    • End

      Declaration

      End

      End of file.

  • VFSFileInput

    Declaration

    struct VFSFileInput;

    Provides basic file input functionality - seeking and reading.

    Discussion

    uses reference counting so that the file is closed when the last instance of provided by the file is destroyed.

    Examples

    1. VFSFile file; //initialized somewhere before auto input = file.input; with(input) { auto buffer = new ubyte[32]; //Read the first 32 bytes from the file: read(buffer); //Read the next 32 bytes: read(buffer); //Read the last 32 bytes in the file: seek(-32, file); read(buffer); }

    • read

      Declaration

      void[] read(void[] target);

      Read at most bytes starting at current file position to target.

      Discussion

      If the file does not have enough bytes to fill target or a reading error is encountered, it reads as much data as possible and returns the part of target containing the read data.

      Parameters

      void[] target

      Buffer to read to.

      Return Value

      Slice of target containing the read data.

    • seek

      Declaration

      void seek(long offset, Seek origin);

      Set file position to offset bytes from specified origin.

      Parameters

      long offset

      Number of bytes to set file position relative to origin.

      Seek origin

      Position to which offset is added.

      Throws

      if trying to seek before the beginning or beyond the end of file.

  • VFSFileOutput

    Declaration

    struct VFSFileOutput;

    Provides basic file output functionality - seeking and writing.

    Discussion

    uses reference counting so that the file is closed when the last instance of provided by the file is destroyed.

    Examples

    1. VFSFile file; //initialized somewhere before auto output = file.output; with(output) { //Write to the file: write(cast(const void[])"The answer is ??"); //Change the last two characters in the file: seek(-2, Seek.End); write(cast(const void[])"42"); }


    1. //Appending: //When appending to the file, every write writes to the end of file //regardless of any calls to seek(), and sets the file position //to end of file. This //(This is to stay in line with the C standard so we can use C functions directly) auto output = file.output(Yes.append); with(output) { //Append to the file: write(cast(const void[])"The answer is ??"); //This will NOT change the last 2 characters: it will append anyway: seek(-2, Seek.End); write(cast(const void[])"42"); }

    • write

      Declaration

      void write(const void[] data);

      Write data to file starting at current file position.

      Note: In append mode, any write will write to the end of file regardless of the current file position and file position will be set to the end of file.

      (This is to stay in line with the C standard so we can use C I/O functions directly)

      Parameters

      void[] data

      Data to write to the file.

      Throws

      on error (e.g. after running out of disk space).

    • seek

      Declaration

      void seek(long offset, Seek origin);

      Set file position to offset bytes from specified origin.

      Parameters

      long offset

      Number of bytes to set file position relative to origin.

      Seek origin

      Position to which offset is added.

      Throws

      if trying to seek before the beginning or behind the end of file, or on a different error.