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

Filters are used in TiddlyWiki to choose tiddlers by specifying simple match criteria.

! 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 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}:'': tests whether a tiddler field has a specified value (`[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

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 current ContextTiddler
* ''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 in the form `/regexp/modifier`. Please refer to you favourite JavaScript documentation to learn more about regular expressions and modifiers.

In the easiest form, regular expressions allow you do do a search on substrings for every field:

* `title:[/example/]`: searches for all tiddlers having "example" in its title.
* `title:[/example$/]`: `$`is an "anchor" for the end of the text. So "example" has to be the end of the title.
* `text:[/jeremy|ruston/i]`: Searches for tiddlers containing Jeremy's first or last name, ignoring the 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