mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-07-08 21:14:25 +00:00
623a3ec8f8
What we have at the moment isn't really the same as TiddlyWiki classic's shadow tiddlers, it's a much simpler system for excluding tiddlers. We'll use the term "shadow" instead to refer to the way that tiddlers in plugins behave, which is exactly like TiddlyWiki classic's shadow tiddlers.
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:
|
|
|
|
* ''system'': selects all system 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
|