API Reference

Enumerations

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

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

std::shared_ptr<GameInterface> loot::CreateGameHandle(const GameType game, const std::string &game_path = "", const std::string &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 game folder, or an empty string. If an empty string, the API will attempt to detect the data path of the specified game by searching for the game’s main master file in a sibling Data folder and by searching for the game’s Registry entry.
  • game_local_path: The relative or absolute path to the game’s folder in %LOCALAPPDATA% or an empty string. If an empty string, 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 loot::DatabaseInterface

The interface provided by API’s database handle.

Data Reading & Writing

virtual void LoadLists(const std::string &masterlist_path, const std::string &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: A string containing the relative or absolute path to the masterlist file that should be loaded.
  • userlist_path: A string containing the relative or absolute path to the userlist file that should be loaded, or an empty string. If an empty string, no userlist will be loaded.

virtual void WriteUserMetadata(const std::string &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::string &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::string &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: A string containing 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::string &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: A string containing 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::string &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: A string containing 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.

Plugin Data Access

virtual PluginMetadata GetPluginMetadata(const std::string &plugin, bool includeUserMetadata = true, bool evaluateConditions = false) const = 0

Get all a plugin’s loaded metadata.

Return
A PluginMetadata object containing all the plugin’s metadata. If the plugin has no metadata, PluginMetadata.IsNameOnly() will return true.
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 PluginMetadata GetPluginUserMetadata(const std::string &plugin, bool evaluateConditions = false) const = 0

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

Return
A PluginMetadata object containing the plugin’s user-added metadata. If the plugin has no metadata, PluginMetadata.IsNameOnly() will return true.
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 loot::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. This function also loads the current load order state.

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.

Throws an exception if the given plugin has not been loaded.

Return
A const PluginInterface reference. The reference remains valid until the LoadPlugins() or SortPlugins() functions are next called or this GameInterface is destroyed.
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 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.

Return
The plugin filename.

virtual std::string GetLowercasedName() const = 0

Get the plugin’s filename in lowercase characters.

Return
The lowercased plugin filename.

virtual std::string GetVersion() const = 0

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

If no version number is found in the description field, an empty string is returned. The description field parsing may fail to extract the version number correctly, though it functions correctly in all known cases.

Return
A string containing a version number, or an empty string.

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 uint32_t GetCRC() const = 0

Get the plugin’s CRC-32 checksum.

Return
The plugin’s CRC-32 checksum if it has been fully read. If only the plugin’s header has been read, 0 will be returned.

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

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

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

Inherits from ConditionalMetadata

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 loot::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 is case-insensitively lexicographically less than the given Location‘s URL, false otherwise.

bool operator==(const Location &rhs) const

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

Return
True if the URLs are case-insensitively 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 loot::LootVersion

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

Public Static Functions

static std::string string()

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 loot::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 case-insensitively 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 case-insensitively 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 loot::Message

Represents a message with localisable text content.

Inherits from ConditionalMetadata

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
If both messages have content, returns true if this Message‘s English text is case-insensitively lexicographically less than the given Message‘s English text, and false otherwise. Otherwise returns true if this Message has no 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 loot::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 loot::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 priorities are replaced if the given PluginMetadata object’s priorities are explicit. This object’s enabled state is replaced by the given object’s state.

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. The returned object also inherits this plugin’s priorities, unless a priority is equal to the given object’s priority, in which case the returned object is given an implicit zero priority instead.
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.

Priority GetLocalPriority() const

Get the plugin’s local priority metadata.

Return
The plugin’s local priority metadata.

Priority GetGlobalPriority() const

Get the plugin’s global priority metadata.

Return
The plugin’s global priority metadata.

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 SetLocalPriority(const Priority &priority)

Set the plugin’s local priority.

Parameters
  • priority: The value to set.

void SetGlobalPriority(const Priority &priority)

Set the plugin’s local priority.

Parameters
  • priority: The value to set.

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 local and global priorities are 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 loot::Priority

Represents the priority of a plugin in the load order.

Plugins have a default implicit priority of zero. Lower priority values cause plugins to be loaded earlier, and higher priority values cause plugins to be loaded later.

Public Functions

Priority()

Construct a Priority object with an implicit value of zero.

Return
A Priority object.

Priority(const int value)

Construct a Priority object with the given priority value.

If the given value is zero, it is marked as being set explicitly. This affects how priority metadata values get merged in PluginMetadata objects.

Return
A Priority object.
Parameters
  • value: The priority value to set. The valid range of values is -127 to 127 inclusive, and values passed to the constructor that lie outside this range are clamped. The input type is an int to avoid invalid values from implicitly wrapping around.

short GetValue() const

Get the stored priority value.

Return
The priority value. While the valid value range fits in 8 bits, a short is returned to avoid interpreting the value as a character.

bool IsExplicit() const

Check if the priority value is explicit or not.

Return
Returns true if the value is non-zero or was explicitly set to zero, and false otherwise.

bool operator<(const Priority &rhs) const

Check if this Priority object is less than another.

Return
True if this Priority object’s value is less than the given Priority object’s value.

bool operator>(const Priority &rhs) const

Check if this Priority object is greater than another.

Return
True if this Priority object’s value is greater than the given Priority object’s value, false otherwise.

bool operator>=(const Priority &rhs) const

Check if this Priority object is greater than or equal to another.

Return
True if this Priority object’s value is greater than or equal to the given Priority object’s value, false otherwise.

bool operator==(const Priority &rhs) const

Check if this Priority object is equal to another.

Return
True if this Priority object’s value is equal to the given Priority object’s value, false otherwise.

bool operator>(const uint8_t rhs) const

Check if this Priority object is greater than a given priority value.

Return
True if this Priority object’s value is greater than the given value, false otherwise.

class loot::Tag

Represents a Bash Tag suggestion for a plugin.

Inherits from ConditionalMetadata

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

Exceptions

class loot::CyclicInteractionError

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

Inherits from runtime_error

Public Functions

CyclicInteractionError(const std::string &firstPlugin, const std::string &lastPlugin, const std::string &backCycle)

Construct an exception detailing a plugin graph cycle.

Parameters
  • firstPlugin: A plugin in the cycle.
  • lastPlugin: Another plugin in the cycle.
  • backCycle: A string describing the path from lastPlugin to firstPlugin.

std::string getFirstPlugin()

Get the first plugin in the chosen forward path of the cycle.

Return
A plugin filename.

std::string getLastPlugin()

Get the first plugin in the chosen forward path of the cycle.

Return
A plugin filename.

std::string getBackCycle()

Get a description of the reverse path from the chosen last plugin to the chosen first plugin of the cycle.

Return
A string describing a path between two plugins in the plugin graph.

class loot::GitStateError

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

Inherits from logic_error

class loot::ConditionSyntaxError

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

Inherits from runtime_error

class loot::FileAccessError

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

Inherits from runtime_error

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.