Use railroad diagrams to explain filter syntax

This commit is contained in:
Astrid Elocson 2015-01-03 20:16:46 +00:00
parent 42efd4116d
commit 388464190d
4 changed files with 83 additions and 63 deletions

View File

@ -7,7 +7,7 @@ type: text/vnd.tiddlywiki
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.
* [[Introduction to Filters]] is a step-by-step introduction to how filters are used
* [[Filter Formal Grammar]] is a technical explanation of the filter syntax.
* [[Filter Syntax]] explains the exact rules for writing filters
The most common filter operators are:

View File

@ -0,0 +1,80 @@
created: 20140210141217955
modified: 20150102174633890
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.
---
;filter
: <$railroad text="""
{ [:whitespace] ("+" | :- | "-") run }
"""/>
A sequence of runs is evaluated from left to right, as follows:
|!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 |
The first run takes `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers.
---
;run
: <$railroad text="""
( "[" {step} "]"
|
'"' [{/'any character except "'/}] '"'
|
"'" [{/"any character except '"/}] '"'
|
[{/"any character except [ ] 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
---
;step
: <$railroad text="""
[:"!"] operator parameter
"""/>
* A step returns a set of tiddlers, in the form of a TitleList
---
;operator
: <$railroad text="""
( keyword [:":" fieldname] | fieldname )
"""/>
* 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`
---
;parameter
: <$railroad text="""
( "[" [{/"any character except ]"/}] "]"
|
"{" [{/"any character except }"/}] "}"
|
"<" [{/"any character except >"/}] ">"
)
"""/>
* `[`...`]` encloses a literal parameter
* `{`...`}` encloses a TextReference parameter
* `<`...`>` encloses a [[variable|Variables]] parameter
---
;whitespace
: <$railroad text="""
{( "space" | "tab" | "linefeed" | "return" | "vertical tab" | "formfeed" )}
"""/>
* A match for the JavaScript regular expression `\s+`

View File

@ -1,61 +0,0 @@
created: 20140210141217955
modified: 20140912145655663
tags: Filters
title: Filter Formal Grammar
type: text/vnd.tiddlywiki
[[Filter expressions|Filters]] follow a grammar that is presented here for those who find formal syntax descriptions helpful. However, you can write your own filter expressions without needing to understand this tiddler.
* [//x//] denotes an optional //x//
* (//x//)... denotes 1 or more instances of //x//
* Literal characters are `monospaced`
* Top-level bullets indicate alternative possibilities
* Second-level bullets are comments and clarifications
;filter
* ( [//whitespace//] [`+`|`-`] //run// )...
;run
* `[` (//operation//)... `]`
* `"` //text// `"`
** The text can contain anything but `"`
* `'` //text// `'`
** The text can contain anything but `'`
* //text//
** The text can contain anything but whitespace and `[` and `]`
** These last three alternatives are short for `[title[text]]`
;operation
* [`!`] //operator// //operand//
;operator
* [//keyword//] [`:` //fieldname//]
** Keywords (`is`, `has`, `tag`, etc) are reserved names that identify filter functions
** A fieldname on its own implies the keyword `field`
** An entirely omitted operator defaults to `title`
;operand
* `[` //text// `]`
** literal -- the text can contain anything but `]`
* `{` //text// `}`
** text reference -- the text can contain anything but `}`
* `<` //text// `>`
** variable -- the text can contain anything but `>`
;whitespace
* One or more spaces, tabs or linefeeds, i.e. a match for the JavaScript regular expression `\s+`
!Evaluation
Each operation returns a set of tiddlers, in the form of a TitleList.
A run evaluates each of the operations it contains, and returns the intersection of the resulting sets.
A sequence of runs is evaluated from left to right, as follows:
|!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 |
The first run of a sequence takes `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers.

View File

@ -4,7 +4,8 @@
"tiddlywiki/googleanalytics",
"tiddlywiki/nodewebkitsaver",
"tiddlywiki/github-fork-ribbon",
"tiddlywiki/browser-sniff"
"tiddlywiki/browser-sniff",
"tiddlywiki/railroad"
],
"themes": [
"tiddlywiki/vanilla",