From 6732d96f78d4ecde003a5d2e93696958dc25b8bd Mon Sep 17 00:00:00 2001 From: yaisog Date: Mon, 6 Mar 2023 17:14:08 +0100 Subject: [PATCH 1/6] Add a description and examples for "strict" results from getindex (#7333) * Add a description and examples for "strict" results * Add another example * Amend description of output with suffix "index" --- .../tiddlers/filters/examples/getindex.tid | 20 +++++++++++++++--- .../tw5.com/tiddlers/filters/getindex.tid | 21 +++++++++++-------- editions/tw5.com/tiddlers/filters/has.tid | 6 +++--- 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/examples/getindex.tid b/editions/tw5.com/tiddlers/filters/examples/getindex.tid index 780c09946..ca18bce84 100644 --- a/editions/tw5.com/tiddlers/filters/examples/getindex.tid +++ b/editions/tw5.com/tiddlers/filters/examples/getindex.tid @@ -1,8 +1,22 @@ created: 20150203140000000 -modified: 20170608150301791 +modified: 20230306140231272 tags: [[getindex Operator]] [[Operator Examples]] title: getindex Operator (Examples) type: text/vnd.tiddlywiki -<<.operator-example 1 "[[$:/palettes/Vanilla]getindex[background]]" "returns the value at index ''background'' of the [[DataTiddler|DataTiddlers]] [[$:/palettes/Vanilla]]">> -<<.operator-example 2 "[all[shadows+tiddlers]tag[$:/tags/Palette]getindex[background]]" "returns all background colors defined in any of the ColourPalettes">> \ No newline at end of file +<<.operator-example 1 "[[$:/palettes/Vanilla]getindex[background]]" "returns the value at index <<.value background>> of the [[DataTiddler|DataTiddlers]] [[$:/palettes/Vanilla]]">> +<<.operator-example 2 "[all[shadows+tiddlers]tag[$:/tags/Palette]getindex[background]]" "returns all background colors defined in any of the ColourPalettes">> + +[[ListopsData]] contains an empty index <<.value ~DataIndex>> which is not returned by the filter operator: +<<.operator-example 3 "[[ListopsData]getindex[DataIndex]]">> + +This filter expression can be used to return the value, even if it is an empty string: +<<.operator-example 4 "[[ListopsData]] :filter[has:index[DataIndex]] :and[getindex[DataIndex]else[]]">> + +There are 5 palettes which define the index <<.value diff-equal-background>>, but none defines a value: +<<.operator-example 5 "[all[shadows+tiddlers]tag[$:/tags/Palette]] :filter[has:index[diff-equal-background]] :map[getindex[diff-equal-background]else[]]">> +In the above example, the [[Map Filter Run Prefix]] is used instead of `:and` as it does not de-duplicate its results. + +Another way to check if an index has an empty value is to [[count|count Operator]] the results from the [[getindex Operator]]: +<<.operator-example 6 "[[$:/palettes/Vanilla]indexes[]] :filter[[$:/palettes/Vanilla]getindexcount[]compare:number:eq[0]]">> +Here, the input to `:filter` is the [[list of indexes|indexes Operator]] which are contained in [[$:/palettes/Vanilla]]. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/getindex.tid b/editions/tw5.com/tiddlers/filters/getindex.tid index 89ddabb83..03302cc6b 100644 --- a/editions/tw5.com/tiddlers/filters/getindex.tid +++ b/editions/tw5.com/tiddlers/filters/getindex.tid @@ -1,17 +1,20 @@ +caption: getindex created: 20150203140000000 -modified: 20150203140000000 +modified: 20230306131335009 +op-purpose: select all values of a data property in the input titles +op-input: a [[selection of titles|Title Selection]] +op-parameter: the name of a [[property|DataTiddlers]] +op-parameter-name: P +op-output: the values of property <<.place P>> in each of the input titles tags: [[Filter Operators]] [[Field Operators]] title: getindex Operator caption: getindex -op-purpose: select all values of a data property in the input titles - -<$macrocall $name=".operator-def" -input="a [[selection of titles|Title Selection]]" -parameter="the name of a [[property|DataTiddlers]]" -paramName="P" -output="the values of property <<.place P>> in each of the input titles" -/> Each input title is processed in turn, and is ignored if it does not denote a [[data tiddler|DataTiddlers]]. If the tiddler contains property <<.place P>>, the value of that property is [[dominantly appended|Dominant Append]] to the output. +<<.tip """If a data tiddler contains index <<.place P>> with an empty value, the empty string is not appended. The following [[Filter Expression]] can be used to also return an empty string +
:filter[has:index[P]] :and[getindex[P]else[]]
""">> + <<.operator-examples "getindex">> + + diff --git a/editions/tw5.com/tiddlers/filters/has.tid b/editions/tw5.com/tiddlers/filters/has.tid index cccb152ae..f05ae1e05 100644 --- a/editions/tw5.com/tiddlers/filters/has.tid +++ b/editions/tw5.com/tiddlers/filters/has.tid @@ -1,9 +1,9 @@ caption: has created: 20140410103123179 -modified: 20190518145446047 +modified: 20230306143207920 op-input: a [[selection of titles|Title Selection]] -op-neg-output: ''without suffix''
» those input tiddlers in which field <<.place F>> does <<.em not>> exist or has an empty value
''suffix `field`''
» those input tiddlers in which field <<.place F>> does <<.em not>> exist
''suffix `index`''
» those input tiddlers in which index <<.place F>> does <<.em not>> exist -op-output: ''without suffix''
» those input tiddlers in which field <<.place F>> has a non-empty value
''suffix `field`''
» those input tiddlers in which field <<.place F>> exists +op-neg-output: ''without suffix''
» those input tiddlers in which field <<.place F>> does <<.em not>> exist or has an empty value
''suffix `field`''
» those input tiddlers in which field <<.place F>> does <<.em not>> exist
''suffix `index`''
» those input data tiddlers in which index <<.place F>> does <<.em not>> exist +op-output: ''without suffix''
» those input tiddlers in which field <<.place F>> has a non-empty value
''suffix `field`''
» those input tiddlers in which field <<.place F>> exists
''suffix `index`''
» those input data tiddlers in which index <<.place F>> exists op-parameter: the name of a [[field|TiddlerFields]]
''suffix `index`''
» those input tiddlers in which index <<.place F>> exists op-parameter: the name of a [[field|TiddlerFields]] or, optionally an [[index|TextReference]] op-parameter-name: F From 2bac676ac4815ed06f497f4788df1ce800d5bfb7 Mon Sep 17 00:00:00 2001 From: yaisog Date: Tue, 7 Mar 2023 22:51:52 +0100 Subject: [PATCH 2/6] Docs: Align description with example (#7339) --- editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid b/editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid index 0762f14e0..2aadfe677 100644 --- a/editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid @@ -32,7 +32,7 @@ For example, the items "abc" and "123" can be appended to the field `myfield` us <$action-listops $field="myfield" $subfilter="abc 123"/> ``` -The same can be achieved using the `$filter` attribute and prepending the [[Filter Run]] `[all[current]get[myfield]enlist-input[]]` to the [[Filter Expression]]: +The same can be achieved using the `$filter` attribute and prepending the [[Filter Run]] `[enlist{!!myfield}]` to the [[Filter Expression]]: ``` <$action-listops $field="myfield" $filter="[enlist{!!myfield}] abc 123"/> From d8c2ab3bafe58b666b42f6a388ba88c30d41cc63 Mon Sep 17 00:00:00 2001 From: Michelle Saad Date: Wed, 8 Mar 2023 18:16:48 +0000 Subject: [PATCH 3/6] Sign CLA (#7342) --- licenses/cla-individual.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/licenses/cla-individual.md b/licenses/cla-individual.md index 744b5e133..6be49c5e0 100644 --- a/licenses/cla-individual.md +++ b/licenses/cla-individual.md @@ -525,3 +525,5 @@ Mateusz Wilczek, @mateuszwilczek, 2023/02/16 Andrea Octo, @andrigamerita, 2023/02/24 HuanC Fu, @hffqyd, 2023/03/03 + +Michelle Saad, @michsa, 2023-03-08 From 714587cdfcdd60de4409dbe8cfbf41698c6aa3cf Mon Sep 17 00:00:00 2001 From: yaisog Date: Fri, 10 Mar 2023 09:48:28 +0100 Subject: [PATCH 4/6] Improve documentation for get and getindex - Update descriptions and examples (#7349) --- .../tw5.com/tiddlers/filters/examples/get.tid | 16 ++++++++++--- .../tiddlers/filters/examples/getindex.tid | 23 ++++++++----------- editions/tw5.com/tiddlers/filters/get.tid | 16 ++++++------- .../tw5.com/tiddlers/filters/getindex.tid | 14 ++++------- 4 files changed, 36 insertions(+), 33 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/examples/get.tid b/editions/tw5.com/tiddlers/filters/examples/get.tid index c49d876d6..de56361cf 100644 --- a/editions/tw5.com/tiddlers/filters/examples/get.tid +++ b/editions/tw5.com/tiddlers/filters/examples/get.tid @@ -1,9 +1,19 @@ created: 20150118134611000 -modified: 20150124201839000 +modified: 20230309180521925 +myfield: tags: [[get Operator]] [[Operator Examples]] title: get Operator (Examples) type: text/vnd.tiddlywiki <<.operator-example 1 "[all[current]get[draft.of]]" "the title of the tiddler of which the current tiddler is a draft">> -<<.operator-example 2 "[get[tags]]">> -<<.operator-example 3 "[each[tags]get[tags]]">> + +<<.operator-example 2 "[get[tags]]" "returns the tags of all tiddlers without de-duplication">> + +<<.operator-example 3 "[get[tags]unique[]]" "returns the tags of all tiddlers with de-duplication">> + +<<.tip """If a data tiddler contains a field with an empty value, the empty string is not appended to the results.""">> + +<<.operator-example 4 "[all[current]get[myfield]]" "the empty value of field <<.field myfield>> is not returned by the <<.olink get>> operator">> + +<<.operator-example 5 "[all[current]] :filter[has:field[myfield]] :map[get[myfield]]" "also returns the empty string">> +The above example works by first using the [[Filter Filter Run Prefix]] to only select titles that have the field <<.field myfield>> and then using the [[Map Filter Run Prefix]] to replace those titles with their value of that field. The [[Map Filter Run Prefix]] outputs an empty string when its filter run returns an empty [[selection|Title Selection]]. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/examples/getindex.tid b/editions/tw5.com/tiddlers/filters/examples/getindex.tid index ca18bce84..beb52fc19 100644 --- a/editions/tw5.com/tiddlers/filters/examples/getindex.tid +++ b/editions/tw5.com/tiddlers/filters/examples/getindex.tid @@ -1,22 +1,19 @@ created: 20150203140000000 -modified: 20230306140231272 +modified: 20230309180501044 tags: [[getindex Operator]] [[Operator Examples]] title: getindex Operator (Examples) type: text/vnd.tiddlywiki -<<.operator-example 1 "[[$:/palettes/Vanilla]getindex[background]]" "returns the value at index <<.value background>> of the [[DataTiddler|DataTiddlers]] [[$:/palettes/Vanilla]]">> -<<.operator-example 2 "[all[shadows+tiddlers]tag[$:/tags/Palette]getindex[background]]" "returns all background colors defined in any of the ColourPalettes">> +<<.operator-example 1 "[[$:/palettes/Vanilla]getindex[background]]" "returns the value of property <<.value background>> of the [[DataTiddler|DataTiddlers]] [[$:/palettes/Vanilla]]">> -[[ListopsData]] contains an empty index <<.value ~DataIndex>> which is not returned by the filter operator: -<<.operator-example 3 "[[ListopsData]getindex[DataIndex]]">> +<<.operator-example 2 "[all[shadows+tiddlers]tag[$:/tags/Palette]getindex[background]]" "returns all background colors defined in any of the ColourPalettes (notice the duplicates in the resulting list)">> -This filter expression can be used to return the value, even if it is an empty string: -<<.operator-example 4 "[[ListopsData]] :filter[has:index[DataIndex]] :and[getindex[DataIndex]else[]]">> +<<.tip """If a data tiddler contains a property with an empty value, the empty string is not appended to the results.""">> -There are 5 palettes which define the index <<.value diff-equal-background>>, but none defines a value: -<<.operator-example 5 "[all[shadows+tiddlers]tag[$:/tags/Palette]] :filter[has:index[diff-equal-background]] :map[getindex[diff-equal-background]else[]]">> -In the above example, the [[Map Filter Run Prefix]] is used instead of `:and` as it does not de-duplicate its results. +<<.operator-example 3 "[[ListopsData]getindex[DataIndex]]" "the empty value of the property <<.field ~DataIndex>> in [[ListopsData]] is not returned by the <<.olink getindex>> operator">> -Another way to check if an index has an empty value is to [[count|count Operator]] the results from the [[getindex Operator]]: -<<.operator-example 6 "[[$:/palettes/Vanilla]indexes[]] :filter[[$:/palettes/Vanilla]getindexcount[]compare:number:eq[0]]">> -Here, the input to `:filter` is the [[list of indexes|indexes Operator]] which are contained in [[$:/palettes/Vanilla]]. \ No newline at end of file +<<.operator-example 4 "[[ListopsData]] :filter[has:index[DataIndex]] :map[getindex[DataIndex]]" "also returns the empty string">> +The above example works by first using the [[Filter Filter Run Prefix]] to only select titles that have the property <<.field ~DataIndex>> and then using the [[Map Filter Run Prefix]] to replace those titles with their value of that property. The [[Map Filter Run Prefix]] outputs an empty string when its filter run returns an empty [[selection|Title Selection]]. + +<<.operator-example 5 "[[$:/palettes/Vanilla]indexes[]] :filter[[$:/palettes/Vanilla]getindexcount[]compare:number:eq[0]]" "returns those colors in [[$:/palettes/Vanilla]] which are defined, but have no value assigned">> +In the above example, <<.olink count>> is used to check if <<.olink getindex>> returns a result (i.e. the corresponding property has a value) or not. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/get.tid b/editions/tw5.com/tiddlers/filters/get.tid index 8623aa6d6..818f1602f 100644 --- a/editions/tw5.com/tiddlers/filters/get.tid +++ b/editions/tw5.com/tiddlers/filters/get.tid @@ -1,17 +1,17 @@ +caption: get created: 20140426183123179 -modified: 20150203185001000 +modified: 20230309163844434 +op-input: a [[selection of titles|Title Selection]] +op-output: the values of field <<.place F>> in each of the input titles +op-parameter: the name of a [[field|TiddlerFields]] +op-parameter-name: F +op-purpose: select all values of a field in the input titles tags: [[Filter Operators]] [[Field Operators]] title: get Operator type: text/vnd.tiddlywiki -caption: get -op-purpose: select all values of a field in the input titles -op-input: a [[selection of titles|Title Selection]] -op-parameter: the name of a [[field|TiddlerFields]] -op-parameter-name: F -op-output: the values of field <<.place F>> in each of the input titles Each input title is processed in turn. If the corresponding tiddler contains field <<.place F>>, and the value of this field is not empty, then its value is appended to the output. -Unlike most other [[Filter Operators]], the [[selection|Title Selection]] output by <<.op get>> can contain duplicates. To avoid duplicates, use `each[F]get[F]`. +<<.tip "Unlike most other [[Filter Operators]], the [[selection|Title Selection]] output by <<.op get>> can contain duplicates. To avoid duplicates, use `get[F]unique[]`.">> <<.operator-examples "get">> diff --git a/editions/tw5.com/tiddlers/filters/getindex.tid b/editions/tw5.com/tiddlers/filters/getindex.tid index 03302cc6b..225a68252 100644 --- a/editions/tw5.com/tiddlers/filters/getindex.tid +++ b/editions/tw5.com/tiddlers/filters/getindex.tid @@ -1,20 +1,16 @@ caption: getindex created: 20150203140000000 -modified: 20230306131335009 -op-purpose: select all values of a data property in the input titles +modified: 20230309163838670 op-input: a [[selection of titles|Title Selection]] +op-output: the values of property <<.place P>> in each of the input titles op-parameter: the name of a [[property|DataTiddlers]] op-parameter-name: P -op-output: the values of property <<.place P>> in each of the input titles +op-purpose: select all values of a data property in the input titles tags: [[Filter Operators]] [[Field Operators]] title: getindex Operator -caption: getindex -Each input title is processed in turn, and is ignored if it does not denote a [[data tiddler|DataTiddlers]]. If the tiddler contains property <<.place P>>, the value of that property is [[dominantly appended|Dominant Append]] to the output. +Each input title is processed in turn, and is ignored if it does not denote a [[data tiddler|DataTiddlers]]. If the corresponding tiddler contains property <<.place P>>, and the value of this property is not empty, then its value is appended to the output. -<<.tip """If a data tiddler contains index <<.place P>> with an empty value, the empty string is not appended. The following [[Filter Expression]] can be used to also return an empty string -
:filter[has:index[P]] :and[getindex[P]else[]]
""">> +<<.tip "Unlike most other [[Filter Operators]], the [[selection|Title Selection]] output by <<.op getindex>> can contain duplicates. To avoid duplicates, use `getindex[P]unique[]`.">> <<.operator-examples "getindex">> - - From e6175227b229b8db1374b824da9dfa207d748c28 Mon Sep 17 00:00:00 2001 From: yaisog Date: Fri, 10 Mar 2023 16:57:51 +0100 Subject: [PATCH 5/6] Add another example for the `get` operator (#7351) --- editions/tw5.com/tiddlers/filters/examples/get.tid | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/examples/get.tid b/editions/tw5.com/tiddlers/filters/examples/get.tid index de56361cf..87655d0cb 100644 --- a/editions/tw5.com/tiddlers/filters/examples/get.tid +++ b/editions/tw5.com/tiddlers/filters/examples/get.tid @@ -1,5 +1,5 @@ created: 20150118134611000 -modified: 20230309180521925 +modified: 20230310154010278 myfield: tags: [[get Operator]] [[Operator Examples]] title: get Operator (Examples) @@ -16,4 +16,7 @@ type: text/vnd.tiddlywiki <<.operator-example 4 "[all[current]get[myfield]]" "the empty value of field <<.field myfield>> is not returned by the <<.olink get>> operator">> <<.operator-example 5 "[all[current]] :filter[has:field[myfield]] :map[get[myfield]]" "also returns the empty string">> -The above example works by first using the [[Filter Filter Run Prefix]] to only select titles that have the field <<.field myfield>> and then using the [[Map Filter Run Prefix]] to replace those titles with their value of that field. The [[Map Filter Run Prefix]] outputs an empty string when its filter run returns an empty [[selection|Title Selection]]. \ No newline at end of file +The above example works by first using the [[Filter Filter Run Prefix]] to only select titles that have the field <<.field myfield>> and then using the [[Map Filter Run Prefix]] to replace those titles with their value of that field. The [[Map Filter Run Prefix]] outputs an empty string when its filter run returns an empty [[selection|Title Selection]]. + +<<.operator-example 6 "[all[tiddlers]] :filter[get[created]compare:date:lt{HelloThere!!created}]" "return all tiddlers that are older than [[HelloThere]]">> +The above example demonstrates two different ways of accessing field values in filters: Use <<.olink get>> when the title is not known in advance as with the [[Filter Filter Run Prefix]] where <<.var currentTiddler>> is set to the current input title. Use a [[TextReference]] as an indirect [[Filter Parameter]] when the title is known. From 0a20c0810738862e83d30f38c0712436b7e27b14 Mon Sep 17 00:00:00 2001 From: "jeremy@jermolene.com" Date: Sun, 12 Mar 2023 15:49:37 +0000 Subject: [PATCH 6/6] Fix Typo Thanks @timp --- editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid b/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid index caffd063c..1a5a77d17 100644 --- a/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid +++ b/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid @@ -8,4 +8,4 @@ A JSON tiddler is a [[data tiddler|DataTiddlers]] containing a [[JSON|JavaScript Its [[ContentType]] is `application/json`. -The [[history list|$:/HistoryList]] is an of a JSON tiddler. +The [[history list|$:/HistoryList]] is an example of a JSON tiddler.