This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

Filter Expression

14th December 2020 at 5:30am
Filter Syntax
whitespace~+-=:named-prefixrun

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

Compare named filter run prefix :filter with filter Operator which applies a subfilter to every input title, removing the titles that return an empty result from the subfilter

Compare named filter run prefix :reduce with reduce Operator which is used to used to flatten a list of items down to a single item by repeatedly applying a subfilter.

In technical / logical terms:

RunEquivalent named prefixInterpretationOutput
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
:intersectionintersection 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:

PrefixInput
-, ~, =, :intersection or none[all[]] tiddler titles, unless otherwise determined by the first filter operator
+, :filter, :reducethe 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: