loot/libloot
0
0
Fork 0
mirror of https://github.com/loot/libloot.git synced 2026-07-27 14:16:01 -07:00
Code Issues Packages Projects Releases Wiki Activity

More syntax changes, separated the 'file' condition function into 'file' and 'regex' since it's otherwise impossible to tell just from the string passed, got rid of the 'if' keyword and turned 'ifnot' into 'not'. Regexes can only contain non-literal syntax in the filename part of the path they give, as a way to prevent accidental scanning of thousands of files across a range of sub-directories. Also changed some of the terminology for the components of a condition string.

Browse Source
This commit is contained in:
WrinklyNinja
2013-01-09 23:44:06 +00:00
parent b4202b7703
commit 4ea3805d42
4 changed files with 323 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README
+4 -1
View File
@@ -252,7 +252,10 @@ to support positioning of plugins precisely relative to other plugins, but it
may be possible to achieve the positioning using only the priority setting. If
possible, that is preferred.
Further details can be found in the File Format doc.
When the masterlist/userlist is loaded, it is scanned for entries for each of
the installed plugins. If more than one match is found, they should be merged.
Further details can be found in the 'docs/BOSS Metadata File Syntax.html' file.
Networking
docs/BOSS Metadata File Syntax.html
+197 -160
View File
@@ -2,54 +2,53 @@
<meta charset="utf-8">
<title>BOSS Metadata File Syntax</title>
<style>
body {font-family:Helvetica,sans-serif;font-size:10pt;}
h1 + p {text-align:center;}
li {margin-bottom:10px;}
li ul, li ol {margin-top:0.4em;}
q {font-style:italic;}
code {display:inline-block; padding:2px 5px; background:#eee;}
td, th {border:1px solid #ddd; padding: 5px; vertical-align:top;}
table {border-collapse:collapse; margin:1em;background:#FafaFf;}
thead {font-weight:bold;background:#99CCFF;}
code.box {line-height:20px; white-space:pre; margin:1em 1em 1em 3em; display:table; padding:5px 10px;}
ol li ol {list-style:lower-alpha;}
ol li ol li ol {list-style:lower-roman;}
ol ol li {margin-bottom:0.2em;}
blockquote {background:#E6E6FA; display:table; padding:5px 10px;}
h1 {text-align:center;font-size:24pt;}
h2 {margin-top:3em;font-size:20pt;}
h3 {margin-top:2em;font-size:16pt;}
h4 {margin-top:2em;font-size:12pt;}
body {
font:12pt/1.5 Helvetica,sans-serif;
text-rendering:optimizeLegibility;}
p, ul, li {margin:1.5em 0;}
h1,h3,h2 {font-weight:normal;}
h1{
font-size:36pt;
line-height:0.5;
margin-top:1.125em;
margin-bottom:0.375em;}
h2{
font-size:24pt;
line-height:0.75;
margin-top:3em;
margin-bottom:1.5em;}
h3{
font-size:18pt;
line-height:1;
margin-top:3.5em;
margin-bottom:1em;}
ul, ol {margin-top:0.5em; margin-bottom:1em;}
li {margin:0.75em 0;}
a:link {text-decoration:none;}
a:hover {text-decoration:underline;}
ol ol {list-style:lower-alpha;}
code {display:inline-block; padding:0 3px; background:#eee;}
td, th {border:1px solid #ddd; padding: 5px; vertical-align:top;}
table {border-collapse:collapse; margin:1.5em; margin-bottom: 3em; background:#fafafa;}
thead {background:#99CCFF;}
code.box {border-radius:5px; border:1px solid #ccc; padding:0.75em; white-space:pre; overflow-x:auto; display:table; margin:1.5em;}
blockquote {border-radius:3px; border:1px solid #0c0; padding:5px; background:#7e7; display:table;margin:1.5em;}
a[href^="http"]:after {padding-left:2px; content: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAVklEQVR4Xn3PgQkAMQhDUXfqTu7kTtkpd5RA8AInfArtQ2iRXFWT2QedAfttj2FsPIOE1eCOlEuoWWjgzYaB/IkeGOrxXhqB+uA9Bfcm0lAZuh+YIeAD+cAqSz4kCMUAAAAASUVORK5CYII=);}
ul.errorMessages > li {margin-bottom:1.4em;}
td.t {background:#90ff90;text-align:center;}
td.c {background:#ff9090;text-align:center;}
td.t:after {content: '\2713';}
td.c:after {content: '\2717';}
img {border:0;}
.slideshow img {opacity:0;
position:absolute;
transition: opacity 1.5s;
-moz-transition: opacity 1.5s;
-webkit-transition: opacity 1.5s;
-o-transition: opacity 1.5s;}
.slideshow img:first-child {opacity:1;}
figcaption {font-style:italic; margin-bottom:2em;}
tr.inactive {color:#888;}
tr.inactive td.c, tr.inactive td.t {background:#E3E3E3;}
span[title] {border-bottom: 1px dotted; font-family: sans-serif; cursor:help;}
dt {margin-bottom:0.5em; margin-top:1em; font-style:italic;}
dd {margin-bottom:0.8em;}
abbr {cursor:help;}
#warning {background:#c00; padding:10px 5px;margin:-8px;}
var {color:#8B4513;}
</style>
<!-- BOSS
A plugin load order optimiser for games that use the esp/esm plugin system.
Copyright (C) 2012 WrinklyNinja
Copyright (C) 2012–2013 WrinklyNinja
This file is part of BOSS.
@@ -68,38 +67,100 @@
<http://www.gnu.org/licenses/>.
-->
<div id="warning">
This documentation is a work in progress, covering a syntax that is also still a work in progress, and is subject to change. The definition of the <code>priority</code> node of the <code>plugin</code> data structure is incomplete.
</div>
<h1>BOSS Metadata File Syntax</h1>
<h2>Contents</h2>
<ol>
<li><a href="#intro">Introduction</a>
<li><a href="#struct">File Structure</a>
<li><a href="#filestruct">Metadata File Structure</a>
<li><a href="#structs">Data Structures</a>
<ol>
<li><a href="#structs-message">Message Data Structure</a>
<li><a href="#structs-file">File Data Structure</a>
<li><a href="#structs-tag">Tag Data Structure</a>
<li><a href="#structs-plugin">Plugin Data Structure</a>
</ol>
<li><a href="#message">Message Strings</a>
<li><a href="#cond">Condition Strings</a>
<ol>
<li><a href="#cond-function">Functions</a>
<li><a href="#cond-operator">The Negator &amp; Junctors</a>
<li><a href="#cond-order">Order Of Evaluation</a>
</ol>
<li><a href="#lang">Language Codes</a>
<li><a href="#license">License</a>
</ol>
<h2 id="intro">Introduction</h2>
<p>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.
<p>Some important points about how BOSS uses YAML.
<p>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 <a href="https://en.wikipedia.org/wiki/YAML">Wikipedia page</a> is a good introduction. All you really need to know is:
<ul>
<li>Child data nodes should be indented two spaces from their parents (see the example later in this document if you don't understand). This isn't a strict requirement, but is the best trade-off between compactness and readability.
<li>Strings should be enclosed in double quotes if they contain any of the following characters: <code>-?:,[]{}#&amp;*!|&gt;'"%@`</code>. Any backslashes or double quotes within a quoted string should be escaped with a backslash, ie. <code>"</code> -> <code>\"</code> and <code>\</code> -> <code>\\</code>.
<li>File paths must be specified using forwardslashes to delimit directory components, not backslashes.
<li>For some file data, BOSS can accept either regular expressions or exact file paths. It differentiates between the two by checking the period preceding the file extension: in regex it should be escaped with a backslash <code>\.</code>, whereas in a file path it is not.
<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.
</ul>
<p>Some important points that are more specific to how BOSS uses YAML:
<ul>
<li>Child data nodes should be indented two spaces from their parents. This isn't a strict requirement, but is the best trade-off between compactness and readability.
<li>Strings should be enclosed in single quotes if they contain any of the following characters: <code>-?:,[]{}#&amp;*!|&gt;"%@`</code>, 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. <code>"</code> &#x2192; <code>\"</code> and <code>\</code> &#x2192; <code>\\</code>.
<li>Strings are case-sensitive, apart from file paths, regular expressions and checksums.
</ul>
<p>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.
<p>Some properties of file paths as used by BOSS:
<ul>
<li>They are evaluated as paths relative to the game's Data folder.
<li>They cannot reference a path outside of the game's folder structure, ie. they cannot contain the substring <code>../../</code>.
<li>Regular expression file paths must be written in the <a href="http://www.boost.org/doc/libs/1_50_0/libs/regex/doc/html/boost_regex/syntax/basic_extended.html">POSIX Extended</a> syntax.
<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>, BOSS 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.
</ul>
<h2 id="filestruct">Metadata File Structure</h2>
<p>The root of a metadata file is a key-value map. BOSS will recognise the following keys, none of which are required:
<table>
<thead><tr><th>Key Name<th>Value Type<th>Notes
<tbody>
<tr><td><code>globals</code><td>message list<td>A list of message data structures for messages that are displayed independently of any plugin.
<tr><td><code>plugins</code><td>plugin list<td>A list of plugin data structures, holding all the plugin metadata within the file.
</table>
<p>Other keys may also be present, but are not processed by BOSS. The message and plugin data structures are detailed in the next section.
<p>An example metadata file:
<code class="box">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
</code>
<h2 id="structs">Data Structures</h2>
<p>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.
<p>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.
<h3 id="structs-message">Message Data Structure</h3>
<p>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.
<p>Messages are given as key-value maps.
<table>
<thead><tr><th>Key Name<th>Required<th>Notes
<tbody>
<tr><td><code>type</code><td>&#x2713;<td>The type string can be one of three keywords, see the table below for their semantics.
<tr><td><code>content</code><td>&#x2713;<td>The actual message content string. It has a few special properties, see the <q>Message Strings</q> section for details.
<tr><td><code>condition</code><td>&#x2717;<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 the <q>Condition Strings</q> section for details.
<tr><td><code>lang</code><td>&#x2717;<td>What language this message is written in, given as an ISO 639-3 language code. The languages BOSS supports are given in the <q>Language Codes</q> section. 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.
<tr><td><code>content</code><td>&#x2713;<td>The actual message content string. It has a few special properties, see <a href="#message">Message Strings</a> for details.
<tr><td><code>condition</code><td>&#x2717;<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 <a href="#cond">Condition Strings</a> for details.
<tr><td><code>lang</code><td>&#x2717;<td>What language this message is written in, given as an ISO 639-3 language code. The languages BOSS supports are given in <a href="#lang">Language Codes</a>. 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.
</table>
<p>There are three message types:
@@ -112,7 +173,7 @@
</table>
<p>Example:
<code class="box">condition: if file("Silgrad_Tower.esm")
<code class="box">condition: 'file("Silgrad_Tower.esm")'
type: warn
content: Use either Silgrad_Tower.esm or Silgrad_Tower_T.esm but not both together.
</code>
@@ -120,46 +181,42 @@ content: Use either Silgrad_Tower.esm or Silgrad_Tower_T.esm but not both togeth
<h3 id="structs-file">File Data Structure</h3>
<p>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.
<p>The simple form:
<code class="box"><var>[filename]</var></code>
<p>where <var>[filename]</var> is a filename relative to the game's Data folder.
<code class="box"><var>filepath</var></code>
<p>where <code><var>filepath</var></code> is a file path relative to the game's Data folder.
<p>The map form:
<table>
<thead><tr><th>Key Name<th>Required<th>Notes
<tbody>
<tr><td><code>name</code><td>&#x2713;<td>A filename relative to the game's Data folder. Case-insensitive. Directory components must be delimited by forwardslashes, not backslashes.
<tr><td><code>display</code><td>&#x2717;<td>A substitute string to be displayed instead of the filename in any generated messages, eg. the name of the mod the file belongs to.
<tr><td><code>condition</code><td>&#x2717;<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 the <q>Condition Strings</q> section for details.
<tr><td><code>name</code><td>&#x2713;<td>A file path relative to the game's Data folder.
<tr><td><code>display</code><td>&#x2717;<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>&#x2717;<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 <a href="#cond">Condition Strings</a> for details.
</table>
<p>Examples:
<code class="box">../obse_loader.exe</code>
or
<code class="box">name: ../obse_loader.exe
condition: if version("../obse_loader.exe", "0.0.18.0", &lt;)
condition: 'version("../obse_loader.exe", "0.0.18.0", &lt;)'
display: OBSE v18+
</code>
<h3 id="structs-tag">Tag Data Structure</h3>
<p>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.
<p>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.
<p>The simple form:
<code class="box"><var>[tag]</var></code>
<p>where <var>[tag]</var> is one of two things:
<ul>
<li>If the Tag is being suggested for addition, <var>[tag]</var> is just the Tag name, eg. <code>Graphics</code>.
<li>If the Tag is being suggested for removal, <var>[tag]</var> is the Tag name preceded by a minus sign, eg. <code>-Graphics</code>.
</ul>
<code class="box"><var>tag</var></code>
<p>where <code><var>tag</var></code> is the Bash Tag, preceded by a minus sign if it is suggested for removal.
<p>The map form:
<table>
<thead><tr><th>Key Name<th>Required<th>Notes
<tbody>
<tr><td><code>name</code><td>&#x2713;<td>A Bash Tag, preceded by a minus sign if it is suggested for removal.
<tr><td><code>condition</code><td>&#x2717;<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 the <q>Condition Strings</q> section for details.
<tr><td><code>condition</code><td>&#x2717;<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 <a href="#cond">Condition Strings</a> for details.
</table>
<p>Examples:
<code class="box">Relations</code>
or
<code class="box">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\")"
</code>
<h3 id="structs-plugin">Plugin Data Structure</h3>
@@ -167,9 +224,9 @@ condition: if file("Mart's Monster Mod for OOO.esm") or if file("FCOM_Convergenc
<table>
<thead><tr><th>Key Name<th>Data Type<th>Required<th>Notes
<tbody>
<tr><td><code>name</code><td>string<td>&#x2713;<td>Can be an exact plugin filename or a regular expression using the <a href="http://www.boost.org/doc/libs/1_50_0/libs/regex/doc/html/boost_regex/syntax/basic_extended.html">POSIX Extended</a> syntax. Case-insensitive.
<tr><td><code>enabled</code><td>boolean<td>&#x2717;<td>Enables or disables use of the plugin object. Used for user rules, but no reason to use it in the masterlist.
<tr><td><code>priority</code><td>integer<td>&#x2717;<td>???
<tr><td><code>name</code><td>string<td>&#x2713;<td>Can be an exact plugin filename or a regular expression plugin filename. If the period that precedes the file extension has been escaped (eg. <code>\.esp</code>, <code>\.esm</code>), the string is treated as a regular expression, otherwise it is treated as an exact filename.
<tr><td><code>enabled</code><td>boolean<td>&#x2717;<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>&#x2717;<td>??? If unspecified, defaults to <code>0</code>.
<tr><td><code>after</code><td>file list<td>&#x2717;<td>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 list<td>&#x2717;<td>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.
<tr><td><code>inc</code><td>file list<td>&#x2717;<td>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
<tr><td><code>tag</code><td>tag list<td>&#x2717;<td>The Bash Tags suggested for this plugin.
</table>
<p>Example:
<code class="box">name: Oscuro's_Oblivion_Overhaul.esm
<code class="box">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.'
</code>
<h2>Metadata File Structure</h2>
<p>The root of a metadata file is a key-value map. BOSS will recognise the following keys, none of which are required:
<table>
<thead><tr><th>Key Name<th>Value Type<th>Notes
<tbody>
<tr><td><code>globals</code><td>message list<td>A list of global messages.
<tr><td><code>plugins</code><td>plugin list<td>
</table>
<p>Other keys may also be present, but are not processed by BOSS.
<p>An example metadata file:
<code class="box">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
</code>
<h2>Message Strings</h2>
<h2 id="message">Message Strings</h2>
<p>URLs in message content strings will be turned into hyperlinks in BOSS's user interface. Recognised URLs are those that start with <code>file:</code>, <code>http:</code> or <code>https:</code> 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.
<p>Examples:
<code class="box">http://www.example.com</code>
@@ -234,93 +260,104 @@ while
becomes
<blockquote><a href="http://www.example.com">example link</a></blockquote>
<h2>Condition Strings</h2>
<p>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:
<code class="box">[keyword] [function] *( [operator] [keyword] [function] )</code>
<p>where <code>*( )</code> encloses a phrase that may be repeated zero or more times.
<p>The <code>[keyword] [function]</code> pair is referred to as a condition, and two conditions joined by an operator is referred to as a compound condition.
<h2 id="cond">Condition Strings</h2>
<p>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 <a href="https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form">EBNF</a> grammar is:
<code class="box">[ negator ], function, { junctor, [ negator ], function } ;</code>
<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>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.
<h3>Keywords</h3>
<p>There are two keywords:
<table>
<thead><tr><th>Keyword<th>Description
<tbody>
<tr><td><code>if</code><td>If the following <code><var>[function]</var></code> evaluates to true, the condition will be true. Otherwise, the condition will be false.
<tr><td><code>ifnot</code><td>If the following <code><var>[function]</var></code> evaluates to false, the condition will be true. Otherwise, the condition will be false.
</table>
<h3>Functions</h3>
<h3 id="cond-function">Functions</h3>
<p>There are several conditions that can be tested for using the functions detailed in the table below.
<table>
<thead><tr><th>Function<th>Syntax<th>Description
<tbody>
<tr><td>File<td><code>file("<var>[filepath]</var>")</code><td>Returns true if <var>[filepath]</var> is installed, false otherwise.
<tr><td>File<td><code>file("<var>[regex]</var>")</code><td>Returns true if a file matching <var>[regex]</var> is found, false otherwise.
<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 expression <code><var>[version] [comparator] [actual version of [filepath]]</var></code> holds true, false otherwise. If <var>[filepath]</var> does not exist and <var>[comparator]</var> is <code>==</code>, <code>&gt;</code> or <code>&gt;=</code>, returns false. If <var>[filepath]</var> does not exist and <var>[comparator]</var> is <code>!=</code>, <code>&lt;</code> or <code>&lt;=</code>, returns true.
<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>File<td><code>file("<var>filepath</var>")</code><td>Returns true if <var>filepath</var> is installed, false otherwise.
<tr><td>File<td><code>regex("<var>regex</var>")</code><td>Returns true if a file matching <var>regex</var> is found, false otherwise.
<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><var>version comparator</var> (actual version of <var>filepath</var>)</code> holds true, false otherwise. If <var>filepath</var> does not exist and <var>comparator</var> is <code>==</code>, <code>&gt;</code> or <code>&gt;=</code>, returns false. If <var>filepath</var> does not exist and <var>comparator</var> is <code>!=</code>, <code>&lt;</code> or <code>&lt;=</code>, returns true.
<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.
</table>
<p>The different types of condition variable described below. Only version strings are case-sensitive.
<p>The different types of variable used in the above functions are described in more detail below.
<table>
<thead><tr><th>Variable Type<th>Syntax Description
<thead><tr><th>Variable Type<th>Description
<tbody>
<tr><td><code>[filepath]</code><td>A file path or regular expression string to match file paths to. Must not contain a double quote character <code>"</code>. 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.
<tr><td><code>[regex]</code><td>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 <a href="http://www.boost.org/doc/libs/1_50_0/libs/regex/doc/html/boost_regex/syntax/basic_extended.html">POSIX Extended</a>.
<tr><td><code>[checksum]</code><td>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.
<tr><td><code>[version]</code><td>A string of characters representing the version of a plugin or executable. BOSS 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>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code> or <code>&gt;=</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.
<tr><td><code>filepath</code><td>A Windows file path.
<tr><td><code>regex</code><td>A regular expression string to match file paths to.
<tr><td><code>checksum</code><td>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.
<tr><td><code>version</code><td>A string of characters representing the version of a plugin or executable. BOSS 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>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code> or <code>&gt;=</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.
</table>
<h3>Operators</h3>
<p>There are two operators, which both operate on the conditions to their immediate left and right:
<h3 id="cond-operator">The Negator &amp; Junctors</h3>
<p>The negator, or logical negation operator, inverts the value of the function that follows it. Its inclusion is optional, and its syntax is simply:
<code class="box">not</code>
<p>Below is a truth table for the negator.
<table>
<thead><tr><th>Operator<th>Syntax<th>Description
<thead><tr><th>Value of <code><var>function</var></code><th>Value of <code>not <var>function</var></code>
<tbody>
<tr><td>Logical AND<td><code>and</code><td>Both condition must evaluate to true for the compound condition to evaluate to true. If not, the compound condition evaluates to false.
<tr><td>Logical OR<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.
<tr><td>false<td>true
<tr><td>true<td>false
</table>
<h3>Order Of Evaluation</h3>
<p>When a condition string is evaluated, its constituent parts are evaluated in the following order:
<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>
<h3 id="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.
<ol>
<li>The function is evaluated.
<li>The keyword-function pair (condition) is evaluated, with the keyword modifying the result of the function's evaluation if necessary.
<li>If AND operators are present, then they are evaluated using the evaluation results of the conditions to their immediate left and right, reading from left to right.
<li>If OR operators are present, then they are evaluated using the evaluation results of the AND operators (if present) or conditions to their immediate left and right, reading from left to right.
<li>Function
<li>Negator
<li>Logical <q>and</q>
<li>Logical <q>or</q>
</ol>
<p>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 <code>[keyword] [function]</code> pair is replaced with <code>C</code> after the first example.
<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>keyword</var> <var>function</var></code> pair is replaced with <code><var>C</var></code> after the first example.
<table>
<thead><tr><th>String Structure<th>Evaluated As
<tbody>
<tr><td><code>[keyword] [function]</code><td><code>( [keyword] ( [function] ) )</code>
<tr><td><code>C and C</code><td><code>( C and C )</code>
<tr><td><code>C or C</code><td><code>( C or C )</code>
<tr><td><code>C and C and C</code><td><code>( ( C and C ) and C )</code>
<tr><td><code>C or C or C</code><td><code>( ( C or C ) or C )</code>
<tr><td><code>C and C or C</code><td><code>( ( C and C ) or C )</code>
<tr><td><code>C or C and C</code><td><code>( C or ( C and C ) )</code>
<tr><td><code>C and C and C and C</code><td><code>( ( ( C and C ) and C ) and C )</code>
<tr><td><code>C and C and C or C</code><td><code>( ( ( C and C ) and C ) or C )</code>
<tr><td><code>C and C or C and C</code><td><code>( ( C and C ) or ( C and C ) )</code>
<tr><td><code>C and C or C or C</code><td><code>( ( ( C and C ) or C ) or C)</code>
<tr><td><code>C or C or C or C</code><td><code>( ( ( C or C ) or C ) or C )</code>
<tr><td><code>C or C or C and C</code><td><code>( ( C or C ) or ( C and C ) )</code>
<tr><td><code>C or C and C or C</code><td><code>( ( C or ( C and C ) ) or C )</code>
<tr><td><code>C or C and C and C</code><td><code>( C or ( ( C and C ) and C ) )</code>
<tr><td><code><var>keyword</var> <var>function</var></code><td><code>( <var>keyword</var> ( <var>function</var> ) )</code>
<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>
</table>
<p>You can also explicitly enclose any condition in brackets to override the evaluation order, eg. <code>C and ( C or C )</code> is evaluated as <code>C and ( C or C )</code> (contrast with the unbracketed string above).
<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.
<h2>Language Codes</h2>
<h2 id="lang">Language Codes</h2>
<p>BOSS supports the following languages and language codes:
<table>
<thead><tr><th>Language<th>ISO 639-3 Code
<tbody>
<tr><td>English<td>eng
<tr><td>Russian<td>rus
</table>
<h2 id="license">License</h2>
<p>This document is part of the BOSS documentation.<br>
Copyright (C) 2011 BOSS Development Team.<br>
Copyright (C) 2012–2013 WrinklyNinja<br>
See the file <q>BOSS ReadMe.html</q> for copying conditions.
src/parsers.h
+121 -43
View File
@@ -37,6 +37,7 @@
#include <boost/regex.hpp>
#include <boost/filesystem.hpp>
#include <boost/algorithm/string.hpp>
#include <boost/algorithm/string/regex.hpp>
#include <boost/spirit/include/qi.hpp>
#include <boost/spirit/include/phoenix_core.hpp>
#include <boost/spirit/include/phoenix_operator.hpp>
@@ -228,7 +229,7 @@ namespace YAML {
out << BeginMap
<< Key << "name" << rhs.Name();
if (!rhs.Condition().empty())
if (rhs.IsConditional())
out << Key << "condition" << rhs.Condition();
if (!rhs.DisplayName().empty())
@@ -300,50 +301,69 @@ namespace boss {
condition_grammar() : condition_grammar::base_type(expression, "condition grammar") {
expression =
andStatement [qi::labels::_val = qi::labels::_1]
>> *((qi::lit("or") >> andStatement) [qi::labels::_val = qi::labels::_val || qi::labels::_1])
compound [qi::labels::_val = qi::labels::_1]
>> *((qi::lit("or") >> compound) [qi::labels::_val = qi::labels::_val || qi::labels::_1])
;
andStatement =
compound =
condition [qi::labels::_val = qi::labels::_1]
>> *((qi::lit("and") >> condition) [qi::labels::_val = qi::labels::_val && qi::labels::_1])
;
condition =
( qi::lit("if") >> type ) [qi::labels::_val = qi::labels::_1]
| ( qi::lit("ifnot") >> type ) [qi::labels::_val = !qi::labels::_1]
| ( '(' >> expression >> ')' ) [qi::labels::_val = qi::labels::_1] //This *should* handle the "brackets override operators" rule.
;
function [qi::labels::_val = qi::labels::_1]
| ( qi::lit("not") > function ) [qi::labels::_val = !qi::labels::_1]
| ( '(' > expression > ')' ) [qi::labels::_val = qi::labels::_1]
;
type =
( "file(" > quotedStr > ')' ) [phoenix::bind(&condition_grammar::CheckFile, this, qi::labels::_val, qi::labels::_1)]
| ( "checksum(" > quotedStr > ',' > qi::hex > ')' ) [phoenix::bind(&condition_grammar::CheckSum, this, qi::labels::_val, qi::labels::_1, qi::labels::_2)]
| ( "version(" > quotedStr > ',' > quotedStr > ',' > comparator > ')' ) [phoenix::bind(&condition_grammar::CheckVersion, this, qi::labels::_val, qi::labels::_1, qi::labels::_2, qi::labels::_3)]
| ( "active(" > quotedStr > ')' ) [phoenix::bind(&condition_grammar::CheckActive, this, qi::labels::_val, qi::labels::_1)]
function =
( "file(" > filePath > ')' ) [phoenix::bind(&condition_grammar::CheckFile, this, qi::labels::_val, qi::labels::_1)]
| ( "regex(" > quotedStr > ')' ) [phoenix::bind(&condition_grammar::CheckRegex, this, qi::labels::_val, qi::labels::_1)]
| ( "checksum(" > filePath > ',' > qi::hex > ')' ) [phoenix::bind(&condition_grammar::CheckSum, this, qi::labels::_val, qi::labels::_1, qi::labels::_2)]
| ( "version(" > filePath > ',' > quotedStr > ',' > comparator > ')' ) [phoenix::bind(&condition_grammar::CheckVersion, this, qi::labels::_val, qi::labels::_1, qi::labels::_2, qi::labels::_3)]
| ( "active(" > filePath > ')' ) [phoenix::bind(&condition_grammar::CheckActive, this, qi::labels::_val, qi::labels::_1)]
;
quotedStr %= '"' > +(unicode::char_ - '"') > '"';
filePath %= '"' > +(unicode::char_ - invalidPathChars) > '"';
invalidPathChars %=
unicode::char_(':')
| unicode::char_('*')
| unicode::char_('?')
| unicode::char_('"')
| unicode::char_('<')
| unicode::char_('>')
| unicode::char_('|')
;
comparator %=
unicode::string("==")
| unicode::string("!=")
| unicode::string("<")
| unicode::string(">")
| unicode::string("<=")
| unicode::string(">=")
;
unicode::string("==")
| unicode::string("!=")
| unicode::string("<")
| unicode::string(">")
| unicode::string("<=")
| unicode::string(">=")
;
expression.name("expression");
compound.name("compound condition");
condition.name("condition");
type.name("condition type");
function.name("function");
quotedStr.name("quoted string");
filePath.name("file path");
comparator.name("comparator");
invalidPathChars.name("invalid file path characters");
qi::on_error<qi::fail>(expression, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(compound, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(condition, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(type, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(function, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(quotedStr, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(filePath, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(comparator, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
qi::on_error<qi::fail>(invalidPathChars, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4));
}
void SetGame(boss::Game& g) {
@@ -351,40 +371,84 @@ namespace boss {
}
private:
qi::rule<Iterator, bool(), Skipper> expression, andStatement, condition, type;
qi::rule<Iterator, std::string()> quotedStr, comparator;
qi::rule<Iterator, bool(), Skipper> expression, compound, condition, function;
qi::rule<Iterator, std::string()> quotedStr, filePath, comparator;
qi::rule<Iterator, char()> invalidPathChars;
boss::Game * game;
//Eval's regex and exact paths. Check for files and ghosted plugins.
void CheckFile(bool& result, const std::string& file) {
if (boost::contains(file, "\\.")) { //Regex. Only supports filenames right now.
result = false;
boost::regex regex;
try {
regex = boost::regex(file, boost::regex::extended|boost::regex::icase);
} catch (boost::regex_error e) {
throw std::runtime_error("The regex string \"" + file + "\" is invalid.");
// LOG_ERROR("\"%s\" is not a valid regular expression. Item skipped.", reg.c_str());
}
for (fs::directory_iterator itr(game->DataPath()); itr != fs::directory_iterator(); ++itr) {
if (fs::is_regular_file(itr->status())) {
if (boost::regex_match(itr->path().filename().string(), regex)) {
result = true;
break;
}
}
}
if (!IsSafePath(file))
throw std::runtime_error("The file path \"" + file + "\" is invalid.");
} else if (IsPlugin(file))
if (IsPlugin(file))
result = boost::filesystem::exists(game->DataPath() / file) || boost::filesystem::exists(game->DataPath() / (file + ".ghost"));
else
result = boost::filesystem::exists(game->DataPath() / file);
}
void CheckRegex(bool& result, const std::string& regexStr) {
result = false;
//Can't support a regex string where all path components may be regex, since this could
//lead to massive scanning if an unfortunately-named directory is encountered.
//As such, only the filename portion can be a regex. Need to separate that from the rest
//of the string.
/* Look for directory separators: in non-regex strings, they are '/' and '\'. In regex,
the backslash is special so must be escaped using another backslash, so look for '/' and "\\".
In C++ string literals, the backslash must be escaped once more to give "\\\\".
Split the regex with another regex! */
//Need to also check if the regex is for a safe path.
boost::regex sepReg("/|(\\\\)", boost::regex::extended);
std::vector<std::string> components;
boost::algorithm::split_regex(components, regexStr, sepReg);
std::string filename = components.back();
components.pop_back();
std::string parent;
for (std::vector<std::string>::const_iterator it=components.begin(), endIt=components.end()--; it != endIt; ++it) {
if (*it == ".")
continue;
parent += *it + '/';
}
if (boost::contains(parent, "../../"))
throw std::runtime_error("The folder path \"" + parent + "\" is invalid.");
//Now we have a valid parent path and a regex filename. Check that
//the parent path exists and is a directory.
boost::filesystem::path parent_path = game->DataPath() / parent;
if (!boost::filesystem::exists(parent_path) || !boost::filesystem::is_directory(parent_path))
return;
boost::regex regex;
try {
regex = boost::regex(filename, boost::regex::extended|boost::regex::icase);
} catch (boost::regex_error e) {
throw std::runtime_error("The regex string \"" + filename + "\" is invalid.");
}
for (fs::directory_iterator itr(parent_path); itr != fs::directory_iterator(); ++itr) {
if (boost::regex_match(itr->path().filename().string(), regex)) {
result = true;
return;
}
}
}
void CheckSum(bool& result, const std::string& file, const uint32_t checksum) {
if (!IsSafePath(file))
throw std::runtime_error("The file path \"" + file + "\" is invalid.");
uint32_t crc;
boost::unordered_map<std::string,uint32_t>::iterator it = game->crcCache.find(boost::to_lower_copy(file));
@@ -442,6 +506,20 @@ namespace boss {
throw std::runtime_error("Error parsing condition at \"" + context + "\", expected \"" + what.tag + "\"");
}
//Checks that the path (not regex) doesn't go outside any game folders.
bool IsSafePath(const std::string& path) {
std::vector<std::string> components;
boost::split(components, path, boost::is_any_of("/\\"));
components.pop_back();
std::string parent_path;
for (std::vector<std::string>::const_iterator it=components.begin(), endIt=components.end()--; it != endIt; ++it) {
if (*it == ".")
continue;
parent_path += *it + '/';
}
return !boost::contains(parent_path, "../../");
}
};
bool ConditionalData::EvalCondition(boss::Game& game) const {
src/tester.cpp
+1 -1
View File
@@ -23,7 +23,7 @@ int main() {
cout << "Testing masterlist parser." << endl;
YAML::Node test = YAML::LoadFile("masterlist-example.yaml");
YAML::Node test = YAML::LoadFile("masterlist.yaml");
list<boss::Message> globalMessages;
if (test["globals"]) {