API Reference¶
Contents
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, orfalse
if it is at exactly the revision given.
-
std::string
-
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.
-
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. 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
: Iffalse
andoutputFile
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
: Iffalse
andoutputFile
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. Iftrue
, 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
: 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::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.
-
virtual void
-
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 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.
- 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.
- 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()
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
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.
-
virtual std::string
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
(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
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
(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 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”.
-
static std::string
-
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.
-
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.
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
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.
-
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::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
UnsetGroup
()¶ Unsets the plugin’s group.
-
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.
-
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 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.
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.