diff --git a/editions/tw5.com/tiddlers/concepts/Filters.tid b/editions/tw5.com/tiddlers/concepts/Filters.tid index ac0d8c1ec..ec055933c 100644 --- a/editions/tw5.com/tiddlers/concepts/Filters.tid +++ b/editions/tw5.com/tiddlers/concepts/Filters.tid @@ -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 <> is a concise notation for selecting a particular set of tiddlers, known as its <>. 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: -<> +``` +<> +``` -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 <> 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 \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/concepts/RailroadDiagrams.tid b/editions/tw5.com/tiddlers/concepts/RailroadDiagrams.tid index f10dc9a73..02ae03ffa 100644 --- a/editions/tw5.com/tiddlers/concepts/RailroadDiagrams.tid +++ b/editions/tw5.com/tiddlers/concepts/RailroadDiagrams.tid @@ -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]]. diff --git a/editions/tw5.com/tiddlers/features/Searching.tid b/editions/tw5.com/tiddlers/features/Searching.tid index cf873789a..27fadec44 100644 --- a/editions/tw5.com/tiddlers/features/Searching.tid +++ b/editions/tw5.com/tiddlers/features/Searching.tid @@ -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" diff --git a/editions/tw5.com/tiddlers/filters/FilterOperators.tid b/editions/tw5.com/tiddlers/filters/FilterOperators.tid index 478f33888..800d635d5 100644 --- a/editions/tw5.com/tiddlers/filters/FilterOperators.tid +++ b/editions/tw5.com/tiddlers/filters/FilterOperators.tid @@ -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 <> 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. -<> +Here are the most commonly used operators: + +<> + +The complete list is: + +<> diff --git a/editions/tw5.com/tiddlers/filters/FilterSyntax.tid b/editions/tw5.com/tiddlers/filters/FilterSyntax.tid index 4b78bd217..5b98e011e 100644 --- a/editions/tw5.com/tiddlers/filters/FilterSyntax.tid +++ b/editions/tw5.com/tiddlers/filters/FilterSyntax.tid @@ -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 <>, 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 <> 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 <>, 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 lower option, e.g. matching `HelloThere`, is short for `[title[HelloThere]]`. + +A <> 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 <> of the step results. + +However, a few operators (known as <>) ignore any preceding steps in the same run, and completely replace the result so far. Examples of this are <> and <>, but not <>. --- ;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 ([[is|FilterOperator: is]], [[has|FilterOperator: has]], [[tag|FilterOperator: tag]], 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 <> 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+` +"""/> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/Introduction to Filters.tid b/editions/tw5.com/tiddlers/filters/Introduction to Filters.tid index d118293b5..fa7621f13 100644 --- a/editions/tw5.com/tiddlers/filters/Introduction to Filters.tid +++ b/editions/tw5.com/tiddlers/filters/Introduction to Filters.tid @@ -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: ``` -<> +[[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 <> 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 <>: ``` -[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 <> have the <> 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 <> in their <> 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 <> 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 <> of the steps in a run. So the example above retrieves vegetarian recipes (other than soups) for 4 people. + +A <> of runs will select the tiddlers that match <> 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 <> 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 <> 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: + +<> `{}` 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 <> whose text happens to be the word <>, we can say + +``` +[tag{Preference}] +``` + +as an alternative to `[tag[Vegetarian]]`. This allows the preference to change over time. + +<> `<>` mean that the parameter is the name of a [[variable|Variables]] whose value is to be used instead. Here we use the built-in <> variable in a filter that selects any tiddlers whose text contains the title of the current one: ``` [search] -``` - -(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]] -``` +``` \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid index a4d897628..0fbf685c8 100644 --- a/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid @@ -24,13 +24,13 @@ Variables are defined by... !!Using Variables -Variables are used via... +Variables are used... -; shorthand +; via shorthand :`<>` -; 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]` ; in [[widgets|Widgets]] : internally, or as widget attributes