diff --git a/docs/LOOT Metadata Syntax.html b/docs/LOOT Metadata Syntax.html index 835d62e2..5f14408e 100644 --- a/docs/LOOT Metadata Syntax.html +++ b/docs/LOOT Metadata Syntax.html @@ -269,30 +269,35 @@ plugins:

LOOT expects metadata to be laid out using a certain set of data structures, described in this section.

Tag Data Structure

-

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: the first is a simple string, and the second is a key-value map. All values in the map are strings. -

The simple form: -

tag
-

where tag is the Bash Tag, preceded by a minus sign if it is suggested for removal. -

The map form: +

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. + +

Map Form

+

All values in the map are strings.

Key NameRequiredNotes
name✓A Bash Tag, preceded by a minus sign if it is suggested for removal.
condition✗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 Condition Strings for details.
-

Examples: + +

Scalar Form

+
tag
+

where tag is equivalent to the value of the name key in the map form. + +

Equality

+

Two tag data structures are equal if the lowercased values of their name keys are identical. + +

Examples

Relations
-or 
name: -Relations
 condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm")'

File Data Structure

-

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: the first is a simple string, and the second is a key-value map. All values in the map are strings. -

The simple form: -

filepath
-

where filepath is an exact (ie. not regex) file path relative to the game's Data folder. -

The map form: +

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. + +

Map Form

+

All values in the map are strings.

@@ -301,9 +306,15 @@ condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.es
Key NameRequiredNotes
condition✗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 Condition Strings for details.
-

Examples: +

Scalar Form

+
filepath
+

where filepath is equivalent to the value of the name key in the map form. + +

Equality

+

Two file data structures are equal if the lowercased values of their name keys are identical. + +

Examples

'../obse_loader.exe'
-or 
name: '../obse_loader.exe'
 condition: 'version("../obse_loader.exe", "0.0.18.0", >=)'
 display: 'OBSE v18+'
@@ -319,8 +330,14 @@ display: 'OBSE v18+'
         conditionstring✗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 Condition Strings for details.
         subslist of strings✗A list of strings to be substituted into the message content string. The content string must use numbered specifiers (%1%, %2%, 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.
 
+
LOOT supports formatting of messages using GitHub Flavored Markdown. Support is provided by the Marked 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.
+
LOOT handles messages and languages as follows:
+
    
+    
  1. If a message's content value is a string, the message will use the string as its content if displayed.
+    
  2. If a message's content 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.
+

 
-
There are three message types:
+
Message Types

 
@@ -328,6 +345,8 @@ display: 'OBSE v18+'
         

     
KeywordDescription
     
warnA warning message, describing a non-critical issue with the user's mods (eg. dirty mods).
         
errorAn error message, decribing a critical installation issue (eg. missing masters, corrupt plugins).
 

+
+
Localised Content Data Structure

 
The localised content data structure is a key-value map, with all values being strings:
 

     
Key NameRequiredNotes
@@ -335,15 +354,16 @@ display: 'OBSE v18+'
         
str✓The actual message content string.
         
lang✓The language that str is written in, given as a POSIX language code. The languages LOOT supports are given in Language Codes.
 

-
LOOT supports formatting of messages using GitHub Flavored Markdown. Support is provided by the Marked 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.
 
-
LOOT handles messages and languages as follows:
-
    
-    
  1. If a message's content value is a string, the message will use the string as its content if displayed.
-    
  2. If a message's content 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.
-

+
Equality

+
The equality of two message data structures is determined by comparing the values of their content keys. As the values of the keys can be different data types, a comparison value is selected for each message using the following logic:
+

+
The two message data structures are then equal if their lowercased comparison values are identical.
 
-
Examples (translations by Google):
+
Examples
(translations by Google)

 
type: say
 condition: 'file("foo.esp")'
 content:
@@ -378,21 +398,26 @@ Note: A newer version of this plugin is availab
 
 
 
Location Data Structure

-
This data structure is used to hold information on where a plugin is hosted online. It is not currently used by LOOT, but it was suggested that since the LOOT team receives a considerable number of plugin URLs, they should be recorded in a standard format, as there is no existing store of such information and it could prove useful in the future.
-
The data structure has two forms: the first is a simple string, and the second is a key-value map. All values in the map are strings.
-
The simple form:
-
URL

-
where URL is a URL at which the plugin may be found.
-
The map form:
+
This data structure is used to hold information on where a plugin is hosted online. It has two forms: a key-value map and a scalar string.
+
+
Map Form

+
All values in the map are strings.

 

     
Key NameRequiredNotes
     

         
link✓A URL at which the plugin may be found.
         
name✗A descriptive name for the URL, which may be used as hyperlink text.
 

-
Examples:
+
+
Scalar Form

+
URL

+
where URL is equivalent to the value of the link key in the map form.
+
+
Equality

+
Two location data structures are equal if the lowercased values of their link keys are identical.
+
+
Examples

 
'http://skyrim.nexusmods.com/mods/19/'

-or
 
link: 'https://steamcommunity.com/sharedfiles/filedetails/?id=419668499'
 name: 'Unofficial Skyrim Patch on Steam Workshop'
 

@@ -408,7 +433,11 @@ name: 'Unofficial Skyrim Patch on Steam Workshop'
         udrinteger✗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.
         navinteger✗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.
 
-
Examples:
+
+
Equality

+
Two location data structures are equal if the values of their crc keys are identical.
+
+
Examples

 
crc: 0x3DF62ABC
 util: '[TES5Edit](http://www.creationkit.com/TES5Edit_Cleaning_Guide_-_TES5Edit)'
 itm: 4
@@ -431,14 +460,15 @@ nav: 0
             
             
For example, priority: 153000352 and priority: 352 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.
             
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 -2000000000 to 2000000000, and if unspecified defaults to 0.
-        afterfile list✗An unordered list 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.
-        reqfile list✗An unordered list 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.
-        incfile list✗An unordered list of files that this plugin is incompatible with. If any of these files are present, an error message will be displayed.
+        afterfile set✗An unordered list 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.
+        reqfile set✗An unordered list 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.
+        incfile set✗An unordered list of files that this plugin is incompatible with. If any of these files are present, an error message will be displayed.
         msgmessage list✗The messages attached to this plugin. The messages will be displayed in the order that they are listed.
-        tagtag list✗An unordered list 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.
-        urllocation list✗An unordered list 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.
-        dirtydirty info list✗An unordered list of dirty info structures for this plugin. Plugin entries with regular expression filenames must not contain dirty info.
+        tagtag set✗An unordered list 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.
+        urllocation set✗An unordered list 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.
+        dirtydirty info set✗An unordered list of dirty info structures for this plugin. Plugin entries with regular expression filenames must not contain dirty info.
 
+
Where a key's data type is an X set, this is equivalent to X list, with the additional constraint that each item in the list must be unique. Uniqueness is determined using the equality criteria for each data structure, as defined earlier.
 
Each plugin must have only one matching non-regex entry. A plugin may match any number of regex entries though, and their metadata will be merged, with later entries being merged into earlier entries as detailed in the table below.
 
 
@@ -448,16 +478,16 @@ nav: 0
         
nameNot merged.
         
enabledReplaced by B's value.
         
priorityReplaced by B's value, unless that value is 0 and it was not explicitly set.
-        
afterMerged. If A and B both contain an entry with the same name value, B's copy is skipped.
-        
reqMerged. If A and B both contain an entry with the same name value, B's copy is skipped.
-        
incMerged. If A and B both contain an entry with the same name value, B's copy is skipped.
-        
msgMerged. If A and B both contain an entry with the same content string, then B's copy is skipped. If there are multiple content strings, the English strings are compared.
-        
tagMerged. If A and B both contain an entry with the same name value, B's copy is skipped, unless one is suggesting the tag for addition and the other is suggesting it for removal, in which case both entries are kept.
-        
urlMerged. If A and B both contain an entry with the same link value, B's copy is skipped.
-        
dirtyMerged. If A and B both contain an entry with the same crc value, B's copy is skipped.
+        
afterMerged. 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.
+        
reqMerged. 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.
+        
incMerged. 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.
+        
msgMerged. 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.
+        
tagMerged.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.
+        
urlMerged. 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.
+        
dirtyMerged.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.
 

 
-
Example:
+
Examples

 
name: 'Oscuro''s_Oblivion_Overhaul.esm'
 req:
   - 'Oblivion.esm'  # Don't do this, Oblivion.esm is a master of Oscuro's_Oblivion_Overhaul.esm, so LOOT already knows it's required.