mirror of
https://github.com/loot/libloot.git
synced 2026-07-27 14:16:01 -07:00
445 lines
16 KiB
C++
445 lines
16 KiB
C++
/* LOOT
|
|
|
|
A load order optimisation tool for Oblivion, Skyrim, Fallout 3 and
|
|
Fallout: New Vegas.
|
|
|
|
Copyright (C) 2012-2026 Oliver Hamlet
|
|
|
|
This file is part of LOOT.
|
|
|
|
LOOT is free software: you can redistribute
|
|
it and/or modify it under the terms of the GNU General Public License
|
|
as published by the Free Software Foundation, either version 3 of
|
|
the License, or (at your option) any later version.
|
|
|
|
LOOT is distributed in the hope that it will
|
|
be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with LOOT. If not, see
|
|
<https://www.gnu.org/licenses/>.
|
|
*/
|
|
#ifndef LOOT_DATABASE_INTERFACE
|
|
#define LOOT_DATABASE_INTERFACE
|
|
|
|
#include <filesystem>
|
|
#include <optional>
|
|
#include <string>
|
|
#include <string_view>
|
|
#include <vector>
|
|
|
|
#include "loot/exception/cyclic_interaction_error.h"
|
|
#include "loot/metadata/group.h"
|
|
#include "loot/metadata/message.h"
|
|
#include "loot/metadata/plugin_metadata.h"
|
|
|
|
namespace loot {
|
|
struct MetadataWriteOptionsImpl;
|
|
|
|
/** @brief Options to configure how metadata files are written. */
|
|
class MetadataWriteOptions {
|
|
public:
|
|
/**
|
|
* @brief Creates a new options object, with all options initially set to
|
|
* `false`.
|
|
*/
|
|
LOOT_API MetadataWriteOptions();
|
|
|
|
/**
|
|
* @brief Creates a new options object, copying the options' values from the
|
|
* given object.
|
|
*/
|
|
LOOT_API MetadataWriteOptions(const MetadataWriteOptions&);
|
|
|
|
/**
|
|
* @brief Creates a new options object, moving the options' values from the
|
|
* given object.
|
|
*/
|
|
LOOT_API MetadataWriteOptions(MetadataWriteOptions&&) noexcept;
|
|
|
|
LOOT_API ~MetadataWriteOptions();
|
|
|
|
/**
|
|
* @brief Assigns the options values of this object by copying them from the
|
|
* given object.
|
|
*/
|
|
LOOT_API MetadataWriteOptions& operator=(const MetadataWriteOptions&);
|
|
|
|
/**
|
|
* @brief Assigns the options values of this object by moving them from the
|
|
* given object.
|
|
*/
|
|
LOOT_API MetadataWriteOptions& operator=(MetadataWriteOptions&&) noexcept;
|
|
|
|
/**
|
|
* @brief Sets the option to overwrite the output file if it already exists.
|
|
* @details If true and the file path already exists, its contents will be
|
|
* replaced.
|
|
*
|
|
* If false and the file path already exists, an error will be
|
|
* returned.
|
|
*
|
|
* This setting has no effect if the file path does not exist.
|
|
* @param truncate
|
|
* The value to set.
|
|
*/
|
|
LOOT_API void SetTruncate(bool truncate);
|
|
|
|
/**
|
|
* @brief Sets the option to write YAML anchors and aliases.
|
|
* @details If true then conditions, constraints, files, file details, plugin
|
|
* cleaning data details, messages and message contents that appear
|
|
* more than once in the metadata will be deduplicated by including
|
|
* a YAML anchor when writing the first occurrence of the value, and
|
|
* writing YAML aliases in place of further occurrences.
|
|
*
|
|
* If false, YAML anchors and aliases will not be used, so no
|
|
* deduplication will occur.
|
|
* @param writeAnchors
|
|
* The value to set.
|
|
*/
|
|
LOOT_API void SetWriteAnchors(bool writeAnchors);
|
|
|
|
/**
|
|
* @brief Sets the option to write YAML anchors in a `common` section.
|
|
* @details If `writeAnchors` is true and this is also true, the document's
|
|
* root-level map will start with a `common` key. Its value will be
|
|
* a list of all the values for which YAML anchors will be written,
|
|
* so that all YAML anchors will appear within that list.
|
|
*
|
|
* This setting has no effect if `writeAnchors` is false.
|
|
* @param writeCommonSection
|
|
* The value to set.
|
|
*/
|
|
LOOT_API void SetWriteCommonSection(bool writeCommonSection);
|
|
|
|
/**
|
|
* @brief Sets the option to write anchors for File values that only have a
|
|
* name.
|
|
* @details If `writeAnchors` is true and this is also true, then all
|
|
* repeated File metadata values will be deduplicated using YAML
|
|
* anchors and aliases.
|
|
*
|
|
* If this is false, then only File metadata that is serialised as
|
|
* a YAML object will be deduplicated (i.e. File values that only
|
|
* have a name will not be deduplicated).
|
|
*
|
|
* This setting has no effect if `writeAnchors` is false.
|
|
* @param anchorFileStrings
|
|
* The value to set.
|
|
*/
|
|
LOOT_API void SetAnchorFileStrings(bool anchorFileStrings);
|
|
|
|
/** Gets the current value of the truncate option. */
|
|
LOOT_API bool GetTruncate() const;
|
|
|
|
/** Gets the current value of the writeAnchors option. */
|
|
LOOT_API bool GetWriteAnchors() const;
|
|
|
|
/** Gets the current value of the writeCommonSection option. */
|
|
LOOT_API bool GetWriteCommonSection() const;
|
|
|
|
/** Gets the current value of the anchorFileStrings option. */
|
|
LOOT_API bool GetAnchorFileStrings() const;
|
|
|
|
private:
|
|
std::unique_ptr<MetadataWriteOptionsImpl> pimpl_;
|
|
};
|
|
|
|
/** @brief The interface provided by API's database handle. */
|
|
class DatabaseInterface {
|
|
public:
|
|
DatabaseInterface() = default;
|
|
DatabaseInterface(const DatabaseInterface&) = delete;
|
|
DatabaseInterface(DatabaseInterface&&) = delete;
|
|
|
|
virtual ~DatabaseInterface() = default;
|
|
|
|
DatabaseInterface& operator=(const DatabaseInterface&) = delete;
|
|
DatabaseInterface& operator=(DatabaseInterface&&) = delete;
|
|
|
|
/**
|
|
* @name Data Reading & Writing
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Loads the masterlist from the path specified.
|
|
* @details Can be called multiple times, each time replacing the
|
|
* previously-loaded data.
|
|
* @param masterlistPath
|
|
* The relative or absolute path to the masterlist file that should be
|
|
* loaded.
|
|
*/
|
|
virtual void LoadMasterlist(const std::filesystem::path& masterlistPath) = 0;
|
|
|
|
/**
|
|
* @brief Loads the masterlist and masterlist prelude from the paths
|
|
specified.
|
|
* @details Can be called multiple times, each time replacing the
|
|
* previously-loaded data.
|
|
* @param masterlistPath
|
|
* The relative or absolute path to the masterlist file that should be
|
|
* loaded.
|
|
* @param masterlistPreludePath
|
|
* The relative or absolute path to the masterlist prelude file that
|
|
* should be loaded.
|
|
*/
|
|
virtual void LoadMasterlistWithPrelude(
|
|
const std::filesystem::path& masterlistPath,
|
|
const std::filesystem::path& masterlistPreludePath) = 0;
|
|
|
|
/**
|
|
* @brief Loads the userlist from the path specified.
|
|
* @details Can be called multiple times, each time replacing the
|
|
* previously-loaded data.
|
|
* @param userlistPath
|
|
* The relative or absolute path to the userlist file that should be
|
|
* loaded.
|
|
*/
|
|
virtual void LoadUserlist(const std::filesystem::path& userlistPath) = 0;
|
|
|
|
/**
|
|
* Writes a metadata file containing all loaded user-added metadata.
|
|
* @param outputFile
|
|
* The path to which the file shall be written.
|
|
* @param options
|
|
* The configuration options to use when writing the file.
|
|
*/
|
|
virtual void WriteUserMetadata(const std::filesystem::path& outputFile,
|
|
const MetadataWriteOptions& options) const = 0;
|
|
|
|
/**
|
|
* @brief Writes a minimal metadata file that only contains plugins with
|
|
* Bash Tag suggestions and/or dirty info, plus the suggestions and
|
|
* info themselves.
|
|
* @param outputFile
|
|
* The path to which the file shall be written.
|
|
* @param options
|
|
* The configuration options to use when writing the file.
|
|
*/
|
|
virtual void WriteMinimalList(const std::filesystem::path& outputFile,
|
|
const MetadataWriteOptions& options) const = 0;
|
|
|
|
/**
|
|
* @brief Evaluate the given condition string.
|
|
* @param condition A condition string.
|
|
*/
|
|
virtual bool Evaluate(const std::string& condition) const = 0;
|
|
|
|
/**
|
|
* @brief Clears the cache of metadata condition evaluation results.
|
|
* @details As many conditions involve reading files and/or directories,
|
|
* libloot caches the results of condition evaluation and reuses
|
|
* those cached results in subsequent evaluations.
|
|
*
|
|
* Clearing the condition cache means that the next time a condition
|
|
* is evaluated, it will be evaluated from scratch instead of using a
|
|
* cached result.
|
|
*/
|
|
virtual void ClearConditionCache() = 0;
|
|
|
|
/**
|
|
* @}
|
|
* @name Non-plugin Data Access
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Gets the Bash Tags that are listed in the loaded metadata lists.
|
|
* @details Bash Tag suggestions can include Bash Tags not in this list.
|
|
* @param includeUserMetadata
|
|
* If true, any Bash Tag metadata present in the userlist is included
|
|
* in the returned metadata, otherwise the metadata returned only
|
|
* includes metadata from the masterlist.
|
|
* @returns The Bash Tag names, which may include duplicates.
|
|
*/
|
|
virtual std::vector<std::string> GetKnownBashTags(
|
|
bool includeUserMetadata = true) const = 0;
|
|
|
|
/**
|
|
* @brief Gets the Bash Tags that are listed in the loaded userlist.
|
|
* @details Bash Tag suggestions can include Bash Tags not in this list.
|
|
* @returns The Bash Tag names, which may include duplicates.
|
|
*/
|
|
virtual std::vector<std::string> GetUserKnownBashTags() const = 0;
|
|
|
|
/**
|
|
* @brief Sets the known Bash Tags to store in the userlist, overwriting any
|
|
* existing definitions there.
|
|
* @param bashTags
|
|
* The Bash Tag names to set.
|
|
*/
|
|
virtual void SetUserKnownBashTags(
|
|
const std::vector<std::string>& bashTags) = 0;
|
|
|
|
/**
|
|
* @brief Get all general messages listed in the loaded metadata lists.
|
|
* @param includeUserMetadata
|
|
* If true, any general messages present in the userlist are included
|
|
* in the returned metadata, otherwise the metadata returned only
|
|
* includes metadata from the masterlist.
|
|
* @param 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.
|
|
* @returns The messages supplied in the metadata lists that are not attached
|
|
* to any particular plugin.
|
|
*/
|
|
virtual std::vector<Message> GetGeneralMessages(
|
|
bool includeUserMetadata = true,
|
|
bool evaluateConditions = false) const = 0;
|
|
|
|
/**
|
|
* @brief Get all general messages listed in the loaded userlist.
|
|
* @param 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.
|
|
* @returns A vector of messages supplied in the userlist but not attached to
|
|
* any particular plugin.
|
|
*/
|
|
virtual std::vector<Message> GetUserGeneralMessages(
|
|
bool evaluateConditions = false) const = 0;
|
|
|
|
/**
|
|
* @brief Sets the general messages to store in the userlist, replacing any
|
|
* messages already stored there.
|
|
* @param messages
|
|
* The messages to set.
|
|
*/
|
|
virtual void SetUserGeneralMessages(const std::vector<Message>& messages) = 0;
|
|
|
|
/**
|
|
* @brief Gets the groups that are defined in the loaded metadata lists.
|
|
* @param 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.
|
|
* @returns The Group objects. Each Group's name is unique, if a group has
|
|
* masterlist and user metadata the two are merged into a single
|
|
* group object.
|
|
*/
|
|
virtual std::vector<Group> GetGroups(
|
|
bool includeUserMetadata = true) const = 0;
|
|
|
|
/**
|
|
* @brief Gets the groups that are defined or extended in the loaded userlist.
|
|
* @returns The Group objects.
|
|
*/
|
|
virtual std::vector<Group> GetUserGroups() const = 0;
|
|
|
|
/**
|
|
* @brief Sets the group definitions to store in the userlist, overwriting any
|
|
* existing definitions there.
|
|
* @param groups
|
|
* The Group objects to set.
|
|
*/
|
|
virtual void SetUserGroups(const std::vector<Group>& groups) = 0;
|
|
|
|
/**
|
|
* @brief Get the "shortest" path between the two given groups according to
|
|
* their load after metadata.
|
|
* @details 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.
|
|
* @param fromGroupName
|
|
* The name of the source group, that loads earlier.
|
|
* @param toGroupName
|
|
* The name of the destination group, that loads later.
|
|
* @returns A vector of Vertex elements representing the path from the source
|
|
* group to the destination group, or an empty vector if no path
|
|
* exists.
|
|
*/
|
|
virtual std::vector<Vertex> GetGroupsPath(
|
|
std::string_view fromGroupName,
|
|
std::string_view toGroupName) const = 0;
|
|
|
|
/**
|
|
* @}
|
|
* @name Plugin Data Access
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Get all a plugin's loaded metadata.
|
|
* @param plugin
|
|
* The filename of the plugin to look up metadata for.
|
|
* @param 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.
|
|
* @param 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.
|
|
* @returns If the plugin has metadata, an optional containing that metadata,
|
|
* otherwise an optional containing no value.
|
|
*/
|
|
virtual std::optional<PluginMetadata> GetPluginMetadata(
|
|
std::string_view plugin,
|
|
bool includeUserMetadata = true,
|
|
bool evaluateConditions = false) const = 0;
|
|
|
|
/**
|
|
* @brief Get a plugin's metadata loaded from the given userlist.
|
|
* @param plugin
|
|
* The filename of the plugin to look up user-added metadata for.
|
|
* @param 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.
|
|
* @returns If the plugin has user-added metadata, an optional containing
|
|
* that metadata, otherwise an optional containing no value.
|
|
*/
|
|
virtual std::optional<PluginMetadata> GetPluginUserMetadata(
|
|
std::string_view plugin,
|
|
bool evaluateConditions = false) const = 0;
|
|
|
|
/**
|
|
* @brief Sets a plugin's user metadata.
|
|
* @param pluginMetadata
|
|
* The user metadata you want to set, with plugin.GetName() being the
|
|
* filename of the plugin the metadata is for, or a regex that matches
|
|
* the relevant filenames.
|
|
*
|
|
* If the plugin metadata's name is not a regex name, any existing user
|
|
* metadata for that plugin name will be replaced.
|
|
*
|
|
* If the plugin metadata has a regex name, the given metadata object
|
|
* will be appended to the list of regex metadata entries, and any
|
|
* existing entries with the same regex name will be retained.
|
|
*/
|
|
virtual void SetPluginUserMetadata(const PluginMetadata& pluginMetadata) = 0;
|
|
|
|
/**
|
|
* @brief Discards all loaded user metadata for the plugin with the given
|
|
* filename.
|
|
* @details Does not discard any plugin metadata with plugin name regexes
|
|
* that match the given filename.
|
|
*
|
|
* Has no effect if the given plugin name contains any of the
|
|
* characters `:\*?|`.
|
|
* @param plugin
|
|
* The filename of the plugin for which all user-added metadata
|
|
* should be deleted.
|
|
*/
|
|
virtual void DiscardPluginUserMetadata(std::string_view plugin) = 0;
|
|
|
|
/**
|
|
* @brief Discards all loaded user metadata for all plugins, and any
|
|
* user-added general messages and known bash tags.
|
|
*/
|
|
virtual void DiscardAllUserMetadata() = 0;
|
|
|
|
/** @} */
|
|
};
|
|
}
|
|
|
|
#endif
|