TiddlyWiki5/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid

created: 20130827080000000
modified: 20140220091253282
tags: concepts
title: TiddlerFilters
type: text/vnd.tiddlywiki

Filters are used in TiddlyWiki to choose tiddlers by specifying simple match criteria. See [[TiddlerFilter Formal Grammar]] for a technical explanation of the syntax.

! Examples

The mechanism is easiest to understand by first presenting some example filter strings:

@@.table-condensed
|!Filter |!Results |
|`HelloThere` |The single tiddler titled `HelloThere` (if it exists) |
|`[[A Title With Several Words]]` |The single tiddler titled `A Title With Several Words` (if it exists) |
|`[title[MyTiddler]]` |The single tiddler titled `MyTiddler` (if it exists) |
|`HelloThere Introduction` |The tiddlers titled `HelloThere` and `Introduction` (if they exist) |
|`[tag[important]]` |All tiddlers with the tag `important` |
|`[tag[important]tag[secret]]` |All tiddlers with both the tag `important` and the tag `secret` |
|`[tag[important]!tag[secret]]` |All tiddlers with the tag `important` but not the tag `secret` |
|`[!tag[important]]` |All tiddlers not with the tag `important` |
|`[tag[important]sort[title]]` |All tiddlers with the tag `important` sorted by title |
|`[tag[important]!sort[title]]` |All tiddlers with the tag `important` reverse sorted by title |
|`[[one]] [[two]] [[three]] +[tag[tom]]` |Any of the tiddlers called `one`, `two` or `three` that exist and are tagged with `tom` |
|`[[one]] [[two]] [[three]] [tag[tom]]` |Any of the tiddlers called `one`, `two` or `three` that exist, along with all of the source tiddlers that are tagged with `tom` |
|`[tag[tom]] [tag[harry]] -[[one][two][three]]` |All tiddlers tagged either `tom` or `harry`, but excluding `one`, `two` and `three` |
|`[[MyTiddler]tags[]]` |All tiddlers being used as tags on the tiddler `MyTiddler` |
|`[[MyTiddler]tagging[]]` |All tiddlers being tagged with `MyTiddler` |
|`[list[MyList]]` |All tiddlers listed in `MyList` |
@@

! Operators

A filter string consists of one or more runs of filter operators that each look like `[operator[operand]]`, where `operator` is one of:

* ''title'': selects the tiddler with the title given in the operand
* ''is'': tests whether a tiddler is a member of the system defined set named in the operand (see below)
* ''has'': tests whether a tiddler has a non-empty value for the field specified in the operand
* ''sort'': sorts the tiddlers by the field specified in the operand
* ''sortcs'': a case sensitive sort of the current tiddlers by the field specified in the operand
* ''nsort'': sorts the tiddlers numerically by the field specified in the operand
* ''nsortcs'': a case sensitive (for the non-numerical elements) numerical sort of the current tiddlers by the field specified in the operand
* ''prefix'': tests whether a tiddlers title starts with the prefix specified in the operand
* ''limit'': limits the number of subresults to the integer specified in the operand
* ''tag'': tests whether a given tag is (`[tag[mytag]]`) or is not (`[!tag[mytag]]`) present on the tiddler
* ''field:{fieldname}'' or ''{fieldname}'': tests whether a tiddler field has a specified value (`[modifier[Jeremy]]` or `[field:modifier[Jeremy]]`) or not (`[!modifier[Jeremy]]`)
* ''tags'': selects the tags on the currently selected tiddlers
* ''tagging'': selects the tiddlers tagged with the currently selected tiddlers
* ''untagged'': selects the any of the selected tiddlers that do not have at least one tag
* ''links'': selects the outgoing links on the currently selected tiddlers
* ''backlinks'': selects the tiddlers that link to the currently selected tiddlers
* ''list'': selects the tiddlers listed in a specified [[TiddlerList|TiddlerLists]]
* ''next'': selects the next item in a TiddlerList after the current tiddler
* ''previous'': selects the previous item in a TiddlerList before the current tiddler
* ''listed'': selects the TiddlerLists that include the current tiddler
* ''each'': selects one tiddler for each discrete value of the specified field
* ''eachday'': selects one tiddler for each discrete day in the specified date field
* ''sameday'': selects all the tiddlers falling into the same day as the provided date in the specified date field
* ''fields'': returns the names of the fields present on the selected tiddlers
* ''search'': returns all tiddlers that contain the specified text
* ''reverse'': reverses the list
* ''first'': selects the first tiddler of the list (or the first n if the operand is n)
* ''last'': selects the last tiddler of the list (or the last n if the operand is n)
* ''rest'': selects all but the first tiddler of the list (or all but the first n if the operand is n)
* ''butfirst'': synonym for ''rest''
* ''bf'': another synonym for ''rest''
* ''butlast'': selects all but the last tiddler of the list (or all but the last n if the operand is n)
* ''bl'': another synonym for ''butlast''
* ''nth'': selects the n-th tiddler of the list. Defaults to n = 1
* ''indexes'': selects the names of the indexes within a [[DataTiddler|DataTiddlers]]

An operator can be negated with by preceding it with `!`, for example `[!tag[Tommy]]` selects the tiddlers that are not tagged with `Tommy`.

The operator defaults to `title` if omitted, so `[[HelloThere]]` is equivalent to `[title[HelloThere]]`. If there are no spaces in the title, then the double square brackets can also be omitted: `HelloThere`.

The operands available with the `is` operator are:

* ''tiddler'': selects all tiddlers excluding shadows, whether or not they are SystemTiddlers
* ''system'': selects all SystemTiddlers
* ''shadow'': selects all ShadowTiddlers
* ''current'': selects the CurrentTiddler
* ''missing'': selects all MissingTiddlers
* ''orphan'': selects all OrphanTiddlers

! Indirect Operands

If a filter operator is written with curly brackets around the operand then it is taken to be a TextReference to the actual value. For example:

* `[search{$:/temp/search}]`: selects all tiddlers containing the string contained in the tiddler titled ''$:/temp/search''.

! Regular Expression Filters

The ''field'' filter also accepts [[regular expressions|http://en.wikipedia.org/wiki/Regular_expression]] with the syntax `/regexp/(modifier)`. For example:

* `[field:title/example/]`: searches for all tiddlers having "example" in their title
* `[field:title:/example$/]`: `$` is an "anchor" for the end of the text so that "example" has to be at the end of the title
* `[field:text/summer|winter/(i)]`: Searches for tiddlers containing "summer" or "winter", ignoring case

! Runs

Operators are combined into runs that function as logically ANDed expressions by bashing them together and merging the square brackets:

```
[tag[one]] [tag[two]] ---> [tag[one]tag[two]]
```

Runs can be preceded with `-` to negate their action, removing the selected tiddlers from the results. For example, `[tag[Tommy]] -HelloThere -[[Another One]]` selects all tiddlers tagged with `Tommy` except those titled `HelloThere` or `Another One`.

Runs can be preceded with `+` in order to make them apply to all of the accumulated results, rather than the original source. For example, `[tag[Jeremy]] [tag[Tommy]] +[sort[title]]` selects the tiddlers tagged `Tommy` or `Jeremy`, and sorts them by the `title` field.

! Processing model

Filters are processed with the following elements:

* a sequence of runs of filter operations
* the incoming source tiddlers, typically all the tiddlers available in the wiki
* the overall result stack
* the subresult stack of the tiddlers selected by the current run