API Reference

Contents

• API Reference

  • Constants

  • Enumerations

  • Public-Field Data Structures

  • Functions

  • Interfaces

  • Classes

  • Exceptions

  • Error Categories

Constants

constexpr unsigned int loot::LIBLOOT_VERSION_MAJOR = 0

libloot’s major version number.

constexpr unsigned int loot::LIBLOOT_VERSION_MINOR = 18

libloot’s minor version number.

constexpr unsigned int loot::LIBLOOT_VERSION_PATCH = 0

libloot’s patch version number.

Enumerations

enum loot::EdgeType

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 group

enumerator overlap

enumerator tieBreak

enum loot::GameType

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

enum loot::LogLevel

Codes used to specify different levels of API logging.

Values:

enumerator trace

enumerator debug

enumerator info

enumerator warning

enumerator error

enumerator fatal

enum loot::MessageType

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.

Public-Field Data Structures

struct loot::SimpleMessage

A structure that holds the type of a message and the message string itself.

Public Members

MessageType type = {MessageType::say}

The type of the message.

std::string language

The language the message string is written in.

std::string text

The message string, which may be formatted using CommonMark.

std::string condition

The message’s condition string.

Functions

void loot::SetLoggingCallback(std::function<void(LogLevel, const char*)> callback)

Set the callback function that is called when logging.

If this function is not called, the default behaviour is to print messages to the console.

Parameters

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

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 folder in %LOCALAPPDATA% or an empty path. If an empty path, the API will attempt to look up the path that %LOCALAPPDATA% corresponds to. This parameter is provided so that systems lacking that environmental variable (eg. Linux) can still use the API.

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, const std::string &language)

Choose a MessageContent object from a vector given a language.

Parameters

• content – The MessageContent objects to choose between.

• language – The locale or language code for the preferred language to select. Locale codes are of the form [language code]_[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 locale or language code is present, that content is returned.

• If a locale code is given and there is no exact match but content for that locale’s language is present, that content is returned.

• If a language code is given and there is no exact match but content for a locale in that langauge is present, that content is returned.

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

• Otherwise, an empty optional is returned.

std::optional<SimpleMessage> loot::ToSimpleMessage(const Message &message, const std::string &language)

Get a given Message as a SimpleMessage given a language.

Parameters

• message – The message to convert.

• language – The preferred language for the message content.

Returns

A SimpleMessage object for the preferred language, or for English if message text is not available for the given language.

std::vector<SimpleMessage> loot::ToSimpleMessages(const std::vector<Message> &messages, const std::string &language)

Get the given messages as simple messages given a language.

Parameters

• messages – The messages to convert.

• language – The preferred language for the message content.

Returns

A vector of SimpleMessage objects for the preferred language, or for English if message text is not available for the given language. The order of the input Message objects is preserved, though any messages without the preferred language or English content will be omitted.

Interfaces

class loot::DatabaseInterface

The interface provided by API’s database handle.

Data Reading & Writing

virtual void LoadLists(const std::filesystem::path &masterlist_path, const std::filesystem::path &userlist_path = "", const std::filesystem::path &masterlist_prelude_path = "") = 0

Loads the masterlist, userlist and masterlist prelude from the paths specified.

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

Parameters

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

• userlist_path – The relative or absolute path to the userlist file that should be loaded, or an empty path. If an empty path, no userlist will be loaded.

• masterlist_prelude_path – The relative or absolute path to the masterlist prelude file that should be loaded. If an empty path, no masterlist prelude will be loaded.

virtual void WriteUserMetadata(const std::filesystem::path &outputFile, const bool overwrite) const = 0

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

Parameters

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

• overwrite – If false and outputFile already exists, no data will be written. Otherwise, data will be written.

virtual void WriteMinimalList(const std::filesystem::path &outputFile, const bool overwrite) 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.

• overwrite – If false and outputFile already exists, no data will be written. Otherwise, data will be written.

Non-plugin Data Access

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

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

Bash Tag suggestions can include plugins not in this list.

Returns

A set of Bash Tag names.

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

Get all general messages listen in the loaded metadata lists.

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 metadata lists but not attached to any particular plugin.

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

An vector of 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

An unordered set of 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 unordered set of Group objects to set.

virtual std::vector<Vertex> GetGroupsPath(const std::string &fromGroupName, const std::string &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(const std::string &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(const std::string &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, overwriting any existing user metadata.

Parameters

pluginMetadata – The user metadata you want to set, with plugin.Name() being the filename of the plugin the metadata is for.

virtual void DiscardPluginUserMetadata(const std::string &plugin) = 0

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

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 loot::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.

Plugin Data Access

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

Check if a file is a valid plugin.

The validity check is not exhaustive: it checks that the file extension is .esm or .esp (after trimming any .ghost extension), and that the TES4 header can be parsed.

Parameters

plugin – The filename of the file to check.

Returns

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

virtual void LoadPlugins(const std::vector<std::string> &plugins, bool loadHeadersOnly) = 0

Parses plugins and loads their data.

Any previously-loaded plugin data is discarded when this function is called.

Parameters

• plugins – The filenames of the plugins to load.

• loadHeadersOnly – If true, only the plugins’ TES4 headers are loaded. If false, all records in the plugins are parsed, apart from the main master file if it has been identified by a previous call to IdentifyMainMasterFile().

virtual const PluginInterface *GetPlugin(const std::string &pluginName) const = 0

Get data for a loaded plugin.

Parameters

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

Returns

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

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

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

Returns

A set of const PluginInterface references. The references remain valid until the LoadPlugins() or SortPlugins() functions are next called or this GameInterface is destroyed.

Sorting

virtual void IdentifyMainMasterFile(const std::string &masterFile) = 0

Identify the game’s main master file.

When sorting, LOOT always only loads the headers of the game’s main master file as a performance optimisation.

virtual std::vector<std::string> SortPlugins(const std::vector<std::string> &plugins) = 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

plugins – A vector of filenames of the plugins to sort, in their current load order.

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 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.

Parameters

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

class loot::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.

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<Tag> 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’s master flag is set.

Returns

True if the master flag is set, 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 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 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 DoFormIDsOverlap(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 loot::ConditionalMetadata

A base class for metadata that can be conditional based on the result of evaluating a condition string.

Subclassed by File, Message, Tag

Public Functions

ConditionalMetadata() = default

Construct a ConditionalMetadata object with an empty condition string.

Returns

A ConditionalMetadata object.

explicit ConditionalMetadata(const std::string &condition)

Construct a ConditionalMetadata object with a given condition string.

Parameters

condition – A condition string, as defined in the LOOT metadata syntax documentation.

Returns

A ConditionalMetadata object.

bool IsConditional() const

Check if the condition string is non-empty.

Returns

True if the condition string is not empty, false otherwise.

std::string GetCondition() const

Get the condition string.

Returns

The object’s condition string.

class loot::Filename

Represents a case-insensitive filename.

Public Functions

Filename() = default

Construct a Filename using an empty string.

Returns

A Filename object.

explicit Filename(const std::string &filename)

Construct a Filename using the given string.

Returns

A Filename object.

explicit operator std::string() const

Get this Filename as a string.

class loot::File : public ConditionalMetadata

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.

Returns

A File object.

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

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.

Returns

A File object.

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).

class loot::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.

Returns

A Group object.

explicit Group(const std::string &name, const std::vector<std::string> &afterGroups = {}, const std::string &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.

Returns

A Group object.

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 const char *DEFAULT_NAME = "default"

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

class loot::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.

Returns

A Location object.

explicit Location(const std::string &url, const std::string &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.

Returns

A Location object.

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 loot::MessageContent

Represents a message’s localised text content.

Public Functions

MessageContent() = default

Construct a MessageContent object with an empty English message string.

Returns

A MessageContent object.

explicit MessageContent(const std::string &text, const std::string &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.

Returns

A MessageContent object.

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 const char *DEFAULT_LANGUAGE = "en"

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

class loot::Message : public ConditionalMetadata

Represents a message with localisable text content.

Public Functions

Message() = default

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

Returns

A Message object.

explicit Message(const MessageType type, const std::string &content, const std::string &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.

Returns

A Message object.

explicit Message(const MessageType type, const std::vector<MessageContent> &content, const std::string &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.

Returns

A Message object.

explicit Message(const SimpleMessage &message)

Construct a Message object from a SimpleMessage object.

Parameters

message – The SimpleMessage object.

Returns

A Message object.

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.

class loot::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.

Returns

A PluginCleaningData object.

explicit PluginCleaningData(uint32_t crc, const std::string &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.

Returns

A PluginCleaningData object.

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

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.

Returns

A PluginCleaningData object.

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.

class loot::PluginMetadata

Represents a plugin’s metadata.

Public Functions

PluginMetadata() = default

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

Returns

A PluginMetadata object.

explicit PluginMetadata(const std::string &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.

Returns

A PluginMetadata object.

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(const std::string &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(const std::string &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 loot::Tag : public ConditionalMetadata

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.

Returns

A Tag object.

explicit Tag(const std::string &tag, const bool isAddition = true, const std::string &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.

Returns

A Tag object.

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.

class loot::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 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 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 loot::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()

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 ConditionSyntaxError : public runtime_error

An exception class thrown if invalid syntax is encountered when parsing a metadata condition.

class FileAccessError : public runtime_error

An exception class thrown if an error is encountered while reading or writing a file.

class loot::UndefinedGroupError : public runtime_error

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

Public Functions

inline UndefinedGroupError(const std::string &groupName)

Construct an exception for an undefined group.

Parameters

groupName – The name of the group that is undefined.

inline std::string GetGroupName()

Get the name of the undefined group.

Returns

A group name.

Error Categories

LOOT uses error category objects to identify errors with codes that originate in lower-level libraries.

const std::error_category &loot::libloadorder_category()

Get the error category that can be used to identify system_error exceptions that are due to libloadorder errors.

Returns

A reference to the static object of unspecified runtime type, derived from std::error_category.