diff --git a/cpp/docs/api/introduction.rst b/cpp/docs/api/introduction.rst index 287a325a..f03adf35 100644 --- a/cpp/docs/api/introduction.rst +++ b/cpp/docs/api/introduction.rst @@ -14,3 +14,26 @@ Users can also add to and modify the metadata used by LOOT through the use of userlist files. libloot provides all of LOOT's non-UI-related functionality, and can be used by third-party developers to access this metadata for use in their own programs. + +Metadata Files +============== + +LOOT stores plugin metadata in YAML files. It distinguishes between three types +of metadata file: + +- *masterlist* files: each game has a single masterlist, which is a public, + curated metadata store +- *masterlist prelude* files: there is a single masterlist prelude, which is a + public store of common metadata templates that can be shared across all + masterlists +- *userlist* files: each game has a userlist, which is a private user-specific + metadata store containing metadata added by the LOOT user. + +All three files use the same syntax, but the masterlist prelude file is used to +replace part of a masterlist file before it is parsed, and metadata in the +userlist extends or replaces metadata sourced from the masterlist. + +LOOT's plugin metadata can be conditional, eg. a plugin may require a patch only +if another plugin is also present. Conditions are not evaluated when metadata is +loaded by libloot: instead, they can be optionally evaluated when accessing the +loaded metadata. diff --git a/cpp/docs/api/miscellaneous.rst b/cpp/docs/api/miscellaneous.rst deleted file mode 100644 index d5aec79a..00000000 --- a/cpp/docs/api/miscellaneous.rst +++ /dev/null @@ -1,93 +0,0 @@ -********************* -Miscellaneous Details -********************* - -String Encoding -=============== - -* All output strings are encoded in UTF-8. -* Metadata files are written encoded in UTF-8. -* Input strings are expected to be encoded in UTF-8. -* Metadata files read are expected to be encoded in UTF-8. -* File paths are case-sensitive if and only if the underlying file system is - case-sensitive. - -Language Codes -============== - -All language strings in the API are codes of the form ``ll`` or ``ll_CC``, where -``ll`` is an ISO 639-1 language code and ``CC`` is an ISO 3166 country code. For -example, the default language for metadata message content is English, -identified by the code ``en``, and Brazilian Portuguese is ``pt_BR``. - -Errors -====== - -All errors encountered are thrown as exceptions that inherit from -``std::exception``. - -Metadata Files -============== - -LOOT stores plugin metadata in YAML files. It distinguishes between three types -of metadata file: - -- *masterlist* files: each game has a single masterlist, which is a public, - curated metadata store -- *masterlist prelude* files: there is a single masterlist prelude, which is a - public store of common metadata templates that can be shared across all - masterlists -- *userlist* files: each game has a userlist, which is a private user-specific - metadata store containing metadata added by the LOOT user. - -All three files use the same syntax, but the masterlist prelude file is used to -replace part of a masterlist file before it is parsed, and metadata in the -userlist extends or replaces metadata sourced from the masterlist. - -LOOT's plugin metadata can be conditional, eg. a plugin may require a patch only -if another plugin is also present. The API's -:cpp:func:`loot::DatabaseInterface::LoadLists()` method parses metadata files -into memory, but does not evaluate these conditions, so the loaded metadata may -contain metadata that is invalid for the installed game that the -:cpp:class:`loot::DatabaseInterface` object being operated on was created for. - -Caching -======= - -All unevaluated metadata is cached between calls to :cpp:func:`loot::DatabaseInterface::LoadLists`. - -The results of evaluating metadata conditions are cached between calls to -:cpp:func:`loot::GameInterface::LoadPlugins`, -:cpp:func:`loot::GameInterface::SortPlugins` and -:cpp:func:`loot::DatabaseInterface::GetGeneralMessages`. - -Plugin content is cached between calls to -:cpp:func:`loot::GameInterface::LoadPlugins` and -:cpp:func:`loot::GameInterface::SortPlugins`. - -Load order is cached between calls to -:cpp:func:`loot::GameInterface::LoadCurrentLoadOrderState`. - -Performance -=========== - -The following may involve filesystem access and reading/parsing or writing of -data from the filesystem: - -- Any function that takes a ``std::filesystem::path`` -- :cpp:any:`loot::GameInterface::IsValidPlugin()` -- :cpp:any:`loot::GameInterface::LoadPlugins()` -- :cpp:any:`loot::GameInterface::LoadCurrentLoadOrderState()` -- :cpp:any:`loot::GameInterface::SetLoadOrder()` - -Evaluating conditions may also involve filesystem read access. - -:cpp:any:`loot::GameInterface::SortPlugins()` is expensive, as it involves loading -all the content of all the plugins, apart from the game's main master file, which is skipped as an optimisation (it doesn't depend on anything else and is much bigger than any other plugin, so is unnecessary and slow to load). - -:cpp:any:`loot::DatabaseInterface::GetGroupsPath()` involves building a graph of all defined groups and -then using it to search for the shortest path between the two given groups, -which may be relatively slow given a sufficiently large and/or complex set of -group definitions. - -All other API functions should be relatively fast. diff --git a/cpp/docs/api/reference.rst b/cpp/docs/api/reference.rst index ff5691fd..6ba03061 100644 --- a/cpp/docs/api/reference.rst +++ b/cpp/docs/api/reference.rst @@ -3,6 +3,19 @@ API Reference ************* .. contents:: + :local: + +String Encoding +=============== + +* All output strings are encoded in UTF-8. +* Input strings are expected to be encoded in UTF-8. + +Errors +====== + +All errors encountered are thrown as exceptions that inherit from +``std::exception``. Constants ========= diff --git a/cpp/docs/index.rst b/cpp/docs/index.rst index d19d8bb7..b997994a 100644 --- a/cpp/docs/index.rst +++ b/cpp/docs/index.rst @@ -7,7 +7,6 @@ libloot :caption: API Documentation api/introduction - api/miscellaneous api/sorting api/reference api/licenses/index