cubos::core::data::EmbeddedArchive class
#include <core/data/fs/embedded_archive.hpp>

Archive implementation which reads data embedded in the application. Meant to be used with the quadrados embed tool.

Can be used to create single-file applications, where all the data is embedded in the executable.

This archive accesses a global map of data, where embedded data can be registered with a given name. Then, to access that data, an instance of this archive is created pointing to that name.

The embed tool generates source files which define and register that data. By linking those files into your application, you're making the data available to be accessed through an instance of this archive.

Base classes

class Archive
Interface for a bridge between the Cubos virtual file system and the real world.

Public types

struct Data
Describes the structure of the embedded data.

Public static functions

static void registerData(const std::string& name, const Data& data)
Registers embedded archive data, which must remain valid for the lifetime of the application.

Constructors, destructors, conversion operators

EmbeddedArchive(const std::string& name)
Constructs pointing to the data with the given name.

Public functions

auto create(std::size_t parent, std::string_view name, bool directory = false) -> std::size_t override
Creates a new file in the archive.
auto destroy(std::size_t id) -> bool override
Destroys a regular file or empty directory in the archive.
auto name(std::size_t id) const -> std::string override
Gets the name of the file with the given id.
auto directory(std::size_t id) const -> bool override
Checks whether the file with the given id is a directory.
auto readOnly() const -> bool override
Checks whether the archive is read-only.
auto parent(std::size_t id) const -> std::size_t override
Gets the identifier of the parent file of the file with the given id.
auto sibling(std::size_t id) const -> std::size_t override
Gets the identifier of the sibling of the file with the given id.
auto child(std::size_t id) const -> std::size_t override
Gets the identifier of the first child of the file with the given id.
auto open(std::size_t id, File::Handle handle, File::OpenMode mode) -> std::unique_ptr<memory::Stream> override
Opens a file in the archive.

Function documentation

static void cubos::core::data::EmbeddedArchive::registerData(const std::string& name, const Data& data)

Registers embedded archive data, which must remain valid for the lifetime of the application.

Parameters
name Name of the embedded archive data.
data Embedded archive data.

This function is called by the code generated by the embed tool.

cubos::core::data::EmbeddedArchive::EmbeddedArchive(const std::string& name)

Constructs pointing to the data with the given name.

Parameters
name Name of the data the embedded archive is going to access.

Aborts if no data with the given name was registered.

std::size_t cubos::core::data::EmbeddedArchive::create(std::size_t parent, std::string_view name, bool directory = false) override

Creates a new file in the archive.

Parameters
parent Parent directory of the new file.
name Name of the new file.
directory Whether the new file is a directory or not.
Returns Identifier of the file, or 0 if the file could not be created.

The first child of the parent will have its sibling set to the new file and then be replaced by the new file.

bool cubos::core::data::EmbeddedArchive::destroy(std::size_t id) override

Destroys a regular file or empty directory in the archive.

Parameters
id Identifier of the file.
Returns Whether the file was destroyed successfully.

Will be replaced in the tree by its sibling.

std::string cubos::core::data::EmbeddedArchive::name(std::size_t id) const override

Gets the name of the file with the given id.

Parameters
id Identifier of the file.
Returns Name of the file.

bool cubos::core::data::EmbeddedArchive::directory(std::size_t id) const override

Checks whether the file with the given id is a directory.

Parameters
id Identifier of the file.
Returns Whether the file is a directory or not.

bool cubos::core::data::EmbeddedArchive::readOnly() const override

Checks whether the archive is read-only.

Returns Whether the archive is read-only.

std::size_t cubos::core::data::EmbeddedArchive::parent(std::size_t id) const override

Gets the identifier of the parent file of the file with the given id.

Parameters
id Identifier of the file.
Returns Identifier of the parent file, or 0 if the file is the root file.

std::size_t cubos::core::data::EmbeddedArchive::sibling(std::size_t id) const override

Gets the identifier of the sibling of the file with the given id.

Parameters
id Identifier of the file.
Returns Identifier of the sibling, or 0 if there are no more files in the parent.

std::size_t cubos::core::data::EmbeddedArchive::child(std::size_t id) const override

Gets the identifier of the first child of the file with the given id.

Parameters
id Identifier of the file.
Returns Identifier of the first child, or 0 if the file is not a directory or is empty.

std::unique_ptr<memory::Stream> cubos::core::data::EmbeddedArchive::open(std::size_t id, File::Handle handle, File::OpenMode mode) override

Opens a file in the archive.

Parameters
id Identifier of the file.
handle Handle to the file.
mode Mode to open the file in.
Returns File stream, or nullptr if the file could not be opened.

Although a bit hacky, the handle parameter is used to keep a reference to the respective File alive, preventing the file from being destroyed while the stream is open.