dgamevfs.stack

Stacked files/directories for seamless access to multiple directories as if they were a single directory.

  • StackDir

    Declaration

    class StackDir: dgamevfs.vfs.VFSDir;

    A directory seamlessly working on a stack of multiple directories.

    Discussion

    Directories can be mounted using the method.

    When looking for a file or directory in a , the last directory is searched first, then the second last, and so on. This means that directories mounted later override those mounted before.

    Example: We have a directory called data with the following contents:

    1. shaders: font.frag font.vert logs: (empty) main.cfg
    and a directory called user_data with the following contents:
    1. shaders: font.frag logs: (empty) custom.cfg
    the following code will work as specified in the comments:
    1. VFSDir data, user_data; //initialized somewhere before auto stack = new StackDir("stack"); stack.mount(data); stack.mount(user_data); //This will access user_data/shaders/font.frag auto frag = stack.file("shaders/font.frag"); //This will access data/shaders/font.vert auto vert = stack.file("shaders/font.vert"); //This will return a StackDir (as VFSDir) with "data/logs" and "user_data/logs" //mounted, in that order: auto logs = stack.dir("logs");


    Accessing a file in a will actually return a , which decides which file to access on read, write and other operations. The is a stack of all files that map to the same path in the in the same order as 's mounted directories.

    For example, when reading or determining file size, the directories in the stack will be searched from newest to oldest and the first file found will be used.

    When writing, the file in the newest writable directory will be written to.



    In some cases, it might be required to access a particular directory in the stack. E.g. a game might have multiple packages stacked on top of each other, but sometimes default, non-overridden version of a file could be needed. This can be done using the :: separator.

    In the context of the previous example:

    1. //This will access data/shaders/font.frag even though user_data/shaders/font.frag exists auto default_frag = stack.file("data::shaders/font.frag");


    is considered writable when any directory in the stack is writable. Similarly, it exists when any directory in the stack exists.

    When we have a that does not exist and we it, the newest directory that is writable will be created. (This can happen when getting a nonexistent subdirectory of a .)

    • this

      Declaration

      pure @safe this(string name);

      Construct a .

      Parameters

      string name

      Name of the .

      Throws

      if name is not valid (contains '/' or "::").

    • mount

      Declaration

      @safe void mount(VFSDir dir);

      Mount a directory.

      Discussion

      Files and directories of a directory mounted later will override those of a directory mounted earlier.

      If dir has a parent in the VFS, a parent-less copy will be created and mounted. (This has no effect whatsoever on the underlying filesystem - it just removes the need for directories to have multiple parents).

      Parameters

      VFSDir dir

      Directory to mount.

      Throws

      if a directory with the same name is already mounted, or if dir has this directory as its child or a child of any of its subdirectories (circular mounting).

  • StackFile

    Declaration

    class StackFile: dgamevfs.vfs.VFSFile;

    A file seamlessly working on a stack of multiple files.

    Discussion

    This is the file implementation returned by methods.

    It has one file from each directory in the - all of these files map to the same path in the .

    When reading from , it will read from the newest file in the stack that exists.

    When writing, it will write to the newest file that is writable regardless of whether it already exists or not.