psl::meta::library class

container class for meta::file's

a meta::library is a collection of meta::file instances. The library will do the basic bookkeeping, allowing you to search and retrieve meta::file instances based on their psl::UID, or tags and narrow it down depending on the meta::file type as well.

There are also facilities to have psl::UID's reference other psl::UID's, and do bi-directional lookups for these relations. As well as the ability to load the persistent companion file that the meta::file describes (in case the psl::UID satisfies is_physical_file() ), and to have that companion file cached for faster reloads.

constructors, destructors, conversion operators

library
location on disk where the library can be found.
public

member-functions

create<…>
creates a new entry with a unique psl::UID and a given type that is either, or derived of meta::file.
public
create<…>
creates a new entry with the given psl::UID and a given type that is either, or derived of meta::file.
public
serialize
serializes the given psl::UID to disk in case it is present, and an on-disk file.
public
remove
tries to remove the given psl::UID from the library.
public
contains
searches the meta::library if it has an entry that corresponds to the given psl::UID.
const public
find
searches for the first psl::UID that is associated with the given tag.
const public
find_all
advanced version of find() that finds all instances of the given tag.
const public
tags
get all tags (if any) associated with the given psl::UID.
const public
has_tag
checks if the given psl::UID has the specific tag associated to it.
const public
set
associates the tag with this specific psl::UID.
public
set
advanced version of set() that allows a list of tags.
public
referencing
gets a list of all psl::UID's the given psl::UID might be referencing.
const public
referencedBy
gets a list of all psl::UID's the given psl::UID might be referenced by.
const public
load
loads the specific psl::UID's content.
public
unload
purges the specific psl::UID's cachec content.
public
get<…>
get the psl::UID's associated meta::file from the meta::library and tries to cast to the templated type.
const public
is_physical_file
checks if the given psl::UID is associated with a physical/persistent file, or dynamically created during the runtime.
const public
get_physical_location
gets the relative location (to the meta::library's location) of the given psl::UID.
const public
size
returns the count of psl::UID's present in the meta::library.
const public

Function documentation

psl::meta::library::library(psl::string8::view lib, std::vector<psl::string8_t> environment = {})

Brief

location on disk where the library can be found.

Details

The constructor will try to load the given filepath, and then parse it. It will also create the minimal representation of each meta::file entry in the given file, with its tags, etc..

Parameters
lib in The filepath to which file should be loaded. This path can either be absolute or relative.
environment

template<typename MF = file>
std::pair<const psl::UID&, MF&> psl::meta::library::create(const psl::UID& uid)

Brief

creates a new entry with the given psl::UID and a given type that is either, or derived of meta::file.

Details

Parameters
uid in The psl::UID that should be associated with this entry.

bool psl::meta::library::serialize(const psl::UID& uid)

Brief

serializes the given psl::UID to disk in case it is present, and an on-disk file.

Details

When you send a psl::UID to this method, the meta::library will verify that it has an entry with the given psl::UID, and that it is linked to an on-disk location. When it satisfies those two requirements, it will then proceed to serialize the file to disk using the current values that are present.

Parameters
uid in The psl::UID you wish to serialize.
Returns true when the psl::UID is both present in the library, and it is linked to an on-disk file.

bool psl::meta::library::remove(const psl::UID& uid, bool safe_mode = true)

Brief

tries to remove the given psl::UID from the library.

Details

Will try to remove the given psl::UID from the meta::library. On success it will notify all other meta::file's that it references, that they no longer are being referenced by this instance.

safe_mode controls wether you should avoid deleting this instance if others are still referencing this psl::UID (true), or forcibly delete this instance regardless (false).

Parameters
uid in The psl::UID you wish to remove.
safe_mode in when true (default), will disallow removing as long as this item is being referenced by others.
Returns true if the instance was removed or not.

bool psl::meta::library::contains(const psl::UID& uid) const

Brief

searches the meta::library if it has an entry that corresponds to the given psl::UID.

Parameters
uid in The psl::UID to search for.
Returns true if found.

std::optional<psl::UID> psl::meta::library::find(psl::string8::view tag) const

Brief

searches for the first psl::UID that is associated with the given tag.

Parameters
tag in The tag to look for, it is case-sensetive.
Returns optionally the first found psl::UID.

std::unordered_set<psl::UID> psl::meta::library::find_all(psl::string8::view tag) const

Brief

advanced version of find() that finds all instances of the given tag.

Parameters
tag in The tag to look for, it is case-sensetive.
Returns an unordered_set of all psl::UID's that have this tag.

const std::vector<psl::string8_t>& psl::meta::library::tags(const psl::UID& uid) const

Brief

get all tags (if any) associated with the given psl::UID.

Details

Parameters
uid in the psl::UID to get all tags for.
Returns a list of all found tags.

bool psl::meta::library::has_tag(const psl::UID& uid, psl::string8::view tag) const

Brief

checks if the given psl::UID has the specific tag associated to it.

Details

Parameters
uid in the psl::UID to check.
tag in the associated tag.
Returns true if the tag is present on the psl::UID.

bool psl::meta::library::set(const psl::UID& uid, psl::string8::view tag)

Brief

associates the tag with this specific psl::UID.

Details

Parameters
uid in the psl::UID to associate with the tag.
tag in the tag to apply to the psl::UID.
Returns if this was successful or not. It could return false in case the psl::UID is not part of the meta::library.

bool psl::meta::library::set(const psl::UID& uid, std::vector<psl::string8::view> tags)

Brief

advanced version of set() that allows a list of tags.

Details

Parameters
uid in the psl::UID to associate with the tags.
tags in the tags to apply to the psl::UID.
Returns if this was successful or not. It could return false in case the psl::UID is not part of the meta::library.

std::unordered_set<psl::UID> psl::meta::library::referencing(const psl::UID& uid) const

Brief

gets a list of all psl::UID's the given psl::UID might be referencing.

Details

as an example, a core::ivk::material_t could be referencing a core::ivk::texture_t, this means that if you call this method using the core::ivk::material_t's psl::UID, then you will get a list back that atleast contains the core::ivk::texture_t psl::UID.

Parameters
uid in the psl::UID to find all references for.
Returns a list of all psl::UID's the given psl::UID is referencing.

std::unordered_set<psl::UID> psl::meta::library::referencedBy(const psl::UID& uid) const

Brief

gets a list of all psl::UID's the given psl::UID might be referenced by.

Details

as an example, a core::ivk::texture_t could be referenced by a core::ivk::material_t, this means that if you call this method using the core::ivk::texture_t's psl::UID, then you will get a list back that atleast contains the core::ivk::material_t psl::UID.

Parameters
uid in the psl::UID for which to find all psl::UID's that might be referencing this psl::UID.
Returns a list of all psl::UID's the given psl::UID is being referenced by.

std::optional<psl::string8::view> psl::meta::library::load(const psl::UID& uid)

Brief

loads the specific psl::UID's content.

Details

Loads the specified psl::UID's associated file, not meta::file, and returns it (if found). The associated file is the companion file for which the meta::file was generated, for example a shader will have a core::meta::shader file on disk, but also the actual shader file (SPIR-V for Vulkan). This returns the SPIR-V file. The file content will get cached into the meta::library to make subsequent load() calls faster.

Parameters
uid in the given psl::UID to optionally find the content for.
Returns the resulting content in UTF-8 format if found.

bool psl::meta::library::unload(const psl::UID& uid)

Brief

purges the specific psl::UID's cachec content.

Details

Unloads the specified psl::UID's associated file, not meta::file, and returns true if it was in the cache and purged. The associated file is the companion file for which the meta::file was generated, for example a shader will have a core::meta::shader file on disk, but also the actual shader file (SPIR-V for Vulkan). This returns the SPIR-V file. You can reload the file into the cache by calling load() with the given psl::UID as parameter.

Parameters
uid in the given psl::UID to purge from the cache.
Returns true if it was found on the meta::library, and had cached contents.

template<typename T = file>
std::optional<T*> psl::meta::library::get(const psl::UID& uid) const

Brief

get the psl::UID's associated meta::file from the meta::library and tries to cast to the templated type.

Details

Searches the meta::library for the given psl::UID, and then tries to satisfy the templated type given. If successful it will return the given template type (default meta::file), otherwise it returns an std::nullopt in case the conversion is not possible at runtime, and will give a compile error when the template type does not satisfy the type constraint.

Template parameters
T should satisfy at least being either meta::file or being derived from meta::file
Parameters
uid in the given psl::UID to find.
Returns the meta::file, or derived class associated with the psl::UID.

bool psl::meta::library::is_physical_file(const psl::UID& uid) const

Brief

checks if the given psl::UID is associated with a physical/persistent file, or dynamically created during the runtime.

Details

Parameters
uid in the psl::UID to check.
Returns true in case it has a persistent backing (that will survive a reboot).

std::optional<psl::string8_t> psl::meta::library::get_physical_location(const psl::UID& uid) const

Brief

gets the relative location (to the meta::library's location) of the given psl::UID.

Details

Parameters
uid in the psl::UID to check.
Returns the relative location to the meta::library if found.

size_t psl::meta::library::size() const

Brief

returns the count of psl::UID's present in the meta::library.

Returns the amount of unique psl::UID's in the current meta::library.