----------------------------------------------------------------------

mlox_rules_guide.txt - A Guide to reading/writing rules for the rule-base

----------------------------------------------------------------------
Copyright 2011 John Moonsugar <john.moonsugar@gmail.com>
License: MIT License (see the file: License.txt)
----------------------------------------------------------------------
This is mlox_rules_guide.txt which describes how to read/write the rules
and use the rule-base.
See mlox_readme.txt for a basic information on what mlox is and how
to use it.
See mlox_guts.txt for a discussion of mlox's inner workings.
----------------------------------------------------------------------

o Note about Line Endings

o How Rules work
oo Filename Expansion
o Ordering Rules
oo The Order Rule
oo Customizing your Load Order
oo The NearStart Rule
oo The NearEnd Rule
o Warning Rules
oo Messages
oo Boolean Expressions
ooo The Desc predicate
ooo The Size predicate
ooo The Ver predicate
oo The Note Rule
oo The Requires Rule
oo The Conflict Rule
oo The Patch Rule

------------------------------------------------------------
o How Rules work

Multiple instances of rules are allowed.

Rules from mlox_user.txt take precedence over those in mlox_base.txt.

The user is encouraged to use mlox_user.txt to customize their load
order, while mlox_base.txt serves as a repository of community
knowledge about plugin order, conflicts, notes and such.

A rule starts with a label, like "[Order]", and ends when a new rule
starts, or at the end of file.

All filename comparisons are caseless, so you do not have to worry

about capitalization of plugin names when entering rules.

Comments begin with ';'. When mlox reads rules, comments are first
stripped, and then blank lines are ignored.

In mlox_base.txt, most rules are grouped into "sections", which begin

with "@" followed by the section name, and each section corresponds
more or less to one "Mod". This is only a convention to help keep
order in the file, and to generate some happy statistics.

Filenames do not need to be quoted. The parser is smart enough to

figure out where the names start and end.
------------------------------------------------------------
oo Filename Expansion

mlox will recognize special characters in filenames used in the rule-base, and
expand them into files that exist in your load order.

First, there are 2 special metacharacters that are treated in the canonical
fashion: '?' and '*':

? matches any single character

* matches any number of characters

There is also a special construct: <VER> which matches something that looks
like a Version number in the filename. This will match the same version number
forms used in the [VER] predicate, refer to the documentation of that
predicate for more.

Examples:

plugin-?.esp matches: plugin-A.esp, plugin-3.esp, and so on.

plugin-*.esp matches: plugin-one.esp plugin-Banana.esp, and so on.
plugin-<VER>.esp matches: plugin-1.0.esp, plugin-3.3g.esp, and so on.

[Note: expanding filenames in rules can be rather CPU intensive, so while they
are convenient, it is suggested that filename expansions be used sparingly.]

------------------------------------------------------------
o Ordering Rules

oo The Order Rule

* The [Order] rule specifies the order of plugins. (In the following
example, plugin-1.esm comes before plugin-2.esp which comes before
plugin-N.esp, and so on). If two orderings conflict, the first one
encountered wins. Order conflicts are called "cycles", and an example
would be if we have one rule that puts aaa.esp before bbb.esp, and
another rule that puts bbb.esp before aaa.esp. Whenever we encounter a
rule that would cause a cycle, it is discarded.

[Order]
plugin-1.esm
plugin-2.esp
.
.
plugin-N.esp

This rule is read: "plugin-1.esm precedes plugin-2.esp which precedes

plugin-N.esp". It means that plugin-1.esm must precede plugin-2.esp
AND plugin-2.esp must precede plugin-N.esp in the load order. This
relationship is transitive, so plugin-1 must also precede plugin-N.

oo Customizing your Load Order

For people that want to customize their load order, the [Order] rule is
probably all that is needed. Here is a simple example:

Let's say you want to make sure that mlox always puts plugin "Foo.esp" before
"Bar.esp". Just create a simple text file called "mlox_user.txt" in your mlox
directory (using Notepad or whatever) containing the following:

[Order]
Foo.esp
Bar.esp

From now on, when you press the mlox update button, mlox will make sure that
this is the order for those 2 plugins.

------------------------------------------------------------
oo The NearStart Rule

* The [NearStart] rule specifies that one or more plugins should

appear as near as possible to the Start of the load order.

[NearStart]
plugin-1.esp
plugin-2.esp
.
.
plugin-N.esp

Normally there will be only one [NearStart] rule, for the main master
file, (Morrowind.esm). It is not a good idea to write lots of
[NearStart] rules. If you think you have to, we should talk. Use
[Order] rules to place plugins in relationship to each other.

------------------------------------------------------------
oo The NearEnd Rule

* The [NearEnd] rule specifies that one or more plugins should appear
as near as possible to the End of the load order.

[NearEnd]
plugin-1.esp
plugin-2.esp
.
.
plugin-N.esp

Normally only a few plugins will appear in [NearEnd] rules, like

"Mashed Lists.esp". Abuse of the [NearEnd] rule is frowned upon.

Note that "NearEnd" does not mean "put this plugin at the end of the
load order". Its meaning is closer to: move this plugin closer to the
end, where possible. For details on how NearEnd works, see the
document: "mlox_guts.txt"

------------------------------------------------------------
o Warning Rules

Note: Warnings are normally only given for "active" plugins (i.e., any
plugin listed in the [Game Files] section of Morrowind.ini). The set
of active plugins is often a subset of all plugins installed in your
data directory. If you wish to see warnings for all installed plugins,
use the "mlox.py -a" command.
------------------------------------------------------------
oo Messages

Rules may be accompanied by a text message. There are 2 styles. The

first style has the message appear in the brackets that surround the
name of the rule. For example:

[CONFLICT don't use these together] A.esp B.esp

In this style, the message may not contain a right-bracket.

The second style is a block (multi-line) message, in which the message
must follow on the line after the rule name, and all message lines
must begin with whitespace. For example:

[CONFLICT]
Do not use
A.esp and B.esp together
A.esp
B.esp

If the message contains information that is considered a "spoiler" it can be

blacked out with <hide>text</hide> and it's up to the user to select the text
to view it.

------------------------------------------------------------
oo Boolean Expressions

The Warning rules are expressed in terms of the Boolean logical

operators: ALL, ANY, NOT. You can nest mlox's Boolean expressions
using brackets "[]". Here's an example:

[NOTE "Whee!"] [ALL A.esp [ANY B1.esp B2.esp]]

This rule says to print the message "Whee!" if you have A.esp active
in your plugins list, along with any of B1.esp or B2.esp.

The operators have to operate on something, and that something is

called a "predicate". This is the basic mlox predicate:

A.esp

It simply means the plugin "A.esp" is in your active load order.

We can make more expressions, or compound predicates from the basic

predicates and the boolean operators:

[ALL A.esp B.esp C.esp]

This predicate states that A.esp, B.esp, and C.esp are all active in
your load order at the same time.

Expressions can nest, so we could say:

[ALL A.esp B.esp [ANY C.esp D.esp]]

This means that A.esp, B.esp, and any of C.esp or D.esp are all active
in your load order at the same time.

The parser is fairly flexible. So all of the following variations of

the same rule are equivalent:

[NOTE "Whee!"] [ALL A.esp [ANY B1.esp B2.esp]]

[NOTE]
"Whee!"
[ALL A.esp [ANY B1.esp B2.esp]]

[NOTE "Whee!"]
[ALL A.esp
[ANY B1.esp B2.esp]]

[NOTE "Whee!"]
[ALL A.esp
[ANY B1.esp
B2.esp]]

----------------------------------------------------------------------
ooo The Desc predicate

The Desc predicate is a special predicate that matches strings in the

header of a plugin with regular expressions.

The form is:

[DESC /regex/ A.esp]

or
[DESC !/regex/ A.esp]

It must all be on one line. The regex should be any normal Python
regular expression pattern:
http://docs.python.org/library/re.html#re-syntax

This predicate means plugin A.esp exists and the Description field of
the plugin header contains the regular expression /regex/. (If the
first slash is preceded by a bang, it means the description string
does not match the given regex). Here's an example:

[Note]
uses deprecated AddToLev* see: http://www.uesp.net/wiki/Tes3Mod:Leveled_Lists
[DESC /v. 1.1109/ Sris_Alchemy_BM.esp]

In this case, the note will only print out if the header of
Sris_Alchemy_BM.esp contains the pattern "v. 1.1109".

You can use a [DESC] predicate in any warning rule, just like any
other expression.

----------------------------------------------------------------------
ooo The Size predicate

The Size predicate is a special predicate that matches the filesize of the
plugin

The form is:

[SIZE ### A.esp]

or
[SIZE !### A.esp]

where ### is the size of the file in bytes. (!### means that the filesize does
not match the given number).

The function must all be on one line.

[Note]
This file contains some GMSTs that need to be cleaned.
[SIZE 2476 moons_soulgems.esp]

In this case, the note will only print out if the size of moons_soulgems.esp
is 2476 bytes.

You can use a [SIZE] predicate in any warning rule, just like any other
expression.

----------------------------------------------------------------------
ooo The Ver predicate

Syntax: [VER operator version plugin.esp)

where operator is: <, =, >

for comparing less than, equal to, or greater than

and version number is something that looks like a version number.

The format can be fairly sloppy. mlox will recognize up to 3 numbers
separated by "." or "_" and followed by a possible alpha character.
So all the following are valid version numbers:

1.2.3a, 1.0, 1, 1a, 1_3a, 77g

The actual regular expression used for matching version numbers is:
(\d+(?:[_.-]?\d+)*[a-z]?)

The Ver predicate is a special predicate that first tries to match the
version number string stored in the plugin header, and if that fails
it tries to match the version number from the plugin filename. If a
version number is found, it can be used in a comparison

This predicate must all be on one line, like so:

[VER = 1.0 A.esp]

This predicate means plugin A.esp exists and the discovered version
number matches 1.0. The format does not have to match the original, as
both the given version number and the version number of the plugin are
converted to a canonical form before comparison. Here's an example:

[Note]
this is an old version, please upgrade
[VER < 1.2 foo.esp]

This is read: "print the Note if the version of the plugin is less
than 1.2". Note that you don't really need whitespace around the
comparison operator, but it is nice for readability.

You can use a [VER] predicate in any warning rule, just like any
other expression.
----------------------------------------------------------------------
oo The Note Rule

Syntax: [Note optional-message] expr-1 expr-2 ... expr-N

Alternate Syntax:
[Note]
optional multi-line comment
expr-1
expr-2
.
.
expr-N

(All the warning rules have a similar longer alternate syntax form as
shown here, which is omitted from now on for the brevity's sake).

The [Note] rule prints the given message when any of the following
expressions is true.

Here's how to print a message if any of A.esp, B.esp, C.esp are active:

[Note message] A.esp B.esp C.esp

This could also be expressed in its longer form:

[Note]
message
A.esp
B.esp
C.esp

And any of the plugins can actually be a full Boolean expression:

[Note message]
[ALL A.esp [NOT X.esp]]
[ANY B.esp 7.esp]
[ALL C.esp elephant.esp potato.esp]

Note: from now on, we'll use the abbreviation <expr> to mean any
Boolean expression.

The [Note] rule is just a handy general rule that can be used for almost
any situation.

----------------------------------------------------------------------
oo The Requires Rule

Syntax: [Requires optional-message] expr-1 expr-2

The [Requires] rule specifies that when the dependant expression

(expr-1) is true, that the consequent expression (expr-2) must be
true.

This rule is naturally used to express the dependencies often described

in mod Readmes.
Here's an example:

[Requires]
"Assassins Armory - Arrows.esp" requires the Area Effect Arrows
plugin to be present
(Ref: "Assassin's Armory readme.doc")
Assassins Armory - Arrows.esp
[ANY AreaEffectArrows XB Edition.esp
AreaEffectArrows.esp]

Since there are a couple versions of the AreaEffectArrows plugin, we

make an [ANY] expression for them, since we could any of them. So
this rule says: "Assassins Armory - Arrows.esp" requires that either
"AreaEffectArrows XB Edition.esp" or "AreaEffectArrows.esp" must be
active. If not, you get a warning and the message.

The bit in the block message that starts with "(Ref:" is just a
Convention used to point you to the source of information where the
rule was taken from, it's often the readme for the mod, or a web page.

----------------------------------------------------------------------
oo The Conflict Rule

Syntax: [Conflict optional-message] expr-1 expr-2 ... expr-N

* The [Conflict] rule specifies that if any two of the following

expressions are true, then we print out the given message indicating a
conflict problem.

----------------------------------------------------------------------
oo The Patch Rule

Syntax: [Patch optional-message] expr-1 expr-2

* The [Patch] rule specifies a mutual dependency as in the case of a

patch plugin that modifies some original plugin(s), or that glues two
more plugins together to make them compatible. We use this rule to say
two things:

1) that we wouldn't want the patch without the original it is supposed

to patch, and
2) we wouldn't want the original to go unpatched.

Here's how we can say that one plugin has a patch:

[Patch message] patch.esp original.esp

Here's how we can say that a glue (compatibility) patch is necessary

for two separate plugins:

[Patch message] glue-patch.esp [ALL original-X.esp original-Y.esp]

It is sometimes the case that one of the original plugins has multiple
versions, in which case we could say:

[Patch message]
glue-patch.esp
[ALL original-X.esp
[ANY original-Y-MW-Only.esp
 original-Y-TB+BM.esp]]

This means that glue-patch.esp will patch together either:

original-X.esp AND original-Y-MW-Only.esp
or
original-X.esp AND original-Y-TB+BM.esp

----------------------------------------------------------------------