It is just as important to be able to get stuff OUT of TW as it is to put
it in, so I wanted to document the grammar for the filters. Filters allow a
much richer search capability than is currently allowed by the sidebar
search box.
TL;DR:
Here is an example which allows searching in a particular field, including
custom fields:
Create a new tiddler. Add the following to it:
<$list filter={{!!searchbox}}>
</$list>
Then add a field named "searchbox." Turn on the preview pane (the "show
preview" button) and type the following into the searchbox field:
[field:abcde/fghij/(i)]
Where "abcde" is the field name you want to search and "fghij" is the
string you want to search for. You will immediately see a list of matching
tiddlers.
-------------------
The following is a formal grammar I constructed by going through the source
code. If it is documented elsewhere (I couldn't find it!) or if I've made
any mistakes please let me know. I found the exercise to be very
instructive, and the results impressively flexible!
<filter-string> ::= <opt-whitespaces> <filter-operand> |
<opt-whitespaces> <filter-operand>
<filter-string>
// whitespace matched with javascript "\s+", which matches
// space, tab, carriage return, new line, vertical tab, and form feed
<opt-whitespaces> ::= <opt-whitespace> |
<opt-whitespace> <opt-whitespaces>
<opt-whitespace ::= " " | "\t" | "0xD" | "0xA" | "0xB" | "0xC"
<filter-operand> ::= <opt-operation-prefix>
<string-or-operator-list>
<opt-operation-prefix> ::= "+" | "-" | ""
<string-or-operator-list> ::= <operation> |
"\"" <string> "\"" |
"'" <string> "'" |
<string>
<operation> ::= "[" <operator-list> "]"
<operator-list> ::= <operator> | <operator> <operator-list>
<operator> ::= <opt-operator-prefix><operator><operand>
<opt-operator-prefix> ::= "!" | ""
<operator> ::= <operator-name> |
<operator-name> ":" <opt-operator-suffix>
<operator-name> ::= "" | "is" | "has" | "each" | "field" ...
<opt-operator-suffix> ::= <string> | ""
<operand> ::= "["<search-string>"]" |
"{"<indirect-search-string>"}" |
<regex>
<regex> ::= "/" <string> "/" <opt-regex-args>
<opt-regex-args> ::= "(" <regex-args> ")" | ""
<regex-args> ::= <regex-arg> | <regex-arg> <regex-args>
<regex-arg> ::= "m" | "y" | "g" | "i"
<string> ::= <string-type-1> | <string-type-2> | ...
RESULTING VARIABLES:
At the end of this parsing you end up with some or all of:
* opt-operation-prefix
* opt-operator-prefix
* operator-name
* opt-operator-suffix, and
* operand
These are used diffently by the different operators. For example, the field
filter operator supports:
* opt-operator-prefix to negate the result
* regex or <string> operand (N.B. this must be explicitly supported by each
filter operator)
* opt-operator-suffix to specify a fieldname against which to filter
NOTES:
* The <string> is actually a terminal and is matched by varying regexes
throughout TW. In general single- or double- quoted strings match,
respectively, strings of non-single and non-double quotes. Unquoted strings
include the extra exclusion of whitespace and square bracket characters.
* In the case where the <string-or-operator-list> is NOT an <operation> it
is treated as the operand passed to the default operator (see next bullet).
It is not parsed as a full <operation>.
* If <operator-name> is the empty string then it will be set to "title"
(i.e. the title filter operator is the default operator)
* Results are collected and each operation is applied in turn. The
<opt-operation-prefix> can be used to specify how the corresponding
operation is used. Suppose T is the set of all tiddlers, R0 is the current
set of results, and Fx is the xth operation. Then
** No prefix (""): R0 = R0 U Fx(T) (set union)
** "-": R0 = R0 - Fx(T) (set difference)
** "+": R0 = Fx(R0)
N.B. that <filter-operand>s are not commutative!
* The parser was simplified by treating regex "/" as a "bracket" of sorts,
meaning there could only be a start and end bracket. Thus the regex
arguments, like i, are included in parenthesis immediately following the
trailing "/".
--
You received this message because you are subscribed to the Google Groups
"TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/tiddlywiki.
For more options, visit https://groups.google.com/groups/opt_out.
