API Reference

Enumerations

enum loot::EdgeType

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

Values:

hardcoded
masterFlag
master
masterlistRequirement
userRequirement
masterlistLoadAfter
userLoadAfter
group
overlap
tieBreak
enum loot::GameType

Codes used to create database handles for specific games.

Values:

tes4

The Elder Scrolls IV: Oblivion

tes5

The Elder Scrolls V: Skyrim

fo3

Fallout 3

fonv

Fallout: New Vegas

fo4

Fallout 4

tes5se

The Elder Scrolls V: Skyrim Special Edition

fo4vr

Fallout 4 VR

tes5vr

Skyrim VR

enum loot::LogLevel

Codes used to specify different levels of API logging.

Values:

trace
debug
info
warning
error
fatal
enum loot::MessageType

Codes used to indicate the type of a message.

Values:

say

A notification message that is of no significant severity.

warn

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

error

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

Public-Field Data Structures

struct MasterlistInfo

A structure that holds data about a masterlist’s source control revision.

Public Members

std::string revision_id

The revision hash for the masterlist. If the masterlist doesn’t exist, or there is no Git repository at its location, this will be empty.

std::string revision_date

A pointer to a string containing the ISO 8601 formatted revision date, ie. YYYY-MM-DD. If the masterlist doesn’t exist, or there is no Git repository at its location, this will be empty.

bool is_modified

true if the masterlist has been edited since the outputted revision, or false if it is at exactly the revision given.

struct SimpleMessage

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

Public Members

MessageType type

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 GitHub Flavored Markdown.

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.

Return
True if the API versions are compatible, false otherwise.
Parameters
  • major: The major version number to check.
  • minor: The minor version number to check.
  • patch: The patch version number to check.

void loot::InitialiseLocale(const std::string &id = "")

Initialise the current global locale using the given ID.

This sets the global locale up so that the library’s UTF-8 support can function.

Parameters
  • id: A locale ID. The default value is a blank string, which will use the system default locale.

std::shared_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.

Return
The new game handle.
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.

Interfaces

class 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 = "") = 0

Loads the masterlist and userlist 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.

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.

Masterlist Update

virtual bool UpdateMasterlist(const std::filesystem::path &masterlist_path, const std::string &remote_url, const std::string &remote_branch) = 0

Update the given masterlist.

Uses Git to update the given masterlist to a given remote. If the masterlist doesn’t exist, this will create it. This function also initialises a Git repository in the given masterlist’s parent folder. If the masterlist was not already up-to-date, it will be re-loaded, but not re-evaluated.

If a Git repository is already present, it will be used to perform a diff-only update, but if for any reason a fast-forward merge update is not possible, the existing repository will be deleted and a new repository cloned from the given remote.

Return
true if the masterlist was updated. false if no update was necessary, ie. it was already up-to-date. If true, the masterlist will have been re-loaded, but will need to be re-evaluated separately.
Parameters
  • masterlist_path: The relative or absolute path to the masterlist file that should be updated. The filename must match the filename of the masterlist file in the given remote repository, otherwise it will not be updated correctly. Although LOOT itself expects this filename to be “masterlist.yaml”, the API does not check for any specific filename.
  • remote_url: The URL of the remote from which to fetch updates. This can also be a relative or absolute path to a local repository.
  • remote_branch: The branch of the remote from which to apply updates. LOOT’s official masterlists are versioned using separate branches for each new version of the masterlist syntax, so if you’re using them, check their repositories to see which is the latest release branch.

virtual MasterlistInfo GetMasterlistRevision(const std::filesystem::path &masterlist_path, const bool get_short_id) const = 0

Get the given masterlist’s revision.

Getting a masterlist’s revision is only possible if it is found inside a local Git repository.

Return
The revision data.
Parameters
  • masterlist_path: The relative or absolute path to the masterlist file that should be queried.
  • get_short_id: If true, the shortest unique hexadecimal revision hash that is at least 7 characters long will be outputted. Otherwise, the full 40 character hash will be outputted.

virtual bool IsLatestMasterlist(const std::filesystem::path &masterlist_path, const std::string &branch) const = 0

Check if the given masterlist is the latest available for a given branch.

Return
True if the masterlist revision matches the latest masterlist revision for the given branch, and false otherwise.
Parameters
  • masterlist_path: The relative or absolute path to the masterlist file for which the latest revision should be obtained. It needs to be in a local Git repository.
  • branch: The branch to check against.

Non-plugin Data Access

virtual std::set<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.

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

Return
A vector of messages supplied in the metadata lists but not attached to any particular plugin.
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.

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

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

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

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

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

Return
An unordered set of Group objects.

virtual void SetUserGroups(const std::unordered_set<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.

Return
A vector of Vertex elements representing the path from the source group to the destination group, or an empty vector if no path exists.
Parameters
  • fromGroupName: The name of the source group, that loads earlier.
  • toGroupName: The name of the destination group, that loads later.

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.

Return
If the plugin has metadata, an optional containing that metadata, otherwise an optional containing no value.
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.

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

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

Return
If the plugin has user-added metadata, an optional containing that metadata, otherwise an optional containing no value.
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.

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 GameInterface

The interface provided for accessing game-specific functionality.

Metadata Access

virtual std::shared_ptr<DatabaseInterface> GetDatabase() = 0

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

Return
A shared pointer to the game’s DatabaseInterface

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.

Return
True if the file is a valid plugin, false otherwise.
Parameters
  • plugin: The filename of the file to check.

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 std::shared_ptr<const PluginInterface> GetPlugin(const std::string &pluginName) const = 0

Get data for a loaded plugin.

Return
A shared pointer to a const PluginInterface implementation. The pointer is null if the given plugin has not been loaded.
Parameters
  • pluginName: The filename of the plugin to get data for.

virtual std::set<std::shared_ptr<const PluginInterface>> GetLoadedPlugins() const = 0

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

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

Return
A vector of the given plugin filenames in their sorted load order.
Parameters
  • plugins: A vector of filenames of the plugins to sort.

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 IsPluginActive(const std::string &plugin) const = 0

Check if a plugin is active.

Return
True if the plugin is active, false otherwise.
Parameters
  • plugin: The filename of the plugin for which to check the active state.

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

Get the current load order.

Return
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 PluginInterface

Represents a plugin file that has been parsed by LOOT.

Public Functions

virtual std::string GetName() const = 0

Get the plugin’s filename.

Return
The plugin filename.

virtual float GetHeaderVersion() const = 0

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

Return
The value of the version field, or NaN if the field 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.

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

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

virtual std::set<Tag> GetBashTags() const = 0

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

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

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

Return
True if the master flag is set, false otherwise.

virtual bool IsLightMaster() const = 0

Check if the plugin is a light master.

Return
True if plugin is a light master, false otherwise.

virtual bool IsValidAsLightMaster() const = 0

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

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

virtual bool IsEmpty() const = 0

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

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

Return
True if the plugin loads an archive, false otherwise.

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

Check if two plugins contain records for the same FormIDs.

Return
True if the plugins both contain at least one record with the same FormID, false otherwise.
Parameters
  • plugin: The other plugin to check for FormID overlap with.

Classes

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

Construct a ConditionalMetadata object with an empty condition string.

Return
A ConditionalMetadata object.

ConditionalMetadata(const std::string &condition)

Construct a ConditionalMetadata object with a given condition string.

Return
A ConditionalMetadata object.
Parameters
  • condition: A condition string, as defined in the LOOT metadata syntax documentation.

bool IsConditional() const

Check if the condition string is non-empty.

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

void ParseCondition() const

Check if the condition string is syntactically valid.

Throws a ConditionSyntaxError if the condition string’s syntax is not valid.

std::string GetCondition() const

Get the condition string.

Return
The object’s condition string.

class File : public ConditionalMetadata

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

Public Functions

File()

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

Return
A File object.

File(const std::string &name, const std::string &display = "", const std::string &condition = "")

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

Return
A File object.
Parameters
  • name: The filename of the file.
  • display: The name to be displayed for the file in messages.
  • condition: The File‘s condition string.

bool operator<(const File &rhs) const

A less-than operator implemented with no semantics so that File objects can be stored in sets.

Return
True if this File‘s name is case-insensitively lexicographically less than the given File‘s name, false otherwise.

bool operator==(const File &rhs) const

Check if two File objects are equal by comparing their filenames.

Return
True if the filenames are case-insensitively equal, false otherwise.

std::string GetName() const

Get the filename of the file.

Return
The file’s filename.

std::string GetDisplayName() const

Get the display name of the file.

Return
The file’s display name.

class Group

Represents a group to which plugin metadata objects can belong.

Public Functions

Group()

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

Return
A Group object.

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

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

Return
A Group object.
Parameters
  • name: The group name.
  • afterGroups: The names of groups this group loads after.
  • description: A description of the group.

bool operator==(const Group &rhs) const

Check if two Group objects are equal by comparing their names.

Return
True if the names are case-sensitively equal, false otherwise.

std::string GetName() const

Get the name of the group.

Return
The group’s name.

std::string GetDescription() const

Get the description of the group.

Return
The group’s description.

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

Get the set of groups this group loads after.

Return
A set of group names.

class Location

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

Public Functions

Location()

Construct a Location with empty URL and name strings.

Return
A Location object.

Location(const std::string &url, const std::string &name = "")

Construct a Location with the given URL and name.

Return
A Location object.
Parameters
  • url: The URL at which the plugin can be found.
  • name: A name for the URL, eg. the page or site name.

bool operator<(const Location &rhs) const

A less-than operator implemented with no semantics so that Location objects can be stored in sets.

Return
True if this Location‘s URL string is lexicographically less than the given Location‘s URL string, false otherwise.

bool operator==(const Location &rhs) const

Check if two Location objects are equal by comparing their URLs.

Return
True if the URL strings are equal, false otherwise.

std::string GetURL() const

Get the object’s URL.

Return
A URL string.

std::string GetName() const

Get the object’s name.

Return
The name of the location.

class LootVersion

A purely static class that provides information about the version of libloot that is being run.

Public Static Functions

static std::string GetVersionString()

Get the API version as a string.

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

Public Static Attributes

const unsigned int major

The major version number.

const unsigned int minor

The minor version number.

const unsigned int patch

The patch version number.

const std::string revision

The source control revision that the API was built from.

class MessageContent

Represents a message’s localised text content.

Public Functions

MessageContent()

Construct a MessageContent object with an empty English message string.

Return
A MessageContent object.

MessageContent(const std::string &text, const std::string &language = defaultLanguage)

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

Return
A MessageContent object.
Parameters
  • text: The message text.
  • language: The language that the message is written in.

std::string GetText() const

Get the message text.

Return
A string containing the message text.

std::string GetLanguage() const

Get the message language.

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

bool operator<(const MessageContent &rhs) const

A less-than operator implemented with no semantics so that MessageContent objects can be stored in sets.

Return
True if this MessageContent‘s text is lexicographically less than the given MessageContent‘s text, false otherwise.

bool operator==(const MessageContent &rhs) const

Check if two MessageContent objects are equal by comparing their texts.

Return
True if the texts are equal, false otherwise.

Public Static Functions

static MessageContent Choose(const std::vector<MessageContent> content, const std::string &language)

Choose a MessageContent object from a vector given a language.

Return
A MessageContent object. If the given vector is empty, a default-constructed MessageContent is returned.
Parameters
  • content: The MessageContent objects to choose between.
  • language: The language code for the preferred language to select. If no message in the preferred language is present, the English MessageContent will be returned.

Public Static Attributes

const std::string defaultLanguage

The code for the default language assumed for message content, which is English.

class Message : public ConditionalMetadata

Represents a message with localisable text content.

Public Functions

Message()

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

Return
A Message object.

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.

Return
A Message object.
Parameters
  • type: The message type.
  • content: The English message content text.
  • condition: A condition string.

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.

Return
A Message object.
Parameters
  • type: The message type.
  • content: The message content. If multilingual, one language must be English.
  • condition: A condition string.

bool operator<(const Message &rhs) const

A less-than operator implemented with no semantics so that Message objects can be stored in sets.

Return
Returns true if this Message‘s content is lexicographically less than the given Message‘s content, and false otherwise.

bool operator==(const Message &rhs) const

Check if two Message objects are equal by comparing their content.

Return
True if the contents are equal, false otherwise.

MessageType GetType() const

Get the message type.

Return
The message type.

std::vector<MessageContent> GetContent() const

Get the message content.

Return
The message’s MessageContent objects.

MessageContent GetContent(const std::string &language) const

Get the message content given a language.

Return
A MessageContent object for the preferred language, or for English if a MessageContent object is not available for the given language.
Parameters
  • language: The preferred language for the message content.

SimpleMessage ToSimpleMessage(const std::string &language) const

Get the message as a SimpleMessage given a language.

Return
A SimpleMessage object for the preferred language, or for English if message text is not available for the given language.
Parameters
  • language: The preferred language for the message content.

class PluginCleaningData

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

Public Functions

PluginCleaningData()

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

Return
A PluginCleaningData object.

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

Return
A PluginCleaningData object.
Parameters
  • crc: The CRC of a plugin.
  • utility: The utility that the plugin cleanliness was checked with.

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

Construct a PluginCleaningData object with the given values.

Return
A PluginCleaningData object.
Parameters
  • crc: A clean or dirty plugin’s CRC.
  • utility: The utility that the plugin cleanliness was checked with.
  • info: 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.

bool operator<(const PluginCleaningData &rhs) const

A less-than operator implemented with no semantics so that PluginCleaningData objects can be stored in sets.

Return
True if this PluginCleaningData‘s CRC is less than the given PluginCleaningData‘s CRC, false otherwise.

bool operator==(const PluginCleaningData &rhs) const

Check if two PluginCleaningData objects are equal by comparing their CRCs.

Return
True if the CRCs are equal, false otherwise.

uint32_t GetCRC() const

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

Return
A CRC-32 checksum.

unsigned int GetITMCount() const

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

Return
The number of Identical To Master records in the plugin.

unsigned int GetDeletedReferenceCount() const

Get the number of deleted references in the plugin.

Return
The number of deleted references in the plugin.

unsigned int GetDeletedNavmeshCount() const

Get the number of deleted navmeshes in the plugin.

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

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

std::vector<MessageContent> GetInfo() 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.

Return
A vector of localised MessageContent objects.

MessageContent ChooseInfo(const std::string &language) const

Choose an info MessageContent object given a preferred language.

Return
The MessageContent object for the preferred language, or if one does not exist, the English-language MessageContent object.
Parameters
  • language: The preferred language’s code.

class PluginMetadata

Represents a plugin’s metadata.

Public Functions

PluginMetadata()

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

Return
A PluginMetadata object.

PluginMetadata(const std::string &name)

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

Return
A PluginMetadata object.
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 enabled state is replaced by the given object’s state. This object’s group is replaced by the given object’s group if the latter is explicit.

Parameters
  • plugin: The plugin metadata to merge.

PluginMetadata NewMetadata(const PluginMetadata &plugin) const

Get metadata in this object that isn’t present in the given PluginMetadata object.

Return
A PluginMetadata object containing the metadata in this object that is not in the given object. The returned object inherits this object’s enabled state and group.
Parameters

std::string GetName() const

Get the plugin name.

Return
The plugin name.

std::string GetLowercasedName() const

Get the lowercased plugin name.

Return
The lowercased plugin name.

bool IsEnabled() const

Check if the plugin metadata is enabled for use during sorting.

Return
True if the metadata will be used during sorting, false otherwise.

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

Get the plugin’s group.

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

std::set<File> GetLoadAfterFiles() const

Get the plugins that the plugin must load after.

Return
The plugins that the plugin must load after.

std::set<File> GetRequirements() const

Get the files that the plugin requires to be installed.

Return
The files that the plugin requires to be installed.

std::set<File> GetIncompatibilities() const

Get the files that the plugin is incompatible with.

Return
The files that the plugin is incompatible with.

std::vector<Message> GetMessages() const

Get the plugin’s messages.

Return
The plugin’s messages.

std::set<Tag> GetTags() const

Get the plugin’s Bash Tag suggestions.

Return
The plugin’s Bash Tag suggestions.

std::set<PluginCleaningData> GetDirtyInfo() const

Get the plugin’s dirty plugin information.

Return
The PluginCleaningData objects that identify the plugin as dirty.

std::set<PluginCleaningData> GetCleanInfo() const

Get the plugin’s clean plugin information.

Return
The PluginCleaningData objects that identify the plugin as clean.

std::set<Location> GetLocations() const

Get the locations at which this plugin can be found.

Return
The locations at which this plugin can be found.

std::vector<SimpleMessage> GetSimpleMessages(const std::string &language) const

Get the plugin’s messages as SimpleMessage objects for the given language.

Return
The plugin’s messages as SimpleMessage objects.
Parameters
  • language: The language to create the SimpleMessage objects for.

void SetEnabled(const bool enabled)

Set whether the plugin metadata is enabled for use during sorting or not.

Parameters
  • enabled: The value to set.

void SetGroup(const std::string &group)

Set the plugin’s group.

Parameters
  • group: The name of the group this plugin belongs to.

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

Set the files that the plugin must load after.

Parameters
  • after: The files to set.

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

Set the files that the plugin requires to be installed.

Parameters
  • requirements: The files to set.

void SetIncompatibilities(const std::set<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::set<Tag> &tags)

Set the plugin’s Bash Tag suggestions.

Parameters
  • tags: The Bash Tag suggestions to set.

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

Set the plugin’s dirty information.

Parameters
  • info: The dirty information to set.

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

Set the plugin’s clean information.

Parameters
  • info: The clean information to set.

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

Set the plugin’s locations.

Parameters
  • locations: The locations to set.

bool HasNameOnly() const

Check if no plugin metadata is set.

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

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

bool operator==(const PluginMetadata &rhs) const

Check if two PluginMetadata objects are equal by comparing their name values.

Return
True if the plugin names are case-insensitively equal, false otherwise.

bool operator!=(const PluginMetadata &rhs) const

Check if two PluginMetadata objects are not equal by comparing their name values.

Return
True if the plugin names are not case-insensitively equal, false otherwise.

bool operator==(const std::string &rhs) const

Check if object’s name value is equal to the given string.

Return
True if the plugin name is case-insensitively equal to the given string, false otherwise.

bool operator!=(const std::string &rhs) const

Check if object’s name value is not equal to the given string.

Return
True if the plugin name is not case-insensitively equal to the given string, false otherwise.

class Tag : public ConditionalMetadata

Represents a Bash Tag suggestion for a plugin.

Public Functions

Tag()

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

Return
A Tag object.

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.

Return
A Tag object.
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 operator<(const Tag &rhs) const

A less-than operator implemented with no semantics so that Tag objects can be stored in sets.

Return
True if this Tag is suggested for addition and the other is not. If both Tags are suggested for addition or both are suggested for removal, returns true if this Tag‘s name is lexicographically less than the given Tag‘s name, false otherwise.

bool operator==(const Tag &rhs) const

Check if two Tag objects are equal.

Return
True if both Tags are suggested for addition or both are suggested for removal, and the Tag names are equal, false otherwise.

bool IsAddition() const

Check if the tag should be added.

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

std::string GetName() const

Get the tag’s name.

Return
The tag’s name.

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

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.

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.

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

Return
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()

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.

Return
A vector of Vertex elements representing the cyclic path.

class GitStateError : public logic_error

An exception class thrown if an error occurs when performing an operation on a Git repository due to invalid state.

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

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

Public Functions

UndefinedGroupError(const std::string &groupName)

Construct an exception for an undefined group.

Parameters
  • groupName: The name of the group that is undefined.

std::string GetGroupName()

Get the name of the undefined group.

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

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

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

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

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