TiddlyWiki5/editions/tw5.com/tiddlers/filters/Introduction to Filters.tid

created: 20140410101941871
modified: 20141009180223576
tags: Learning Filters
title: Introduction to filter notation
type: text/vnd.tiddlywiki

: (This explains the basics of writing a [[filter|Filters]] to select a set of tiddlers. For a more technical summary, see [[Filter Syntax]].)

The simplest case is where you already know exactly which tiddlers you want. Type each title in double square brackets, with a space or linebreak between each one and the next:

```
[[Recipe book]] [[ScrambledEggs]] [[Mom's apple pie]]
```

You can omit the square brackets when a title doesn't contain any spaces:

```
[[Recipe book]] ScrambledEggs [[Mom's apple pie]]

```

The double square brackets are actually a shorthand for this:

```
[title[Scrambled eggs]]
```

… which gives us the <<doc-def "general model">> for any filter:

```
[method[parameter]]
```

For instance, here's how to select all the tiddlers that have been tagged <<doc-tag Recipe>>:

```
[tag[Recipe]]
```

We can reverse the meaning by adding an exclamation mark `!` just before the method. For example, we can select any tiddlers that do <<doc-em not>> have the <<doc-tag Recipe>> tag:

```
[!tag[Recipe]]
```

Tiddlers can be filtered by other fields than just title and tags:

```
[field:serving[4]]
```

That example will select any tiddlers that have <<doc-field-value 4>> in their <<doc-field serving>> field.

As the word "serving" isn't a standard filter method (and isn't likely to become one), you can safely omit the `field:` prefix:

```
[serving[4]]
```

!Combinations

The filters we've looked at so far have involved just one step each. But you can <<doc-def run>> several steps together like this:

```
[tag[Vegetarian]!tag[soup]serving[4]]
```

Notice how the entire run is contained in a single pair of square brackets.

A tiddler has to match <<doc-em all>> of the steps in a run. So the example above retrieves vegetarian recipes (other than soups) for 4 people.

A <<doc-em sequence>> of runs will select the tiddlers that match <<doc-em any>> of the runs. We can use this to find recipes that serve either 3, 4 or 5 people:

```
[serving[3]] [serving[4]] [serving[5]]
```

If we want to ignore vegetarian recipes that serve 4, we can say this:

```
[serving[3]] [serving[4]!tag[vegetarian]] [serving[5]]
```

By default, each run considers every tiddler in the wiki. But we can use a `+` sign to force a run to consider only the tiddlers that were selected by the preceding runs:

```
[serving[3]] [serving[4]] [serving[5]] +[tag[Vegetarian]] +[sort[title]]
```

This selects recipes for 3, 4 or 5 people, then filters <<doc-em those>> to remove the vegetarian ones, and finally sorts any that are left into alphabetical order of title.

In a similar way, we can use a `-` sign to <<doc-em remove>> a run's tiddlers from the result so far. Here we select all vegetarian recipes apart from two:

```
[tag[Vegetarian]] -[title[ScrambledEggs]] -BeansOnToast
```

!Special parameters

The parameter of each step we've seen so far has been in square brackets, meaning that ~TiddlyWiki treats it literally. But two other kinds of bracket are possible:

<<doc-def "Curly brackets">> `{}` mean that the parameter is a TextReference, and that its value is to be looked up in a specified tiddler. For example, if we have a tiddler called <<tid Preference>> whose text happens to be the word <<doc-field-value Vegetarian>>, we can say

```
[tag{Preference}]
```

as an alternative to `[tag[Vegetarian]]`. This allows the preference to change over time.

<<doc-def "Angle brackets">> `<>` mean that the parameter is the name of a [[variable|Variables]] whose value is to be used instead. Here we use the built-in <<doc-clink currentTiddler "WidgetVariable: currentTiddler">> variable in a filter that selects any tiddlers whose text contains the title of the current one:

```
[search<currentTiddler>]
```