priority node of the plugin data structure is incomplete.
+The metadata file syntax is what BOSS's masterlists and userlists are written in (as of BOSS v3 - prior versions will not be covered here). If you know YAML, good news: the metadata file syntax is essentially just YAML v1.2! If you don't know YAML, then this section is for you. -
Some important points about how BOSS uses YAML. +
As of BOSS v3, the metadata file syntax is what BOSS's masterlists and userlists are written in. If you know YAML, good news: the metadata file syntax is essentially just YAML 1.2. If you don't know YAML, then its Wikipedia page is a good introduction. All you really need to know is:
-?:,[]{}#&*!|>'"%@`. Any backslashes or double quotes within a quoted string should be escaped with a backslash, ie. " -> \" and \ -> \\.
- \., whereas in a file path it is not.
+ Some important points that are more specific to how BOSS uses YAML: +
-?:,[]{}#&*!|>"%@`, unless they also contain any single quotes, in which case the string should be enclosed in double quotes instead. Any backslashes or double quotes within a double-quoted string should be escaped with a backslash, ie. " → \" and \ → \\.
+ These docs give all example syntax in YAML's least compact representation: you can also use the compact representation, but as it is less readable, this is not recommended. +
Some properties of file paths as used by BOSS: +
../../.
+ Meshes\\Resources(1|2)\\(upperclass)?table.nif, BOSS 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.
+The root of a metadata file is a key-value map. BOSS will recognise the following keys, none of which are required: +
| Key Name | Value Type | Notes + |
|---|---|---|
globals | message list | A list of message data structures for messages that are displayed independently of any plugin. + |
plugins | plugin list | A list of plugin data structures, holding all the plugin metadata within the file. + |
Other keys may also be present, but are not processed by BOSS. The message and plugin data structures are detailed in the next section. +
An example metadata file:
+globals:
+ - type: say
+ content: You are using the latest version of BOSS.
+ condition: 'version("../BOSS/BOSS.exe", "2.1.1.0", ==)'
+plugins:
+ - name: Armamentarium.esm
+ tag:
+ - Relev
+ - name: ArmamentariumFran.esm
+ tag:
+ - Relev
+ - name: 'Beautiful People 2ch-Ed.esm'
+ tag:
+ - Eyes
+ - Graphics
+ - Hair
+ - R.Relations
+
While you could write whatever you wanted in a metadata file without problems, so long as it was valid YAML, BOSS expects the metadata to be laid out using a certain set of data structures, described in this section. +
While you could write whatever you wanted in a metadata file without problems, so long as it was valid YAML, it would be pointless as BOSS expects the metadata to be laid out using a certain set of data structures, described in this section.
Messages are given as key-value maps. All values are strings, and the type, content and lang strings are case-sensitive. The condition string has varying case sensitivity according to its content. +
Messages are given as key-value maps.
| Key Name | Required | Notes |
|---|---|---|
type | ✓ | The type string can be one of three keywords, see the table below for their semantics. - |
content | ✓ | The actual message content string. It has a few special properties, see the Message Stringssection for details. - |
condition | ✗ | 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 the Condition Stringssection for details. - |
lang | ✗ | What language this message is written in, given as an ISO 639-3 language code. The languages BOSS supports are given in the Language Codessection. If no language is given, then the message will always be displayed. If a language is given and it does not match the language BOSS is running for, the message will not be displayed, otherwise its display is dependent on the evaluation of the condition string, if present. + |
content | ✓ | The actual message content string. It has a few special properties, see Message Strings for details. + |
condition | ✗ | 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. + |
lang | ✗ | What language this message is written in, given as an ISO 639-3 language code. The languages BOSS supports are given in Language Codes. If no language is given, then the message will always be displayed. If a language is given and it does not match the language BOSS is running for, the message will not be displayed, otherwise its display is dependent on the evaluation of the condition string, if present. |
There are three message types: @@ -112,7 +173,7 @@
Example:
- Not to be confused with the structure of the metadata file itself, this structure can be used to hold filenames. 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:
- where [filename] is a filename relative to the game's Data folder.
+ where The map form:
Examples:
BOSS metadata files can contain suggestions for the addition or removal of Bash Tags, and this is the structure used for them. Like the file data structure, it has simple string and key-value map forms. All values in the map are strings. The Tag name is case-sensitive.
+ BOSS metadata files can contain suggestions for the addition or removal of Bash Tags, and this is the structure used for them. Like the file data structure, it has simple string and key-value map forms. All values in the map are strings.
The simple form:
- where [tag] is one of two things:
- where The map form:
Examples:
Example:
- The root of a metadata file is a key-value map. BOSS will recognise the following keys, none of which are required:
- Other keys may also be present, but are not processed by BOSS.
- An example metadata file:
- URLs in message content strings will be turned into hyperlinks in BOSS's user interface. Recognised URLs are those that start with Examples:
Condition strings can be used to ensure that data is only acted on by BOSS under certain circumstances. They are similar in form to conditional expressions in programming languages, and their format is:
- where The Condition strings can be used to ensure that data is only acted on by BOSS under certain circumstances. They are very similar to boolean conditional expressions in programming languages such as Python, though more limited. Their EBNF grammar is:
+ The Unlike previous versions of BOSS, BOSS v3 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.
- There are two keywords:
- There are several conditions that can be tested for using the functions detailed in the table below.
The different types of condition variable described below. Only version strings are case-sensitive.
+ The different types of variable used in the above functions are described in more detail below.
There are two operators, which both operate on the conditions to their immediate left and right:
+ The negator, or logical negation operator, inverts the value of the function that follows it. Its inclusion is optional, and its syntax is simply:
+ Below is a truth table for the negator.
When a condition string is evaluated, its constituent parts are evaluated in the following order:
+ There are two supported junctors, the logical conjunction (logical The following is a truth table for the junctors:
+ When a condition string is evaluated, its constituent parts are evaluated according to the standard precedence rules of operator logic, ie.
In case the words are confusing, here's a table of generic condition string structures and how they get evaluated, using brackets to display precedence. To reduce the number of brackets visible in the more complicated examples, the 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 You can also explicitly enclose any condition in brackets to override the evaluation order, eg. You can also explicitly enclose any condition in brackets to override the evaluation order, eg. BOSS supports the following languages and language codes:
This document is part of the BOSS documentation.condition: if file("Silgrad_Tower.esm")
+condition: 'file("Silgrad_Tower.esm")'
type: warn
content: Use either Silgrad_Tower.esm or Silgrad_Tower_T.esm but not both together.
@@ -120,46 +181,42 @@ content: Use either Silgrad_Tower.esm or Silgrad_Tower_T.esm but not both togeth
File Data Structure
[filename]
-filepath
+filepath is a file path relative to the game's Data folder.
Key Name Required Notes
name✓ A filename relative to the game's Data folder. Case-insensitive. Directory components must be delimited by forwardslashes, not backslashes.
- display✗ A substitute string to be displayed instead of the filename in any generated messages, eg. the name of the mod the file belongs to.
- 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 the Condition Strings
section for details.
+ name✓ A file path relative to the game's Data folder.
+ display✗ 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.
+ 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.
../obse_loader.exe
or
name: ../obse_loader.exe
-condition: if version("../obse_loader.exe", "0.0.18.0", <)
+condition: 'version("../obse_loader.exe", "0.0.18.0", <)'
display: OBSE v18+
Tag Data Structure
-[tag]
-
-
+Graphics.
- -Graphics.
-tag
+tag is the Bash Tag, preceded by a minus sign if it is suggested for removal.
Key Name Required Notes
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 the Condition Strings
section for details.
+ 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.
Relations
or
name: -Relations
-condition: if file("Mart's Monster Mod for OOO.esm") or if file("FCOM_Convergence.esm")
+condition: "file(\"Mart's Monster Mod for OOO.esm\") or file(\"FCOM_Convergence.esm\")"
Plugin Data Structure
@@ -167,9 +224,9 @@ condition: if file("Mart's Monster Mod for OOO.esm") or if file("FCOM_Convergenc
Key Name Data Type Required Notes
namestring ✓ Can be an exact plugin filename or a regular expression using the POSIX Extended syntax. Case-insensitive.
- enabledboolean ✗ Enables or disables use of the plugin object. Used for user rules, but no reason to use it in the masterlist.
- priorityinteger ✗ ???
+ namestring ✓ Can be an exact plugin filename or a regular expression plugin filename. If the period that precedes the file extension has been escaped (eg. \.esp, \.esm), the string is treated as a regular expression, otherwise it is treated as an exact filename.
+ enabledboolean ✗ 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 true.
+ priorityinteger ✗ ??? If unspecified, defaults to 0.
afterfile list ✗ 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 ✗ Files that this plugin requires to be present. If any of these files are missing, an error message will be displayed. The list can contain a mixture of plugins and other files, but all plugins must be given in their required load order relative to one another. Intended for use specifying implicit dependencies, as BOSS will detect a plugin's explicit masters itself.
incfile list ✗ Files that this plugin is incompatible with. If any of these files are present, an error message will be displayed.
@@ -177,7 +234,7 @@ condition: if file("Mart's Monster Mod for OOO.esm") or if file("FCOM_Convergenc
tagtag list ✗ The Bash Tags suggested for this plugin.
name: Oscuro's_Oblivion_Overhaul.esm
+name: "Oscuro's_Oblivion_Overhaul.esm"
tag:
- Actors.Spells
- Graphics
@@ -186,44 +243,13 @@ tag:
- Scripts
- Stats
- name: -Relations
- condition: if file("Mart's Monster Mod for OOO.esm") or if file("FCOM_Convergence.esm")
+ condition: "file(\"Mart's Monster Mod for OOO.esm\") or file(\"FCOM_Convergence.esm\")"
msg:
- type: say
- content: Do not clean. "Dirty" edits are intentional and required for the mod to function.
+ content: 'Do not clean. "Dirty" edits are intentional and required for the mod to function.'
-Metadata File Structure
-
-
-Key Name Value Type Notes
- globalsmessage list A list of global messages.
- pluginsplugin list
- globals:
- - type: say
- content: You are using the latest version of BOSS.
- condition: if version("../BOSS/BOSS.exe", "2.1.1.0", ==)
-plugins:
- - name: Armamentarium.esm
- tag:
- - Relev
- - name: ArmamentariumFran.esm
- tag:
- - Relev
- - name: Beautiful People 2ch-Ed.esm
- tag:
- - Eyes
- - Graphics
- - Hair
- - R.Relations
-
-
-
-
-Message Strings
+Message Strings
file:, http: or https: and contain no spaces (valid URLs can't contain spaces anyway). URLs can be labelled by writing the label after the URL, with a space separating them, and enclosing the URL and label in double quotes.
http://www.example.com
@@ -234,93 +260,104 @@ while
becomes
example link
-Condition Strings
-[keyword] [function] *( [operator] [keyword] [function] )
-*( ) encloses a phrase that may be repeated zero or more times.
-[keyword] [function] pair is referred to as a condition, and two conditions joined by an operator is referred to as a compound condition.
+
+Condition Strings
+[ negator ], function, { junctor, [ negator ], function } ;
+[ negator ], function grammar is referred to as a condition, and two conditions joined by an operator, ie. condition, operator, condition is referred to as a compound condition.
Keywords
-
-
-
-Keyword Description
- ifIf the following [function] evaluates to true, the condition will be true. Otherwise, the condition will be false.
- ifnotIf the following [function] evaluates to false, the condition will be true. Otherwise, the condition will be false.
-Functions
+Functions
-Function Syntax Description
File file("[filepath]")Returns true if [filepath] is installed, false otherwise.
- File file("[regex]")Returns true if a file matching [regex] is found, false otherwise.
- Checksum checksum("[filepath]", [checksum])Returns true if the calculated checksum of [filepath] matches [checksum], false otherwise. If [filepath] does not exist, returns false.
- Version version("[filepath]", "[version]", [comparator])Returns true if the expression [version] [comparator] [actual version of [filepath]] holds true, false otherwise. If [filepath] does not exist and [comparator] is ==, > or >=, returns false. If [filepath] does not exist and [comparator] is !=, < or <=, returns true.
- Plugin Active Status active("[filepath]")Returns true if [filepath] is a .esp or .esm file that is both installed and active, false otherwise.
+ File file("filepath")Returns true if filepath is installed, false otherwise.
+ File regex("regex")Returns true if a file matching regex is found, false otherwise.
+ Checksum checksum("filepath", checksum)Returns true if the calculated checksum of filepath matches checksum, false otherwise. If filepath does not exist, returns false.
+ Version version("filepath", "version", comparator)Returns true if the boolean expression version comparator (actual version of filepath) holds true, false otherwise. If filepath does not exist and comparator is ==, > or >=, returns false. If filepath does not exist and comparator is !=, < or <=, returns true.
+ Plugin Active Status active("filepath")Returns true if filepath is a .esp or .esm file that is both installed and active, false otherwise.
-
-Variable Type Syntax Description
+ Variable Type Description
[filepath]A file path or regular expression string to match file paths to. Must not contain a double quote character ". Evaluated relative to the game's Data folder. If a regex, the string cannot contain any directory components, ie. matches can only exist in the Data folder. Paths must use forwardslashes to delimit directory components.
- [regex]A regular expression string to match filenames to. Evaluated relative to the game's Data folder. The string cannot contain any directory components. The syntax used must be POSIX Extended.
- [checksum]A string of hexadecimal digits representing an unsigned integer that is the data checksum of a file. BOSS displays the checksums of plugins in its user interface after running.
- [version]A string of characters representing the version of a plugin or executable. BOSS displays the versions of plugins in its user interface after running.
- [comparator]A comparison operator, ie. one of ==, !=, <, >, <= or >=, 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.
+ filepathA Windows file path.
+ regexA regular expression string to match file paths to.
+ checksumA string of hexadecimal digits representing an unsigned integer that is the data checksum of a file. BOSS displays the checksums of plugins in its user interface after running.
+ versionA string of characters representing the version of a plugin or executable. BOSS displays the versions of plugins in its user interface after running.
+ comparatorA comparison operator, ie. one of ==, !=, <, >, <= or >=, 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.
Operators
-The Negator & Junctors
+not
+
-
-Operator Syntax Description
+ Value of functionValue of not function
Logical AND andBoth condition must evaluate to true for the compound condition to evaluate to true. If not, the compound condition evaluates to false.
- Logical OR orOne 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.
+ false true
+ true false
Order Of Evaluation
-and
operator) and the logical disjunction (logical or
operator), that operate on the expressions to their left and right.
+
+
+Junctor Syntax Description
+ Logical Conjunction andBoth conditions must evaluate to true for the compound condition to evaluate to true. If not, the compound condition evaluates to false.
+ Logical Disjunction orOne 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.
+
+
+
+Value of condition1Value of condition2Value of condition1 and condition2Value of condition1 or condition2
+ true true true true
+ true false false true
+ false true false true
+ false false false false
+ Order Of Evaluation
+
-
-and
+ or
[keyword] [function] pair is replaced with C after the first example.
+keyword function pair is replaced with C after the first example.
-String Structure Evaluated As
[keyword] [function]( [keyword] ( [function] ) )
- C and C( C and C )
- C or C( C or C )
- C and C and C( ( C and C ) and C )
- C or C or C( ( C or C ) or C )
- C and C or C( ( C and C ) or C )
- C or C and C( C or ( C and C ) )
- C and C and C and C( ( ( C and C ) and C ) and C )
- C and C and C or C( ( ( C and C ) and C ) or C )
- C and C or C and C( ( C and C ) or ( C and C ) )
- C and C or C or C( ( ( C and C ) or C ) or C)
- C or C or C or C( ( ( C or C ) or C ) or C )
- C or C or C and C( ( C or C ) or ( C and C ) )
- C or C and C or C( ( C or ( C and C ) ) or C )
- C or C and C and C( C or ( ( C and C ) and C ) )
+ keyword function( keyword ( function ) )
+ C and C( C and C )
+ C or C( C or C )
+ C and C and C( ( C and C ) and C )
+ C or C or C( ( C or C ) or C )
+ C and C or C( ( C and C ) or C )
+ C or C and C( C or ( C and C ) )
+ C and C and C and C( ( ( C and C ) and C ) and C )
+ C and C and C or C( ( ( C and C ) and C ) or C )
+ C and C or C and C( ( C and C ) or ( C and C ) )
+ C and C or C or C( ( ( C and C ) or C ) or C)
+ C or C or C or C( ( ( C or C ) or C ) or C )
+ C or C or C and C( ( C or C ) or ( C and C ) )
+ C or C and C or C( ( C or ( C and C ) ) or C )
+ C or C and C and C( C or ( ( C and C ) and C ) )
C and ( C or C ) is evaluated as C and ( C or C ) (contrast with the unbracketed string above).
+C and ( C or C ) is evaluated as C and ( C or C ), in contrast to the unbracketed string above.
-Language Codes
+Language Codes
Language ISO 639-3 Code
English eng
+ Russian rus
License
-Copyright (C) 2011 BOSS Development Team.
+Copyright (C) 2012–2013 WrinklyNinja
See the file BOSS ReadMe.html
for copying conditions.
diff --git a/src/parsers.h b/src/parsers.h
index d9d8beb7..4b1b1b76 100644
--- a/src/parsers.h
+++ b/src/parsers.h
@@ -37,6 +37,7 @@
#include