API Reference¶
Contents
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, orfalse
if it is at exactly the revision given.
-
std::string
-
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.
-
MessageType
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
: Iffalse
andoutputFile
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
: Iffalse
andoutputFile
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. Iftrue
, 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
: Iftrue
, 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.
-
virtual void
-
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 theTES4
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 toIdentifyMainMasterFile()
.
-
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()
orSortPlugins()
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()
orSortPlugins()
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.
-
virtual std::shared_ptr<DatabaseInterface>
-
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.
-
virtual std::string
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
(const std::string &name, const std::string &display = "", const std::string &condition = "")¶ Construct a File with the given name, display name and condition strings.
-
bool
operator<
(const File &rhs) const¶ A less-than operator implemented with no semantics so that File objects can be stored in sets.
-
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
(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.
-
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”.
-
static std::string
-
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.
-
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.
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
plugin
: The PluginMetadata object to compare against.
-
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::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
(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 greater than or equal to another.
-
-
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.
-
bool
operator<
(const Tag &rhs) const¶ A less-than operator implemented with no semantics so that Tag objects can be stored in sets.
-
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.