From 2f86779a2774457daf6bb25720ac03df451adf60 Mon Sep 17 00:00:00 2001 From: btheado Date: Wed, 24 Nov 2021 15:02:40 -0500 Subject: [PATCH] Add doc tiddlers for reduce filter run prefix functionality (#6277) * Added documentation tiddlers for reduce filter run prefix * Make filter text box wider so long filters fit better * removed some duplicate words * Restored the :reduce filter run prefix tip --- .../filters/syntax/Filter Expression.tid | 4 +- .../syntax/Filter Run Prefix (Examples).tid | 20 +--------- .../Reduce Filter Run Prefix (Examples).tid | 27 +++++++++++++ .../syntax/Reduce Filter Run Prefix.tid | 38 +++++++++++++++++++ .../tw5.com/tiddlers/system/doc-styles.tid | 4 +- 5 files changed, 71 insertions(+), 22 deletions(-) create mode 100644 editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix (Examples).tid create mode 100644 editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix.tid diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid index fb621743b..e0d6c0d6a 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid @@ -1,5 +1,5 @@ created: 20150124182421000 -modified: 20210618153333369 +modified: 20211124193218807 tags: [[Filter Syntax]] title: Filter Expression type: text/vnd.tiddlywiki @@ -25,7 +25,7 @@ If a run has: * 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">> * 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">> * 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. diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid index 970bcc434..d68342d66 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid @@ -1,5 +1,5 @@ created: 20201117073343969 -modified: 20210428084013109 +modified: 20211124153029405 tags: [[Filter Syntax]] [[Filter Run Prefix Examples]] title: Filter Run Prefix (Examples) type: text/vnd.tiddlywiki @@ -27,23 +27,7 @@ The following examples use the [[field Operator]] and [[compare Operator]] tiddl !! `:reduce` examples -``` -[tag[shopping]] :reduce[get[quantity]add] -``` - -is equivalent to: - -``` -\define num-items() [get[quantity]add] - -[tag[shopping]reduce] -``` - -Specifying a default value when input is empty: - -`[tag[non-existent]] :reduce[get[price]multiply{!!quantity}add] :else[[0]]` - -<$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]` will produce 0, not 6. If you need to specify an initial accumulator value, use the [[reduce Operator]]."""/> +See [[Reduce Filter Run Prefix (Examples)]] !! `:sort` examples diff --git a/editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix (Examples).tid b/editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix (Examples).tid new file mode 100644 index 000000000..c88472216 --- /dev/null +++ b/editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix (Examples).tid @@ -0,0 +1,27 @@ +created: 20211124151912931 +modified: 20211124160747921 +tags: [[Filter Syntax]] [[Reduce Filter Run Prefix]] [[Filter Run Prefix Examples]] +title: Reduce Filter Run Prefix (Examples) +type: text/vnd.tiddlywiki + +\define multiply-input() [multiply] + +The following examples use these data tiddlers: + +
    +<$list filter="[tag[shopping]!has[draft.of]]"> +
  • +''<$link><$text text=<>/>'' quantity: <$text text={{!!quantity}}/>, price: <$text text={{!!price}}/> +
    • + +
+ +<<.operator-example 1 "[tag[shopping]] :reduce[get[quantity]add]">> +<<.operator-example 2 "[tag[shopping]] :reduce[get[price]multiply{!!quantity}add]">> +<<.operator-example 3 "[tag[shopping]] :reduce[compare:number:gt[0]thenaddsuffix[, ]addsuffixelse]" "Uses `` to act differently on the first item than the rest. Just for demonstration. Better to use the [[join Operator]] to accomplish this task">> +<<.operator-example 4 "[tag[non-existent]] :reduce[get[price]multiply{!!quantity}add]" "Empty input produces empty output">> +<<.operator-example 5 "[tag[non-existent]] :reduce[get[price]multiply{!!quantity}add] :else[[0]]" "Use `:else` to ensure output if input was empty">> + +<$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]` will produce 0, not 6. If you need to specify an initial accumulator value, use the [[reduce Operator]]."""/> +<<.operator-example 6 "=1 =2 =3 :reduce[multiply]" "Empty initial value is treated as 0 by mathematical operators">> +<<.operator-example 7 "=1 =2 =3 +[reduce,[1]]" "Setting initial value is sometimes necessary for correct results">> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix.tid b/editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix.tid new file mode 100644 index 000000000..3a9fd8a82 --- /dev/null +++ b/editions/tw5.com/tiddlers/filters/syntax/Reduce Filter Run Prefix.tid @@ -0,0 +1,38 @@ +created: 20211124151912931 +modified: 20211124170117511 +tags: [[Filter Syntax]] [[Filter Run Prefix]] +title: Reduce Filter Run Prefix +type: text/vnd.tiddlywiki + +<<.from-version "5.1.23">> + +|''purpose'' |replaces all filter output so far with a single item by repeatedly applying a filter run to each input title | +|''input'' |all titles from previous filter runs | +|''output''|the accumulated single item | + +Each input title from previous runs is passed to this run in turn. The result of each previous call to this run is made available in the next call via the variable named "accumulator". The result of the last call to this run is returned as the output. A typical use is to add up the values in a given field of each input title. + +The following variables are available within the filter run: + +* ''accumulator'' - the result of the previous filter run +* ''currentTiddler'' - the input title +* ''..currentTiddler'' - the value of the variable `currentTiddler` outside the filter run. <<.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 + +<<.tip "Compare named filter run prefix `:reduce` with [[reduce Operator]] which is used to flatten a list of items down to a single item by repeatedly applying a subfilter.">> + +``` +[tag[shopping]] :reduce[get[quantity]add] +``` + +is equivalent to: + +``` +\define num-items() [get[quantity]add] + +[tag[shopping]reduce] +``` + +[[Examples|Reduce Filter Run Prefix (Examples)]] \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/system/doc-styles.tid b/editions/tw5.com/tiddlers/system/doc-styles.tid index 679aadb43..b87f1f1f5 100644 --- a/editions/tw5.com/tiddlers/system/doc-styles.tid +++ b/editions/tw5.com/tiddlers/system/doc-styles.tid @@ -1,5 +1,5 @@ created: 20150117152612000 -modified: 20211105172548676 +modified: 20211124164948726 tags: $:/tags/Stylesheet title: $:/editions/tw5.com/doc-styles type: text/vnd.tiddlywiki @@ -112,7 +112,7 @@ td svg { } .doc-example input[type=search] { - width: 60%; + width: 95%; } .doc-example pre:first-child { margin-top: 0;