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::
LanguageCode
¶ Codes used to specify the preferred language for messages when evaluating masterlists and userlists.
If a message is not available in the preferred language, its English string will be used. Note that messages with only one language string are assumed to be written in English, but this cannot be guaranteed (any violations should be reported as bugs so that they can be fixed).
Values:
-
english
¶
-
spanish
¶
-
russian
¶
-
french
¶
-
chinese
¶
-
polish
¶
-
brazilian_portuguese
¶
-
finnish
¶
-
german
¶
-
danish
¶
-
korean
¶
-
swedish
¶
-
-
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.
-
-
enum
loot::
PluginCleanliness
¶ Codes used to indicate the cleanliness of a plugin according to the information contained within the loaded masterlist/userlist.
Values:
-
clean
¶ Indicates that the plugin is clean.
-
dirty
¶ Indicates that the plugin is dirty.
-
do_not_clean
¶ Indicates that the plugin contains dirty edits, but that they are part of the plugin’s intended functionality and should not be removed.
-
unknown
¶ Indicates that no data is available on whether the plugin is dirty or not.
-
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.
-
LanguageCode
language
¶ The language the message string is written in.
-
std::string
text
¶ The message string, which may be formatted using GitHub Flavored Markdown.
-
MessageType
-
struct
loot::
PluginTags
¶ A structure that holds data about the Bash Tag suggestions made by LOOT for a plugin.
Public Members
-
std::set<std::string>
added
¶ A set of Bash Tag names suggested for addition to the specified plugin. Empty if no Bash Tag additions are suggested.
-
std::set<std::string>
removed
¶ A set of Bash Tag names suggested for removal from the specified plugin. Empty if no Bash Tag removals are suggested.
-
bool
userlist_modified
¶ true
if the Bash Tag suggestions were modified by data in the userlist,false
otherwise.
-
std::set<std::string>
Functions¶
-
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.
-
std::shared_ptr<DatabaseInterface>
loot::
CreateDatabase
(const GameType game, const std::string &game_path = "", const std::string &game_local_path = "")¶ Initialise a new database handle.
Creates a handle for a database, which is then used by all database functions.
- Return
- The new database 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 Loading
-
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
EvalLists
() = 0¶ Evaluates all conditions and regular expression metadata entries.
Repeated calls re-evaluate the metadata from scratch. This function affects the output of all the database access functions.
Sorting
-
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.
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) = 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.
Plugin Data Access
-
virtual PluginTags
GetPluginTags
(const std::string &plugin) = 0¶ Outputs the Bash Tags suggested for addition and removal by the database for the given plugin.
- Return
- Bash Tag data for the plugin.
- Parameters
plugin
: The filename of the plugin to look up Bash Tag suggestions for.
-
virtual std::vector<SimpleMessage>
GetPluginMessages
(const std::string &plugin, const LanguageCode language) = 0¶ Outputs the messages associated with the given plugin in the database.
- Return
- A vector of messages associated with the specified plugin. Empty if the plugin has no messages associated with it.
- Parameters
plugin
: The filename of the plugin to look up messages for.language
: The language to use when choosing which message content strings to return.
-
virtual PluginCleanliness
GetPluginCleanliness
(const std::string &plugin) = 0¶ Determines the database’s knowledge of a plugin’s cleanliness.
Outputs whether the plugin should be cleaned or not, or if no data is available. The mechanism used to determine that a plugin should not be cleaned is not very reliable, and is likely to fail if
EvalLists()
was called with a language other than English. As such, some plugins that should not be cleaned may have thePluginCleanliness::unknown
code outputted.- Return
- A plugin cleanliness code.
- Parameters
plugin
: The plugin to look up the cleanliness state for.
Miscellaneous
-
virtual void
WriteMinimalList
(const std::string &outputFile, const bool overwrite) = 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.
-
virtual void
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::
GameDetectionError
¶ An exception class thrown if an error occurs when detecting installed games.
Inherits from runtime_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.