tiddlywiki 5.1.23 → 5.2.2

package/editions/tw5.com/tiddlers/filters/range.tid

@@ -1,14 +1,15 @@
 created: 20171221184734665
-modified: 20171229211834620
-tags: [[Filter Operators]] [[Negatable Operators]]
+modified: 20210907170339891
+tags: [[Filter Operators]] [[Negatable Operators]] [[Selection Constructors]]
 title: range Operator
 type: text/vnd.tiddlywiki
 caption: range
 op-purpose: generate a range of numbers
 op-input: ignored
-op-parameter: a range specification, like `[1,5]`
+op-parameter: a range specification, like `[1],[5]`
 op-parameter-name: N
 op-output: a series of evenly spaced numbers ranging from `<begin>` to `<end>`
+op-neg-output: a series of evenly spaced numbers ranging from `<begin>` to `<end>` in reverse order
 
 \define range_example(range)
 ```
@@ -18,20 +19,22 @@ op-output: a series of evenly spaced numbers ranging from `<begin>` to `<end>`
 <$list variable=n filter="[range[$range$]]"><<n>> </$list>
 \end
 
-The `range` operator produces a list of numbers counting up or down.  It's useful for counting and numbering, or in combination with the [[Formula Plugin]].
+The `range` operator produces a list of numbers counting up or down.  It is useful for counting and numbering.
 
-|!Purpose|produce a range of numbers|
-|!Input|ignored.|
-|!Parameter|1-3 numbers separated by `,` or `;`.|
-|!Output|A series of evenly spaced numbers ranging from `<begin>` to `<end>`|
-|!`!` Output|As ''Output'', but with order reversed.|
+<<.from-version "5.2.0">> The range operator has been updated to use multiple operands to specify its parameters. Prior to this version, the range operator only had one operand, with the three parts delimited by `,`, `;` or `:`.
 
-The parameter has three forms:
+```
+[range[<begin>]]
+[range[<begin>],[<end>]]
+[range[<begin>],[<end>],[<step>]]
+```
 
-|Parameter|Output|h
-|`<end>`|Whole numbers up to `<end>`.|
-|`<begin>,<end>`|Numbers from `<begin>` to `<end>`, spaced by whole numbers.|
-|`<begin>,<end>,<step>`|Numbers from `<begin>` to `<end>` spaced out by `<step>`.|
+The behaviour depends on the number of operands:
+
+|Parameter |Output |h
+|`<end>` |Whole numbers up to `<end>` |
+|`<begin>,<end>` |Numbers from `<begin>` to `<end>`, spaced by whole numbers |
+|`<begin>,<end>,<step>` |Numbers from `<begin>` to `<end>` spaced out by `<step>` |
 
 Each part must be a number, and works as follows:
 
@@ -44,19 +47,18 @@ Each part must be a number, and works as follows:
 ** Cannot be zero.
 ** We always count from `<begin>` toward `<end>`, whether `<step>` is positive or negative.
 
-The number of decimal points in the output is fixed, and based on the parameter with the //most// decimal points.
+The number of decimal points in the output is fixed, and based on the operand with the //most// decimal points.
 
 To prevent the browser from freezing, `range` is currently limited to 10,000 values.
 
-
 !!Examples
 
 <<range_example "7">>
 
-<<range_example "1, 10">>
+<<range_example "1],[10">>
 
-<<range_example "17,13">>
+<<range_example "17],[13">>
 
-<<range_example "1.001, 5, 1">>
+<<range_example "1.001],[5],[1">>
 
-<<range_example ".5,1.4,.004">>
+<<range_example ".5],[1.4],[.004">>

package/editions/tw5.com/tiddlers/filters/reduce.tid

@@ -1,6 +1,6 @@
 caption: reduce
 created: 20201004154131193
-modified: 20201208185109549
+modified: 20210522162536854
 op-input: a [[selection of titles|Title Selection]] passed as input to the filter
 op-output: the final result of running the subfilter <<.place S>>
 op-parameter: a [[filter expression|Filter Expression]]. Optional second parameter for initial value for accumulator
@@ -18,6 +18,7 @@ The following variables are available within the subfilter:
 
 * ''accumulator'' - the result of the previous subfilter run
 * ''currentTiddler'' - the input title
+* ''..currentTiddler'' - the value of the variable `currentTiddler` outside the subfilter. <<.from-version "5.2.0">>
 * ''index'' - the numeric index of the current list item (with zero being the first item in the list)
 * ''revIndex'' - the reverse numeric index of the current list item (with zero being the last item in the list)
 * ''length'' - the total length of the input list

package/editions/tw5.com/tiddlers/filters/removeprefix.tid

@@ -1,5 +1,5 @@
 created: 20140410103123179
-modified: 20150203190709000
+modified: 20220218023400000
 tags: [[Filter Operators]] [[String Operators]]
 title: removeprefix Operator
 type: text/vnd.tiddlywiki
@@ -9,9 +9,24 @@ op-input: a [[selection of titles|Title Selection]]
 op-parameter: a string of characters
 op-parameter-name: S
 op-output: those input titles that start with <<.place S>>, but with those characters discarded
-
-<<.s-matching-is-case-sensitive>>
+op-suffix: the <<.op removeprefix>> operator uses a rich suffix, see below for details
 
 <<.tip " This filters out input titles that do not start with S. For removing S without filtering out input titles that don't start with S, see [[trim|trim Operator]].">>
 
+<<.from-version "5.2.2">>
+
+The <<.op removeprefix>> operator uses an extended syntax that permits multiple flags to be passed:
+
+```
+[removeprefix:<flag list>[<operand>]]
+```
+
+* ''flag list'': a comma delimited list of flags
+* ''operand'': filter operand
+
+The available flags are:
+
+* ''casesensitive'': (default), this flag forces a case-sensitive match, where upper and lower case letters are considered different
+* ''caseinsensitive'': overrides the default so that upper and lower case letters are considered identical for matching purposes
+
 <<.operator-examples "removeprefix">>

package/editions/tw5.com/tiddlers/filters/removesuffix.tid

@@ -1,5 +1,5 @@
 created: 20140828133830424
-modified: 20150203190744000
+modified: 20220218023400000
 tags: [[Filter Operators]] [[String Operators]]
 title: removesuffix Operator
 type: text/vnd.tiddlywiki
@@ -9,9 +9,24 @@ op-input: a [[selection of titles|Title Selection]]
 op-parameter: a string of characters
 op-parameter-name: S
 op-output: those input titles that end with <<.place S>>, but with those characters discarded
-
-<<.s-matching-is-case-sensitive>>
+op-suffix: the <<.op removesuffix>> operator uses a rich suffix, see below for details
 
 <<.tip " This filters out input titles that do not end with S. For removing S without filtering out input titles that don't end with S, see [[trim|trim Operator]].">>
 
+<<.from-version "5.2.2">>
+
+The <<.op removesuffix>> operator uses an extended syntax that permits multiple flags to be passed:
+
+```
+[removesuffix:<flag list>[<operand>]]
+```
+
+* ''flag list'': a comma delimited list of flags
+* ''operand'': filter operand
+
+The available flags are:
+
+* ''casesensitive'': (default), this flag forces a case-sensitive match, where upper and lower case letters are considered different
+* ''caseinsensitive'': overrides the default so that upper and lower case letters are considered identical for matching purposes
+
 <<.operator-examples "removesuffix">>

package/editions/tw5.com/tiddlers/filters/search-replace Operator.tid

@@ -1,6 +1,6 @@
 caption: search-replace
 created: 20201107111139011
-modified: 20201107122008854
+modified: 20210829174535854
 op-input: a [[selection of titles|Title Selection]]
 op-output: the input titles with the search string replaced with the replacement string
 op-parameter: the <<.op search-replace>> operator requires 2 parameters, see below for details
@@ -18,7 +18,7 @@ The <<.op search-replace>> operator uses an extended syntax that allows for mult
 [search-replace:<flag list>:<regexp-mode>[<search-term>],[<replacement>]]
 ```
 
-* ''flag-list'': ''g'' for global mode to replace all matches, ''i'' for case-insensitive mode, "gi" for both. (optional)
+* ''flag-list'': ''g'' for global mode to replace all matches, ''i'' for case-insensitive mode, <<.from-version "5.2.0">> ''m'' for multiline mode, "gim" for all. (optional)
 * ''regexp-mode'': ''regexp'' to treat the first parameter as a regular expression (optional).
 * ''search-term'': string or regular expression that should be replaced
 * ''replacement'': string that should replace the search-term

package/editions/tw5.com/tiddlers/filters/search.tid

@@ -1,15 +1,15 @@
+caption: search
 created: 20140410103123179
-modified: 20190731212738712
+modified: 20211129120739275
+op-input: a [[selection of titles|Title Selection]]
+op-neg-output: those input tiddlers in which <<.em not>> all of the search terms can be found
+op-output: those input tiddlers in which <<.em all>> of the search terms can be found in the value of field <<.place F>>
+op-parameter: one or more search terms, separated by spaces, or a literal search string
+op-purpose: filter the input by searching tiddler content
+op-suffix: the <<.op search>> operator uses a rich suffix, see below for details
 tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] [[Negatable Operators]]
 title: search Operator
 type: text/vnd.tiddlywiki
-caption: search
-op-purpose: filter the input by searching tiddler content
-op-input: a [[selection of titles|Title Selection]]
-op-suffix: the <<.op search>> operator uses a rich suffix, see below for details
-op-parameter: one or more search terms, separated by spaces, or a literal search string
-op-output: those input tiddlers in which <<.em all>> of the search terms can be found in the value of field <<.place F>>
-op-neg-output: those input tiddlers in which <<.em not>> all of the search terms can be found
 
 <<.from-version "5.1.18">> The search filter operator was significantly enhanced in 5.1.18. Earlier versions do not support the extended syntax and therefore do not permit searching multiple fields, or the ''literal'' or ''casesensitive'' options.
 
@@ -38,7 +38,8 @@ The available flags are:
 ** ''literal'': considers the search string to be a literal string, and requires an exact match
 ** ''whitespace'': considers the search string to be a literal string, but will consider all runs of whitespace to be equivalent to a single space. Thus `A B` matches `A   B`
 ** ''regexp'': treats the search string as a regular expression. Note that the ''regexp'' option obviates the need for the older <<.olink regexp>> operator.
-** ''words'': (the default) treats the search string as a list of tokens separated by whitespace, and matches if all of the tokens appear in the string (regardless of ordering and whether there is other text in between)
+** ''words'': (the default) treats the search string as a list of tokens separated by whitespace, and matches if ''all of the tokens'' appear in the string (regardless of ordering and whether there is other text in between)
+** ''some'': <<.from-version "5.2.2">> treats the search string as a list of tokens separated by whitespace, and matches if ''at least one'' of the tokens appear in the string
 * ''casesensitive'': if present, this flag forces a case-sensitive match, where upper and lower case letters are considered different. By default, upper and lower case letters are considered identical for matching purposes.
 * ''anchored'': <<.from-version "5.1.20">> anchors the search to the start of the string (applies to ''whitespace'', ''literal'' and ''words'' modes)
 

package/editions/tw5.com/tiddlers/filters/sha256 Operator.tid

@@ -0,0 +1,18 @@
+caption: sha256
+created: 20220129105504961
+modified: 20220129105504961
+op-input: a [[selection of titles|Title Selection]]
+op-output: the base64 encoded sha256 of the input, truncated to the specified length
+op-parameter: the number of characters to return, up to a maximum of 64
+op-parameter-name: L
+op-purpose: apply sha256 hash to a string
+tags: [[Filter Operators]] [[String Operators]]
+title: sha256 Operator
+type: text/vnd.tiddlywiki
+from-version: 5.1.14
+
+Hashes are a way of turning strings of arbitrary length into obfuscated strings of fixed length. They are often used in situations where items need to be stored by name but it is inconvenient to allow arbitrary length strings.
+
+See Wikipedia for details of the [[sha256|https://en.wikipedia.org/wiki/SHA-2]] operation.
+
+<<.operator-examples "sha256">>

package/editions/tw5.com/tiddlers/filters/sin Operator.tid

@@ -0,0 +1,13 @@
+caption: sin
+created: 20211019203650938
+modified: 20211021222816944
+op-input: a [[selection of titles|Title Selection]]
+op-output: the sine of the input angles (numeric value between -1 and 1)
+op-purpose: calculate the sine value of a list of angles (given in radians)
+tags: [[Filter Operators]] [[Mathematics Operators]] [[Trigonometric Operators]] [[Unary Mathematics Operators]]
+title: sin Operator
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.1.21">> See [[Mathematics Operators]] for an overview.
+
+<<.operator-examples "sin">>

package/editions/tw5.com/tiddlers/filters/sortsub Operator.tid

@@ -1,21 +1,23 @@
-created: 20200424160155182
-modified: 20200424160155182
-tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]] [[Negatable Operators]]
-title: sortsub Operator
-type: text/vnd.tiddlywiki
 caption: sortsub
-op-purpose: sort the input by the result of evaluating a subfilter for each item
+created: 20200424160155182
+modified: 20210522162521222
 op-input: a [[selection of titles|Title Selection]]
+op-neg-output: the input, sorted into reverse order by the result of evaluating subfilter <<.param S>>
+op-output: the input, sorted into ascending order by the result of evaluating subfilter <<.param S>>
 op-parameter: a subfilter to be evaluated
 op-parameter-name: S
+op-purpose: sort the input by the result of evaluating a subfilter for each item
 op-suffix: the type used for the comparison (string, number, integer, date, version), defaulting to string
 op-suffix-name: T
-op-output: the input, sorted into ascending order by the result of evaluating subfilter <<.param S>>
-op-neg-output: the input, sorted into reverse order by the result of evaluating subfilter <<.param S>>
+tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]] [[Negatable Operators]]
+title: sortsub Operator
+type: text/vnd.tiddlywiki
 
 Each item in the list of input titles is passed to the subfilter in turn. The subfilter transforms the input titles into the form needed for sorting. For example, the subfilter `[length[]]` transforms each input title in the number representing its length, and thus sorts the input titles according to their length.
 
-Note that within the subfilter, the "currentTiddler" variable is set to the title of the tiddler being processed. This permits subfilters like `[{!!value}divide{!!cost}]` to be used for computation.
+Note that within the subfilter, the "currentTiddler" variable is set to the title of the tiddler being processed. This permits subfilters like `[{!!value}divide{!!cost}]` to be used for computation. 
+
+The value of currentTiddler outside the subfilter is available in the variable "..currentTiddler". <<.from-version "5.2.0">>
 
 The suffix <<.place T>> determines how the items are compared and can be:
 
@@ -24,6 +26,7 @@ The suffix <<.place T>> determines how the items are compared and can be:
 * "integer" - invalid integers are interpreted as zero
 * "date" - invalid dates are interpreted as 1st January 1970
 * "version" - invalid versions are interpreted as "v0.0.0"
+* "alphanumeric" - treat items as alphanumerics <<.from-version "5.2.0">>
 
 Note that subfilters should return the same number of items that they are passed. Any missing entries will be treated as zero or the empty string. In particular, when retrieving the value of a field with the [[get Operator]] it is helpful to guard against a missing field value using the [[else Operator]]. For example `[get[myfield]else[default-value]...`.
 

package/editions/tw5.com/tiddlers/filters/standard-deviation Operator.tid

@@ -0,0 +1,15 @@
+caption: standard-deviation
+created: 20210426130150358
+modified: 20210426131553530
+op-input: a [[selection of titles|Title Selection]]
+op-output: the standard-deviation of the input as numbers
+op-purpose: treating each input title as a number, compute their standard-deviation
+tags: [[Reducing Mathematics Operators]] [[Filter Operators]] [[Mathematics Operators]]
+title: standard-deviation Operator
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.2.0">> See [[Mathematics Operators]] for an overview.
+
+<<.tip """ The `standard-deviation` operator treats the input as a complete population and not a sample""">>
+
+<<.operator-examples "standard-deviation">>

package/editions/tw5.com/tiddlers/filters/storyviews.tid

@@ -1,6 +1,6 @@
 created: 20150126141718000
 modified: 20150203191420000
-tags: [[Filter Operators]] [[Special Operators]]
+tags: [[Filter Operators]] [[Special Operators]] [[Selection Constructors]]
 title: storyviews Operator
 type: text/vnd.tiddlywiki
 caption: storyviews

package/editions/tw5.com/tiddlers/filters/subfilter Operator.tid

@@ -1,6 +1,6 @@
 caption: subfilter
 created: 20181031175129475
-modified: 20181031175129475
+modified: 20211217135706478
 op-input: a [[selection of titles|Title Selection]] passed as input to the subfilter
 op-neg-input: a [[selection of titles|Title Selection]] passed as input to the subfilter
 op-neg-output: those input titles that are <<.em not>> returned from the subfilter  <<.place S>>
@@ -8,11 +8,11 @@ op-output: the [[selection of titles|Title Selection]] returned from the subfilt
 op-parameter: a [[filter expression|Filter Expression]]
 op-parameter-name: S
 op-purpose: select titles from the operand interpreted as a [[filter expression|Filter Expression]]
-tags: [[Filter Operators]] [[Field Operators]] [[Selection Constructors]] [[Negatable Operators]]
+tags: [[Filter Operators]] [[Field Operators]] [[Selection Constructors]] [[Negatable Operators]] [[Selection Constructors: Conditional]]
 title: subfilter Operator
 type: text/vnd.tiddlywiki
 
-<<.from-version "5.1.18">> Note that the subfilter operator was introduced in version 5.1.18 and is not available in earlier versions.
+<<.from-version "5.1.18">> Note that the <<.op subfilter>> operator was introduced in version 5.1.18 and is not available in earlier versions.
 
 <<.tip " Literal filter operands cannot contain square brackets but you can work around the issue by using a variable:">>
 
@@ -24,4 +24,6 @@ type: text/vnd.tiddlywiki
 
 <<.tip "Compare with the similar [[filter|filter Operator]] operator which runs a subfilter against each title, returning those titles that return a non-empty list (and discards the results of the subfilter)">>
 
+The <<.op subfilter>> operator will act as a [[constructor|Selection Constructors]] whenever the filter defined by its operand is a [[constructor|Selection Constructors]]. Otherwise, it will act as a [[modifier|Selection Constructors]].
+
 <<.operator-examples "subfilter">>

package/editions/tw5.com/tiddlers/filters/suffix.tid

@@ -1,5 +1,5 @@
 created: 20140828133830424
-modified: 20150203192738000
+modified: 20220218023400000
 tags: [[Filter Operators]] [[String Operators]] [[Negatable Operators]]
 title: suffix Operator
 type: text/vnd.tiddlywiki
@@ -10,7 +10,22 @@ op-parameter: a string of characters
 op-parameter-name: S
 op-output: those input titles that end with <<.place S>>
 op-neg-output: those input tiddlers that do <<.em not>> end with <<.place S>>
+op-suffix: the <<.op suffix>> operator uses a rich suffix, see below for details
 
-<<.s-matching-is-case-sensitive>>
+<<.from-version "5.2.2">>
+
+The <<.op suffix>> operator uses an extended syntax that permits multiple flags to be passed:
+
+```
+[suffix:<flag list>[<operand>]]
+```
+
+* ''flag list'': a comma delimited list of flags
+* ''operand'': filter operand
+
+The available flags are:
+
+* ''casesensitive'': (default), this flag forces a case-sensitive match, where upper and lower case letters are considered different
+* ''caseinsensitive'': overrides the default so that upper and lower case letters are considered identical for matching purposes
 
 <<.operator-examples "suffix">>

package/editions/tw5.com/tiddlers/filters/syntax/Cascade Filter Run Prefix (Examples).tid

@@ -0,0 +1,46 @@
+created: 20211130114857532
+filter1: [prefix[ca]then[ca]]
+filter2: [suffix[at]then[at]]
+filter3: other
+modified: 20211204010918504
+tags: [[Filter Run Prefix Examples]] [[Filter Syntax]] [[Cascade Filter Run Prefix]]
+title: Cascade Filter Run Prefix (Examples)
+type: text/vnd.tiddlywiki
+
+The <<.op ":cascade">> filter run prefix is used by the ~TiddlyWiki core to choose the colour for each tiddler as used in the tag pill generated by the tag macro.
+
+`:cascade[all[shadows+tiddlers]tag[$:/tags/TiddlerColourFilter]!is[draft]get[text]]`
+
+The filter expression inside the above <<.op :cascade>> filter run returns a list of filters from the text fields of tiddlers tagged <<tag $:/tags/TiddlerColourFilter>> as shown below:
+
+<ul>
+<$list filter="[all[shadows+tiddlers]tag[$:/tags/TiddlerColourFilter]!is[draft]get[text]]">
+<li><pre><$text text=<<currentTiddler>>/></pre></li>
+</$list>
+</ul>
+
+For each input title, each of these filters is now applied to in turn until the first filter that returns a non-empty list. The first result from this non-empty list replaces that input title and is used as the colour for that tiddler.
+
+<<.operator-example 1 """[all[shadows+tiddlers]] :cascade[all[shadows+tiddlers]tag[$:/tags/TiddlerColourFilter]!is[draft]get[text]] +[!is[blank]limit[10]]""">>
+
+!! Extended example
+
+This example illustrates step-by-step how the <<.op :cascade>> filter run works.
+
+A filter expression whose output returns a list of filters is required. Typically such a filter expression will construct the list of filters by querying some field in a set of tiddlers (likely via tag). To keep this example self-contained, 3 filters are stored in the //filter1//, //filter2// and //filter3// fields of this tiddler. [[Text references|TextReference]] and instances of the [[append operator|append Operator]] are used to combine the fields into a list of filters.
+
+The filter `[{!!filter1}append{!!filter2}append{!!filter3}]`, generates this list of filters:
+
+<ul>
+<$list filter="[{!!filter1}append{!!filter2}append{!!filter3}]">
+<li><pre><$text text=<<currentTiddler>>/></pre></li>
+</$list>
+</ul>
+
+For this example, `cat can bat bug` will be used as the input titles. Each input title will be evaluated by <<.op :cascade>> against each of the above filters in turn. To help understand what <<.op :cascade>> sees internally, the following table uses the [[Map Filter Run Prefix]] to show the result of each individual filter.
+
+|^<<.operator-example c1.1 "cat can bat bug :map[prefix[ca]then[ca]]">>|^<<.operator-example c1.2 "cat can bat bug :map[suffix[at]then[at]]">>|^<<.operator-example c1.3 "cat can bat bug :map[[other]]">>|
+
+Click "Try it" on the above 3 examples. The first non-blank value from each row as read from left to right will be returned when <<.op :cascade>> is used. Click "Try it" below to see the final result:
+ 
+<<.operator-example c1.4 "cat can bat bug :cascade[{!!filter1}append{!!filter2}append{!!filter3}]">>

package/editions/tw5.com/tiddlers/filters/syntax/Cascade Filter Run Prefix.tid

@@ -0,0 +1,20 @@
+created: 20211130114043280
+modified: 20211130121544118
+tags: [[Filter Syntax]] [[Filter Run Prefix]]
+title: Cascade Filter Run Prefix
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.2.1">>
+
+|''purpose'' |modify input titles by evaluating in turn a list of filters - as returned by the filter expression for this run - for each input title. |
+|''input'' |all titles from previous filter runs |
+|''output''|the input titles as modified by the filters returned by this filter run |
+
+The [[filter expression|Filter Expression]] for this [[filter run|Filter Run]] is evaluated to return a list of filters. Each input title is then evaluated against each of the filters in turn, and the input title is replaced with the first result of the first filter that returns a non-empty list. If none of the filters return a result for an input title, it is replaced with an empty string.
+
+The following variables are available within the filter run:
+
+* <<.var currentTiddler>> - the input title
+* <<.var ..currentTiddler>> - the value of the variable `currentTiddler` outside the filter run.
+
+[[Examples|Cascade Filter Run Prefix (Examples)]]

package/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid

@@ -1,5 +1,5 @@
 created: 20150124182421000
-modified: 20201214053032397
+modified: 20211129014550442
 tags: [[Filter Syntax]]
 title: Filter Expression
 type: text/vnd.tiddlywiki
@@ -23,14 +23,23 @@ If a run has:
 * the prefix `~`, if the filter output so far is an empty list then the output titles of the run are [[dominantly appended|Dominant Append]] to the filter's output. If the filter output so far is not an empty list then the run is ignored. <<.from-version "5.1.18">>
 * named prefixes for filter runs are available. <<.from-version "5.1.23">>
 * named prefix `:filter`, it receives the filter output so far as its input. The next run is evaluated for each title of the input, removing every input title for which the output is an empty list. <<.from-version "5.1.23">>
+** See [[Filter Filter Run Prefix]].
 * named prefix `:intersection` replaces all filter output so far with titles that are present in the output of this run, as well as the output from previous runs. Forms the input for the next run. <<.from-version "5.1.23">>
+** See [[Intersection Filter Run Prefix]].
 * named prefix `:reduce` replaces all filter output so far with a single item by repeatedly applying a formula to each input title. A typical use is to add up the values in a given field of each input title. <<.from-version "5.1.23">>
-** [[Examples|Filter Run Prefix (Examples)]]
+** See [[Reduce Filter Run Prefix]].
+* named prefix `:sort` sorts all filter output so far by applying this run to each input title and sorting according to that output. <<.from-version "5.2.0">>
+** See [[Sort Filter Run Prefix]].
+* named prefix `:map` transforms all filter output so far by applying this run to each input title and replacing the input title with the output of this run for that title.
+** See [[Map Filter Run Prefix]]. <<.from-version "5.2.0">>
+
 
 <<.tip "Compare named filter run prefix `:filter` with [[filter Operator]] which applies a subfilter to every input title, removing the titles that return an empty result from the subfilter">>
 
 <<.tip "Compare named filter run prefix `:reduce` with [[reduce Operator]] which is used to used to flatten a list of items down to a single item by repeatedly applying a subfilter.">> 
 
+<<.tip """Within the filter runs prefixed with `:reduce`, `:sort`, `:map` and `:filter`, the "currentTiddler" variable is set to the title of the tiddler being processed. The value of currentTiddler outside the subfilter is available in the variable "..currentTiddler".<<.from-version "5.2.0">>""" >>
+
 In technical / logical terms:
 
 |!Run |!Equivalent named prefix |!Interpretation |!Output |
@@ -47,7 +56,7 @@ The input of a run is normally a list of all the non-[[shadow|ShadowTiddlers]] t
 
 |Prefix|Input|h
 |`-`, `~`, `=`, `:intersection` or none| <$link to="all Operator">`[all[]]`</$link> tiddler titles, unless otherwise determined by the first [[filter operator|Filter Operators]]|
-|`+`, `:filter`, `:reduce`|the filter output of all previous runs so far|
+|`+`, `:filter`, `:reduce`,`:sort`|the filter output of all previous runs so far|
 
 Precisely because of varying inputs, be aware that both prefixes `-` and `+` do not behave inverse to one another!
 

package/editions/tw5.com/tiddlers/filters/syntax/Filter Filter Run Prefix (Examples).tid

@@ -0,0 +1,30 @@
+created: 20211129022707404
+modified: 20211204154839890
+tags: [[Filter Syntax]] [[Filter Run Prefix Examples]] [[Filter Filter Run Prefix]]
+title: Filter Filter Run Prefix (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[tag[HelloThere]] :filter[get[text]length[]compare:integer:gteq[1000]]">>
+<<.operator-example 2 "[tag[HelloThere]] :filter[get[text]length[]compare:integer:lteq[2000]]">>
+<<.operator-example 3 "[tag[HelloThere]] :filter[get[text]length[]compare:integer:gteq[1000]] :filter[get[text]length[]compare:integer:lteq[2000]]">>
+<<.operator-example 4 "[tag[Features]] :filter[links[]!is[shadow]is[missing]]">>
+
+<<.operator-example 5 "A B C D E F :filter[<index>remainder[2]compare:integer:eq[0]]" "Return every other element of the input list">>
+
+<<.operator-example 6 "[tag[shopping]] :filter[{!!quantity}compare:integer:gt[4]] :map[addprefix[ ]addprefix{!!quantity}]">>
+<<.operator-example 7 "[tag[shopping]] :filter[{!!quantity}compare:integer:lteq[4]] :map[addprefix[ ]addprefix{!!quantity}]">>
+
+!! Comparison between `:filter` and `:and`/`+` filter run prefixes
+
+The functionality of the <<.op :filter>> filter run prefix has some overlap with the <<.op :and>> prefix (alias <<.op +>>). Notice the filter expressions above all have the following two properties:
+
+# The start of the filter expression transforms the input titles (i.e. `get[text]length[]`, `links[]`, `<index>remainder[2]`, `{!!quantity}`.
+# The end of the filter expression only sends input items to the output if they meet some condition (i.e. `compare`, `is`).
+
+The purpose of the <<.op :filter>> prefix is to return the original input titles despite property #1 causing those input titles to be transformed. That way, the "meet some condition" check can be performed on something other than the original input. If some filter expression does not require property #1, then the <<.op :and>> prefix can be used instead.
+
+| <<.op :filter>> | <<.op :and>> |
+|^<<.operator-example c1.1 "[tag[HelloThere]] :filter[get[text]length[]compare:integer:gteq[1000]]">>|^<<.operator-example c1.2 "[tag[HelloThere]] :and[get[text]length[]compare:integer:gteq[1000]]">>|
+|^<<.operator-example c2.1 "[tag[Features]] :filter[links[]!is[shadow]is[missing]]">>|^<<.operator-example c2.2 "[tag[Features]] :and[links[]!is[shadow]is[missing]]">>|
+|!results are the same|<|
+|^<<.operator-example c3.1 "cat can bat bug :filter[suffix[at]minlength[3]]">>|^<<.operator-example c3.2 "cat can bat bug :and[suffix[at]minlength[3]]">>|

package/editions/tw5.com/tiddlers/filters/syntax/Filter Filter Run Prefix.tid

@@ -0,0 +1,27 @@
+created: 20211129022455873
+modified: 20211129022550425
+tags: [[Filter Syntax]] [[Filter Run Prefix]]
+title: Filter Filter Run Prefix
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.1.23">>
+
+|''purpose'' |remove every input title for which the filter run output is an empty list |
+|''input'' |all titles from previous filter runs |
+|''output''|the input titles for which the filter run is not empty |
+
+It receives the filter output so far as its input. The next run is evaluated for each title of the input, removing every input title for which the output is an empty list.
+
+Note that within the filter run, the "currentTiddler" variable is set to the title of the tiddler being processed. This permits filter runs like `:filter[{!!price}multiply{!!cost}compare:integer:gteq[5]]` to be used for computation. The value of currentTiddler outside the run is available in the variable "..currentTiddler".
+
+The following variables are available within the filter run:
+
+* ''currentTiddler'' - the input title
+* ''..currentTiddler'' - the value of the variable `currentTiddler` outside the filter run.
+* ''index'' - <<.from-version "5.2.1">> the numeric index of the current list item (with zero being the first item in the list).
+* ''revIndex'' - <<.from-version "5.2.1">> the reverse numeric index of the current list item (with zero being the last item in the list).
+* ''length'' - <<.from-version "5.2.1">> the total length of the input list.
+
+<<.tip "Compare named filter run prefix `:filter` with [[filter Operator]] which applies a subfilter to every input title, removing the titles that return an empty result from the subfilter">>
+
+[[Examples|Filter Filter Run Prefix (Examples)]]

package/editions/tw5.com/tiddlers/filters/syntax/Filter Parameter.tid

@@ -1,5 +1,5 @@
 created: 20150220152540000
-modified: 20201103110920722
+modified: 20210629215024053
 tags: [[Filter Syntax]]
 title: Filter Parameter
 type: text/vnd.tiddlywiki
@@ -24,7 +24,8 @@ The parameter to a [[filter operator|Filter Operators]] can be:
 :: The parameter is the text indicated by the [[text reference|TextReference]] whose name appears between the curly brackets, i.e. a [[field|TiddlerFields]] of a specified tiddler, or the value of a property of a specified [[data tiddler|DataTiddlers]].
 : <<.def variable>>
 :: `<like this>`
-:: The parameter is the current value of the [[variable|Variables]] whose name appears between the angle brackets. Macro parameters are <<.em not>> supported.
+:: The parameter is the current value of the [[variable|Variables]] whose name appears between the angle brackets. Macro parameters are <<.em not>> supported up to and including ~TiddlyWiki v5.1.23.
+::<<.from-version "5.2.0">> Literal macro parameters are supported. For example: `[<now [UTC]YYYY0MM0DD0hh0mm0ssXXX>]`.
 
 <<.from-version "5.1.23">> Filter operators support multiple parameters which are separated by a ` , ` character.
 

package/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid

@@ -1,46 +1,21 @@
 created: 20201117073343969
-modified: 20201208185546667
-tags: [[Filter Syntax]]
+modified: 20211129032537195
+tags: [[Filter Syntax]] [[Filter Run Prefix Examples]]
 title: Filter Run Prefix (Examples)
 type: text/vnd.tiddlywiki
 
-!! Difference between `+` and `:intersection`
+!! `:filter` examples
 
-The `+` prefix should be thought of as an "AND" in formal logic, e.g. "give me all titles that satisfy condition A ''and'' condition B". But it's not suitable for all cases; if condition B uses a filter operator that replaces its input, then it will be difficult to use the `+` prefix. For example, if you wanted to find out what tags two tiddlers have in common, you might try to write a filter expression like:
+See [[Filter Filter Run Prefix (Examples)]]
 
-* <$link to="tags Operator">`[[field Operator]tags[]] +[[compare Operator]tags[]]`</$link>
+!! `:intersection` examples
 
-But that won't work, because the second filter run will end up throwing away its input and replacing it with an input consisting of the single title `[[compare Operator]]`. So the result you'd get from that filter expression would be just the tags of the `compare Operator` tiddler.
-
-For cases like this, the `:intersection` prefix is what you need. It takes the filter output so far, //sets it aside//, and starts the next filter run with all tiddler titles as input. Then once the latest filter run has completed, it takes the latest output, compares it to the set-aside output, and produces a new output that contains only titles that appeared in both the set-aside output and the latest output. So to get only the tags that the `field Operator` and `compare Operator` tiddlers have in common, you would write a filter expression like this:
-
-* <$link to="tags Operator">`[[field Operator]tags[]] :intersection[[compare Operator]tags[]]`</$link>
-
-The following examples use the [[field Operator]] and [[compare Operator]] tiddlers and their respective tags.
-
-<<.operator-example 1 "[[field Operator]tags[]]">>
-<<.operator-example 2 "[[compare Operator]tags[]]">>
-
-<<.operator-example 3 "[[field Operator]tags[]] +[[compare Operator]tags[]]" """The "field Operator" tiddler's tags are lost, so only the "compare Operator" tiddler's tags are returned""">>
-
-<<.operator-example 4 "[[field Operator]tags[]] :intersection[[compare Operator]tags[]]" """Returns the tags that both tiddlers have in common""">>
+See [[Intersection Filter Run Prefix (Examples)]]
 
 !! `:reduce` examples
 
-```
-[tag[shopping]] :reduce[get[quantity]add<accumulator>]
-```
-
-is equivalent to:
-
-```
-\define num-items() [get[quantity]add<accumulator>]
-
-[tag[shopping]reduce<num-items>]
-```
-
-Specifying a default value when input is empty:
+See [[Reduce Filter Run Prefix (Examples)]]
 
-`[tag[non-existent]] :reduce[get[price]multiply{!!quantity}add<accumulator>] :else[[0]]`
+!! `:sort` examples
 
-<$macrocall $name=".tip" _="""Unlike the [[reduce Operator]], the `:reduce` prefix cannot specify an initial value for the accumulator, so its initial value will always be empty (which is treated as 0 by mathematical operators). So `=1 =2 =3 :reduce[multiply<accumulator>]` will produce 0, not 6. If you need to specify an initial accumulator value, use the [[reduce Operator]]."""/>
+See [[Sort Filter Run Prefix (Examples)]]