diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..0e0fcb00 --- /dev/null +++ b/.gitignore @@ -0,0 +1,52 @@ +# Compiled source # +################### +*.com +*.class +*.dll +*.exe +*.o +*.so + +# Packages # +############ +# it's better to unpack these files and commit the raw source +# git has its own built in compression methods +*.7z +*.dmg +*.gz +*.iso +*.jar +*.rar +*.tar +*.zip + +# Logs and databases # +###################### +*.log +*.sql +*.sqlite + +# OS generated files # +###################### +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +Icon? +ehthumbs.db +Thumbs.db + +# Other # +######### + +*.user +*.suo +*.sdf +*.opensdf +externals/ +build/ +out/ +bin/ +ipch/ +libstrings-tester.txt diff --git a/docs/BOSS Metadata File Syntax.html b/docs/BOSS Metadata File Syntax.html new file mode 100644 index 00000000..e01b7b63 --- /dev/null +++ b/docs/BOSS Metadata File Syntax.html @@ -0,0 +1,325 @@ + + +BOSS Metadata File Syntax + + + +

BOSS Metadata File Syntax

+ +

Contents

+
    +
  1. Introduction +
  2. File Structure +
  3. Data Structures +
+ +

Introduction

+

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

+ + +

Data Structures

+

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

Message Data Structure

+

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. + + +
Key NameRequiredNotes +
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 Strings section 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 Strings section 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 Codes 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. +
+ +

There are three message types: + + +
KeywordDescription +
sayA generic message, useful for miscellaneous notes. +
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). +
+ +

Example: +condition: if file("Silgrad_Tower.esm") +type: warn +content: Use either Silgrad_Tower.esm or Silgrad_Tower_T.esm but not both together. + + +

File Data Structure

+

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: +[filename] +

where [filename] is a filename relative to the game's Data folder. +

The map form: + + +
Key NameRequiredNotes +
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. +
+ +

Examples: +../obse_loader.exe +or +name: ../obse_loader.exe +condition: if version("../obse_loader.exe", "0.0.18.0", <) +display: OBSE v18+ + + +

Tag Data Structure

+

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

The simple form: +[tag] +

where [tag] is one of two things: +

+

The map form: + + +
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 the Condition Strings section for details. +
+

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

Plugin Data Structure

+

This is the structure that brings all the others together, and forms the main component of a metadata file. It is a key-value map. + + +
Key NameData TypeRequiredNotes +
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✗??? +
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. +
msgmessage list✗The messages attached to this plugin. +
tagtag list✗The Bash Tags suggested for this plugin. +
+

Example: +name: Oscuro's_Oblivion_Overhaul.esm +tag: + - Actors.Spells + - Graphics + - Invent + - Relations + - Scripts + - Stats + - name: -Relations + condition: if file("Mart's Monster Mod for OOO.esm") or if file("FCOM_Convergence.esm") +msg: + - type: say + content: Do not clean. "Dirty" edits are intentional and required for the mod to function. + + +

Metadata File Structure

+

The root of a metadata file is a key-value map. BOSS will recognise the following keys, none of which are required: + + +
Key NameValue TypeNotes +
globalsmessage listA list of global messages. +
pluginsplugin list +
+

Other keys may also be present, but are not processed by BOSS. +

An example metadata file: +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

+

URLs in message content strings will be turned into hyperlinks in BOSS's user interface. Recognised URLs are those that start with 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. +

Examples: +http://www.example.com +becomes +

http://www.example.com
+while +"http://www.example.com example link" +becomes +
example link
+ +

Condition Strings

+

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: +[keyword] [function] *( [operator] [keyword] [function] ) +

where *( ) encloses a phrase that may be repeated zero or more times. +

The [keyword] [function] pair is referred to as a condition, and two conditions joined by an operator is referred to as a compound condition. +

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

Keywords

+

There are two keywords: + + +
KeywordDescription +
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

+

There are several conditions that can be tested for using the functions detailed in the table below. + + +
FunctionSyntaxDescription +
Filefile("[filepath]")Returns true if [filepath] is installed, false otherwise. +
Filefile("[regex]")Returns true if a file matching [regex] is found, false otherwise. +
Checksumchecksum("[filepath]", [checksum])Returns true if the calculated checksum of [filepath] matches [checksum], false otherwise. If [filepath] does not exist, returns false. +
Versionversion("[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 Statusactive("[filepath]")Returns true if [filepath] is a .esp or .esm file that is both installed and active, false otherwise. +
+ +

The different types of condition variable described below. Only version strings are case-sensitive. + + +
Variable TypeSyntax 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. +
+ +

Operators

+

There are two operators, which both operate on the conditions to their immediate left and right: + + +
OperatorSyntaxDescription +
Logical ANDandBoth condition must evaluate to true for the compound condition to evaluate to true. If not, the compound condition evaluates to false. +
Logical ORorOne 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. +
+ +

Order Of Evaluation

+

When a condition string is evaluated, its constituent parts are evaluated in the following order: +

    +
  1. The function is evaluated. +
  2. The keyword-function pair (condition) is evaluated, with the keyword modifying the result of the function's evaluation if necessary. +
  3. 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. +
  4. 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. +
+

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 [keyword] [function] pair is replaced with C after the first example. + + +
String StructureEvaluated 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 ) ) +
+ +

Language Codes

+

BOSS supports the following languages and language codes: + + +
LanguageISO 639-3 Code +
Englisheng +
+ +

License

+

This document is part of the BOSS documentation.
+Copyright (C) 2011 BOSS Development Team.
+See the file BOSS ReadMe.html for copying conditions. diff --git a/src/parsers.h b/src/parsers.h index 70aa555a..64e46a6e 100644 --- a/src/parsers.h +++ b/src/parsers.h @@ -317,21 +317,32 @@ namespace boss { 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 > ',' > unicode::char_ > ')' ) [phoenix::bind(&condition_grammar::CheckVersion, this, qi::labels::_val, qi::labels::_1, qi::labels::_2, qi::labels::_3)] + | ( "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)] ; - quotedStr = '"' > +(unicode::char_ - '"') > '"'; + quotedStr %= '"' > +(unicode::char_ - '"') > '"'; + + comparator %= + unicode::string("==") + | unicode::string("!=") + | unicode::string("<") + | unicode::string(">") + | unicode::string("<=") + | unicode::string(">=") + ; expression.name("expression"); condition.name("condition"); type.name("condition type"); quotedStr.name("quoted string"); + comparator.name("comparator"); qi::on_error(expression, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4)); qi::on_error(condition, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4)); qi::on_error(type, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4)); qi::on_error(quotedStr, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4)); + qi::on_error(comparator, phoenix::bind(&condition_grammar::SyntaxError, this, qi::labels::_1, qi::labels::_2, qi::labels::_3, qi::labels::_4)); } void SetGame(boss::Game& g) { @@ -339,8 +350,8 @@ namespace boss { } private: - qi::rule expression, condition, type; - qi::rule quotedStr; + qi::rule expression, andStatement, condition, type; + qi::rule quotedStr, comparator; boss::Game * game; @@ -394,11 +405,11 @@ namespace boss { result = checksum == crc; } - void CheckVersion(bool& result, const std::string& file, const std::string& version, const char comparator) { + void CheckVersion(bool& result, const std::string& file, const std::string& version, const std::string& comparator) { CheckFile(result, file); if (!result) { - if (comparator == '<') + if (comparator == "!=" || comparator == "<" || comparator == "<=") result = true; return; } @@ -406,20 +417,13 @@ namespace boss { Version givenVersion = Version(version); Version trueVersion = Version(game->DataPath() / file); - switch (comparator) { - case '>': - if (trueVersion <= givenVersion) - result = false; - break; - case '<': - if (trueVersion >= givenVersion) - result = false; - break; - case '=': - if (trueVersion != givenVersion) - result = false; - break; - } + if ( (comparator == "==" && trueVersion != givenVersion) + || (comparator == "!=" && trueVersion == givenVersion) + || (comparator == "<" && trueVersion >= givenVersion) + || (comparator == ">" && trueVersion <= givenVersion) + || (comparator == "<=" && trueVersion > givenVersion) + || (comparator == ">=" && trueVersion < givenVersion)) + result = false; } void CheckActive(bool& result, const std::string& file) {