Merge pull request #1316 from aelocson/filter-syntax

Use railroad diagrams to explain filter syntax

editions/tw5.com/tiddlers/concepts/Filters.tid

@@ -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:
 

editions/tw5.com/tiddlers/filters/FilterSyntax.tid

@@ -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+`

editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid

@@ -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.

editions/tw5.com/tiddlywiki.info

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