mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-06-13 17:16:48 +00:00
74 lines
4.2 KiB
Plaintext
74 lines
4.2 KiB
Plaintext
title: TiddlerFilters
|
|
tags: docs concepts
|
|
|
|
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]]` |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
|
|
* ''sort-case-sensitive'': a case sensitive 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
|
|
* ''list'': selects the tiddlers listed in a specified tiddler (newline delimited)
|
|
|
|
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:
|
|
|
|
* ''shadow'': selects all shadow tiddlers
|
|
* ''current'': selects the current ContextTiddler
|
|
|
|
! 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
|