mirror of
https://github.com/loot/libloot.git
synced 2026-07-27 14:16:01 -07:00
170 lines
6.0 KiB
ReStructuredText
170 lines
6.0 KiB
ReStructuredText
*****************
|
|
Condition Strings
|
|
*****************
|
|
|
|
Condition strings can be used to ensure that data is only acted on by LOOT under certain circumstances. They are very similar to boolean conditional expressions in programming languages such as Python, though more limited.
|
|
|
|
Omitting optional parentheses (see below), their `EBNF`_ grammar is:
|
|
|
|
.. productionlist::
|
|
compound_condition: condition, { ( logical_and | logical_or ), condition }
|
|
condition: [ logical_not ], function
|
|
logical_and: "and"
|
|
logical_or: "or"
|
|
logical_not: "not"
|
|
|
|
.. _EBNF: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form
|
|
|
|
Types
|
|
=====
|
|
|
|
.. describe:: file_path
|
|
|
|
A double-quoted file path, or ``"LOOT"``, which references the LOOT executable being run.
|
|
|
|
.. describe:: regular_expression
|
|
|
|
A double-quoted file path, with a regular expression in place of a filename. The path must use ``/`` for directory separators, not ``\``. The regular expression must be written in a `modified Perl <https://docs.rs/regex/1.0.5/regex/index.html#syntax>`_ syntax.
|
|
|
|
Only the filename path component will be evaluated as a regular expression. For example, given the regex file path ``Meshes/Resources(1|2)/(upperclass)?table.nif``, LOOT 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.
|
|
|
|
.. describe:: checksum
|
|
|
|
A string of hexadecimal digits representing an unsigned integer that is the data checksum of a file. LOOT displays the checksums of plugins in its user interface after running.
|
|
|
|
.. describe:: version
|
|
|
|
A double-quoted string of characters representing the version of a plugin or executable. LOOT displays the versions of plugins in its user interface after running.
|
|
|
|
.. describe:: comparison_operator
|
|
|
|
One of the following comparison operators.
|
|
|
|
.. describe:: ==
|
|
|
|
Is equal to
|
|
|
|
.. describe:: !=
|
|
|
|
Is not equal to
|
|
|
|
.. describe:: <
|
|
|
|
Is less than
|
|
|
|
.. describe:: >
|
|
|
|
Is greater than
|
|
|
|
.. describe:: <=
|
|
|
|
Is less than or equal to
|
|
|
|
.. describe:: >=
|
|
|
|
Is greater than or equal to
|
|
|
|
Functions
|
|
=========
|
|
|
|
There are several conditions that can be tested for using the functions detailed below. All functions return a boolean. For functions that take a path or regex, the argument is treated as regex if it contains any of the characters ``:\*?|``.
|
|
|
|
.. describe:: file(file_path path)
|
|
|
|
Returns true if ``path`` is installed, and false otherwise.
|
|
|
|
.. describe:: file(regular_expression regex)
|
|
|
|
Returns true if a file matching ``regex`` is found, and false otherwise.
|
|
|
|
.. describe:: active(file_path path)
|
|
|
|
Returns true if ``path`` is an active plugin, and false otherwise.
|
|
|
|
.. describe:: active(regular_expression regex)
|
|
|
|
Returns true if an active plugin matching ``regex`` is found, and false otherwise.
|
|
|
|
.. describe:: many(regular_expression regex)
|
|
|
|
Returns true if more than one file matching ``regex`` is found, and false otherwise.
|
|
|
|
.. describe:: many_active(regular_expression regex)
|
|
|
|
Returns true if more than one active plugin matching ``regex`` is found, and false otherwise.
|
|
|
|
.. describe:: is_master(file_path path)
|
|
|
|
Returns true if ``path`` is an installed master plugin, and false otherwise.
|
|
|
|
.. describe:: checksum(file_path path, checksum expected_checksum)
|
|
|
|
Returns true if the calculated CRC-32 checksum of ``path`` matches ``expected_checksum``, and false otherwise. Returns false if ``path`` does not exist.
|
|
|
|
.. describe:: version(file_path path, version given_version, comparison_operator comparator)
|
|
|
|
Returns true if the boolean expression::
|
|
|
|
actual_version comparator given_version
|
|
|
|
(where ``actual version`` is the version read from ``path``) holds true, and
|
|
false otherwise. If ``path`` is a plugin, its version is read from its
|
|
description field. If ``path`` is not a plugin, it will be assumed to be an
|
|
executable (e.g. ``*.exe`` or ``*.dll``), and its version is read from its
|
|
File Version field. If ``path`` does not exist or does not have a version
|
|
number, its version is assumed to be ``0``. If ``path`` isn't a plugin or an
|
|
executable, an error will occur.
|
|
|
|
The comparison uses the precedence rules defined by `Semantic Versioning
|
|
<http://semver.org/>`_, extended to allow leading zeroes, an arbitrary number
|
|
of release version numbers, case-insensitivity and a wider range of separator
|
|
characters.
|
|
|
|
.. describe:: product_version(file_path path, version given_version, comparison_operator comparator)
|
|
|
|
Returns true if the boolean expression::
|
|
|
|
actual_version comparator given_version
|
|
|
|
(where ``actual version`` is the version read from ``path``) holds true, and
|
|
false otherwise. ``path`` must be an executable (e.g. ``*.exe`` or ``*.dll``),
|
|
and its version is read from its Product Version field. If ``path`` does not
|
|
exist or does not have a version number, its version is assumed to be ``0``.
|
|
If ``path`` is not an executable, an error will occur.
|
|
|
|
The comparison uses the precedence rules defined by `Semantic Versioning
|
|
<http://semver.org/>`_, extended to allow leading zeroes, an arbitrary number
|
|
of release version numbers, case-insensitivity and a wider range of separator
|
|
characters.
|
|
|
|
Logical Operators
|
|
=================
|
|
|
|
The ``and``, ``or`` and ``not`` operators have their usual definitions, except that the ``not`` operator only ever operates on the result of the function immediately following it.
|
|
|
|
Order of Evaluation
|
|
-------------------
|
|
|
|
Condition strings are evaluated according to the usual C-style operator precedence rules, and parentheses can be used to override these rules. For example::
|
|
|
|
function and function or not function
|
|
|
|
is evaluated as::
|
|
|
|
( function and function ) or ( not function )
|
|
|
|
but::
|
|
|
|
function and ( function or not function )
|
|
|
|
is evaluated as::
|
|
|
|
function and ( function or ( not function ) )
|
|
|
|
Parentheses cannot be used between a ``not`` operator and the function following it.
|
|
|
|
Performance
|
|
===========
|
|
|
|
LOOT caches the results of condition evaluations. A regular expression check will still take longer than a file check though, so use the former only when appropriate to do so.
|