libdonut
2.3.2
Application framework for cross-platform game development in C++20
|
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... | |
Filesystem & | operator= (const Filesystem &)=delete |
Copying a filesystem is not allowed, since it manages global state. More... | |
Filesystem & | operator= (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... | |
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.
|
explicit |
Initialize the virtual filesystem.
programFilepath | the first string in the argument vector passed to the main function of the program, i.e. argv[0]. |
options | initial configuration of the virtual filesystem, see FilesystemOptions. |
File::Error | if initialization failed. |
std::bad_alloc | on allocation failure. |
donut::Filesystem::~Filesystem | ( | ) |
Destructor.
|
delete |
Copying a filesystem is not allowed, since it manages global state.
|
delete |
Moving a filesystem is not allowed, since it manages global state.
|
delete |
Copying a filesystem is not allowed, since it manages global state.
|
delete |
Moving a filesystem is not allowed, since it manages global state.
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.
organizationName | non-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. |
applicationName | non-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. |
std::bad_alloc | on allocation failure. |
std::string donut::Filesystem::getOutputDirectory | ( | ) | const |
Get the current output directory of the virtual filesystem.
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.
path | host filepath of the new output directory to set. |
File::Error | on failure to set the output directory to the given path. |
std::bad_alloc | on allocation failure. |
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.
path | host filepath of the directory or archive to mount. Must not be nullptr. |
priority | mount priority of the archive to be mounted, see FilesystemMountPriority. |
File::Error | on failure to mount the given filepath. |
void donut::Filesystem::unmountArchive | ( | const char * | path | ) |
Unmount a previously mounted directory or archive on the host filesystem from the virtual filesystem.
path | host filepath of the directory or archive to unmount, which was previously mounted by mountArchive() or mountArchives(). Must not be nullptr. |
File::Error | on failure to unmount the given filepath. |
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.
filepath | virtual filepath of the mounted directory to search for archives in. Must not be nullptr. |
archiveFileExtension | non-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. |
priority | mount priority of the archives to be mounted, see FilesystemMountPriority. |
File::Error | on failure to search for archives or mount an archive. |
std::bad_alloc | on allocation failure. |
void donut::Filesystem::unmountArchives | ( | std::span< const std::string > | paths | ) |
Unmount multiple archives.
Equivalent to calling unmountArchive() on each given path.
paths | the host filepaths of the archives to unmount, which were previously mounted by mountArchive() or mountArchives(). |
File::Error | on failure to unmount a given filepath. |
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.
filepath | virtual filepath of the file to get the archive of. Must not be nullptr. |
void donut::Filesystem::createDirectory | ( | const char * | filepath | ) |
Create a new host directory in the output directory.
filepath | virtual filepath, relative to the current output directory, of the new directory to be created. Must not be nullptr. |
Error | on failure to create the given directory. |
std::bad_alloc | on allocation failure. |
void donut::Filesystem::deleteFile | ( | const char * | filepath | ) |
Delete a host file or directory in the output directory.
filepath | virtual filepath, relative to the current output directory, of the file or directory to delete. Must not be nullptr. |
Error | on failure to delete the given file or directory. |
std::bad_alloc | on allocation failure. |
bool donut::Filesystem::fileExists | ( | const char * | filepath | ) | const |
Check if a given virtual filepath has a corresponding host file mounted.
filepath | virtual filepath to check for a mounted file. Must not be nullptr. |
File::Metadata donut::Filesystem::getFileMetadata | ( | const char * | filepath | ) | const |
Get the metadata of a file that is mounted at a given virtual filepath.
filepath | virtual filepath of the file to get the metadata of. Must not be nullptr. |
File::Error | on failure to get the metadata, such as if no file is mounted at the given filepath. |
std::bad_alloc | on allocation failure. |
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.
filepath | virtual filepath of the directory to enumerate. Must not be nullptr. |
Error | on failure to enumerate the directory. |
std::bad_alloc | on allocation failure. |
"{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.File donut::Filesystem::openFile | ( | const char * | filepath | ) | const |
Open a file in the virtual filesystem for reading.
filepath | virtual filepath of the file to open. Must not be nullptr. |
File::Error | on failure to open the file for reading. |
std::bad_alloc | on allocation failure. |
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.
filepath | virtual filepath of the new file to be created, relative to the current output directory. Must not be nullptr. |
File::Error | on failure to delete the existing file, create the new file, or open the new file for writing. |
std::bad_alloc | on allocation failure. |
File donut::Filesystem::appendFile | ( | const char * | filepath | ) |
Open a file in the output directory specified by the virtual filesystem for appended writing.
filepath | virtual filepath of the file to be opened, relative to the current output directory. Must not be nullptr. |
File::Error | on failure to open the file for writing. |
std::bad_alloc | on allocation failure. |