From b15d33bf912eff5f490f6f823d13219fc4024dbc Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Sat, 27 Oct 2018 17:00:22 +0100 Subject: [PATCH] Update metadata syntax docs --- docs/metadata/changelog.rst | 40 ++++++++++++++++++++++-- docs/metadata/conditions.rst | 4 ++- docs/metadata/data_structures/plugin.rst | 2 ++ docs/metadata/file_structure.rst | 2 +- docs/metadata/introduction.rst | 9 ++---- 5 files changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/metadata/changelog.rst b/docs/metadata/changelog.rst index 770793b8..f13a8706 100644 --- a/docs/metadata/changelog.rst +++ b/docs/metadata/changelog.rst @@ -4,8 +4,44 @@ Version History The version history of the metadata syntax is given below. -0.13 -==== +0.14 - Unreleased +================= + +Added +----- + +- The ``Group`` data structure now has a ``description`` key that takes a string + value. + +Changed +------- + +- ``clean`` and ``dirty`` metadata are now allowed in regex plugin entries. +- ``Location``, ``Message``, ``MessageContent`` and ``Tag`` equality comparisons + are now case-sensitive. +- Regular expressions in condition strings now use a `modified Perl grammar`_ + instead of a modified ECMAScript grammar. ``Plugin`` object ``name`` fields + still use the modified ECMAScript grammar for regex values. To improve + portability and avoid mistakes, it's best to stick to using the subset of + regular expression features that are common to both grammars. + +Removed +------- + +- The change in regular expression grammar means that the following regular + expression features are no longer supported in condition strings: + + - ``\c`` control code escape sequences, use ``\x`` instead + - The ``\0`` null escape sequence, - use ``\x00`` instead + - The ``[:d:]``, ``[:w:]`` and ``[:s:]`` character classes, + use ``[:digit:]``, ``[:alnum:]`` and ``[:space:]`` instead respectively. + - ``\`` backreferences + - ``(?=)`` and ``(?!)`` positive and negative lookahead + +.. _modified Perl grammar: https://docs.rs/regex/1.0.5/regex/index.html#syntax + +0.13 - 2018-04-02 +================= Added ----- diff --git a/docs/metadata/conditions.rst b/docs/metadata/conditions.rst index 83e591ed..04e51ce3 100644 --- a/docs/metadata/conditions.rst +++ b/docs/metadata/conditions.rst @@ -24,7 +24,9 @@ Types .. describe:: regular_expression - A double-quoted regular expression string to match file paths to. + 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 `_ syntax. + + 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. .. describe:: checksum diff --git a/docs/metadata/data_structures/plugin.rst b/docs/metadata/data_structures/plugin.rst index e86581de..a211cd1c 100644 --- a/docs/metadata/data_structures/plugin.rst +++ b/docs/metadata/data_structures/plugin.rst @@ -9,6 +9,8 @@ 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 `modified ECMAScript `_ syntax. + .. describe:: enabled ``boolean`` diff --git a/docs/metadata/file_structure.rst b/docs/metadata/file_structure.rst index e39f1725..69fcd5dd 100644 --- a/docs/metadata/file_structure.rst +++ b/docs/metadata/file_structure.rst @@ -26,7 +26,7 @@ The root of a metadata file is a key-value map. LOOT will recognise the followin plugin list *and* plugin set - The plugin data structures that hold all the plugin metadata within the file. It is a mixture of a list and a set because **no non-regex plugin value may be equal to any other non-regex plugin value** , but there may be any number of equal regex plugin values, and non-regex plugin values may be equal to regex plugin values.If multiple plugin values match a single plugin, their metadata is merged in the order the values are listed, and as defined in :ref:`plugin-merging`. + The plugin data structures that hold all the plugin metadata within the file. It is a mixture of a list and a set because **no non-regex plugin value may be equal to any other non-regex plugin value** , but there may be any number of equal regex plugin values, and non-regex plugin values may be equal to regex plugin values. If multiple plugin values match a single plugin, their metadata is merged in the order the values are listed, and as defined in :ref:`plugin-merging`. The message and plugin data structures are detailed in the next section. diff --git a/docs/metadata/introduction.rst b/docs/metadata/introduction.rst index 92016f44..d867ea56 100644 --- a/docs/metadata/introduction.rst +++ b/docs/metadata/introduction.rst @@ -13,12 +13,7 @@ The metadata syntax is what LOOT's masterlists and userlists are written in. If An important point that is more specific to how LOOT uses YAML: * Strings are case-sensitive, apart from file paths, regular expressions and checksums. - -Some properties of file paths as used by LOOT: - -* They are evaluated as paths relative to the game's Data folder. -* They cannot reference a path outside of the game's folder structure, ie. they cannot contain the substring ``../../``. -* Regular expression file paths must be written in the `EMCAScript `_ syntax, and they must use ``/`` for directory separators. -* Only the filename of a regex file path may contain non-literal regex syntax, ie. if the filename part of the regex file path is removed, the remainder must be an exact folder path (though with the regex syntax special characters escaped). 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. +* File paths are evaluated relative to the game's Data folder. +* File paths cannot reference a path outside of the game's folder structure, ie. they cannot contain the substring ``../../``. In this document, where a value's type is given as ``X list`` this is equivalent to a YAML sequence of values which are of the data type ``X``. Where a value's type is given as ``X set``, this is equivalent to a YAML sequence of **unique** values which are of the data type ``X``. Uniqueness is determined using the equality criteria for that data type. All the non-standard data types that LOOT's metadata syntax uses have their equality criteria defined later in this document.