mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-11-24 02:27:19 +00:00
Code Issues Releases Wiki Activity

Merge pull request #1360 from aelocson/filter-docs

Browse Source 
Improve filter documentation
This commit is contained in:
Jeremy Ruston 2015-01-11 19:56:45 +00:00
commit 7067ba0326
7 changed files with 154 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
editions/tw5.com/tiddlers/concepts/Filters.tid
View File

@ -1,16 +1,25 @@
created: 20130827080000000
created: 20130827080000000=
modified: 20140912145347313
tags: Reference Concepts
title: Filters
type: text/vnd.tiddlywiki
list: [[Introduction to filter notation]] [[Filter Syntax]]
Filters are used in TiddlyWiki to choose tiddlers by specifying simple match criteria. They are used by widgets like the ListWidget and the CountWidget to perform operations on multiple tiddlers at once.
You can think of TiddlyWiki as a database where the records are tiddlers. A database typically provides a way of discovering which records match a given pattern, and in ~TiddlyWiki this is done with filters.
* [[Introduction to Filters]] is a step-by-step introduction to how filters are used
* [[Filter Syntax]] explains the exact rules for writing filters
A <<doc-def filter>> is a concise notation for selecting a particular set of tiddlers, known as its <<doc-def "result">>. Whenever ~TiddlyWiki encounters a filter, it calculates the result. Further work can then be done with just those tiddlers, such as [[counting|CountWidget]] or [[listing|ListWidget]] them.
The most common filter operators are:
The following example passes a filter to the [[list-links macro|ListMacro]] to display a list of all tiddlers whose titles start with the letter H:
<<list-links "[tag[CommonFilters]]">>
```
<<list-links "[prefix[H]]">>
```
See FilterOperators for a complete list of available filter operators
The result of a filter can change as tiddlers are added and deleted in the wiki. ~TiddlyWiki recalculates the results on the fly, automatically updating any filter-based counts or lists as well.
[[Advanced Search|$:/AdvancedSearch]] has a <<doc-advancedsearch-tab Filter>> tab that makes it easy to experiment with filters.
;Find out more:
* [[Introduction to filter notation]] -- a step-by-step walkthrough
* [[Filter Syntax]] -- the exact rules of the notation
* [[FilterOperators]] -- the available methods of filtering

4
editions/tw5.com/tiddlers/concepts/RailroadDiagrams.tid
View File

@ -10,6 +10,8 @@ Each diagram starts on the left and ends on the right. Simply follow any line fr
start [:optional] {repeated +","} end
"""/>
In the example above, a comma appears between each occurrence of the `repeated` item. The comma path runs from right to left, and can only be reached by first passing through `repeated`.
Characters in round boxes are literal, i.e. they denote themselves. A name in a rectangular box denotes a further railroad diagram.
The railroad diagrams on this site are generated using the [[Railroad Plugin]].
The railroad diagrams on this site are generated with the [[Railroad Plugin]].

2
editions/tw5.com/tiddlers/features/Searching.tid
View File

@ -22,4 +22,4 @@ Clicking on the magnifying glass icon to the right of the search box will open [
* The ''shadows'' tab allows you to limit your search to shadow tiddlers
* The ''filter'' tab is not a search box, per se, but a way to obtain a list of all tiddlers that meet the specific criteria described by that filter, for example, "All tags except system tags". More information in [[Introduction to Filters]]
* The ''filter'' tab is not a search box, per se, but a way to obtain a list of all tiddlers that meet the specific criteria described by that [[filter|Filters]], for example, "All tags except system tags"

12
editions/tw5.com/tiddlers/filters/FilterOperators.tid
View File

@ -4,8 +4,14 @@ tags: Concepts
title: FilterOperators
type: text/vnd.tiddlywiki
Filter operators are the individual elements of [[filters|Filters]]. See [[Introduction to Filters]] for details.
A <<doc-def "filter operator">> is a predefined name attached to an individual step in a [[filter|Filters]]. It defines how that step is to be performed.
The full list of available filter operators is:
A typical step is written as `[operator[parameter]]`, although not all of the operators need a parameter.
<<list-links "[tag[Filters]]">>
Here are the most commonly used operators:
<<list-links "[tag[CommonFilters]]">>
The complete list is:
<<list-links "[tag[Filters]] -[[Introduction to filter notation]] -[[Filter Syntax]]">>

67
editions/tw5.com/tiddlers/filters/FilterSyntax.tid
View File

@ -4,7 +4,9 @@ tags: Filters
title: Filter Syntax
type: text/vnd.tiddlywiki
[[Filter expressions|Filters]] follow a grammar that is presented here, using [[RailroadDiagrams]], for those who find formal syntax descriptions helpful. However, you can write your own filter expressions without needing to understand this tiddler.
[[Filters]] follow a grammar that is presented here, using [[RailroadDiagrams]], for those who find formal syntax descriptions helpful. However, [[you can learn to write filters|Introduction to filter notation]] without needing to understand this tiddler.
When a filter is evaluated, it generates a <<doc-def result>>, which is an ordered set of items. No item can appear more than once in the result. The items are usually tiddler titles, but certain specialised filters generate other items, such as Node.js command words.
---
@ -13,14 +15,14 @@ type: text/vnd.tiddlywiki
{ [:whitespace] ("+" | :- | "-") run }
"""/>
A sequence of runs is evaluated from left to right, as follows:
A <<doc-def filter>> is a sequence of runs, evaluated from left to right.
|!Sequence |!Interpretation |
|`run1 run2` |union of the sets, i.e. the tiddlers in //either// run1 //or// run2 |
|`run1 -run2` |difference of the sets, i.e. run1 but excluding any tiddlers in run2 |
|`run1 +run2` |run2 takes run1 as its input |
Each run receives an <<doc-def "input set">>, which it modifies to produce a result. The first run in a sequence receives `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers. The second run receives the result of the first run as its input, and so on.
The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers.
|!Run |!Interpretation |!Result |
|`run` |union of sets|input OR run |
|`+run` |intersection of sets |input AND run |
|`-run` |difference of sets|input AND NOT run |
---
@ -28,45 +30,59 @@ The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-miss
: <$railroad text="""
( "[" {step} "]"
|
'"' [{/'any character except "'/}] '"'
|
"'" [{/"any character except '"/}] '"'
|
[{/"any character except [ ] or whitespace"/}]
[:{/"anything but [ ] or whitespace"/}]
)
"""/>
* The last three options are short for `[title[text]]`
* A run evaluates each of its steps and returns the intersection of the results
<!-- The following has been removed from the diagram until issue #1346 is addressed:
'"' [:{/'anything but "'/}] '"'
|
"'" [:{/"anything but '"/}] '"'
|
-->
The lower option, e.g. matching `HelloThere`, is short for `[title[HelloThere]]`.
A <<doc-def run>> is a sequence of steps, evaluated from left to right.
The run's result is basically the intersection of the step results. In other words, the run's result contains the items that are found in <<doc-em all>> of the step results.
However, a few operators (known as <<doc-def selectors>>) ignore any preceding steps in the same run, and completely replace the result so far. Examples of this are <<doc-clink "commands" "FilterOperator: commands">> and <<doc-clink "title" "FilterOperator: title">>, but not <<doc-clink "field:title" "FilterOperator: field">>.
---
;step
: <$railroad text="""
[:"!"] operator parameter
[:"!"] [:method] parameter
"""/>
* A step returns a set of tiddlers, in the form of a TitleList
If the method is omitted, it defaults to `title`.
---
;operator
;method
: <$railroad text="""
( keyword [:":" fieldname] | fieldname )
operator [:":" suffix]
"""/>
* Keywords are reserved names (<code>[[is|FilterOperator: is]]</code>, <code>[[has|FilterOperator: has]]</code>, <code>[[tag|FilterOperator: tag]]</code>, etc) of specific filtering functions
* A fieldname on its own implies the keyword `field`
* An entirely omitted operator defaults to `title`
The operator is drawn from a list of [[predefined names|FilterOperators]].
The suffix is additional information, usually the name of a [[field|TiddlerFields]], that extends the meaning of certain operators.
An unrecognised operator name is is treated as the suffix to the <<doc-clink "field" "FilterOperator: field">> operator.
---
;parameter
: <$railroad text="""
( "[" [{/"any character except ]"/}] "]"
( "[" [:{/"anything but ]"/}] "]"
|
"{" [{/"any character except }"/}] "}"
"{" [:{/"anything but }"/}] "}"
|
"<" [{/"any character except >"/}] ">"
"<" [:{/"anything but >"/}] ">"
)
"""/>
* `[`...`]` encloses a literal parameter
* `{`...`}` encloses a TextReference parameter
* `<`...`>` encloses a [[variable|Variables]] parameter
@ -76,5 +92,4 @@ The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-miss
;whitespace
: <$railroad text="""
{( "space" | "tab" | "linefeed" | "return" | "vertical tab" | "formfeed" )}
"""/>
* A match for the JavaScript regular expression `\s+`
"""/>

192
editions/tw5.com/tiddlers/filters/Introduction to Filters.tid
View File

@ -1,146 +1,114 @@
created: 20140410101941871
modified: 20141009180223576
tags: Learning
title: Introduction to Filters
tags: Learning Filters
title: Introduction to filter notation
type: text/vnd.tiddlywiki
This is a step-by-step introduction to how [[Filters]] are used. [[Filter Syntax]] presents a more technical summary of this information.
: (This explains the basics of writing a [[filter|Filters]] to select a set of tiddlers. For a more technical summary, see [[Filter Syntax]].)
! Using Filters
Filters are a special notation for expressing lists of tiddlers within WikiText.
Filters are used in the ListMacro, TabsMacro, ListWidget, CountWidget, and many other areas of TiddlyWiki.
For example, this is how the ListMacro would be used to display the first example below:
The simplest case is where you already know exactly which tiddlers you want. Type each title in double square brackets, with a space or linebreak between each one and the next:
```
<<list-links "HelloThere Introduction [[Title with Spaces]]">>
[[Recipe book]] [[ScrambledEggs]] [[Mom's apple pie]]
```
The easiest way to experiment with tiddler filters is by typing them into the ''Filter'' tab of the [[advanced search panel|$:/AdvancedSearch]].
! Simple Filters
The simplest example of a filter is a list of tiddler titles (if necessary quoted with double square brackets):
You can omit the square brackets when a title doesn't contain any spaces:
```
HelloThere Introduction [[Title with Spaces]]
```
The titles must be separated by one or more spaces and/or linebreaks.
! Filter Operators
Filter operators are used to select tiddlers in particular ways. For example, this filter consists of a single step that selects all tiddlers tagged ''introduction'':
[[Recipe book]] ScrambledEggs [[Mom's apple pie]]
```
[tag[introduction]]
```
The word `tag` is the ''operator'' and `introduction` is the ''parameter'' (sometimes called the ''operand'').
See [[Filters]] for a complete list of the available operators.
!! Default Filter Operator
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`.
! Negating Filter Steps
A filter step can be negated by preceding the operator with an exclamation mark (`!`). This example selects all tiddlers that are not tagged ''introduction'':
The double square brackets are actually a shorthand for this:
```
[!tag[introduction]]
[title[Scrambled eggs]]
```
! Operator Suffixes
Some filter operators can take an optional suffix that provides further information. For example, the `field` operator takes a suffix indicating the field to be compared. The following filter returns all tiddlers that have ''JeremyRuston'' in the `modifier` field:
… which gives us the <<doc-def "general model">> for any filter:
```
[field:modifier[JeremyRuston]]
[method[parameter]]
```
! Field Operator Shortcut
If an operator is not recognised, then it is instead interpreted as the suffix of the `field` operator. Thus, these two filters both return all the tiddlers that contain the string ''create'' in their `caption` field:
For instance, here's how to select all the tiddlers that have been tagged <<doc-tag Recipe>>:
```
[caption[create]]
[field:caption[create]]
[tag[Recipe]]
```
! Indirect Parameters
If a filter step has curly brackets around its parameter, then it is taken to be a TextReference to the actual value. For example, this filter selects all tiddlers containing the string contained in the ''$:/temp/search'' tiddler:
We can reverse the meaning by adding an exclamation mark `!` just before the method. For example, we can select any tiddlers that do <<em not>> have the <<doc-tag Recipe>> tag:
```
[search{$:/temp/search}]
[!tag[Recipe]]
```
! Variable Parameters
Tiddlers can be filtered by other fields than just title and tags:
If a filter step has angle brackets around its parameter, then it is taken to be the name of a variable containing the actual value. For example, this filter selects all tiddlers containing the title of the current tiddler:
```
[field:serving[4]]
```
That example will select any tiddlers that have <<doc-field-value 4>> in their <<doc-field serving>> field.
As the word "serving" isn't a standard filter method (and isn't likely to become one), you can safely omit the `field:` prefix:
```
[serving[4]]
```
!Combinations
The filters we've looked at so far have involved just one step each. But you can <<doc-def run>> several steps together like this:
```
[tag[Vegetarian]!tag[soup]serving[4]]
```
Notice how the entire run is contained in a single pair of square brackets.
A tiddler has to match <<em all>> of the steps in a run. So the example above retrieves vegetarian recipes (other than soups) for 4 people.
A <<em sequence>> of runs will select the tiddlers that match <<em any>> of the runs. We can use this to find recipes that serve either 3, 4 or 5 people:
```
[serving[3]] [serving[4]] [serving[5]]
```
If we want to ignore vegetarian recipes that serve 4, we can say this:
```
[serving[3]] [serving[4]!tag[vegetarian]] [serving[5]]
```
By default, each run considers every tiddler in the wiki. But we can use a `+` sign to force a run to consider only the tiddlers that were selected by the preceding runs:
```
[serving[3]] [serving[4]] [serving[5]] +[tag[Vegetarian]] +[sort[title]]
```
This selects recipes for 3, 4 or 5 people, then filters <<em those>> to remove the vegetarian ones, and finally sorts any that are left into alphabetical order of title.
In a similar way, we can use a `-` sign to <<em remove>> a run's tiddlers from the result so far. Here we select all vegetarian recipes apart from two:
```
[tag[Vegetarian]] -[title[ScrambledEggs]] -BeansOnToast
```
!Special parameters
The parameter of each step we've seen so far has been in square brackets, meaning that ~TiddlyWiki treats it literally. But two other kinds of bracket are possible:
<<doc-def "Curly brackets">> `{}` mean that the parameter is a TextReference, and that its value is to be looked up in a specified tiddler. For example, if we have a tiddler called <<tid Preference>> whose text happens to be the word <<doc-field-value Vegetarian>>, we can say
```
[tag{Preference}]
```
as an alternative to `[tag[Vegetarian]]`. This allows the preference to change over time.
<<doc-def "Angle brackets">> `<>` mean that the parameter is the name of a [[variable|Variables]] whose value is to be used instead. Here we use the built-in <<doc-clink currentTiddler "WidgetVariable: currentTiddler">> variable in a filter that selects any tiddlers whose text contains the title of the current one:
```
[search<currentTiddler>]
```
(The built-in `currentTiddler` variable keeps track of which tiddler is the current one.)
! ORing Multiple Filter Steps
You can use multiple filter steps at once. If you write the steps separately, the overall result is the set of tiddlers that match //any// of the steps. Each step is processed separately, adding its tiddlers to the overall result.
This example selects all tiddlers that are either tagged ''introduction'' or ''demo'':
```
[tag[introduction]] [tag[demo]]
```
Here's an example that returns tiddlers tagged ''alpha'' or ''beta'' that are also tagged ''task'' but not tagged ''done'':
```
[tag[alpha]] [tag[beta]] +[tag[task]!tag[done]]
```
! ANDing Multiple Filter Steps
A sequence of steps can also be combined by bashing them together and merging the outer square brackets. This is called a "run". The result is the set of tiddlers that match //all// of the steps in the run.
For example, here we select tiddlers that are tagged ''introduction'' and also tagged ''demo'':
```
[tag[introduction]tag[demo]]
```
Here's another example that selects all tiddlers tagged ''introduction'' that are //not// tagged ''demo'':
```
[tag[introduction]!tag[demo]]
```
! Negating Runs
Ordinarily, each run //adds// to the accumulated results. Prefixing a run with `-` instead causes the list of tiddlers selected to be //removed// from the results. For example, this example returns all the tiddlers tagged ''introduction'', apart from `HelloThere` and `Title with Spaces`:
```
[tag[introduction]] -HelloThere -[[Title with Spaces]]
```
This example returns all tiddlers tagged ''introduction'' that are not also tagged ''demo'':
```
[tag[introduction]] -[tag[demo]]
```
! Working with Filter Results
Usually, each run takes the entire store of available tiddlers as its source. Prefixing a run with `+` causes the results so far accumulated to be used as the source instead.
For example, this filter selects tiddlers tagged ''introduction'' or ''demo'', and then sorts the resulting list by the `title` field:
```
[tag[introduction]] [tag[demo]] +[sort[title]]
```
```

8
editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid
View File

@ -24,13 +24,13 @@ Variables are defined by...
!!Using Variables
Variables are used via...
Variables are used...
; shorthand
; via shorthand
:`<<variableName>>`
; variable substitution within [[macros|Macros]]
; via variable substitution within [[macros|Macros]]
:`$(variableName)$`
; as variable operands in [[filter expressions|Introduction to Filters]]
; as parameters to [[filter steps|Filters]]
: `[operator<variableName>]`
; in [[widgets|Widgets]]
: internally, or as widget attributes