Update docs

docs/api/changelog.rst

@@ -8,6 +8,13 @@ Version History
 Added
 -----
 
+- ``PluginCleaningData::with_condition()`` and
+  ``PluginCleaningData::condition()`` for setting and getting the new condition
+  field on plugin cleaning data objects. The C++ wrapper's
+  :cpp:any:`loot::PluginCleaningData` constructor has gained a ``condition``
+  parameter that defaults to an empty string, and
+  :cpp:any:`loot::PluginCleaningData::GetCondition()` can be used to get the
+  value that was passed to the constructor.
 - ``Database::clear_condition_cache()`` clears the cache of metadata
   condition evaluation results, allowing more control over when conditions are
   re-evaluated. As before, loading the current load order state, loading plugins
@@ -100,13 +107,14 @@ Changed
   global/general messages and plugin entries, and at the end of the file. Blank
   lines are also used to separate elements of the ``common`` list if it is
   written.
+- libloot now supports v0.29 of the metadata syntax.
 - Updated cxx and cxx-build to v1.0.192.
 - Updated sphinx_rtd_theme to v3.1.0.
 - Updated dependency versions in Cargo.lock (which sets the versions used by the
   C++ wrapper):
 
   - Updated log to v0.4.29.
-  - Updated loot-condition-interpreter to v5.4.0.
+  - Updated loot-condition-interpreter to v6.0.0.
   - Updated proc-macro2 to v1.0.105.
   - Updated quote to v1.0.43.
   - Updated regress to v0.10.5.

docs/metadata/changelog.rst

@@ -4,6 +4,45 @@ Version History
 
 The version history of the metadata syntax is given below.
 
+0.29 - Unreleased
+=================
+
+Added
+-----
+
+- The cleaning data structure now has an optional ``condition`` key that takes a
+  condition string that must evaluate to true for the cleaning data to be
+  considered relevant.
+- When supplying parameters for version condition functions, the comparator and
+  version string can now be swapped for readability, e.g.
+  ``version("example.esp", ==, "1.0.0")``,
+  ``product_version("example.exe", ==, "1.0.0")`` and
+  ``filename_version("example (.+).esp", ==, "1.0.0")``.
+
+  The new ordering of the parameters should be preferred, and the existing order
+  (file path, version string then comparator) is deprecated and may be removed
+  in a future version of the metadata syntax.
+
+Fixed
+-----
+
+- The documentation described the ``description_contains()`` condition
+  function's regex parameter in the same way as the regex file paths accepted by
+  some other functions, when it's actually a relatively arbitrary regex that
+  may match a substring of a plugin's description field.
+
+Changed
+-------
+
+- When evaluating ``version()`` and ``product_version()`` conditions and no
+  version could be read from the given file path (e.g. because the file does not
+  exist), the function now always evaluates to false. Previously it would
+  evaluate to true when the comparator was ``<``, ``<=`` or ``!=``, and false
+  otherwise.
+- Plugin metadata name regexes now support modifiers.
+- The specific regex syntax and features supported are now explicitly decoupled
+  from metadata syntax versioning, so they can change independently.
+
 0.26 - 2025-04-19
 =================
 

docs/metadata/conditions.rst

@@ -41,7 +41,16 @@ Types
 
 .. describe:: regular_expression
 
-  A double-quoted file path, with a regular expression in place of a filename. The path must use ``/`` for directory separators, not ``\``. The regular expression must be written in a `modified Perl <https://docs.rs/regex/1.0.5/regex/index.html#syntax>`_ syntax.
+  A double-quoted regular expression that is case-insensitive and Unicode-aware.
+
+  .. note::
+    The regular expression is currently expected to be written in a `modified Perl <https://docs.rs/regex/1.0.5/regex/index.html#syntax>`_ syntax.
+
+    The specific syntax and features supported are an implementation detail that may change without changing the masterlist syntax version, so it's best to restrict regexes to the common subset that is supported across several regex flavours and implementations.
+
+.. describe:: regular_expression_path
+
+  A double-quoted file path, with a regular expression in place of a filename. The path must use ``/`` for directory separators, not ``\``. The filename regular expression is prefixed with ``^`` and suffixed with ``$`` before evaluation to ensure that it only matches whole filenames.
 
   Only the filename path component will be evaluated as a regular expression. For example, given the regex file path ``Meshes/Resources(1|2)/(upperclass)?table.nif``, LOOT will look for a file named ``table.nif`` or ``upperclasstable.nif`` in the ``Meshes\Resources(1|2)`` folder, rather than looking in the ``Meshes\Resources1`` and ``Meshes\Resources2`` folders.
 
@@ -90,7 +99,7 @@ There are several conditions that can be tested for using the functions detailed
 
   Returns true if ``path`` is installed, and false otherwise.
 
-.. describe:: file(regular_expression regex)
+.. describe:: file(regular_expression_path regex)
 
   Returns true if a file matching ``regex`` is found, and false otherwise.
 
@@ -109,15 +118,15 @@ There are several conditions that can be tested for using the functions detailed
 
   Returns true if ``path`` is an active plugin, and false otherwise.
 
-.. describe:: active(regular_expression regex)
+.. describe:: active(regular_expression_path regex)
 
   Returns true if an active plugin matching ``regex`` is found, and false otherwise.
 
-.. describe:: many(regular_expression regex)
+.. describe:: many(regular_expression_path regex)
 
   Returns true if more than one file matching ``regex`` is found, and false otherwise.
 
-.. describe:: many_active(regular_expression regex)
+.. describe:: many_active(regular_expression_path regex)
 
   Returns true if more than one active plugin matching ``regex`` is found, and false otherwise.
 
@@ -134,7 +143,7 @@ There are several conditions that can be tested for using the functions detailed
 
   Returns true if the calculated CRC-32 checksum of ``path`` matches ``expected_checksum``, and false otherwise. Returns false if ``path`` does not exist.
 
-.. describe:: version(file_path path, version given_version, comparison_operator comparator)
+.. describe:: version(file_path path, comparison_operator comparator, version given_version)
 
   Returns true if the boolean expression::
 
@@ -146,16 +155,20 @@ There are several conditions that can be tested for using the functions detailed
   * If ``path`` is a plugin, its version is read from its description field.
   * If ``path`` is not a plugin, it will be assumed to be an executable (e.g.
     ``*.exe`` or ``*.dll``), and its version is read from its File Version field.
-  * If ``path`` does not exist or does not have a version number, the condition
-    evaluates to true for the ``!=``, ``<`` and ``<=`` comparators, i.e. a
-    missing version is always less than the given version.
+  * If ``path`` does not exist or does not have a version number, the function
+    returns false.
   * If ``path`` is not readable or is not a plugin or an executable, an error
     will occur.
 
   The supported version syntax and precedence rules are detailed in the section
   below.
 
-.. describe:: product_version(file_path path, version given_version, comparison_operator comparator)
+.. describe:: version(file_path path, version given_version, comparison_operator comparator)
+
+  An older, deprecated form of
+  ``version(file_path path, comparison_operator comparator, version given_version)``.
+
+.. describe:: product_version(file_path path, comparison_operator comparator, version given_version)
 
   Returns true if the boolean expression::
 
@@ -165,15 +178,19 @@ There are several conditions that can be tested for using the functions detailed
   false otherwise. ``path`` must be an executable (e.g. ``*.exe`` or ``*.dll``),
   and its version is read from its Product Version field.
 
-  * If ``path`` does not exist or does not have a version number, the condition
-    evaluates to true for the ``!=``, ``<`` and ``<=`` comparators, i.e. a
-    missing version is always less than the given version.
+  * If ``path`` does not exist or does not have a version number, the function
+    returns false.
   * If ``path`` is not a readable executable, an error will occur.
 
   The supported version syntax and precedence rules are detailed in the section
   below.
 
-.. describe:: filename_version(regular_expression path, version given_version, comparison_operator comparator)
+.. describe:: product_version(file_path path, version given_version, comparison_operator comparator)
+
+  An older, deprecated form of
+  ``product_version(file_path path, comparison_operator comparator, version given_version)``.
+
+.. describe:: filename_version(regular_expression_path path, comparison_operator comparator, version given_version)
 
   The regex in ``path`` must contain a single capturing group.
 
@@ -185,9 +202,17 @@ There are several conditions that can be tested for using the functions detailed
   (where ``actual_version`` is the value captured by the regex) holds true, and
   false otherwise.
 
-  Unlike the other version functions, it always returns false if it cannot find
-  a version to compare against the given version, irrespective of the given
-  comparison operator.
+  If the contents of the parent directory of the filename component of ``path``
+  can't be read, an error will occur.
+
+  If the function can't find a version to compare against the given file path
+  (e.g. because there is no matching filename in the parent path), it always
+  returns false.
+
+.. describe:: filename_version(regular_expression_path path, version given_version, comparison_operator comparator)
+
+  An older, deprecated form of
+  ``filename_version(regular_expression_path path, comparison_operator comparator, version given_version)``.
 
 .. describe:: description_contains(file_path path, regular_expression regex)
 

docs/metadata/data_structures/cleaning.rst

@@ -39,6 +39,10 @@ This structure holds information on which versions of a plugin are dirty or clea
 
   The number of deleted navmeshes reported for the dirty plugin. If undefined, defaults to zero.
 
+.. describe:: condition
+
+  A condition string that is evaluated to determine whether this cleaning data should be used: if it evaluates to true, the data is used, otherwise it is ignored. See :doc:`../conditions` for details.
+
 Equality
 --------
 

docs/metadata/data_structures/file.rst

@@ -55,5 +55,5 @@ Scalar form::
 Map form::
 
   name: '../obse_loader.exe'
-  condition: 'version("../obse_loader.exe", "0.0.18.0", >=)'
+  condition: 'version("../obse_loader.exe", >=, "0.0.18.0")'
   display: 'OBSE v18+'

docs/metadata/data_structures/plugin.rst

@@ -9,11 +9,15 @@ This is the structure that brings all the others together, and forms the main co
 
   **Required.** Can be an exact plugin filename or a regular expression plugin filename. If the filename contains any of the characters ``:\*?|``, the string will be treated as a regular expression, otherwise it will be treated as an exact filename. For example, ``Example\.esm`` will be treated as a regular expression, as it contains a ``\`` character.
 
-  Regular expression plugin filenames must be written in a modified `ECMAScript <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions>`_ syntax. Notable differences include:
+  Regular expression plugin filenames are prefixed with ``^`` and suffixed with ``$`` to ensure they match whole filenames, and are case-insensitive and Unicode-aware.
 
-  - Some ``\p{}`` and ``\P{}`` `Unicode character class escapes <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape>`_ are not supported.
+  .. note::
+    Regular expression plugin filenames are currently expected to be written in a modified `ECMAScript <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions>`_ syntax. Notable differences include:
 
-  Regular expression plugin filenames are prefixed with ``^`` and suffixed with ``$`` to ensure they match whole filenames, and are case-insensitive and Unicode-aware (as if they're created with the ``i`` and ``u`` flags).
+    - Some ``\p{}`` and ``\P{}`` `Unicode character class escapes <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape>`_ are not supported.
+    - The functionality that is enabled by setting the `v <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets>`_ flag (a.k.a. ``unicodeSets``) is not supported. Instead, the regexes are created as if the ``i`` and ``u`` flags are set.
+
+    The specific syntax and features supported are an implementation detail that may change without changing the masterlist syntax version, so it's best to restrict regexes to the common subset that is supported across several regex flavours and implementations.
 
 .. describe:: group
 
@@ -118,7 +122,7 @@ Examples
     - 'Oblivion.esm'  # Don't do this, Oblivion.esm is a master of Oscuro's_Oblivion_Overhaul.esm, so LOOT already knows it's required.
     - name: 'example.esp'
       display: '[Example Mod](http://www.example.com)'
-      condition: 'version("Oscuro''s_Oblivion_Overhaul.esm", "15.0", ==)'
+      condition: 'version("Oscuro''s_Oblivion_Overhaul.esm", ==, "15.0")'
   tag:
     - Actors.Spells
     - Graphics