<p>The metadata syntax is what LOOT's masterlists and userlists are written in. If you know YAML, good news: the syntax is essentially just YAML 1.2. If you don't know YAML, then its <ahref="https://en.wikipedia.org/wiki/YAML">Wikipedia page</a> is a good introduction. All you really need to know is:
<li>How lists and associative arrays (key-value maps) are written.
<li>That whitespace is important, and that only normal spaces (ie. no non-breaking spaces or tabs) count as such.
<li>That data entries that are siblings must be indented by the same amount, and child data nodes must be indented further than their parents (see the example later in this document if you don't understand).
<li>That YAML files must be written in a Unicode encoding.
<li>That each key in a key-value map must only appear once per map object.
<li>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 <code>Meshes\\Resources(1|2)\\(upperclass)?table.nif</code>, LOOT will look for a file named <code>table.nif</code> or <code>upperclasstable.nif</code> in the <code>Meshes\Resources(1|2)</code> folder, rather than looking in the <code>Meshes\Resources1</code> and <code>Meshes\Resources2</code> folders.
<p>In this document, where a value's type is given as <code><var>X</var> list</code>, this is equivalent to a YAML sequence of values which are of the data type <var>X</var>. Where a value's type is given as <code><var>X</var> set</code>, this is equivalent to a YAML sequence of <strong>unique</strong> values which are of the data type <var>X</var>. 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.
<tr><td><code>plugins</code><td>plugin list <i>and</i> plugin set<td>The plugin data structures that hold all the plugin metadata within the file. It is a mixture of a list and a set because <strong>no non-regex plugin value may be equal to any other non-regex plugin value</strong>, but there may be any number of equal regex plugin values, and non-regex plugin values may be equal to regex plugin values.
<p>If multiple plugin values match a single plugin, their metadata is merged in the order the values are listed, and as defined <ahref="#structs-plugin-merge">later in this document</a>.
<p>LOOT metadata files can contain suggestions for the addition or removal of Bash Tags, and this is the structure used for them. It has two forms: a key-value map and a scalar string.
<tr><td><code>name</code><td>✓<td>A Bash Tag, preceded by a minus sign if it is suggested for removal.
<tr><td><code>condition</code><td>✗<td>A condition string that is evaluated to determine whether this Bash Tag should be suggested: if it evaluates to true, the Tag is suggested, otherwise it is ignored. See <ahref="#cond">Condition Strings</a> for details.
<p>Not to be confused with the structure of the metadata file itself, this structure can be used to hold file paths. It has two forms: a key-value map and a scalar string.
<tr><td><code>display</code><td>✗<td>A substitute string to be displayed instead of the file path in any generated messages, eg. the name of the mod the file belongs to.
<tr><td><code>condition</code><td>✗<td>A condition string that is evaluated to determine whether this file data should be used: if it evaluates to true, the data is used, otherwise it is ignored. See <ahref="#cond">Condition Strings</a> for details.
<tr><td><code>type</code><td>string<td>✓<td>The type string can be one of three keywords, see the table below for their semantics.
<tr><td><code>content</code><td>string <i>or</i> localised content list<td>✓<td>Either simply a string, or a list of localised content data structures. If the latter, one of the structures must be for English.
<tr><td><code>condition</code><td>string<td>✗<td>A condition string that is evaluated to determine whether the message should be displayed: if it evaluates to true, the message is displayed, otherwise it is not. See <ahref="#cond">Condition Strings</a> for details.
<tr><td><code>subs</code><td>string list<td>✗<td>A list of strings to be substituted into the message content string. The content string must use numbered specifiers (<code>%1%</code>, <code>%2%</code>, etc.), where the numbers correspond to the position of the substitution string in this list to use, to denote where these strings are to be substituted.
<p>LOOT supports formatting of messages using <ahref="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown</a>. Support is provided by the <ahref="https://github.com/chjj/marked">Marked</a> library (v0.3). Strings that get substituted into messages, such as file display names and dirty info utility strings, also support the same formatting options.
<p>LOOT handles messages and languages as follows:
<ol>
<li>If a message's <code>content</code> value is a string, the message will use the string as its content if displayed.
<li>If a message's <code>content</code> value is a list of localised content structures, then the first structure with a language that matches LOOT's current language will be used as the message's content if displayed. If there are no matches, then the first structure in English will be used.
<tr><td><code>lang</code><td>✓<td>The language that <code>str</code> is written in, given as a POSIX language code. The languages LOOT supports are given in <ahref="#lang">Language Codes</a>.
<p>The equality of two message data structures is determined by comparing the values of their <code>content</code> keys. As the values of the keys can be different types, a comparison value is selected for each message using the following logic:
<h3id="structs-dirty">Dirty Info Data Structure</h3>
<p>This structure holds information on which versions of a plugin are dirty, and how many identical-to-master records, deleted records and deleted navmeshes (if applicable) it contains. Dirty info is given as a key-value map.
<tr><td><code>crc</code><td>hexadecimal integer<td>✓<td>The CRC checksum of the dirty plugin, before cleaning. LOOT displays the CRCs of installed plugins in its report. The 8-character CRC should be preceded by <code>0x</code> so that it is correctly interpreted.
<tr><td><code>itm</code><td>integer<td>✗<td>The number of identical-to-master records reported for the dirty plugin. If the number is unknown, this field should not be supplied. If the number is known and zero, this field should be supplied.
<tr><td><code>udr</code><td>integer<td>✗<td>The number of undeleted records reported for the dirty plugin. If the number is unknown, this field should not be supplied. If the number is known and zero, this field should be supplied.
<tr><td><code>nav</code><td>integer<td>✗<td>The number of deleted navmeshes reported for the dirty plugin. If the number is unknown, this field should not be supplied. If the number is known and zero, this field should be supplied.
<tr><td><code>name</code><td>string<td>✓<td>Can be an exact plugin filename or a regular expression plugin filename. If the filename contains any of the characters <code>:\*?|</code>, the string will be treated as a regular expression, otherwise it will be treated as an exact filename. For example, <code>Example\.esm</code> will be treated as a regular expression, as it contains a <code>\</code> character.
<tr><td><code>enabled</code><td>boolean<td>✗<td>Enables or disables use of the plugin object. Used for user rules, but no reason to use it in the masterlist. If unspecified, defaults to <code>true</code>.
<tr><td><code>priority</code><td>integer<td>✗<td>Modifies plugin position relative to others that change one or more of the same records, but which are otherwise unrelated (ie. neither plugin lists the other as a master, requirement, or in its <code>after</code> list). Plugins that don't change any of the same records are not compared, unless:
<li>One of the plugins has a priority greater than or equal to 1,000,000. In this case, only the modulo (ie. remainder when divided) with 1,000,000 is used when comparing plugin priority values – the rest is only used to signify that the plugin should be compared against all others.
<p>For example, <code>priority: 153000352</code> and <code>priority: 352</code> have equal values when compared, but a plugin with the first priority will be compared against all others, while a (non-empty) plugin with the second priority will be compared against only those it conflicts with.
<p>A plugin with a higher priority value will load after a plugin with a lower priority value. The value can be anything in the range <code>-2000000000</code> to <code>2000000000</code>, and if unspecified defaults to <code>0</code>.
<tr><td><code>after</code><td>file set<td>✗<td>An unordered set of plugins that this plugin must load after, but which are not dependencies. Used for resolving specific compatibility issues and by user rules for specifying custom plugin positions.
<tr><td><code>req</code><td>file set<td>✗<td>An unordered set of files that this plugin requires to be present. This plugin will load after any plugins listed. If any of these files are missing, an error message will be displayed. Intended for use specifying implicit dependencies, as LOOT will detect a plugin's explicit masters itself.
<tr><td><code>inc</code><td>file set<td>✗<td>An unordered set of files that this plugin is incompatible with. If any of these files are present, an error message will be displayed.
<tr><td><code>msg</code><td>message list<td>✗<td>The messages attached to this plugin. The messages will be displayed in the order that they are listed.
<tr><td><code>tag</code><td>tag set<td>✗<td>An unordered set of Bash Tags suggested for this plugin. If a Bash Tag is suggested for both addition and removal, the latter will override the former when the list is evaluated.
<tr><td><code>url</code><td>location set<td>✗<td>An unordered set of locations for this plugin. If the same version can be found at multiple locations, only one location should be recorded. This metadata is not currently used by LOOT.
<tr><td><code>dirty</code><td>dirty info set<td>✗<td>An unordered set of dirty info structures for this plugin. Plugin entries with regular expression filenames <strong>must not</strong> contain dirty info.
<tr><td><code>after</code><td>Merged. If B's file set contains an item that is equal to one already present in A's file set, B's item is discarded.
<tr><td><code>req</code><td>Merged. If B's file set contains an item that is equal to one already present in A's file set, B's item is discarded.
<tr><td><code>inc</code><td>Merged. If B's file set contains an item that is equal to one already present in A's file set, B's item is discarded.
<tr><td><code>msg</code><td>Merged. If B's message list contains an item that is equal to one already present in A's message list, B's item is discarded.
<tr><td><code>tag</code><td>Merged.If B's tag set contains an item that is equal to one already present in A's tag set, B's item is discarded.
<tr><td><code>url</code><td>Merged. If B's location set contains an item that is equal to one already present in A's location set, B's item is discarded.
<tr><td><code>dirty</code><td>Merged.If B's dirty info set contains an item that is equal to one already present in A's dirty info set, B's item is discarded.
<p>Condition strings can be used to ensure that data is only acted on by LOOT under certain circumstances. They are very similar to boolean conditional expressions in programming languages such as Python, though more limited. Their <ahref="https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form">EBNF</a> grammar is:
<p>The <code>[ negator ], function</code> grammar is referred to as a condition, and two conditions joined by an operator, ie. <code>condition, operator, condition</code> is referred to as a compound condition.
<p>LOOT caches the results of condition evaluations, so performance is not really an issue. A regular expression check will still take longer than a file check though, so use the former only when appropriate to do so.
<tr><td>Checksum<td><code>checksum("<var>filepath</var>", <var>checksum</var>)</code><td>Returns true if the calculated checksum of <var>filepath</var> matches <var>checksum</var>, false otherwise. If <var>filepath</var> does not exist, returns false.
<tr><td>Version<td><code>version("<var>filepath</var>", "<var>version</var>", <var>comparator</var>)</code><td>Returns true if the boolean expression <code>(actual version of <var>filepath</var>) <var>comparator version</var></code> holds true, false otherwise. If <var>filepath</var> does not exist and <var>comparator</var> is <code>==</code>, <code>></code> or <code>>=</code>, returns false. If <var>filepath</var> does not exist and <var>comparator</var> is <code>!=</code>, <code><</code> or <code><=</code>, returns true. The comparison is not a straightforward per-character comparison, but instead uses the precedence rules defined by <ahref="http://semver.org/">Semantic Versioning</a>, extended to allow leading zeroes, an arbitrary number of release version numbers, case-insensitivity and a wider range of separator characters.
<tr><td>Plugin Active Status<td><code>active("<var>filepath</var>")</code><td>Returns true if <var>filepath</var> is a <code>.esp</code> or <code>.esm</code> file that is both installed and active, false otherwise.
<tr><td><code>checksum</code><td>A string of hexadecimal digits representing an unsigned integer that is the data checksum of a file. LOOT displays the checksums of plugins in its user interface after running.
<tr><td><code>version</code><td>A string of characters representing the version of a plugin or executable. LOOT displays the versions of plugins in its user interface after running.
<tr><td><code>comparator</code><td>A comparison operator, ie. one of <code>==</code>, <code>!=</code>, <code><</code>, <code>></code>, <code><=</code> or <code>>=</code>, meaning "is equal to", "is not equal to", "is less than", "is greater than", "is less than or equal to" and "is greater than or equal to" respectively.
<p>There are two supported junctors, the logical conjunction (logical <q>and</q> operator) and the logical disjunction (logical <q>or</q> operator), that operate on the expressions to their left and right.
<table>
<thead><tr><th>Junctor<th>Syntax<th>Description
<tbody>
<tr><td>Logical Conjunction<td><code>and</code><td>Both conditions must evaluate to true for the compound condition to evaluate to true. If not, the compound condition evaluates to false.
<tr><td>Logical Disjunction<td><code>or</code><td>One condition or both conditions must evaluate to true for the compound condition to evaluate to true. If neither condition is true, then the compound condition evaluates to false.
</table>
<p>The following is a truth table for the junctors:
<table>
<thead><tr><th>Value of <code><var>condition1</var></code><th>Value of <code><var>condition2</var></code><th>Value of <code><var>condition1</var> and <var>condition2</var></code><th>Value of <code><var>condition1</var> or <var>condition2</var></code>
<tbody>
<tr><td>true<td>true<td>true<td>true
<tr><td>true<td>false<td>false<td>true
<tr><td>false<td>true<td>false<td>true
<tr><td>false<td>false<td>false<td>false
</table>
<h3id="cond-order">Order Of Evaluation</h3>
<p>When a condition string is evaluated, its constituent parts are evaluated according to the standard precedence rules of operator logic, ie.
<p>Below is a table that lists some combinations of conditions, showing for each the order of evaluation by explicit bracketing. To make it easier to read, the <code><var>negator</var><var>function</var></code> pair is shortened to <code><var>C</var></code> after the first example.
<tr><td><code><var>C</var> and <var>C</var></code><td><code>( <var>C</var> and <var>C</var> )</code>
<tr><td><code><var>C</var> or <var>C</var></code><td><code>( <var>C</var> or <var>C</var> )</code>
<tr><td><code><var>C</var> and <var>C</var> and <var>C</var></code><td><code>( ( <var>C</var> and <var>C</var> ) and <var>C</var> )</code>
<tr><td><code><var>C</var> or <var>C</var> or <var>C</var></code><td><code>( ( <var>C</var> or <var>C</var> ) or <var>C</var> )</code>
<tr><td><code><var>C</var> and <var>C</var> or <var>C</var></code><td><code>( ( <var>C</var> and <var>C</var> ) or <var>C</var> )</code>
<tr><td><code><var>C</var> or <var>C</var> and <var>C</var></code><td><code>( <var>C</var> or ( <var>C</var> and <var>C</var> ) )</code>
<tr><td><code><var>C</var> and <var>C</var> and <var>C</var> and <var>C</var></code><td><code>( ( ( <var>C</var> and <var>C</var> ) and <var>C</var> ) and <var>C</var> )</code>
<tr><td><code><var>C</var> and <var>C</var> and <var>C</var> or <var>C</var></code><td><code>( ( ( <var>C</var> and <var>C</var> ) and <var>C</var> ) or <var>C</var> )</code>
<tr><td><code><var>C</var> and <var>C</var> or <var>C</var> and <var>C</var></code><td><code>( ( <var>C</var> and <var>C</var> ) or ( <var>C</var> and <var>C</var> ) )</code>
<tr><td><code><var>C</var> and <var>C</var> or <var>C</var> or <var>C</var></code><td><code>( ( ( <var>C</var> and <var>C</var> ) or <var>C</var> ) or <var>C</var>)</code>
<tr><td><code><var>C</var> or <var>C</var> or <var>C</var> or <var>C</var></code><td><code>( ( ( <var>C</var> or <var>C</var> ) or <var>C</var> ) or <var>C</var> )</code>
<tr><td><code><var>C</var> or <var>C</var> or <var>C</var> and <var>C</var></code><td><code>( ( <var>C</var> or <var>C</var> ) or ( <var>C</var> and <var>C</var> ) )</code>
<tr><td><code><var>C</var> or <var>C</var> and <var>C</var> or <var>C</var></code><td><code>( ( <var>C</var> or ( <var>C</var> and <var>C</var> ) ) or <var>C</var> )</code>
<tr><td><code><var>C</var> or <var>C</var> and <var>C</var> and <var>C</var></code><td><code>( <var>C</var> or ( ( <var>C</var> and <var>C</var> ) and <var>C</var> ) )</code>
<p>You can also explicitly enclose any condition in brackets to override the evaluation order, eg. <code><var>C</var> and ( <var>C</var> or <var>C</var> )</code> is evaluated as <code><var>C</var> and ( <var>C</var> or <var>C</var> )</code>, in contrast to the unbracketed string above.
<li>Removed support for the <code>ver</code> key in location data structures.</li>
<li>Added support for the <code>name</code> key in location data structures.</li>
<li>Added support for the <code>many("<var>regex</var>")</code> condition function.</li>
<li>Changed detection of regular expression plugin entries. Previously, a plugin entry was treated as having a regular expression filename if the filename ended with <code>\.esp</code> or <code>\.esp</code>. Now, a plugin entry is treated as having a regular expression filename if the filename contains one or more of <code>:\*?|</code>.</li>
<li>The plugin data structure definition in this document was fixed so that it correctly gives the values of the <code>after</code>, <code>req</code>, <code>inc</code>, <code>tag</code>, <code>url</code> and <code>dirty</code> keys as sets, not lists.
<li>This document now defines the equality criteria for all of the metadata syntax's non-standard data structures.
<li>The algorithm used for version comparison has been changed to give better results for a wider variety of version strings.
<li>Changed support for Markdown formatting in messages. Previously, only URL hyperlinking was supported, and only for <code>file:</code>, <code>http:</code> and <code>https:</code> URLs using the <code>[label](url)</code> or <code><url></code> syntaxes. Now, the <ahref="https://github.com/chjj/marked">Marked</a> library (v0.3) is used to provide support for most of GitHub Flavored Markdown, minus the GitHub-specific features (like @mentions, issue/repo linking and emoji).</li>
<li>Added support for message string substitution keys, i.e. <code>sub</code>, in message data structures.</li>
<li>Added support for YAML merge keys, i.e. <code><<</code>.</li>
