mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-08-23 10:06:44 +00:00
120 lines
7.2 KiB
Plaintext
120 lines
7.2 KiB
Plaintext
created: 20130827080000000
|
|
modified: 20140107114229585
|
|
tags: concepts
|
|
title: TiddlerFilters
|
|
type: text/vnd.tiddlywiki
|
|
|
|
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:{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.
|
|
|
|
|
|
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
|