@ -9,9 +9,10 @@ Don't be afraid though, filters are fairly intuitive and easy to use.
\item[Filter] is generally speaking a tool able to ``Filter'' (that is: select some elements, while discarding others) according to the some criteria. In case of OpenCS: records are being filtered according to the criteria of user choice. Criteria are written down in language with simple syntax.
\item[Criteria] describes condition under with any any record is being select by the filter.
\item[Syntax] as you may noticed computers (in general) are rather strict, and expect only strictly formulated orders -- that is: written with correct syntax. Our syntax is simple and described in the {B}asics subsection.
\item[Expression] is a criteria, only written with OpenCS filter syntax.
\item[Token] is any part of the expression, responsible for checking for the criteria in specified column.
\item[Node] is any part of the expression, responsible for performing logical operations on tokens. That is: group two (or more) tokens together in order to create a expression that will check for criteria placed in two (again: or more) columns (logical ``or'', ``and''); create any expression that will show only records that does not met criteria of specific token(logical ``not'').
\item[Expression] is way we are actually performing filtering. Filter can be treated as ``functions'': accepts arguments, and evaluates either to the true or false for every column record.
\item[N-ary] is any expression that is useful to group two (or more) other expressions together in order to create filter that will check for criteria placed in two (again: or more) columns (logical ``or'', ``and'').
\item[unary] is any expression that expects one other expression. The example is ``not'' expression.
\item[nullary] is expression that does not accepts other expressions. It accepts arguments specified later.
\end{description}
\subsection{Basics}
@ -44,31 +45,54 @@ We strongly recommend to take a look at the filters table right now to see what
If you want to create your own filter you have to know exactly what do you want to get in order to translate this into the tokens and nodes. Finally, you will have to write this as legal expression -- that is: using correct syntax. As a result table will show only desired rows.\\
Advance subsection covers everything that you need to know in order to create any filter you may want to.
\subsection{Namespaces}
It is a ``namespace``, a term borrowed from the C++ language. In case of OpenCS namespace determinate if the filter will be stored along with your project or if it will be forgotten as soon as OpenCS quits.
It is a ``namespace``, a term borrowed from the C++ language. In case of OpenCS namespace of the filter determinate if the filter will be stored along with your project or if it will be forgotten as soon as OpenCS quits.
\begin{description}
\item[project::] namespace indicates that filter is stored inside the project file.
\item[session::] namespace indicates that filter is not stored inside the project file, and once you will quit OpenCS (close session) the filter will be gone. Forever! Until then it can be found inside the filters table.
\end{description}
In addition to this two scopes, there is a third one; called one-shot. One-shot filters are not stored anywhere and as the name implies they are supposed to be created when needed only once. Good thing about the one-shot filters is that you don't need to open filters table in order to create it. Instead you just type it directly inside the filter field, starting with ``!''.\\
Still, you may wonder how you are supposed to write expressions, what and nodes tokens are avaible, and what syntax looks like.
Still, you may wonder how you are supposed to write expressions, what expressions you should use, and what syntax looks like.
\subsubsection{Tokens}
Each token is used in similar manner. First off: you have to write it's name (for instance: ``string'') and secondly: condition that will be checked inside brackets (for instance string(something, something)). If conditions of your expression will be meet by a record (technical speaking: evaluated true) the record will show up in the table.\\
\subsubsection{Nullary expressions}
Each expression is used in similar manner. First off: you have to write it's name (for instance: ``string'') and secondly: condition that will be checked inside brackets (for instance string(something, something)). If conditions of your expression will be meet by a record (technical speaking: evaluated true) the record will show up in the table.\\
It is clear that you need to know what are you checking, that's is: what column of the table contains information that you are interested in and what should be inside specific cell inside this column to meet your requirements. In most cases first word inside brackets sets column you want to see, while the second one sets desired value inside of the cell. To separate column from the value use comma.
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 OpenCS 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 token.\footnote{There is no Boolean (''true'' or ``false'') value in the OpenCS. You should use string token for those.} String evaluates to true, when record contains in the specified column exactly the same value as specified.
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 OpenCS 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 token.\footnote{There is no Boolean (''true'' or ``false'') value in the OpenCS. 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 token is among the most often used. Examples:
Since majority of the columns contain string values, string is among the most often used expressions. Examples:
\begin{itemize}
\item string(``Record Type'', ``Weapon'') -- will evaluate to true for all records containing ``Weapon'' in the ``Record Type'' column cell. This group contains every weapon (including arrows and bolts) found in the game.
\item string(``Portable'', ``true'') -- will evaluate to true for all records containing word true inside ``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 would need. However, this token is even more powerfull -- 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: ``string("armor type", ".* gauntlet"))`` because ''.*'' in regexps means just: ``anything''. This filter says: please, show me ``any'' gauntlet. There are left and right gauntlets in the morrowind so this will evaluate to true for both. Simple, isn't it?
This is probably enough to create around 90\% string filters you would need. However, this expression is even more powerfull -- 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: ``string("armor type", ".* gauntlet"))`` because ''.*'' in regexps means just: ``anything''. This filter says: please, show me ``any'' gauntlet. There are left and right gauntlets in the morrowind 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 mostly the mentioned ``.*'' is needed and therefore the following description of regexps can be skipped by vast majority of readers.
%TO-DO: write the regexps essentials.
\\
Regular expressions is 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).
While string token 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 token. 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.
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 value(something, [5, 10]) will evaluate to true.
\item To exclude value use () brackets. For value equal 5, expression value(something, (5, 10)) will evaluate to false.
\item Mixing brackets is completely legal. For value equal 10, expression value(something, [5, 10) will evaluate to true. The same expression will evaluate to false for value equal 10.
\end{itemize}
\subsection{Logical expressions}
This subsection takes care of two remaining groups of expressions: binary and unary. The only unary expression present in the OpenCS is logical not, while the remaining binary expressions are: or, and. This clearly makes theme from 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 not comes in handy. Adding not before expression will revert it: if expression was returning true, it will return false; if it was returning false, it will return true. Brackets are not needed: not will revert only the first expression following it.\\
To show this on know example, let's consider the ''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 ''not string("armor type", ".* gauntlet"))``. This is probably not the most useful filter on earth, but this is not a surprise: real value of not expression shines when combined with or, and filter.
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.\\
Or expression is useful when showing two different group of records is needed. For instance the standard actor filter is using the following ''or(string(``record type'', npc), string(``record type'', creature))`` and will show both npcs and creatures.
And is a expression that will return true if all arguments evaluates to true. As in the case of ''or`` you can use two or more arguments, separated by the comma.\\
As We mentioned earlier in the ''not`` filter, combining not with and can be very useful. For instance to show all armor types, excluding gauntlets you can write the following: ''and (not string("armor type", ".* gauntlet"), string(''Record Type``, ''Armor``))''.
Marek Kochanowicz
11 years ago