String in programmers language is often\footnote{Often, not always. There are different programming languages using slightly different terms.}
just a word for anything composed of characters. In case of \OCS{} this is in fact true for every value inside the column that is not composed
of the pure numbers. Even columns containing only ``true`` and ``false`` values can be targeted by the string expression\footnote{There is no
Boolean (``true'' or ``false'') value in the \OCS. You should use string for those.}. String evaluates to true,
when record contains in the specified column exactly the same value as specified.
Since majority of the columns contain string values, string is among the most often used expressions. Examples:
\begin{itemize}
\item\mono{string(``Record Type'', ``Weapon'')} -- will evaluate to true for all records containing \mono{Weapon} in the \mono{Record Type} column cell.
This group contains every weapon (including arrows and bolts) found in the game.
\item\mono{string(``Portable'', ``true'')} -- will evaluate to true for all records containing word true inside \mono{Portable} column cell.
This group contains every portable light sources (lanterns, torches etc.).
\end{itemize}
This is probably enough to create around 90 string filters you will eventually need. However, this expression is even more powerful
-- it accepts regular expressions (also called regexps). Regular expressions is a way to create string criteria that will be matched
by one than just one specific value in the column. For instance, you can display both left and right gauntlets with the following expression:
\mono{string("armor type", ".* gauntlet"))} because \mono{.*} in regexps means just: ``anything''. This filter says: please, show me ``any'' gauntlet.
There are left and right gauntlets in the \MW{} so this will evaluate to true for both. Simple, isn't it?
Creating regexps can be a difficult and annoying -- especially when you need complex criteria. On the other hand, we are under impression that in reality complex expressions are needed only in sporadic cases. In fact, the truth is: that most of the time only already mentioned
\mono{.*} is needed and therefore the following description of regexps can be skipped by vast majority of readers.
Before working with Regular Expressions, you should understand what actually are regular expressions. Essentially, the idea is simple:
when you are writing any word, you are using strictly defined letters -- that is: letters create a word. What you want to do with regular
expression is to use set of rules that will match to many words. It is not that difficult to see what it's needed to do so: first,
you will clearly need way to determinate what letters you want to match (word is composed by letters).
Before introducing other ways to choose between characters, I want explain anchors. Anchors allows you to decide where to ``look'' in the string.
You surely should know about \mono{\textasciicircum} anchor and \mono{\textdollar}. Putting \mono{\textasciicircum} will tell to \OCS{}
to look on the beginning of string, while \mono{\textdollar} is used to mark the end of it. For instance, pattern
\mono{\textasciicircum{}Pink.* elephant.\textdollar} will match any sentence beginning with the word \mono{Pink} and ending with
\mono{ elephant.}. Pink fat elephant. Pink cute elephant. It does not matter what is in between because \mono{.*} is used.
You have already seen the power of the simple \mono{.*}. But what if you want to chose between only two (or more) letters? Well, this is when
\mono{[|]} comes in handy. If you write something like: \mono{\textasciicircum[a|k].*} you are simply telling \OCS{} to filter anything that
starts with either \mono{a} or \mono{k}. Using \mono{\textasciicircum[a|k|l].*} will work in the same manner, that is; it will also cover strings starting with \mono{l} as well.
What if you want to match more than just one latter? Just use \mono{(|)}. It is pretty similar to the above one letter as you see, but it is
used to fit more than just one character. For instance: \mono{\textasciicircum(Pink|Green).* (elephant|crocodile).\textdollar} will be
true for all sentences starting with \mono{Pink} or \mono{Green} and ending with either \mono{elephant.} or \mono{crocodile.}.
Regular expressions are not the main topic of this manual. If you wish to learn more on this subject please, read the documentation on
Qt regular expressions syntax, or TRE regexp syntax (it is almost like in Qt). Above is just enough to use \OCS{} effectively.
While string expression covers vast group of columns containing string values, there are in fact columns with just numerical values like
``weight``. To filter those we need a value expression. This one works in similar manner to the string filter: first token name and criteria
inside brackets. Clearly, conditions should hold column to test in. However in this case wanted value is specified as a range.
As you would imagine the range can be specified as including a border value, or excluding. We are using two types of brackets for this:
\begin{itemize}
\item To include value use [] brackets. For value equal 5, expression \mono{value(something, [5, 10])} will evaluate to true.
\item To exclude value use () brackets. For value equal 5, expression \mono{value(something, (5, 10))} will evaluate to false.
\item Mixing brackets is completely legal. For value equal 10, expression \mono{value(something, [5, 10)} will evaluate to true.
The same expression will evaluate to false for value equal 10.
\end{itemize}
\paragraph{``true'' and ``false''}
Nullary \textit{true} and \textit{false} do not accept any arguments, and always evaluates to true (in case of \textit{true})
and false (in case of \textit{false}) no matter what. The main usage of this expressions is the give users ability to quickly
disable some part of the filter that makes heavy use of the logical expressions.
\subsubsection{Logical expressions}
This subsection takes care of two remaining groups of expressions: binary and unary. The only unary expression present in the \OCS{} is logical
\textit{not}, while the remaining binary expressions are: \textit{or}, \textit{and}. This clearly makes them (from the user point of view)
belonging to the same group of logical expressions.
\paragraph{not -- not expression()}
Sometimes you may be in need of reversing the output of the expression. This is where \textit{not} comes in handy. Adding \textit{not} before
expression will revert it: if expression was returning true, it will return false; if it was returning false, it will return true. Parenthesis are not needed: \textit{not} will revert only the first expression following it.
To show this on know example, let's consider the \mono{string("armor type", ".* gauntlet"))} filter. As we mentioned earlier this will return true
for every gauntlet found in game. In order to show everything, but gauntlets we simply do \mono{not string("armor type", ".* gauntlet"))}.
This is probably not the most useful filter on earth. The real value of \textit{not} expression shines when combined with
\textit{Or} is a expression that will return true if one of the arguments evaluates to true. You can use two or more arguments, separated by the comma.
\textit{Or} expression is useful when showing two different group of records is needed. For instance the standard actor filter is using the following
\mono{or(string(``record type'', npc), string(``record type'', creature))} and will show both npcs and creatures.
