diff --git a/docs/api/Doxyfile b/docs/api/Doxyfile index b010b277..099bccf8 100644 --- a/docs/api/Doxyfile +++ b/docs/api/Doxyfile @@ -784,6 +784,7 @@ WARN_LOGFILE = INPUT = include/loot \ include/loot/enum \ include/loot/exception \ + include/loot/metadata \ include/loot/struct # This tag can be used to specify the character encoding of the source files diff --git a/docs/api/reference.rst b/docs/api/reference.rst index 47e9d019..f83c95e9 100644 --- a/docs/api/reference.rst +++ b/docs/api/reference.rst @@ -11,6 +11,8 @@ Enumerations .. doxygenenum:: loot::LanguageCode +.. doxygenenum:: loot::LogVerbosity + .. doxygenenum:: loot::MessageType .. doxygenenum:: loot::PluginCleanliness @@ -27,9 +29,13 @@ Public-Field Data Structures Functions ========= +.. doxygenfunction:: loot::SetLoggingVerbosity + +.. doxygenfunction:: loot::SetLogFile + .. doxygenfunction:: loot::IsCompatible -.. doxygenfunction:: loot::CreateDatabase +.. doxygenfunction:: loot::CreateGameHandle Interfaces ========== @@ -37,12 +43,48 @@ Interfaces .. doxygenclass:: loot::DatabaseInterface :members: +.. doxygenclass:: loot::GameInterface + :members: + +.. doxygenclass:: loot::PluginInterface + :members: + Classes ======= +.. doxygenclass:: loot::ConditionalMetadata + :members: + +.. doxygenclass:: loot::File + :members: + +.. doxygenclass:: loot::Language + :members: + +.. doxygenclass:: loot::Location + :members: + .. doxygenclass:: loot::LootVersion :members: +.. doxygenclass:: loot::MessageContent + :members: + +.. doxygenclass:: loot::Message + :members: + +.. doxygenclass:: loot::PluginCleaningData + :members: + +.. doxygenclass:: loot::PluginMetadata + :members: + +.. doxygenclass:: loot::Priority + :members: + +.. doxygenclass:: loot::Tag + :members: + Exceptions ========== diff --git a/include/loot/database_interface.h b/include/loot/database_interface.h index 26aa361b..4274fdb5 100644 --- a/include/loot/database_interface.h +++ b/include/loot/database_interface.h @@ -202,7 +202,7 @@ public: /** * @brief Sets a plugin's user metadata, overwriting any existing user * metadata. - * @param plugin + * @param pluginMetadata * The user metadata you want to set, with plugin.Name() being the * filename of the plugin the metadata is for. */ diff --git a/include/loot/language.h b/include/loot/language.h index f8aea71f..e1e44ca4 100644 --- a/include/loot/language.h +++ b/include/loot/language.h @@ -32,15 +32,53 @@ #include "loot/enum/language_code.h" namespace loot { +/** + * @brief Represents a language, and used to map between API language codes, + * locale codes and language names. + */ class Language { public: + /** + * @brief A convenience constant that contains all available language codes. + */ LOOT_API static const std::vector codes; + /** + * @brief Construct a Language object. + * @param code + * A LOOT API language code. + * @return A Language object for the given code. + */ LOOT_API Language(const LanguageCode code); + + /** + * @brief Construct a Language object. + * @param locale + * A POSIX locale code. + * @return A Language object. If the locale code corresponds to a language + * with a LanguageCode value, the object is for that language, + * otherwise it is for English. + */ LOOT_API Language(const std::string& locale); + /** + * Get the language's LanguageCode. + * @return The language's LanguageCode. + */ LOOT_API LanguageCode GetCode() const; + + /** + * Get the language's name for itself. + * + * For example, ``Русский``, not ``Russian``. + * @return The language's name. + */ LOOT_API std::string GetName() const; + + /** + * Get the language's POSIX locale code. + * @return The language's POSIX locale code. + */ LOOT_API std::string GetLocale() const; private: static LanguageCode GetCode(const std::string& locale); diff --git a/include/loot/metadata/conditional_metadata.h b/include/loot/metadata/conditional_metadata.h index 49f97cf2..12700db5 100644 --- a/include/loot/metadata/conditional_metadata.h +++ b/include/loot/metadata/conditional_metadata.h @@ -29,14 +29,45 @@ #include "loot/api_decorator.h" namespace loot { +/** + * A base class for metadata that can be conditional based on the result of + * evaluating a condition string. + */ class ConditionalMetadata { public: + /** + * Construct a ConditionalMetadata object with an empty condition string. + * @return A ConditionalMetadata object. + */ LOOT_API ConditionalMetadata(); + + /** + * Construct a ConditionalMetadata object with a given condition string. + * @param condition + * A condition string, as defined in the LOOT metadata syntax + * documentation. + * @return A ConditionalMetadata object. + */ LOOT_API ConditionalMetadata(const std::string& condition); + /** + * Check if the condition string is non-empty. + * @return True if the condition string is not empty, false otherwise. + */ LOOT_API bool IsConditional() const; + + /** + * Check if the condition string is syntactically valid. + * + * Throws a ``ConditionSyntaxError`` if the condition string's syntax is not + * valid. + */ LOOT_API void ParseCondition() const; + /** + * Get the condition string. + * @return The object's condition string. + */ LOOT_API std::string GetCondition() const; private: std::string condition_; diff --git a/include/loot/metadata/file.h b/include/loot/metadata/file.h index d2afaaac..581060e3 100644 --- a/include/loot/metadata/file.h +++ b/include/loot/metadata/file.h @@ -30,16 +30,55 @@ #include "loot/metadata/conditional_metadata.h" namespace loot { +/** + * Represents a file in a game's Data folder, including files in subdirectories. + */ class File : public ConditionalMetadata { public: + /** + * Construct a File with blank name, display and condition strings. + * @return A File object. + */ LOOT_API File(); + + /** + * Construct a File with the given name, display name and condition strings. + * @param name + * The filename of the file. + * @param display + * The name to be displayed for the file in messages. + * @param condition + * The File's condition string. + * @return A File object. + */ LOOT_API File(const std::string& name, const std::string& display = "", const std::string& condition = ""); + /** + * A less-than operator implemented with no semantics so that File objects can + * be stored in sets. + * @returns True if this File's name is case-insensitively lexicographically + * less than the given File's name, false otherwise. + */ LOOT_API bool operator < (const File& rhs) const; + + /** + * Check if two File objects are equal by comparing their filenames. + * @returns True if the filenames are case-insensitively equal, false + * otherwise. + */ LOOT_API bool operator == (const File& rhs) const; + /** + * Get the filename of the file. + * @return The file's filename. + */ LOOT_API std::string GetName() const; + + /** + * Get the display name of the file. + * @return The file's display name. + */ LOOT_API std::string GetDisplayName() const; private: std::string name_; diff --git a/include/loot/metadata/location.h b/include/loot/metadata/location.h index 5af6b506..1aa2b220 100644 --- a/include/loot/metadata/location.h +++ b/include/loot/metadata/location.h @@ -30,15 +30,52 @@ #include "loot/api_decorator.h" namespace loot { +/** + * Represents a URL at which the parent plugin can be found. + */ class Location { public: + /** + * Construct a Location with empty URL and name strings. + * @return A Location object. + */ LOOT_API Location(); + + /** + * Construct a Location with the given URL and name. + * @param url + * The URL at which the plugin can be found. + * @param name + * A name for the URL, eg. the page or site name. + * @return A Location object. + */ LOOT_API Location(const std::string& url, const std::string& name = ""); + /** + * A less-than operator implemented with no semantics so that Location objects + * can be stored in sets. + * @returns True if this Location's URL is case-insensitively + * lexicographically less than the given Location's URL, false + * otherwise. + */ LOOT_API bool operator < (const Location& rhs) const; + + /** + * Check if two Location objects are equal by comparing their URLs. + * @returns True if the URLs are case-insensitively equal, false otherwise. + */ LOOT_API bool operator == (const Location& rhs) const; + /** + * Get the object's URL. + * @return A URL string. + */ LOOT_API std::string GetURL() const; + + /** + * Get the object's name. + * @return The name of the location. + */ LOOT_API std::string GetName() const; private: std::string url_; diff --git a/include/loot/metadata/message.h b/include/loot/metadata/message.h index 7caae54c..67ae76b4 100644 --- a/include/loot/metadata/message.h +++ b/include/loot/metadata/message.h @@ -35,21 +35,91 @@ #include "loot/struct/simple_message.h" namespace loot { +/** + * Represents a message with localisable text content. + */ class Message : public ConditionalMetadata { public: + /** + * Construct a Message object of type 'say' with blank content and condition + * strings. + * @return A Message object. + */ LOOT_API Message(); + + /** + * Construct a Message object with the given type, English content and + * condition string. + * @param type + * The message type. + * @param content + * The English message content text. + * @param condition + * A condition string. + * @return A Message object. + */ LOOT_API Message(const MessageType type, const std::string& content, const std::string& condition = ""); + + /** + * Construct a Message object with the given type, content and condition + * string. + * @param type + * The message type. + * @param content + * The message content. If multilingual, one language must be English. + * @param condition + * A condition string. + * @return A Message object. + */ LOOT_API Message(const MessageType type, const std::vector& content, const std::string& condition = ""); + /** + * A less-than operator implemented with no semantics so that Message objects + * can be stored in sets. + * @returns If both messages have content, returns true if this Message's + * English text is case-insensitively lexicographically less than the + * given Message's English text, and false otherwise. + * Otherwise returns true if this Message has no content, and false + * otherwise. + */ LOOT_API bool operator < (const Message& rhs) const; + + /** + * Check if two Message objects are equal by comparing their content. + * @returns True if the contents are equal, false otherwise. + */ LOOT_API bool operator == (const Message& rhs) const; + /** + * Get the message type. + * @return The message type. + */ LOOT_API MessageType GetType() const; + + /** + * Get the message content. + * @return The message's MessageContent objects. + */ LOOT_API std::vector GetContent() const; + + /** + * Get the message content given a language. + * @param language + * The preferred language for the message content. + * @return A MessageContent object for the preferred language, or for English + * if a MessageContent object is not available for the given language. + */ LOOT_API MessageContent GetContent(const LanguageCode language) const; + /** + * Get the message as a SimpleMessage given a language. + * @param language + * The preferred language for the message content. + * @return A SimpleMessage object for the preferred language, or for English + * if message text is not available for the given language. + */ LOOT_API SimpleMessage ToSimpleMessage(const LanguageCode language) const; private: MessageType type_; diff --git a/include/loot/metadata/message_content.h b/include/loot/metadata/message_content.h index 63d00599..51c0d960 100644 --- a/include/loot/metadata/message_content.h +++ b/include/loot/metadata/message_content.h @@ -30,17 +30,65 @@ #include "loot/language.h" namespace loot { +/** + * Represents a message's localised text content. + */ class MessageContent { public: + /** + * Construct a MessageContent object with an empty English message string. + * @return A MessageContent object. + */ LOOT_API MessageContent(); + + /** + * Construct a Message object with the given text in the given language. + * @param text + * The message text. + * @param language + * The language that the message is written in. + * @return A MessageContent object. + */ LOOT_API MessageContent(const std::string& text, const LanguageCode language); + /** + * Get the message text. + * @return A string containing the message text. + */ LOOT_API std::string GetText() const; + + /** + * Get the message language. + * @return A code representing the language that the message is written in. + */ LOOT_API LanguageCode GetLanguage() const; + /** + * A less-than operator implemented with no semantics so that MessageContent + * objects can be stored in sets. + * @returns True if this MessageContent's text is case-insensitively + * lexicographically less than the given MessageContent's text, false + * otherwise. + */ LOOT_API bool operator < (const MessageContent& rhs) const; + + /** + * Check if two MessageContent objects are equal by comparing their texts. + * @returns True if the texts are case-insensitively equal, false otherwise. + */ LOOT_API bool operator == (const MessageContent& rhs) const; + /** + * Choose a MessageContent object from a vector given a language. + * @param content + * The MessageContent objects to choose between. + * @param language + * The LanguageCode for the preferred language to select. If no + * message in the preferred language is present, the English + * MessageContent will be returned. + * @return A MessageContent object. If the given vector is empty, a + * default-constructed MessageContent is returned. + */ LOOT_API static MessageContent Choose(const std::vector content, const LanguageCode language); private: diff --git a/include/loot/metadata/plugin_cleaning_data.h b/include/loot/metadata/plugin_cleaning_data.h index e0c65040..2aacd439 100644 --- a/include/loot/metadata/plugin_cleaning_data.h +++ b/include/loot/metadata/plugin_cleaning_data.h @@ -32,28 +32,123 @@ #include "loot/metadata/message.h" namespace loot { +/** + * Represents data identifying the plugin under which it is stored as dirty or + * clean. + */ class PluginCleaningData { public: + /** + * 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. + */ LOOT_API PluginCleaningData(); + + /** + * Construct a PluginCleaningData object with the given CRC and utility, + * zero ITM count, deleted reference count and deleted navmesh count + * values and no info. + * @param crc + * The CRC of a plugin. + * @param utility + * The utility that the plugin cleanliness was checked with. + * @return A PluginCleaningData object. + */ LOOT_API PluginCleaningData(uint32_t crc, const std::string& utility); + + /** + * Construct a PluginCleaningData object with the given values. + * @param crc + * A clean or dirty plugin's CRC. + * @param utility + * The utility that the plugin cleanliness was checked with. + * @param info + * A vector of localised information message strings about the plugin + * cleanliness. + * @param itm + * The number of Identical To Master records found in the plugin. + * @param ref + * The number of deleted references found in the plugin. + * @param nav + * The number of deleted navmeshes found in the plugin. + * @return A PluginCleaningData object. + */ LOOT_API PluginCleaningData(uint32_t crc, const std::string& utility, const std::vector& info, unsigned int itm, unsigned int ref, unsigned int nav); - + /** + * A less-than operator implemented with no semantics so that + * PluginCleaningData objects can be stored in sets. + * @returns True if this PluginCleaningData's CRC is less than the given + * PluginCleaningData's CRC, false otherwise. + */ LOOT_API bool operator < (const PluginCleaningData& rhs) const; + + /** + * Check if two PluginCleaningData objects are equal by comparing their CRCs. + * @returns True if the CRCs are equal, false otherwise. + */ LOOT_API bool operator == (const PluginCleaningData& rhs) const; + /** + * Get the CRC that identifies the plugin that the cleaning data is for. + * @return A CRC-32 checksum. + */ LOOT_API uint32_t GetCRC() const; + + /** + * Get the number of Identical To Master records in the plugin. + * @return The number of Identical To Master records in the plugin. + */ LOOT_API unsigned int GetITMCount() const; + + /** + * Get the number of deleted references in the plugin. + * @return The number of deleted references in the plugin. + */ LOOT_API unsigned int GetDeletedReferenceCount() const; + + /** + * Get the number of deleted navmeshes in the plugin. + * @return The number of deleted navmeshes in the plugin. + */ LOOT_API unsigned int GetDeletedNavmeshCount() 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. + */ LOOT_API std::string GetCleaningUtility() 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. + */ LOOT_API std::vector GetInfo() const; + /** + * Choose an info MessageContent object given a preferred language. + * @param language + * The preferred language's LanguageCode. + * @return The MessageContent object for the preferred language, or if one + * does not exist, the English-language MessageContent object. + */ LOOT_API MessageContent ChooseInfo(const LanguageCode language) const; + + /** + * Get a warning message describing the cleaning data. + * @return A Message object detailing the number and types of dirty edits + * found, the cleaning utility used, plus any additional information. + */ LOOT_API Message AsMessage() const; private: uint32_t crc_; diff --git a/include/loot/metadata/plugin_metadata.h b/include/loot/metadata/plugin_metadata.h index 80c66e78..85c30004 100644 --- a/include/loot/metadata/plugin_metadata.h +++ b/include/loot/metadata/plugin_metadata.h @@ -41,57 +41,264 @@ #include "loot/metadata/tag.h" namespace loot { +/** + * Represents a plugin's metadata. + */ class PluginMetadata { public: + /** + * Construct a PluginMetadata object with a blank plugin name and no metadata. + * @return A PluginMetadata object. + */ LOOT_API PluginMetadata(); + + /** + * Construct a PluginMetadata object with no metadata for a plugin with the + * given filename. + * @param name + * The filename of the plugin that the object is constructed for. + * @return A PluginMetadata object. + */ LOOT_API PluginMetadata(const std::string& name); //Merges from the given plugin into this one, unless there is already equal metadata present. //For 'enabled' and 'priority' metadata, use the given plugin's values, but if the 'priority' user value is zero, ignore it. + /** + * 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. + * @param plugin + * The plugin metadata to merge. + */ LOOT_API void MergeMetadata(const PluginMetadata& plugin); // Returns metadata in this plugin not in the given plugin. //For 'enabled', use this plugin's value. //For 'priority', use 0 if the two plugin priorities are equal, and make it not explicit. Otherwise use this plugin's value. + + /** + * Get metadata in this object that isn't present in the given PluginMetadata + * object. + * @param plugin + * The PluginMetadata object to compare against. + * @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. + */ LOOT_API PluginMetadata NewMetadata(const PluginMetadata& plugin) const; + /** + * Get the plugin name. + * @return The plugin name. + */ LOOT_API std::string GetName() const; + + /** + * Get the lowercased plugin name. + * @return The lowercased plugin name. + */ LOOT_API std::string GetLowercasedName() const; + + /** + * Check if the plugin metadata is enabled for use during sorting. + * @return True if the metadata will be used during sorting, false otherwise. + */ LOOT_API bool IsEnabled() const; + + /** + * Get the plugin's local priority metadata. + * @return The plugin's local priority metadata. + */ LOOT_API Priority GetLocalPriority() const; + + /** + * Get the plugin's global priority metadata. + * @return The plugin's global priority metadata. + */ LOOT_API Priority GetGlobalPriority() const; + + /** + * Get the plugins that the plugin must load after. + * @return The plugins that the plugin must load after. + */ LOOT_API std::set GetLoadAfterFiles() const; + + /** + * Get the files that the plugin requires to be installed. + * @return The files that the plugin requires to be installed. + */ LOOT_API std::set GetRequirements() const; + + /** + * Get the files that the plugin is incompatible with. + * @return The files that the plugin is incompatible with. + */ LOOT_API std::set GetIncompatibilities() const; + + /** + * Get the plugin's messages. + * @return The plugin's messages. + */ LOOT_API std::vector GetMessages() const; + + /** + * Get the plugin's Bash Tag suggestions. + * @return The plugin's Bash Tag suggestions. + */ LOOT_API std::set GetTags() const; + + /** + * Get the plugin's dirty plugin information. + * @return The PluginCleaningData objects that identify the plugin as dirty. + */ LOOT_API std::set GetDirtyInfo() const; + + /** + * Get the plugin's clean plugin information. + * @return The PluginCleaningData objects that identify the plugin as clean. + */ LOOT_API std::set GetCleanInfo() const; + + /** + * Get the locations at which this plugin can be found. + * @return The locations at which this plugin can be found. + */ LOOT_API std::set GetLocations() const; + /** + * Get the plugin's messages as SimpleMessage objects for the given language. + * @param language + * The language to create the SimpleMessage objects for. + * @return The plugin's messages as SimpleMessage objects. + */ LOOT_API std::vector GetSimpleMessages(const LanguageCode language) const; + /** + * Set whether the plugin metadata is enabled for use during sorting or not. + * @param enabled + * The value to set. + */ LOOT_API void SetEnabled(const bool enabled); + + /** + * Set the plugin's local priority. + * @param priority + * The value to set. + */ LOOT_API void SetLocalPriority(const Priority& priority); + + /** + * Set the plugin's local priority. + * @param priority + * The value to set. + */ LOOT_API void SetGlobalPriority(const Priority& priority); + + /** + * Set the files that the plugin must load after. + * @param after + * The files to set. + */ LOOT_API void SetLoadAfterFiles(const std::set& after); - LOOT_API void SetRequirements(const std::set& reqs); - LOOT_API void SetIncompatibilities(const std::set& incs); + + /** + * Set the files that the plugin requires to be installed. + * @param requirements + * The files to set. + */ + LOOT_API void SetRequirements(const std::set& requirements); + + /** + * Set the files that the plugin must load after. + * @param incompatibilities + * The files to set. + */ + LOOT_API void SetIncompatibilities(const std::set& incompatibilities); + + /** + * Set the plugin's messages. + * @param messages + * The messages to set. + */ LOOT_API void SetMessages(const std::vector& messages); + + /** + * Set the plugin's Bash Tag suggestions. + * @param tags + * The Bash Tag suggestions to set. + */ LOOT_API void SetTags(const std::set& tags); + + /** + * Set the plugin's dirty information. + * @param info + * The dirty information to set. + */ LOOT_API void SetDirtyInfo(const std::set& info); + + /** + * Set the plugin's clean information. + * @param info + * The clean information to set. + */ LOOT_API void SetCleanInfo(const std::set& info); + + /** + * Set the plugin's locations. + * @param locations + * The locations to set. + */ LOOT_API void SetLocations(const std::set& locations); + /** + * 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. + */ LOOT_API bool HasNameOnly() const; + + /** + * Check if the plugin name is a regular expression. + * @return True if the plugin name contains any of the characters ``:\*?|``, + * false otherwise. + */ LOOT_API bool IsRegexPlugin() const; - //Compare name strings. + /** + * Check if two PluginMetadata objects are equal by comparing their name + * values. + * @returns True if the plugin names are case-insensitively equal, false + * otherwise. + */ LOOT_API bool operator == (const PluginMetadata& rhs) const; + + /** + * Check if two PluginMetadata objects are not equal by comparing their name + * values. + * @returns True if the plugin names are not case-insensitively equal, false + * otherwise. + */ LOOT_API bool operator != (const PluginMetadata& rhs) const; - //Compare name string. + + /** + * Check if object's name value is equal to the given string. + * @returns True if the plugin name is case-insensitively equal to the given + * string, false otherwise. + */ LOOT_API bool operator == (const std::string& rhs) const; + + /** + * Check if object's name value is not equal to the given string. + * @returns True if the plugin name is not case-insensitively equal to the + * given string, false otherwise. + */ LOOT_API bool operator != (const std::string& rhs) const; private: std::string name_; @@ -110,8 +317,16 @@ private: } namespace std { +/** + * A specialisation of std::hash for loot::PluginMetadata. + */ template<> struct hash { + /** + * Calculate a hash value for an object of a class that implements + * loot::PluginMetadata. + * @return The hash generated from the plugin's lowercased filename. + */ size_t operator() (const loot::PluginMetadata& plugin) const { return hash()(plugin.GetLowercasedName()); } diff --git a/include/loot/metadata/priority.h b/include/loot/metadata/priority.h index 8c135562..16fe27de 100644 --- a/include/loot/metadata/priority.h +++ b/include/loot/metadata/priority.h @@ -29,23 +29,85 @@ #include "loot/api_decorator.h" namespace loot { +/** + * 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. + */ class Priority { public: + /** + * Construct a Priority object with an implicit value of zero. + * @return A Priority object. + */ LOOT_API Priority(); + // Take an int to prevent literals that are too large for one byte from // wrapping around to negative values. + /** + * 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. + * @param 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. + * @return A Priority object. + */ LOOT_API explicit Priority(const int value); - // Doesn't return an int8_t because it is commonly signed char, which - // yaml-cpp interprets as a character rather than an integer. + /** + * 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. + */ LOOT_API short GetValue() 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. + */ LOOT_API bool IsExplicit() const; + /** + * Check if this Priority object is less than another. + * @return True if this Priority object's value is less than the given + * Priority object's value. + */ LOOT_API bool operator < (const Priority& rhs) const; + + /** + * Check if this Priority object is greater than another. + * @return True if this Priority object's value is greater than the given + * Priority object's value, false otherwise. + */ LOOT_API bool operator > (const Priority& rhs) const; + + /** + * Check if this Priority object is greater than or equal to another. + * @return True if this Priority object's value is greater than or equal to + * the given Priority object's value, false otherwise. + */ LOOT_API bool operator >= (const Priority& rhs) const; + + /** + * Check if this Priority object is equal to another. + * @return True if this Priority object's value is equal to the given + * Priority object's value, false otherwise. + */ LOOT_API bool operator == (const Priority& rhs) const; + + /** + * Check if this Priority object is greater than a given priority value. + * @return True if this Priority object's value is greater than the given + * value, false otherwise. + */ LOOT_API bool operator > (const uint8_t rhs) const; private: diff --git a/include/loot/metadata/tag.h b/include/loot/metadata/tag.h index f23c3125..9acf3519 100644 --- a/include/loot/metadata/tag.h +++ b/include/loot/metadata/tag.h @@ -30,17 +30,62 @@ #include "loot/metadata/conditional_metadata.h" namespace loot { +/** + * Represents a Bash Tag suggestion for a plugin. + */ class Tag : public ConditionalMetadata { public: + /** + * Construct a Tag object with an empty tag name suggested for addition, with + * an empty condition string. + * @return A Tag object. + */ LOOT_API Tag(); + + /** + * Construct a Tag object with the given name, for addition or removal, with + * the given condition string. + * @param tag + * The name of the Bash Tag. + * @param isAddition + * True if the tag should be added, false if it should be removed. + * @param condition + * A condition string. + * @return A Tag object. + */ LOOT_API Tag(const std::string& tag, const bool isAddition = true, const std::string& condition = ""); + /** + * A less-than operator implemented with no semantics so that Tag objects + * can be stored in sets. + * @returns True if this Tag is suggested for addition and the other is not. + * If both Tags are suggested for addition or both are suggested for + * removal, returns true if this Tag's name is case-insensitively + * lexicographically less than the given Tag's name, false + * otherwise. + */ LOOT_API bool operator < (const Tag& rhs) const; + + /** + * Check if two Tag objects are equal. + * @returns True if both Tags are suggested for addition or both are suggested + * for removal, and the Tag names are case-insensitively equal, false + * otherwise. + */ LOOT_API bool operator == (const Tag& rhs) const; + /** + * Check if the tag should be added. + * @return True if the tag should be added, false if it should be removed. + */ LOOT_API bool IsAddition() const; + + /** + * Get the tag's name. + * @return The tag's name. + */ LOOT_API std::string GetName() const; private: std::string name_; diff --git a/include/loot/plugin_interface.h b/include/loot/plugin_interface.h index a7eb9b98..3f3bb6b4 100644 --- a/include/loot/plugin_interface.h +++ b/include/loot/plugin_interface.h @@ -32,26 +32,101 @@ #include "loot/metadata/tag.h" namespace loot { +/** + * Represents a plugin file that has been parsed by LOOT. + */ class PluginInterface { public: + /** + * Get the plugin's filename. + * @return The plugin filename. + */ virtual std::string GetName() const = 0; + + /** + * Get the plugin's filename in lowercase characters. + * @return The lowercased plugin filename. + */ virtual std::string GetLowercasedName() 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::string GetVersion() const = 0; + + /** + * Get the plugin's masters. + * @return The plugin's masters in the same order they are listed in the file. + */ virtual std::vector GetMasters() const = 0; + + /** + * Get any status messages associated with the plugin. + * + * For example, if parsing failed, it could be recorded in a status message. + * @return A vector of status messages. + */ virtual std::vector GetStatusMessages() 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::set GetBashTags() 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 uint32_t GetCRC() const = 0; + /** + * Check if the plugin's master flag is set. + * @return True if the master flag is set, false otherwise. + */ virtual bool IsMaster() 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 IsEmpty() 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 LoadsArchive() const = 0; + + /** + * Check if two plugins contain records for the same FormIDs. + * @param plugin + * The other plugin to check for FormID overlap with. + * @return True if the plugins both contain at least one record with the same + * FormID, false otherwise. + */ virtual bool DoFormIDsOverlap(const PluginInterface& plugin) const = 0; }; } namespace std { +/** + * A specialisation of std::hash for loot::PluginInterface. + */ template<> struct hash { + /** + * Calculate a hash value for an object of a class that implements + * loot::PluginInterface. + * @return The hash generated from the plugin's lowercased filename. + */ size_t operator() (const loot::PluginInterface& plugin) const { return hash()(plugin.GetLowercasedName()); } diff --git a/include/loot/windows_encoding_converters.h b/include/loot/windows_encoding_converters.h index d7395ddc..0ae15873 100644 --- a/include/loot/windows_encoding_converters.h +++ b/include/loot/windows_encoding_converters.h @@ -40,6 +40,15 @@ # include "shlwapi.h" namespace loot { +/** + * Convert a UTF-8 std::string to a UTF-16 std::wstring. + * + * This isn't strictly part of the LOOT API, but is used within the API and the + * LOOT application, so is shared through the API. + * @param str + * A string encoded in UTF-8. + * @return A wstring encoded in UTF-16. + */ inline std::wstring ToWinWide(const std::string& str) { size_t len = MultiByteToWideChar(CP_UTF8, 0, str.c_str(), str.length(), 0, 0); std::wstring wstr(len, 0); @@ -47,6 +56,15 @@ inline std::wstring ToWinWide(const std::string& str) { return wstr; } +/** + * Convert a UTF-16 std::wstring to a UTF-8 std::string. + * + * This isn't strictly part of the LOOT API, but is used within the API and the + * LOOT application, so is shared through the API. + * @param wstr + * A wstring encoded in UTF-16. + * @return A string encoded in UTF-8. + */ inline std::string FromWinWide(const std::wstring& wstr) { size_t len = WideCharToMultiByte(CP_UTF8, 0, wstr.c_str(), wstr.length(), NULL, 0, NULL, NULL); std::string str(len, 0);