mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-08-23 18:16:44 +00:00
97 lines
5.6 KiB
Plaintext
97 lines
5.6 KiB
Plaintext
created: 201308270800
|
|
modified: 201311242006
|
|
tags: concepts
|
|
title: TiddlerFilters
|
|
|
|
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
|
|
* ''sortcs'': 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
|
|
* ''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''.
|
|
|
|
! 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
|