API Reference

Enumerations

Warning

doxygenenum: Cannot find enum “loot::GameType” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

Warning

doxygenenum: Cannot find enum “loot::LanguageCode” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

Warning

doxygenenum: Cannot find enum “loot::MessageType” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

Warning

doxygenenum: Cannot find enum “loot::PluginCleanliness” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

Public-Field Data Structures

Warning

doxygenstruct: Cannot find class “loot::MasterlistInfo” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

Warning

doxygenstruct: Cannot find class “loot::SimpleMessage” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

Warning

doxygenstruct: Cannot find class “loot::PluginTags” in doxygen xml output for project “loot” from directory: ../build/docs/xml/

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

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 the PluginCleanliness::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 -

    If false and outputFile already exists, no data will be written. Otherwise, data will be written.

Classes

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.

Exceptions

class loot::CyclicInteractionError

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

Inherits from runtime_error

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.