C++ API Reference

String Encoding

• All output strings are encoded in UTF-8.

• Input strings are expected to be encoded in UTF-8.

Errors

All errors encountered are thrown as exceptions that inherit from std::exception.

Constants

constexpr unsigned int loot::LIBLOOT_VERSION_MAJOR = 0

libloot’s major version number.

constexpr unsigned int loot::LIBLOOT_VERSION_MINOR = 29

libloot’s minor version number.

constexpr unsigned int loot::LIBLOOT_VERSION_PATCH = 5

libloot’s patch version number.

Enumerations

enum class loot::EdgeType : unsigned int

An enum representing the different possible types of interactions between plugins or groups.

Values:

enumerator hardcoded

enumerator masterFlag

enumerator master

enumerator masterlistRequirement

enumerator userRequirement

enumerator masterlistLoadAfter

enumerator userLoadAfter

enumerator masterlistGroup

enumerator userGroup

enumerator recordOverlap

enumerator assetOverlap

enumerator tieBreak

enumerator blueprintMaster

enum class loot::GameType : unsigned int

Codes used to create database handles for specific games.

Values:

enumerator tes4

The Elder Scrolls IV: Oblivion

enumerator tes5

The Elder Scrolls V: Skyrim

enumerator fo3

Fallout 3

enumerator fonv

Fallout: New Vegas

enumerator fo4

Fallout 4

enumerator tes5se

The Elder Scrolls V: Skyrim Special Edition

enumerator fo4vr

Fallout 4 VR

enumerator tes5vr

Skyrim VR

enumerator tes3

The Elder Scrolls III: Morrowind

enumerator starfield

Starfield

enumerator openmw

OpenMW

enumerator oblivionRemastered

The Elder Scrolls IV: Oblivion Remastered

enum class loot::LogLevel : unsigned int

Codes used to specify different levels of API logging.

Values:

enumerator trace

enumerator debug

enumerator info

enumerator warning

enumerator error

enum class loot::MessageType : unsigned int

Codes used to indicate the type of a message.

Values:

enumerator say

A notification message that is of no significant severity.

enumerator warn

A warning message, used to indicate that an issue may be present that the user may wish to act on.

enumerator error

An error message, used to indicate that an issue that requires user action is present.

Functions

void loot::SetLoggingCallback(std::function<void(LogLevel, std::string_view)> callback)

Set the callback function that is called when logging.

Parameters:

callback – The function called when logging. The first parameter is the level of the message being logged, and the second is the message.

void loot::SetLogLevel(LogLevel level)

Set the log severity level.

The default level setting is trace. This function has no effect if no logging callback has been set.

Parameters:

level – Messages of this severity level and higher will be logged.

bool loot::IsCompatible(const unsigned int major, const unsigned int minor, const unsigned int patch)

Checks for API compatibility.

Checks whether the loaded API is compatible with the given version of the API, abstracting API stability policy away from clients. The version numbering used is major.minor.patch.

Parameters:

• major – The major version number to check.

• minor – The minor version number to check.

• patch – The patch version number to check.

Returns:

True if the API versions are compatible, false otherwise.

std::unique_ptr<GameInterface> loot::CreateGameHandle(const GameType game, const std::filesystem::path &game_path, const std::filesystem::path &game_local_path = "")

Initialise a new game handle.

Creates a handle for a game, which is then used by all game-specific functions.

Parameters:

• game – A game code for which to create the handle.

• game_path – The relative or absolute path to the directory containing the game’s executable.

• game_local_path – The relative or absolute path to the game’s local data folder, or an empty path. The local data folder is usually in %LOCALAPPDATA%, but Morrowind has no local data folder and OpenMW’s is in the user’s My Games folder on Windows and in $HOME/.config on Linux. If an empty path is provided, the API will attempt to look up the relevant local data path, which may fail in some situations (e.g. when running libloot natively on Linux for a game other than Morrowind or OpenMW).

Returns:

The new game handle.

std::string loot::GetLiblootVersion()

Get the library version.

Returns:

A string of the form “major.minor.patch”.

std::string loot::GetLiblootRevision()

Get the source control revision that libloot was built from.

Returns:

A string containing the revision ID.

std::optional<MessageContent> loot::SelectMessageContent(const std::vector<MessageContent> content, std::string_view language)

Choose a MessageContent object from a vector given a language.

Parameters:

• content – The MessageContent objects to choose between.

• language – The preferred language to select. Values are expected to have the form [language code] or [language code]_[country code], where [language code] is an ISO 639-1 language code and [country code] is an ISO 3166 country code.

Returns:

A MessageContent object.

• If the vector only contains a single element, that element is returned.

• If content with a language that exactly matches the given language is present, that content is returned.

• If the given language includes a country code and there is no exact match but content for the same language code is present, that content is returned.

• If the given language does not include a country code and there is no exact match but content for thet same language code is present, that content is returned.

• If no matches are found and content in the default language is present, that content is returned.

• Otherwise, an empty optional is returned.

Interfaces

class DatabaseInterface

The interface provided by API’s database handle.

Data Reading & Writing

virtual void LoadMasterlist(const std::filesystem::path &masterlistPath) = 0

Loads the masterlist from the path specified.

Can be called multiple times, each time replacing the previously-loaded data.

Parameters:

masterlistPath – The relative or absolute path to the masterlist file that should be loaded.

virtual void LoadMasterlistWithPrelude(const std::filesystem::path &masterlistPath, const std::filesystem::path &masterlistPreludePath) = 0

Loads the masterlist and masterlist prelude from the paths specified.

Can be called multiple times, each time replacing the previously-loaded data.

Parameters:

• masterlistPath – The relative or absolute path to the masterlist file that should be loaded.

• masterlistPreludePath – The relative or absolute path to the masterlist prelude file that should be loaded.

virtual void LoadUserlist(const std::filesystem::path &userlistPath) = 0

Loads the userlist from the path specified.

Can be called multiple times, each time replacing the previously-loaded data.

Parameters:

userlistPath – The relative or absolute path to the userlist file that should be loaded.

virtual void WriteUserMetadata(const std::filesystem::path &outputFile, const MetadataWriteOptions &options) const = 0

Writes a metadata file containing all loaded user-added metadata.

Parameters:

• outputFile – The path to which the file shall be written.

• options – The configuration options to use when writing the file.

virtual void WriteMinimalList(const std::filesystem::path &outputFile, const MetadataWriteOptions &options) const = 0

Writes a minimal metadata file that only contains plugins with Bash Tag suggestions and/or dirty info, plus the suggestions and info themselves.

Parameters:

• outputFile – The path to which the file shall be written.

• options – The configuration options to use when writing the file.

virtual bool Evaluate(const std::string &condition) const = 0

Evaluate the given condition string.

Parameters:

condition – A condition string.

virtual void ClearConditionCache() = 0

Clears the cache of metadata condition evaluation results.

As many conditions involve reading files and/or directories, libloot caches the results of condition evaluation and reuses those cached results in subsequent evaluations.

Clearing the condition cache means that the next time a condition is evaluated, it will be evaluated from scratch instead of using a cached result.

Non-plugin Data Access

virtual std::vector<std::string> GetKnownBashTags(bool includeUserMetadata = true) const = 0

Gets the Bash Tags that are listed in the loaded metadata lists.

Bash Tag suggestions can include Bash Tags not in this list.

Parameters:

includeUserMetadata – If true, any Bash Tag metadata present in the userlist is included in the returned metadata, otherwise the metadata returned only includes metadata from the masterlist.

Returns:

The Bash Tag names, which may include duplicates.

virtual std::vector<std::string> GetUserKnownBashTags() const = 0

Gets the Bash Tags that are listed in the loaded userlist.

Bash Tag suggestions can include Bash Tags not in this list.

Returns:

The Bash Tag names, which may include duplicates.

virtual void SetUserKnownBashTags(const std::vector<std::string> &bashTags) = 0

Sets the known Bash Tags to store in the userlist, overwriting any existing definitions there.

Parameters:

bashTags – The Bash Tag names to set.

virtual std::vector<Message> GetGeneralMessages(bool includeUserMetadata = true, bool evaluateConditions = false) const = 0

Get all general messages listed in the loaded metadata lists.

Parameters:

• includeUserMetadata – If true, any general messages present in the userlist are included in the returned metadata, otherwise the metadata returned only includes metadata from the masterlist.

• evaluateConditions – If true, any metadata conditions are evaluated before the metadata is returned, otherwise unevaluated metadata is returned. Evaluating general message conditions also clears the condition cache before evaluating conditions.

Returns:

The messages supplied in the metadata lists that are not attached to any particular plugin.

virtual std::vector<Message> GetUserGeneralMessages(bool evaluateConditions = false) const = 0

Get all general messages listed in the loaded userlist.

Parameters:

evaluateConditions – If true, any metadata conditions are evaluated before the metadata is returned, otherwise unevaluated metadata is returned. Evaluating general message conditions also clears the condition cache before evaluating conditions.

Returns:

A vector of messages supplied in the userlist but not attached to any particular plugin.

virtual void SetUserGeneralMessages(const std::vector<Message> &messages) = 0

Sets the general messages to store in the userlist, replacing any messages already stored there.

Parameters:

messages – The messages to set.

virtual std::vector<Group> GetGroups(bool includeUserMetadata = true) const = 0

Gets the groups that are defined in the loaded metadata lists.

Parameters:

includeUserMetadata – If true, any group metadata present in the userlist is included in the returned metadata, otherwise the metadata returned only includes metadata from the masterlist.

Returns:

The Group objects. Each Group’s name is unique, if a group has masterlist and user metadata the two are merged into a single group object.

virtual std::vector<Group> GetUserGroups() const = 0

Gets the groups that are defined or extended in the loaded userlist.

Returns:

The Group objects.

virtual void SetUserGroups(const std::vector<Group> &groups) = 0

Sets the group definitions to store in the userlist, overwriting any existing definitions there.

Parameters:

groups – The Group objects to set.

virtual std::vector<Vertex> GetGroupsPath(std::string_view fromGroupName, std::string_view toGroupName) const = 0

Get the “shortest” path between the two given groups according to their load after metadata.

The “shortest” path is defined as the path that maximises the amount of user metadata involved while minimising the amount of masterlist metadata involved. It’s not the path involving the fewest groups.

Parameters:

• fromGroupName – The name of the source group, that loads earlier.

• toGroupName – The name of the destination group, that loads later.

Returns:

A vector of Vertex elements representing the path from the source group to the destination group, or an empty vector if no path exists.

Plugin Data Access

virtual std::optional<PluginMetadata> GetPluginMetadata(std::string_view plugin, bool includeUserMetadata = true, bool evaluateConditions = false) const = 0

Get all a plugin’s loaded metadata.

Parameters:

• plugin – The filename of the plugin to look up metadata for.

• includeUserMetadata – If true, any user metadata the plugin has is included in the returned metadata, otherwise the metadata returned only includes metadata from the masterlist.

• evaluateConditions – If true, any metadata conditions are evaluated before the metadata is returned, otherwise unevaluated metadata is returned. Evaluating plugin metadata conditions does not clear the condition cache.

Returns:

If the plugin has metadata, an optional containing that metadata, otherwise an optional containing no value.

virtual std::optional<PluginMetadata> GetPluginUserMetadata(std::string_view plugin, bool evaluateConditions = false) const = 0

Get a plugin’s metadata loaded from the given userlist.

Parameters:

• plugin – The filename of the plugin to look up user-added metadata for.

• evaluateConditions – If true, any metadata conditions are evaluated before the metadata is returned, otherwise unevaluated metadata is returned. Evaluating plugin metadata conditions does not clear the condition cache.

Returns:

If the plugin has user-added metadata, an optional containing that metadata, otherwise an optional containing no value.

virtual void SetPluginUserMetadata(const PluginMetadata &pluginMetadata) = 0

Sets a plugin’s user metadata.

If the plugin metadata’s name is not a regex name, any existing user metadata for that plugin name will be replaced.

If the plugin metadata has a regex name, the given metadata object will be appended to the list of regex metadata entries, and any existing entries with the same regex name will be retained.

Parameters:

pluginMetadata – The user metadata you want to set, with plugin.GetName() being the filename of the plugin the metadata is for, or a regex that matches the relevant filenames.

virtual void DiscardPluginUserMetadata(std::string_view plugin) = 0

Discards all loaded user metadata for the plugin with the given filename.

Does not discard any plugin metadata with plugin name regexes that match the given filename.

Has no effect if the given plugin name contains any of the characters :\*?|.

Parameters:

plugin – The filename of the plugin for which all user-added metadata should be deleted.

virtual void DiscardAllUserMetadata() = 0

Discards all loaded user metadata for all plugins, and any user-added general messages and known bash tags.

class GameInterface

The interface provided for accessing game-specific functionality.

Metadata Access

virtual DatabaseInterface &GetDatabase() = 0

Get the database interface used for accessing metadata-related functionality.

Returns:

A reference to the game’s DatabaseInterface. The reference remains valid for the lifetime of the GameInterface instance.

virtual const DatabaseInterface &GetDatabase() const = 0

Get the database interface used for accessing metadata-related functionality.

Returns:

A reference to the game’s DatabaseInterface. The reference remains valid for the lifetime of the GameInterface instance.

Plugin Data Access

virtual bool IsValidPlugin(const std::filesystem::path &pluginPath) const = 0

Check if a file is a valid plugin.

The validity check is not exhaustive: it generally checks that the file is a valid plugin file extension for the game and that its header (if applicable) can be parsed.

Parameters:

pluginPath – The path to the file to check. Relative paths are resolved relative to the game’s plugins directory, while absolute paths are used as given.

Returns:

True if the file is a valid plugin, false otherwise.

virtual void LoadPlugins(const std::vector<std::filesystem::path> &pluginPaths, bool loadHeadersOnly) = 0

Parses plugins and loads their data.

If a given plugin filename (or one that is case-insensitively equal) has already been loaded, its previously-loaded data data is discarded. Any existing PluginInterface objects are unaffected.

If the game is Morrowind, OpenMW or Starfield, it’s only valid to fully load a plugin if its masters are already loaded or included in the same input vector.

Parameters:

• pluginPaths – The plugin paths to load. Relative paths are resolved relative to the game’s plugins directory, while absolute paths are used as given. Each plugin filename must be unique within the vector.

• loadHeadersOnly – If true, only the plugins’ headers are loaded. If false, all records in the plugins are parsed.

virtual void ClearLoadedPlugins() = 0

Clears the plugins loaded by previous calls to LoadPlugins().

This does not affect any existing PluginInterface objects.

virtual std::unique_ptr<const PluginInterface> GetPlugin(std::string_view pluginName) const = 0

Get data for a loaded plugin.

Parameters:

pluginName – The filename of the plugin to get data for.

Returns:

A pointer to a const PluginInterface implementation. The pointer is null if the given plugin has not been loaded.

virtual std::vector<std::unique_ptr<const PluginInterface>> GetLoadedPlugins() const = 0

Get a set of const references to all loaded plugins’ PluginInterface objects.

Returns:

A set of pointers to const PluginInterface objects.

Sorting

virtual std::vector<std::string> SortPlugins(const std::vector<std::string> &pluginFilenames) = 0

Calculates a new load order for the game’s installed plugins (including inactive plugins) and outputs the sorted order.

Pulls metadata from the masterlist and userlist if they are loaded, and reads the contents of each plugin. No changes are applied to the load order used by the game. This function does not load or evaluate the masterlist or userlist.

Parameters:

pluginFilenames – The plugins to sort, in their current load order. All given plugins must have been loaded using LoadPlugins().

Returns:

A vector of the given plugin filenames in their sorted load order.

Load Order Interaction

virtual void LoadCurrentLoadOrderState() = 0

Load the current load order state, discarding any previously held state.

This function should be called whenever the load order or active state of plugins “on disk” changes, so that the cached state is updated to reflect the changes.

virtual bool IsLoadOrderAmbiguous() const = 0

Check if the load order is ambiguous.

This checks that all plugins in the current load order state have a well-defined position in the “on disk” state, and that all data sources are consistent. If the load order is ambiguous, different applications may read different load orders from the same source data.

Returns:

True if the load order is ambiguous, false otherwise.

virtual std::filesystem::path GetActivePluginsFilePath() const = 0

Gets the path to the file that holds the list of active plugins.

The active plugins file path is often within the game’s local path, but its name and location varies by game and game configuration, so this function exposes the path that libloot uses.

Returns:

The file path.

virtual bool IsPluginActive(const std::string &plugin) const = 0

Check if a plugin is active.

Parameters:

plugin – The filename of the plugin for which to check the active state.

Returns:

True if the plugin is active, false otherwise.

virtual std::vector<std::string> GetLoadOrder() const = 0

Get the current load order.

Returns:

A vector of plugin filenames in their load order.

virtual void SetLoadOrder(const std::vector<std::string> &loadOrder) = 0

Set the game’s load order.

There is no way to persist the load order of inactive OpenMW plugins, so setting an OpenMW load order will have no effect if the relative order of active plugins is unchanged.

Parameters:

loadOrder – A vector of plugin filenames sorted in the load order to set.

Public Functions

virtual GameType GetType() const = 0

Get the game’s type.

Returns:

The game’s type.

virtual std::vector<std::filesystem::path> GetAdditionalDataPaths() const = 0

Gets the currently-set additional data paths.

The following games are configured with additional data paths by default:

• Fallout 4, when installed from the Microsoft Store

• Starfield

• OpenMW

virtual void SetAdditionalDataPaths(const std::vector<std::filesystem::path> &additionalDataPaths) = 0

Set additional data paths.

The additional data paths are used when interacting with the load order, evaluating conditions and scanning for archives (BSA/BA2 depending on the game). Additional data paths are used in the order they are given (except with OpenMW, which checks them in reverse order), and take precedence over the game’s main data path.

class PluginInterface

Represents a plugin file that has been parsed by LOOT.

Public Functions

virtual std::string GetName() const = 0

Get the plugin’s filename.

Returns:

The plugin filename. If the plugin was ghosted when it was loaded, this filename will be without the .ghost suffix, unless the game is OpenMW, in which case ghosted plugins are not supported.

virtual std::optional<float> GetHeaderVersion() const = 0

Get the value of the version field in the HEDR subrecord of the plugin’s TES4 record.

Returns:

The value of the version field, or an empty optional if that value is NaN or could not be found.

virtual std::optional<std::string> GetVersion() const = 0

Get the plugin’s version number from its description field.

The description field may not contain a version number, or LOOT may be unable to detect it. The description field parsing may fail to extract the version number correctly, though it functions correctly in all known cases.

Returns:

An optional containing a version string if one is found, otherwise an optional containing no value.

virtual std::vector<std::string> GetMasters() const = 0

Get the plugin’s masters.

Returns:

The plugin’s masters in the same order they are listed in the file.

virtual std::vector<std::string> GetBashTags() const = 0

Get any Bash Tags found in the plugin’s description field.

Returns:

A set of Bash Tags. The order of elements in the set holds no semantics.

virtual std::optional<uint32_t> GetCRC() const = 0

Get the plugin’s CRC-32 checksum.

Returns:

An optional containing the plugin’s CRC-32 checksum if the plugin has been fully loaded, otherwise an optional containing no value.

virtual bool IsMaster() const = 0

Check if the plugin is a master plugin.

What causes a plugin to be a master plugin varies by game, but is usually indicated by the plugin having its master flag set and/or by its file extension. However, OpenMW uses neither for determining plugins’ load order so all OpenMW plugins are treated as non-masters.

The term “master” is potentially confusing: a plugin A may not be a master plugin, but may still be a master of another plugin by being listed as such in that plugin’s header record. Master plugins are sometimes referred to as master files or simply masters, while the other meaning is always referenced in relation to another plugin.

Returns:

True if the plugin is a master plugin, false otherwise.

virtual bool IsLightPlugin() const = 0

Check if the plugin is a light plugin.

Returns:

True if plugin is a light plugin, false otherwise.

virtual bool IsMediumPlugin() const = 0

Check if the plugin is a medium plugin.

Returns:

True if plugin is a medium plugin, false otherwise.

virtual bool IsUpdatePlugin() const = 0

Check if the plugin is an update plugin.

Returns:

True if plugin is an update plugin, false otherwise.

virtual bool IsBlueprintPlugin() const = 0

Check if the plugin is a blueprint plugin.

Returns:

True if plugin is a blueprint plugin, false otherwise.

virtual bool IsValidAsLightPlugin() const = 0

Check if the plugin is or would be valid as a light plugin.

Returns:

True if the plugin is a valid light plugin or would be a valid light plugin, false otherwise.

virtual bool IsValidAsMediumPlugin() const = 0

Check if the plugin is or would be valid as a medium plugin.

Returns:

True if the plugin is a valid medium plugin or would be a valid medium plugin, false otherwise.

virtual bool IsValidAsUpdatePlugin() const = 0

Check if the plugin is or would be valid as an update plugin.

Returns:

True if the plugin is a valid update plugin or would be a valid update plugin, false otherwise.

virtual bool IsEmpty() const = 0

Check if the plugin contains any records other than its TES4 header.

Returns:

True if the plugin only contains a TES4 header, false otherwise.

virtual bool LoadsArchive() const = 0

Check if the plugin loads an archive (BSA/BA2 depending on the game).

Returns:

True if the plugin loads an archive, false otherwise.

virtual bool DoRecordsOverlap(const PluginInterface &plugin) const = 0

Check if two plugins contain a record with the same ID.

Parameters:

plugin – The other plugin to check for overlap with.

Returns:

True if the plugins both contain at least one record with the same ID, false otherwise. FormIDs are compared for all games apart from Morrowind, which doesn’t have FormIDs and so has other identifying data compared.

Classes

class Filename

Represents a case-insensitive filename.

Public Functions

Filename() = default

Construct a Filename using an empty string.

explicit Filename(std::string_view filename)

Construct a Filename using the given string.

explicit operator std::string() const

Get this Filename as a string.

class File

Represents a file in a game’s Data folder, including files in subdirectories.

Public Functions

File() = default

Construct a File with blank name, display and condition strings.

explicit File(std::string_view name, std::string_view display = "", std::string_view condition = "", const std::vector<MessageContent> &detail = {}, std::string_view constraint = "")

Construct a File with the given name, display name and condition strings.

Parameters:

• name – The filename of the file.

• display – The name to be displayed for the file in messages, formatted using CommonMark.

• condition – The File’s condition string.

• detail – The detail message content, which may be appended to any messages generated for this file. If multilingual, one language must be English.

• constraint – A condition string that must evaluate to true for the file’s existence to be recognised.

Filename GetName() const

Get the filename of the file.

Returns:

The file’s filename.

std::string GetDisplayName() const

Get the display name of the file.

Returns:

The file’s display name.

std::vector<MessageContent> GetDetail() const

Get the detail message content of the file.

If this file causes an error message to be displayed, the detail message content should be appended to that message, as it provides more detail about the error (e.g. suggestions for how to resolve it).

std::string GetCondition() const

Get the condition string.

Returns:

The file’s condition string.

std::string GetConstraint() const

Get the constraint that applies to the file.

Returns:

The file’s constraint.

class Group

Represents a group to which plugin metadata objects can belong.

Public Functions

Group() = default

Construct a Group with the name “default” and an empty set of groups to load after.

explicit Group(std::string_view name, const std::vector<std::string> &afterGroups = {}, std::string_view description = "")

Construct a Group with the given name, description and set of groups to load after.

Parameters:

• name – The group name.

• afterGroups – The names of groups this group loads after.

• description – A description of the group.

std::string GetName() const

Get the name of the group.

Returns:

The group’s name.

std::string GetDescription() const

Get the description of the group.

Returns:

The group’s description.

std::vector<std::string> GetAfterGroups() const

Get the set of groups this group loads after.

Returns:

A set of group names.

Public Static Attributes

static constexpr std::string_view DEFAULT_NAME = "default"

The name of the group to which all plugins belong by default.

class Location

Represents a URL at which the parent plugin can be found.

Public Functions

Location() = default

Construct a Location with empty URL and name strings.

explicit Location(std::string_view url, std::string_view name = "")

Construct a Location with the given URL and name.

Parameters:

• url – The URL at which the plugin can be found.

• name – A name for the URL, eg. the page or site name.

std::string GetURL() const

Get the object’s URL.

Returns:

A URL string.

std::string GetName() const

Get the object’s name.

Returns:

The name of the location.

class MessageContent

Represents a message’s localised text content.

Public Functions

MessageContent() = default

Construct a MessageContent object with an empty English message string.

explicit MessageContent(std::string_view text, std::string_view language = DEFAULT_LANGUAGE)

Construct a Message object with the given text in the given language.

Parameters:

• text – The message text.

• language – The language that the message is written in.

std::string GetText() const

Get the message text.

Returns:

A string containing the message text.

std::string GetLanguage() const

Get the message language.

Returns:

A code representing the language that the message is written in.

Public Static Attributes

static constexpr std::string_view DEFAULT_LANGUAGE = "en"

The code for the default language assumed for message content, which is “en” (English).

class Message

Represents a message with localisable text content.

Public Functions

Message() = default

Construct a Message object of type ‘say’ with blank content and condition strings.

explicit Message(const MessageType type, std::string_view content, std::string_view condition = "")

Construct a Message object with the given type, English content and condition string.

Parameters:

• type – The message type.

• content – The English message content text.

• condition – A condition string.

explicit Message(const MessageType type, const std::vector<MessageContent> &content, std::string_view condition = "")

Construct a Message object with the given type, content and condition string.

Parameters:

• type – The message type.

• content – The message content. If multilingual, one language must be English.

• condition – A condition string.

MessageType GetType() const

Get the message type.

Returns:

The message type.

std::vector<MessageContent> GetContent() const

Get the message content.

Returns:

The message’s MessageContent objects.

std::string GetCondition() const

Get the condition string.

Returns:

The message’s condition string.

class PluginCleaningData

Represents data identifying the plugin under which it is stored as dirty or clean.

Public Functions

PluginCleaningData() = default

Construct a PluginCleaningData object with zero CRC, ITM count, deleted reference count and deleted navmesh count values, an empty utility string and no detail.

explicit PluginCleaningData(uint32_t crc, std::string_view utility)

Construct a PluginCleaningData object with the given CRC and utility, zero ITM count, deleted reference count and deleted navmesh count values and no detail.

Parameters:

• crc – The CRC of a plugin.

• utility – The utility that the plugin cleanliness was checked with.

explicit PluginCleaningData(uint32_t crc, std::string_view utility, const std::vector<MessageContent> &detail, unsigned int itm, unsigned int ref, unsigned int nav, std::string_view condition)

Construct a PluginCleaningData object with the given values.

Parameters:

• crc – A clean or dirty plugin’s CRC.

• utility – The utility that the plugin cleanliness was checked with.

• detail – A vector of localised information message strings about the plugin cleanliness.

• itm – The number of Identical To Master records found in the plugin.

• ref – The number of deleted references found in the plugin.

• nav – The number of deleted navmeshes found in the plugin.

• condition – A condition string.

uint32_t GetCRC() const

Get the CRC that identifies the plugin that the cleaning data is for.

Returns:

A CRC-32 checksum.

unsigned int GetITMCount() const

Get the number of Identical To Master records in the plugin.

Returns:

The number of Identical To Master records in the plugin.

unsigned int GetDeletedReferenceCount() const

Get the number of deleted references in the plugin.

Returns:

The number of deleted references in the plugin.

unsigned int GetDeletedNavmeshCount() const

Get the number of deleted navmeshes in the plugin.

Returns:

The number of deleted navmeshes in the plugin.

std::string GetCleaningUtility() const

Get the name of the cleaning utility that was used to check the plugin.

Returns:

A cleaning utility name, possibly related information such as a version number and/or a CommonMark-formatted URL to the utility’s download location.

std::vector<MessageContent> GetDetail() const

Get any additional informative message content supplied with the cleaning data, eg. a link to a cleaning guide or information on wild edits or manual cleaning steps.

Returns:

A vector of localised MessageContent objects.

std::string GetCondition() const

Get the condition string.

Returns:

The cleaning data’s condition string.

class PluginMetadata

Represents a plugin’s metadata.

Public Functions

PluginMetadata() = default

Construct a PluginMetadata object with a blank plugin name and no metadata.

explicit PluginMetadata(std::string_view name)

Construct a PluginMetadata object with no metadata for a plugin with the given filename.

Parameters:

name – The filename of the plugin that the object is constructed for.

void MergeMetadata(const PluginMetadata &plugin)

Merge metadata from the given PluginMetadata object into this object.

If an equal metadata object already exists in this PluginMetadata object, it is not duplicated. This object’s group is replaced by the given object’s group if the latter is explicit.

Parameters:

plugin – The plugin metadata to merge.

std::string GetName() const

Get the plugin name.

Returns:

The plugin name.

std::optional<std::string> GetGroup() const

Get the plugin’s group.

Returns:

An optional containing the name of the group this plugin belongs to if it was explicitly set, otherwise an optional containing no value.

std::vector<File> GetLoadAfterFiles() const

Get the plugins that the plugin must load after.

Returns:

The plugins that the plugin must load after.

std::vector<File> GetRequirements() const

Get the files that the plugin requires to be installed.

Returns:

The files that the plugin requires to be installed.

std::vector<File> GetIncompatibilities() const

Get the files that the plugin is incompatible with.

Returns:

The files that the plugin is incompatible with.

std::vector<Message> GetMessages() const

Get the plugin’s messages.

Returns:

The plugin’s messages.

std::vector<Tag> GetTags() const

Get the plugin’s Bash Tag suggestions.

Returns:

The plugin’s Bash Tag suggestions.

std::vector<PluginCleaningData> GetDirtyInfo() const

Get the plugin’s dirty plugin information.

Returns:

The PluginCleaningData objects that identify the plugin as dirty.

std::vector<PluginCleaningData> GetCleanInfo() const

Get the plugin’s clean plugin information.

Returns:

The PluginCleaningData objects that identify the plugin as clean.

std::vector<Location> GetLocations() const

Get the locations at which this plugin can be found.

Returns:

The locations at which this plugin can be found.

void SetGroup(std::string_view group)

Set the plugin’s group.

Parameters:

group – The name of the group this plugin belongs to.

void UnsetGroup()

Unsets the plugin’s group.

void SetLoadAfterFiles(const std::vector<File> &after)

Set the files that the plugin must load after.

Parameters:

after – The files to set.

void SetRequirements(const std::vector<File> &requirements)

Set the files that the plugin requires to be installed.

Parameters:

requirements – The files to set.

void SetIncompatibilities(const std::vector<File> &incompatibilities)

Set the files that the plugin must load after.

Parameters:

incompatibilities – The files to set.

void SetMessages(const std::vector<Message> &messages)

Set the plugin’s messages.

Parameters:

messages – The messages to set.

void SetTags(const std::vector<Tag> &tags)

Set the plugin’s Bash Tag suggestions.

Parameters:

tags – The Bash Tag suggestions to set.

void SetDirtyInfo(const std::vector<PluginCleaningData> &info)

Set the plugin’s dirty information.

Parameters:

info – The dirty information to set.

void SetCleanInfo(const std::vector<PluginCleaningData> &info)

Set the plugin’s clean information.

Parameters:

info – The clean information to set.

void SetLocations(const std::vector<Location> &locations)

Set the plugin’s locations.

Parameters:

locations – The locations to set.

bool HasNameOnly() const

Check if no plugin metadata is set.

Returns:

True if the group is implicit and the metadata containers are all empty, false otherwise.

bool IsRegexPlugin() const

Check if the plugin name is a regular expression.

Returns:

True if the plugin name contains any of the characters :\*?|, false otherwise.

bool NameMatches(std::string_view pluginName) const

Check if the given plugin name matches this plugin metadata object’s name field.

If the name field is a regular expression, the given plugin name will be matched against it, otherwise the strings will be compared case-insensitively. The given plugin name must be literal, i.e. not a regular expression.

Returns:

True if the given plugin name matches this metadata’s plugin name, false otherwise.

std::string AsYaml() const

Serialises the plugin metadata as YAML.

Returns:

The serialised plugin metadata.

class Tag

Represents a Bash Tag suggestion for a plugin.

Public Functions

explicit Tag() = default

Construct a Tag object with an empty tag name suggested for addition, with an empty condition string.

explicit Tag(std::string_view tag, const bool isAddition = true, std::string_view condition = "")

Construct a Tag object with the given name, for addition or removal, with the given condition string.

Parameters:

• tag – The name of the Bash Tag.

• isAddition – True if the tag should be added, false if it should be removed.

• condition – A condition string.

bool IsAddition() const

Check if the tag should be added.

Returns:

True if the tag should be added, false if it should be removed.

std::string GetName() const

Get the tag’s name.

Returns:

The tag’s name.

std::string GetCondition() const

Get the condition string.

Returns:

The tag’s condition string.

class MetadataWriteOptions

Options to configure how metadata files are written.

Public Functions

MetadataWriteOptions()

Creates a new options object, with all options initially set to false.

MetadataWriteOptions(const MetadataWriteOptions&)

Creates a new options object, copying the options’ values from the given object.

MetadataWriteOptions(MetadataWriteOptions&&) noexcept

Creates a new options object, moving the options’ values from the given object.

MetadataWriteOptions &operator=(const MetadataWriteOptions&)

Assigns the options values of this object by copying them from the given object.

MetadataWriteOptions &operator=(MetadataWriteOptions&&) noexcept

Assigns the options values of this object by moving them from the given object.

void SetTruncate(bool truncate)

Sets the option to overwrite the output file if it already exists.

If true and the file path already exists, its contents will be replaced.

If false and the file path already exists, an error will be returned.

This setting has no effect if the file path does not exist.

Parameters:

truncate – The value to set.

void SetWriteAnchors(bool writeAnchors)

Sets the option to write YAML anchors and aliases.

If true then conditions, constraints, files, file details, plugin cleaning data details, messages and message contents that appear more than once in the metadata will be deduplicated by including a YAML anchor when writing the first occurrence of the value, and writing YAML aliases in place of further occurrences.

If false, YAML anchors and aliases will not be used, so no deduplication will occur.

Parameters:

writeAnchors – The value to set.

void SetWriteCommonSection(bool writeCommonSection)

Sets the option to write YAML anchors in a common section.

If writeAnchors is true and this is also true, the document’s root-level map will start with a common key. Its value will be a list of all the values for which YAML anchors will be written, so that all YAML anchors will appear within that list.

This setting has no effect if writeAnchors is false.

Parameters:

writeCommonSection – The value to set.

void SetAnchorFileStrings(bool anchorFileStrings)

Sets the option to write anchors for File values that only have a name.

If writeAnchors is true and this is also true, then all repeated File metadata values will be deduplicated using YAML anchors and aliases.

If this is false, then only File metadata that is serialised as a YAML object will be deduplicated (i.e. File values that only have a name will not be deduplicated).

This setting has no effect if writeAnchors is false.

Parameters:

anchorFileStrings – The value to set.

bool GetTruncate() const

Gets the current value of the truncate option.

bool GetWriteAnchors() const

Gets the current value of the writeAnchors option.

bool GetWriteCommonSection() const

Gets the current value of the writeCommonSection option.

bool GetAnchorFileStrings() const

Gets the current value of the anchorFileStrings option.

class Vertex

A class representing a plugin or group vertex in a path, and the type of the edge to the next vertex in the path if one exists.

Public Functions

explicit Vertex(std::string_view name)

Construct a Vertex with the given name and no out edge.

Parameters:

name – The name of the plugin or group that this vertex represents.

explicit Vertex(std::string_view name, EdgeType outEdgeType)

Construct a Vertex with the given name and out edge type.

Parameters:

• name – The name of the plugin or group that this vertex represents.

• outEdgeType – The type of the edge going out from this vertex.

std::string GetName() const

Get the name of the plugin or group.

Returns:

The name of the plugin or group.

std::optional<EdgeType> GetTypeOfEdgeToNextVertex() const

Get the type of the edge going to the next vertex.

Each edge goes from the vertex that loads earlier to the vertex that loads later.

Returns:

The edge type.

Exceptions

class CyclicInteractionError : public runtime_error

An exception class thrown if a cyclic interaction is detected when sorting a load order.

Public Functions

CyclicInteractionError(std::vector<Vertex> cycle)

Construct an exception detailing a plugin or group graph cycle.

Parameters:

cycle – A representation of the cyclic path.

std::vector<Vertex> GetCycle() const

Get a representation of the cyclic path.

Each Vertex is the name of a graph element (plugin or group) and the type of the edge going to the next Vertex. The last Vertex has an edge going to the first Vertex.

Returns:

A vector of Vertex elements representing the cyclic path.

class PluginNotLoadedError : public runtime_error

An exception class thrown if a plugin that must be loaded hasn’t been loaded.

class UndefinedGroupError : public runtime_error

An exception class thrown if group is referenced but is undefined.

Public Functions

UndefinedGroupError(std::string_view groupName)

Construct an exception for an undefined group.

Parameters:

groupName – The name of the group that is undefined.

std::string GetGroupName() const

Get the name of the undefined group.

Returns:

A group name.