xref: /dports/games/openmw/openmw-openmw-0.47.0/docs/source/manuals/openmw-cs/record-filters.rst

Record Filters
##############

Filters are a key element of the OpenMW CS user interface, they allow rapid and
easy access to records presented in all tables. In order to use this
application effectively you need to familiarise yourself with all the concepts
and instructions explained in this chapter. The filter system is somewhat
unusual at first glance, but once you understand the basics it will be fairly
intuitive and easy to use

Filters are a key element to using the OpenMW CS efficiently by allowing you to
narrow down the table entries very quickly and find what you are looking for.
The filter system might appear unusual at first, you don't just type in a word
and get all instances where it occurs, instead filters are first-class objects
in the CS with their own table. This allows you to define very specific filters
for your project and store them on disc to use in the next session. The CS
allows you fine-grained control, you can choose whether to make a filter
persistent between session, only for one session or use a one-off filter by
typing it directly into the filter field.



Terms used
**********

Filter
   A Filter is generally speaking a tool able to filter the elements of a
   table, that is select some elements while discarding others, according to
   some criteria. These criteria are written using their own syntax.

Criterion
   A criterion describes some condition a record needs to satisfy in order to
   be selected. They are written using a special syntax which is explained
   below. We can logically combine multiple criteria in a filter for finer
   control.

Expression
   Expressions are how we perform filtering. They look like functions in a
   programming language: they have a name and accept a number of arguments.
   The expression evaluates to either ``true`` or ``false`` for every record in
   the table. The arguments are expressions themselves.

Arity
   The arity of an expression tells us how many arguments it takes. Expressions
   taking no arguments are called *nullary*, those taking one argument are
   known as *unary* expressions and those taking two arguments are called
   *binary*.



Interface
*********

Above each table there is a text field which is used to enter a filter: either
one predefined by the OpenMW CS developers or one  made by you. Another
important element is the filter table found under *View* → *Filters*. You
should see the default filters made by the OpenMW team in the table. The table
has the columns *Filter*, *Description* and *Modified*.

ID
   A unique name used to refer to this filter. Note that every ID has a
   scope prefix, we will explain these soon.

Modified
   This is the same as for all the other records, it tells us whether the
   filter is *added* or *removed*. Filters are specific to a project instead of
   a content file, they have no effect on the game itself.

Filter
   The actual contents of the filter are given here using the filter syntax.
   Change the expressions to modify what the filter returns.

Description
   A textual description of what the filter does.



Using predefined filters
************************

To use a filter you have to type its ID into the filter field above a table.

For instance, try to opening the objects table (under the world menu) and type
into the filters field ``project::weapons``. As soon as you complete the text
the table will show only the weapons. The string ``project::weapons`` is the ID
of one of the predefined filters. This means that in order to use the filter
inside the table you type its name inside the filter field.

Filter IDs follow these general conventions:

- IDs of filters for a specific record type contain usually the name of a
  specific group. For instance the ``project::weapons`` filter contains the
  term ``weapons``. Plural form is always used.

- When filtering a specific subgroup the ID is prefixed with the name of the
  more general filter. For instance ``project::weaponssilver`` will filter only
  silver weapons and ``project::weaponsmagical`` will filter only magical
  weapons.

- There are few exceptions from the above rule. For instance there are
  ``project::added``, ``project::removed``, ``project::modified`` and
  ``project::base``. You might except something more like
  ``project::statusadded`` but in this case requiring these extra characters
  would not improve readability.

We strongly recommend you take a look at the filters table right now to see
what you can filter with the defaults. Try using the default filters first
before writing you own.



Writing your own filters
************************

As mentioned before, filters are just another type of record in the OpenMW CS.
To create a new filter you will have to add a new record to the *Filters* table
and set its properties to your liking. Filters are created by combining
existing filters into more complex ones.


Scopes
======

Every default filter has the prefix ``project``. This is a *scope*, a mechanism
that determines the lifetime of the filter. These are the supported scopes:

``project::``
   Indicates that the filter is to be used throughout the project in multiple
   sessions. You can restart the CS and the filter will still be there.

``session::``
   Indicates that the filter is not stored between multiple sessions and once
   you quit the OpenMW CS application the filter will be gone. Until then it
   can be found inside the filters table.

Project-filters are stored in an internal project file, not final content file
meant for the player. Keep in mind when collaborating with other modders that
you need to share the same project file.



Writing expressions
===================

The syntax for expressions is as follows:

.. code::

   <name>
   <name>(<arg1>)
   <name>(<arg1>, <arg2>, ..., <argn>)

Where ``<name>`` is the name of the expression, such as ``string`` and the
``<arg>`` are expressions themselves. A nullary expression consists only of its
name. A unary expression contains its argument within a pair of parentheses
following the name. If there is more than one argument they are separated by
commas inside the parentheses.

An example of a binary expression is ``string("Record Type", weapon)``; the
name is ``string``, and it takes two arguments which are strings of string
type. The meaning of arguments depends on the expression itself. In this case
the first argument is the name of a record column and the second field is the
values we want to test it against.

Strings are sequences of characters and are case-insensitive. If a string
contains spaces it must be quoted, otherwise the quotes are optional and
ignored.


Constant Expressions
--------------------

These expressions take no arguments and always return the same result.

``true``
   Always evaluates to ``true``.

``false``
   Always evaluates to ``false``.


Comparison Expressions
----------------------

``string(<column>, <value>)``
   The ``<value>`` is a regular expression pattern. The expressions evaluates
   to ``true`` when the value of a record in ``<column>`` matches the pattern.
   Since the majority of the columns contain string values, ``string`` is among
   the most often used expressions. Examples:

   ``string("Record Type", "Weapon")``
      Will evaluate to ``true`` for all records containing ``Weapon`` in the
      *Record Type* column cell.

   ``string("Portable", "true")``
      Will evaluate to ``true`` [#]_ for all records containing word ``true`` inside
      *Portable* column cell.

.. [#] There is no Boolean (``true`` or ``false``) value in the OpenMW CS. You
       should use a string for those.


``value(<value>, (<lower>, <upper>))``
   Match a value type, such as a number, with a range of possible values. The
   argument ``<value>`` is the string name of the value we want to compare, the
   second argument is a pair of lower and upper bounds for the range interval.

   One can use either parentheses ``()`` or brackets ``[]`` to surround the
   pair. Brackets are inclusive and parentheses are exclusive. We can also mix
   both styles:

   .. code::

      value("Weight", [20, 50))

   This will match any objects with a weight greater or equal to 20 and
   strictly less than 50.


Logical Expressions
-------------------

``not <expression>``
   Logically negates the result of an expression. If ``<expression>`` evaluates
   to ``true`` the negation is ``false``, and if ``<expression>`` evaluates to
   ``false`` the negation is ``true``. Note that there are no parentheses
   around the argument.

``or(<expr1>, <expr2>, ..., <exprN>)``
   Logical disjunction, evaluates to ``true`` if at least one argument
   evaluates to ``true`` as well, otherwise the expression evaluates to
   ``false``.

   As an example assume we want to filter for both NPCs and creatures; the
   expression for that use-case is

   .. code::

      or(string("record type", "npc"), string("record type", "creature"))

   In this particular case only one argument can evaluate to ``true``, but one
   can write expressions where multiple arguments can be ``true`` at a time.

``or(<expr1>, <expr2>, ..., <exprN>)``
   Logical conjunction, evaluates to ``true`` if and only if all arguments
   evaluate to ``true`` as well, otherwise the expression evaluates to
   ``false``.

   As an example assume we want to filter for weapons weighting less than a hundred
   units The expression for that use-case is

   .. code::

      and(string("record type", "weapon"), value("weight", (0, 100)))


Anonymous filters
=================

Creating a whole new filter when you only intend to use it once can be
cumbersome. For that reason the OpenMW CS supports *anonymous* filters which
can be typed directly into the filters field of a table. They are not stored
anywhere, when you clear the field the filter is gone forever.

In order to define an anonymous filter you type an exclamation mark as the
first character into the field followed by the filter definition (e.g.
``!string("Record Type", weapon)`` to filter only for weapons).



Creating and saving filters
***************************

Filters are managed the same way as other records: go to the filters table,
right click and select the option *Add Record* from the context menu. You are
given a choice between project- or session scope. Choose the scope from the
dropdown and type in your desired ID for the filter. A newly created filter
does nothing since it still lacks expressions. In order to add your queries you
have to edit the filter record.


Replacing the default filters set
=================================

OpenMW CS allows you to substitute the default filter set for the entire
application. This will affect the default filters for all content files that
have not been edited on this computer and user account.

Create a new content file, add the desired filters, remove the undesired ones
and save. Now rename the *project* file to ``defaultfilters`` and make sure the
``.omwaddon.project`` file extension is removed. This file will act as a
template for all new files from now on. If you wish to go back to the
old default set rename or remove this custom file.