A filter expression is the outermost level of the filter syntax. It consists of one or more runs.
If a run has:
- no prefix, its output titles are dominantly appended to the filter's output
- the prefix
=
, output titles are appended to the filter's output without de-duplication. New in: 5.1.20 - the prefix
-
, output titles are removed from the filter's output (if such tiddlers exist) - the prefix
+
, it receives the filter output so far as its input; its output then replaces all filter output so far and forms the input for the next run - the prefix
~
, if the filter output so far is an empty list then the output titles of the run are dominantly appended to the filter's output. If the filter output so far is not an empty list then the run is ignored. New in: 5.1.18 - named prefixes for filter runs are available. New in: 5.1.23
- named prefix
:filter
, it receives the filter output so far as its input. The next run is evaluated for each title of the input, removing every input title for which the output is an empty list. New in: 5.1.23 - named prefix
:intersection
replaces all filter output so far with titles that are present in the output of this run, as well as the output from previous runs. Forms the input for the next run. New in: 5.1.23 - named prefix
:reduce
replaces all filter output so far with a single item by repeatedly applying a formula to each input title. A typical use is to add up the values in a given field of each input title. New in: 5.1.23 - named prefix
:sort
sorts all filter output so far by applying this run to each input title and sorting according to that output. New in: 5.2.0 - named prefix
:map
transforms all filter output so far by applying this run to each input title and replacing the input title with the output of this run for that title.
In technical / logical terms:
Run | Equivalent named prefix | Interpretation | Output |
---|---|---|---|
run | :or[run] | de-duplicated union of sets | ... OR run |
=run | :all[run] | union of sets without de-duplication | ... OR run |
+run | :and[run] | accumulation of filter steps | ... AND run |
-run | :except[run] | difference of sets | ... AND NOT run |
~run | :else[run] | else | ... ELSE run |
:intersection | intersection of sets |
For the difference between +
and :intersection
, see Filter Run Prefix (Examples).
The input of a run is normally a list of all the non-shadow tiddler titles in the wiki (in no particular order). But the +
prefix can change this:
Prefix | Input |
- , ~ , = , :intersection or none | [all[]] tiddler titles, unless otherwise determined by the first filter operator |
+ , :filter , :reduce ,:sort | the filter output of all previous runs so far |
Precisely because of varying inputs, be aware that both prefixes -
and +
do not behave inverse to one another!
For example, in both of the following, $:/baz
will only be removed if it actually exists:
To understand why, consider the input for both final runs with their -
prefix.
In order to remove $:/baz
in any case, existing or not, simply use the +
prefix with negated filter operators: