libdonut  2.3.2
Application framework for cross-platform game development in C++20
Public Member Functions | List of all members
donut::Filesystem Class Reference

Persistent system for managing the virtual filesystem. More...

#include <donut/Filesystem.hpp>

Public Member Functions

 Filesystem (const char *programFilepath, const FilesystemOptions &options={})
 Initialize the virtual filesystem. More...
 
 ~Filesystem ()
 Destructor. More...
 
 Filesystem (const Filesystem &)=delete
 Copying a filesystem is not allowed, since it manages global state. More...
 
 Filesystem (Filesystem &&)=delete
 Moving a filesystem is not allowed, since it manages global state. More...
 
Filesystemoperator= (const Filesystem &)=delete
 Copying a filesystem is not allowed, since it manages global state. More...
 
Filesystemoperator= (Filesystem &&)=delete
 Moving a filesystem is not allowed, since it manages global state. More...
 
std::string getStandardOutputDirectory (const char *organizationName, const char *applicationName) const
 Get a suitable output directory for configuration files and other save data on the host platform, which is usually located somwhere within the user's home directory in a sub-folder tailored to this specific application. More...
 
std::string getOutputDirectory () const
 Get the current output directory of the virtual filesystem. More...
 
void setOutputDirectory (std::string path)
 Set the output directory of the virtual filesystem, where all output files will be written. More...
 
void mountArchive (const char *path, FilesystemMountPriority priority=FilesystemMountPriority::HIGHER)
 Mount a directory or archive on the host filesystem to the root directory of the virtual filesystem. More...
 
void unmountArchive (const char *path)
 Unmount a previously mounted directory or archive on the host filesystem from the virtual filesystem. More...
 
std::vector< std::string > mountArchives (const char *filepath, const char *archiveFileExtension, FilesystemMountPriority priority=FilesystemMountPriority::HIGHER)
 Mount all archives in a given directory on the host filesystem to the root directory of the virtual filesystem. More...
 
void unmountArchives (std::span< const std::string > paths)
 Unmount multiple archives. More...
 
const char * findArchiveOfFile (const char *filepath) const
 Get the host filepath of the mounted archive on the host filesystem that contains a given virtual file. More...
 
void createDirectory (const char *filepath)
 Create a new host directory in the output directory. More...
 
void deleteFile (const char *filepath)
 Delete a host file or directory in the output directory. More...
 
bool fileExists (const char *filepath) const
 Check if a given virtual filepath has a corresponding host file mounted. More...
 
File::Metadata getFileMetadata (const char *filepath) const
 Get the metadata of a file that is mounted at a given virtual filepath. More...
 
std::vector< std::string > getFilenamesInDirectory (const char *filepath) const
 Get a list of the filenames of all readable virtual filepaths that are direct children of a given directory. More...
 
File openFile (const char *filepath) const
 Open a file in the virtual filesystem for reading. More...
 
File createFile (const char *filepath)
 Create a file in the output directory and open it for writing, overwriting any existing file at the same filepath. More...
 
File appendFile (const char *filepath)
 Open a file in the output directory specified by the virtual filesystem for appended writing. More...
 

Detailed Description

Persistent system for managing the virtual filesystem.

This system allows for mounting multiple host filesystem directories to the same virtual mount point, mapping each contained file path to the corresponding host file with the highest mount priority for the purposes of reading. For writing, the filesystem defines a specific centralized folder known as the output directory, where any output files will be written. See FilesystemOptions for more information.

Constructor & Destructor Documentation

◆ Filesystem() [1/3]

donut::Filesystem::Filesystem ( const char *  programFilepath,
const FilesystemOptions options = {} 
)
explicit

Initialize the virtual filesystem.

Parameters
programFilepaththe first string in the argument vector passed to the main function of the program, i.e. argv[0].
optionsinitial configuration of the virtual filesystem, see FilesystemOptions.
Exceptions
File::Errorif initialization failed.
std::bad_allocon allocation failure.
Warning
The behavior of passing programFilepath a value other than the argv[0] string received from main is undefined.
There can only be one active virtual filesystem in a program at a time.
See also
setOutputDirectory()
mountArchives()
mountArchive()

◆ ~Filesystem()

donut::Filesystem::~Filesystem ( )

Destructor.

◆ Filesystem() [2/3]

donut::Filesystem::Filesystem ( const Filesystem )
delete

Copying a filesystem is not allowed, since it manages global state.

◆ Filesystem() [3/3]

donut::Filesystem::Filesystem ( Filesystem &&  )
delete

Moving a filesystem is not allowed, since it manages global state.

Member Function Documentation

◆ operator=() [1/2]

Filesystem& donut::Filesystem::operator= ( const Filesystem )
delete

Copying a filesystem is not allowed, since it manages global state.

◆ operator=() [2/2]

Filesystem& donut::Filesystem::operator= ( Filesystem &&  )
delete

Moving a filesystem is not allowed, since it manages global state.

◆ getStandardOutputDirectory()

std::string donut::Filesystem::getStandardOutputDirectory ( const char *  organizationName,
const char *  applicationName 
) const

Get a suitable output directory for configuration files and other save data on the host platform, which is usually located somwhere within the user's home directory in a sub-folder tailored to this specific application.

Parameters
organizationNamenon-owning pointer to a null-terminated UTF-8 string that commonly identifies the publisher of the application, such as an organization name, alias or internet domain. This will be used for the name of the organization folder in the user/platform-specific preferences directory on platforms where it is applicable. Must not be nullptr.
applicationNamenon-owning pointer to a null-terminated UTF-8 string that uniquely identifies the application among all other applications released by the same organization. This will be used for the name of the application folder under the organization folder in the user/platform-specific preferences directory on platforms where it is applicable. Must not be nullptr.
Returns
a directory that can be passed to setOutputDirectory(), or an empty string if a suitable output directory could not be determined.
Exceptions
std::bad_allocon allocation failure.
See also
setOutputDirectory()
getOutputDirectory()

◆ getOutputDirectory()

std::string donut::Filesystem::getOutputDirectory ( ) const

Get the current output directory of the virtual filesystem.

Returns
the host filepath corresponding to the current output directory, or an empty string if no output directory is currently set.
See also
getStandardOutputDirectory()
setOutputDirectory()

◆ setOutputDirectory()

void donut::Filesystem::setOutputDirectory ( std::string  path)

Set the output directory of the virtual filesystem, where all output files will be written.

The specified directory will be created if it doesn't already exist.

Parameters
pathhost filepath of the new output directory to set.
Exceptions
File::Erroron failure to set the output directory to the given path.
std::bad_allocon allocation failure.
Note
To be able to read files from the output directory, it must also be mounted using mountArchive().
See also
getStandardOutputDirectory()
getOutputDirectory()

◆ mountArchive()

void donut::Filesystem::mountArchive ( const char *  path,
FilesystemMountPriority  priority = FilesystemMountPriority::HIGHER 
)

Mount a directory or archive on the host filesystem to the root directory of the virtual filesystem.

Parameters
pathhost filepath of the directory or archive to mount. Must not be nullptr.
prioritymount priority of the archive to be mounted, see FilesystemMountPriority.
Exceptions
File::Erroron failure to mount the given filepath.
Note
If the given path is already mounted, no change will occur.
See also
mountArchives()
unmountArchive()

◆ unmountArchive()

void donut::Filesystem::unmountArchive ( const char *  path)

Unmount a previously mounted directory or archive on the host filesystem from the virtual filesystem.

Parameters
pathhost filepath of the directory or archive to unmount, which was previously mounted by mountArchive() or mountArchives(). Must not be nullptr.
Exceptions
File::Erroron failure to unmount the given filepath.
See also
mountArchive()

◆ mountArchives()

std::vector<std::string> donut::Filesystem::mountArchives ( const char *  filepath,
const char *  archiveFileExtension,
FilesystemMountPriority  priority = FilesystemMountPriority::HIGHER 
)

Mount all archives in a given directory on the host filesystem to the root directory of the virtual filesystem.

This is useful for allowing users to easily create and share modifications or plugins that add or override application resources by simply adding the mod archive to the given directory.

The newly mounted archives will have a higher priority than any previously mounted archives when choosing which host file to map a virtual filepath to, meaning more recently mounted files are preferred.

Parameters
filepathvirtual filepath of the mounted directory to search for archives in. Must not be nullptr.
archiveFileExtensionnon-owning pointer to a null-terminated UTF-8 string of the filename extension of the archive files to mount. If set to nullptr, all found archives will be mounted regardless of extension.
prioritymount priority of the archives to be mounted, see FilesystemMountPriority.
Returns
an input-iterable sequence containing the host filepaths of the archives that were mounted, in no specific order.
Exceptions
File::Erroron failure to search for archives or mount an archive.
std::bad_allocon allocation failure.
Note
The found archives are mounted in no particular order.
See also
unmountArchives()
mountArchive()
unmountArchive()

◆ unmountArchives()

void donut::Filesystem::unmountArchives ( std::span< const std::string >  paths)

Unmount multiple archives.

Equivalent to calling unmountArchive() on each given path.

Parameters
pathsthe host filepaths of the archives to unmount, which were previously mounted by mountArchive() or mountArchives().
Exceptions
File::Erroron failure to unmount a given filepath.
See also
mountArchives()
mountArchive()
unmountArchives()

◆ findArchiveOfFile()

const char* donut::Filesystem::findArchiveOfFile ( const char *  filepath) const

Get the host filepath of the mounted archive on the host filesystem that contains a given virtual file.

Parameters
filepathvirtual filepath of the file to get the archive of. Must not be nullptr.
Returns
the host filepath of the directory or archive that was previously passed to mountArchive(), in which the corresponding virtual file was found, or nullptr if the virtual file was not found at any active mount point.
Warning
This function may return nullptr.
See also
mountArchive()

◆ createDirectory()

void donut::Filesystem::createDirectory ( const char *  filepath)

Create a new host directory in the output directory.

Parameters
filepathvirtual filepath, relative to the current output directory, of the new directory to be created. Must not be nullptr.
Exceptions
Erroron failure to create the given directory.
std::bad_allocon allocation failure.

◆ deleteFile()

void donut::Filesystem::deleteFile ( const char *  filepath)

Delete a host file or directory in the output directory.

Parameters
filepathvirtual filepath, relative to the current output directory, of the file or directory to delete. Must not be nullptr.
Exceptions
Erroron failure to delete the given file or directory.
std::bad_allocon allocation failure.
Warning
If successful, this will delete the actual file that corresponds to the given virtual filepath on the host filesystem; not just the virtual file entry.
Although deleting a file will prevent it from being read again through conventional means, the physical data that was contained in the file may or may not remain untouched on disk, meaning that this function cannot be relied upon to securly erase sensitive data.
Note
Directories must be empty before they can be successfully deleted using this function.

◆ fileExists()

bool donut::Filesystem::fileExists ( const char *  filepath) const

Check if a given virtual filepath has a corresponding host file mounted.

Parameters
filepathvirtual filepath to check for a mounted file. Must not be nullptr.
Returns
true if a file is mounted at the given filepath, false otherwise.
See also
getFileMetadata()
getFilenamesInDirectory()

◆ getFileMetadata()

File::Metadata donut::Filesystem::getFileMetadata ( const char *  filepath) const

Get the metadata of a file that is mounted at a given virtual filepath.

Parameters
filepathvirtual filepath of the file to get the metadata of. Must not be nullptr.
Returns
the file metadata, see File::Metadata.
Exceptions
File::Erroron failure to get the metadata, such as if no file is mounted at the given filepath.
std::bad_allocon allocation failure.

◆ getFilenamesInDirectory()

std::vector<std::string> donut::Filesystem::getFilenamesInDirectory ( const char *  filepath) const

Get a list of the filenames of all readable virtual filepaths that are direct children of a given directory.

Parameters
filepathvirtual filepath of the directory to enumerate. Must not be nullptr.
Returns
an input-iterable sequence containing the filenames, in no specific order.
Exceptions
Erroron failure to enumerate the directory.
std::bad_allocon allocation failure.
Note
This function is not recursive, and only returns the filename component of the direct descendants of the given directory, without the leading directory path. The full virtual filepath of each result can be formatted as "{filepath}/{filename}", where {filepath} is the directory filepath that was passed to the function, and {filename} is one of the results in the returned sequence. Note that this path may refer to any kind of file, including a subdirectory. Use getFileMetadata() to find out which kind of file it refers to.
See also
fileExists()
getFileMetadata()

◆ openFile()

File donut::Filesystem::openFile ( const char *  filepath) const

Open a file in the virtual filesystem for reading.

Parameters
filepathvirtual filepath of the file to open. Must not be nullptr.
Returns
a new virtual file handle with an input stream set up to read the opened file starting at file position 0.
Exceptions
File::Erroron failure to open the file for reading.
std::bad_allocon allocation failure.
See also
createFile()
appendFile()

◆ createFile()

File donut::Filesystem::createFile ( const char *  filepath)

Create a file in the output directory and open it for writing, overwriting any existing file at the same filepath.

Parameters
filepathvirtual filepath of the new file to be created, relative to the current output directory. Must not be nullptr.
Returns
a new virtual file handle with an output stream set up to write to the new empty file that was opened.
Exceptions
File::Erroron failure to delete the existing file, create the new file, or open the new file for writing.
std::bad_allocon allocation failure.
Warning
If successful, any existing host file that corresponds to the given virtual filepath in the output directory on the host filesystem will be deleted on the host filesystem; not just its virtual file entry. All modifications made through the virtual file handle will also be reflected in the physical file on the host file system.
See also
openFile()
appendFile()

◆ appendFile()

File donut::Filesystem::appendFile ( const char *  filepath)

Open a file in the output directory specified by the virtual filesystem for appended writing.

Parameters
filepathvirtual filepath of the file to be opened, relative to the current output directory. Must not be nullptr.
Returns
a new virtual file handle with an output stream set up to write to the end of the opened file.
Exceptions
File::Erroron failure to open the file for writing.
std::bad_allocon allocation failure.
Warning
If successful, the existing host file that corresponds to the given virtual filepath in the output directory on the host filesystem will receive all modifications made through the virtual file handle.
Note
A new, empty file will be created if the specified file doesn't already exist.
See also
openFile()
createFile()

The documentation for this class was generated from the following file: