From ade1c40911db272d5d43122d933afba142db4e21 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Mon, 19 Jan 2015 19:37:26 +0000 Subject: [PATCH] Revise terminology around tiddler sets --- .../tiddlers/concepts/AbsoluteOperators.tid | 6 +-- .../tiddlers/concepts/DominantAppend.tid | 6 +-- .../tiddlers/concepts/FilterParameters.tid | 4 +- .../tw5.com/tiddlers/concepts/Filters.tid | 4 +- .../tw5.com/tiddlers/concepts/TiddlerSets.tid | 10 ---- .../tw5.com/tiddlers/concepts/TitleList.tid | 8 +-- .../tiddlers/concepts/TitleSelections.tid | 10 ++++ .../tw5.com/tiddlers/fields/ListField.tid | 4 +- .../tiddlers/filters/FilterOperators.tid | 6 +-- .../tw5.com/tiddlers/filters/FilterSyntax.tid | 10 ++-- .../tw5.com/tiddlers/filters/addprefix.tid | 16 +++--- .../tw5.com/tiddlers/filters/addsuffix.tid | 16 +++--- editions/tw5.com/tiddlers/filters/after.tid | 12 ++--- editions/tw5.com/tiddlers/filters/all.tid | 22 ++++---- .../tw5.com/tiddlers/filters/backlinks.tid | 6 +-- editions/tw5.com/tiddlers/filters/before.tid | 12 ++--- editions/tw5.com/tiddlers/filters/butlast.tid | 8 +-- .../tw5.com/tiddlers/filters/commands.tid | 4 +- editions/tw5.com/tiddlers/filters/each.tid | 6 +-- editions/tw5.com/tiddlers/filters/eachday.tid | 8 +-- .../tiddlers/filters/editiondescription.tid | 6 ++- .../tiddlers/filters/examples/indexes.tid | 8 +++ .../tw5.com/tiddlers/filters/examples/is.tid | 13 +++++ .../tiddlers/filters/examples/last.tid | 11 ++++ editions/tw5.com/tiddlers/filters/field.tid | 8 +-- editions/tw5.com/tiddlers/filters/fields.tid | 8 +-- editions/tw5.com/tiddlers/filters/first.tid | 8 +-- editions/tw5.com/tiddlers/filters/get.tid | 4 +- editions/tw5.com/tiddlers/filters/has.tid | 6 +-- editions/tw5.com/tiddlers/filters/indexes.tid | 23 +++++---- editions/tw5.com/tiddlers/filters/is.tid | 50 +++++++++++-------- editions/tw5.com/tiddlers/filters/last.tid | 22 ++++---- editions/tw5.com/tiddlers/howtos/Tagging.tid | 4 +- .../tiddlers/system/operator-macros.tid | 10 ++-- .../Creating journal tiddlers.tid | 4 +- 35 files changed, 207 insertions(+), 156 deletions(-) delete mode 100644 editions/tw5.com/tiddlers/concepts/TiddlerSets.tid create mode 100644 editions/tw5.com/tiddlers/concepts/TitleSelections.tid create mode 100644 editions/tw5.com/tiddlers/filters/examples/indexes.tid create mode 100644 editions/tw5.com/tiddlers/filters/examples/is.tid create mode 100644 editions/tw5.com/tiddlers/filters/examples/last.tid diff --git a/editions/tw5.com/tiddlers/concepts/AbsoluteOperators.tid b/editions/tw5.com/tiddlers/concepts/AbsoluteOperators.tid index 4c097d8f4..161c63691 100644 --- a/editions/tw5.com/tiddlers/concepts/AbsoluteOperators.tid +++ b/editions/tw5.com/tiddlers/concepts/AbsoluteOperators.tid @@ -1,11 +1,11 @@ created: 20150117204109000 -modified: 20150117204242000 +modified: 20150119190116000 tags: Concepts title: Absolute Operators type: text/vnd.tiddlywiki The output of a filter step depends on its [[operator|Filter Operators]]: -* Most operators perform <<.def relative>> to their input. They examine each input string in turn and filter out any that don't match. Such steps narrow down the output of a run. +* Most operators perform <<.def relative>> to their input. They examine each input title in turn and filter out any that don't match. Such steps narrow down the output of a run. -* <<.def Absolute>> operators ignore their input and generate an independent output instead. <<.olink title>> is an example: the result of `[title[A]title[B]]` is `B`. But the <<.olink field>> operator is relative, so the result of `[title[A]field:title[B]` is empty. \ No newline at end of file +* <<.def Absolute>> operators ignore their input and generate an independent output instead. <<.olink title>> is an example: the result of `[title[A]title[B]]` is `B`. But the <<.olink field>> operator is relative, so the result of `[title[A]field:title[B]` is empty. diff --git a/editions/tw5.com/tiddlers/concepts/DominantAppend.tid b/editions/tw5.com/tiddlers/concepts/DominantAppend.tid index 4b4bb9e3b..996cf9cf6 100644 --- a/editions/tw5.com/tiddlers/concepts/DominantAppend.tid +++ b/editions/tw5.com/tiddlers/concepts/DominantAppend.tid @@ -1,11 +1,11 @@ created: 20151714300000000 -modified: 20150117172438000 +modified: 20150119191515000 tags: Concepts title: Dominant Append type: text/vnd.tiddlywiki A <<.def "dominant append">> is a frequent occurrence in [[filter|Filters]] processing. -Filters manipulate sets of items in which no item can appear more than once, and they often append one such set to another. +Filters manipulate [[selections|Title Selections]] in which no title can appear more than once, and they often append one selection to another. -This is done in such a way that if the result would contain two copies of the same item, the <<.em earlier>> one is removed. The appended items thus dominate over any earlier duplicates. +This is done in such a way that if the result would contain two copies of the same title, the <<.em earlier>> one is removed. The appended titles thus dominate over any earlier duplicates. diff --git a/editions/tw5.com/tiddlers/concepts/FilterParameters.tid b/editions/tw5.com/tiddlers/concepts/FilterParameters.tid index f6e08ef4b..5bb828548 100644 --- a/editions/tw5.com/tiddlers/concepts/FilterParameters.tid +++ b/editions/tw5.com/tiddlers/concepts/FilterParameters.tid @@ -1,5 +1,5 @@ created: 20151714300000000 -modified: 20150117193508000 +modified: 20150119185917000 tags: Concepts title: Filter Parameters type: text/vnd.tiddlywiki @@ -12,7 +12,7 @@ The parameter to a [[filter operator|Filter Operators]] can be: ;<<.def indirect>> :<<.def transcluded>> :: `{like this}` -:: The value of a field of a specified tiddler, or the value of an index of a specified [[data tiddler|DataTiddlers]] +:: The value of a field of a specified tiddler, or the value of a property of a specified [[data tiddler|DataTiddlers]] :<<.def variable>> ::`` :: The value of the specified [[variable|Variables]] diff --git a/editions/tw5.com/tiddlers/concepts/Filters.tid b/editions/tw5.com/tiddlers/concepts/Filters.tid index 988ad840d..9bc5ed6bc 100644 --- a/editions/tw5.com/tiddlers/concepts/Filters.tid +++ b/editions/tw5.com/tiddlers/concepts/Filters.tid @@ -1,5 +1,5 @@ created: 20130827080000000 -modified: 20150117193502000 +modified: 20150119191522000 tags: Reference Concepts title: Filters type: text/vnd.tiddlywiki @@ -7,7 +7,7 @@ list: [[Introduction to filter notation]] [[Filter Syntax]] You can think of TiddlyWiki as a database in which 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. -A <<.def filter>> is a concise notation for selecting a particular [[set of tiddlers|Tiddler Sets]], known as its <<.def "output">>. Whenever ~TiddlyWiki encounters a filter, it calculates the output. Further work can then be done with just those tiddlers, such as [[counting|CountWidget]] or [[listing|ListWidget]] them. +A <<.def filter>> is a concise notation for selecting a particular [[set of tiddlers|Title Selections]], known as its <<.def "output">>. Whenever ~TiddlyWiki encounters a filter, it calculates the output. Further work can then be done with just those tiddlers, such as [[counting|CountWidget]] or [[listing|ListWidget]] them. 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: diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerSets.tid b/editions/tw5.com/tiddlers/concepts/TiddlerSets.tid deleted file mode 100644 index bac6c370f..000000000 --- a/editions/tw5.com/tiddlers/concepts/TiddlerSets.tid +++ /dev/null @@ -1,10 +0,0 @@ -created: 20150117152418000 -modified: 20150117165517000 -tags: Concepts -title: Tiddler Sets - -A <<.def "tiddler set">> is a data structure. It is an ordered collection of strings, usually tiddler titles, containing no duplicates. - -Tiddler sets are important in [[filter|Filters]] processing. - -The simplest way to generate one is to use the TitleList syntax. diff --git a/editions/tw5.com/tiddlers/concepts/TitleList.tid b/editions/tw5.com/tiddlers/concepts/TitleList.tid index 7c595da47..db459af15 100644 --- a/editions/tw5.com/tiddlers/concepts/TitleList.tid +++ b/editions/tw5.com/tiddlers/concepts/TitleList.tid @@ -1,9 +1,9 @@ created: 20150117152418000 -modified: 20150117163928000 +modified: 20150119191533000 tags: Concepts -title: TitleList +title: Title Lists -A <<.def "title list">> is a line of text that presents one or more tiddler titles, strung together with a space between each one and the next. +A <<.def "title list">> is a line of text that contians one or more tiddler titles, strung together with a space between each one and the next. If a title <<.em contains>> a space, it needs double square brackets around it: @@ -11,4 +11,4 @@ If a title <<.em contains>> a space, it needs double square brackets around it: Title lists are used in various places, including PermaLinks and the ListField. -They are in fact the simplest case of a [[filter|Filters]]. +They are in fact the simplest case of a [[filter|Filters]], and are thus a way of expressing a [[title selection|Title Selections]]. diff --git a/editions/tw5.com/tiddlers/concepts/TitleSelections.tid b/editions/tw5.com/tiddlers/concepts/TitleSelections.tid new file mode 100644 index 000000000..dee8a89e6 --- /dev/null +++ b/editions/tw5.com/tiddlers/concepts/TitleSelections.tid @@ -0,0 +1,10 @@ +created: 20150117152418000 +modified: 20150119191302000 +tags: Concepts +title: Title Selections + +A <<.def "title selection">> is an ordered set of tiddler titles (or similar strings), in which no title appears more than once. + +Title selections are important in [[filter|Filters]] processing. + +The simplest way to write one down is as a [[title list|Title Lists]]. diff --git a/editions/tw5.com/tiddlers/fields/ListField.tid b/editions/tw5.com/tiddlers/fields/ListField.tid index 511f83e0a..91eb5b17c 100644 --- a/editions/tw5.com/tiddlers/fields/ListField.tid +++ b/editions/tw5.com/tiddlers/fields/ListField.tid @@ -1,11 +1,11 @@ created: 20130830092500000 -modified: 20150117163423000 +modified: 20150119191334000 tags: Fields title: ListField caption: list type: text/vnd.tiddlywiki -The `list` [[field of a tiddler|TiddlerFields]] is an optional feature that can be used to help structure your content. It is defined as an [[ordered sequence of tiddler titles|TitleList]], and it can be used in several ways: +The `list` [[field of a tiddler|TiddlerFields]] is an optional feature that can be used to help structure your content. Its value is a [[title list|Title Lists]], and it can be used in several ways: * The `list` field of a tiddler that is being used as a tag determines the ordering of the tiddlers that carry that tag - see [[Tagging]] for details * The `list` [[filter|Filters]] selects the entries from a list diff --git a/editions/tw5.com/tiddlers/filters/FilterOperators.tid b/editions/tw5.com/tiddlers/filters/FilterOperators.tid index b81cb949c..b192bf5e0 100644 --- a/editions/tw5.com/tiddlers/filters/FilterOperators.tid +++ b/editions/tw5.com/tiddlers/filters/FilterOperators.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118180311000 +modified: 20150119190404000 tags: Concepts Filters title: Filter Operators type: text/vnd.tiddlywiki @@ -12,7 +12,7 @@ A <<.def "filter operator">> is a predefined name attached to an individual step Purpose Common -<$list filter="[tag[Filter Operators]]"> +<$list filter="[tag[Filter Operators]sort[]]"> <$link to={{!!title}}>{{!!caption}} {{!!purpose}} <$list filter="[all[current]tag[Common Operators]]">{{$:/core/images/done-button}} @@ -21,4 +21,4 @@ A <<.def "filter operator">> is a predefined name attached to an individual step A typical step is written as `[operator[parameter]]`, although not all of the operators need a [[parameter|Filter Parameters]]. -Most steps operate on a set of input items. For the exact rules, see [[Filter Syntax]]. +Most steps accept a [[selection|Selection]] of tiddler titles as their input. For the exact rules, see [[Filter Syntax]]. diff --git a/editions/tw5.com/tiddlers/filters/FilterSyntax.tid b/editions/tw5.com/tiddlers/filters/FilterSyntax.tid index 09c3e1126..5f49ad6e3 100644 --- a/editions/tw5.com/tiddlers/filters/FilterSyntax.tid +++ b/editions/tw5.com/tiddlers/filters/FilterSyntax.tid @@ -1,12 +1,12 @@ created: 20140210141217955 -modified: 20150117204215000 +modified: 20150119191956000 tags: Filters title: Filter Syntax type: text/vnd.tiddlywiki <<.preamble """[[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.""">> -A <<.def filter>> is a pipeline for transforming an <<.def input>> into an <<.def output>>. Both the input and the output are [[ordered sets|Tiddler Sets]] of strings, usually tiddler titles. +A <<.def filter>> is a pipeline for transforming an <<.def input>> into an <<.def output>>. Both the input and the output are [[ordered sets|Title Selections]] of tiddler titles or similar strings. Filters are built from smaller pieces, called ''runs'' and ''steps'', each of which also transforms an input to an output. @@ -19,10 +19,10 @@ Filters are built from smaller pieces, called ''runs'' and ''steps'', each of wh A filter starts with an empty output. Its runs are processed from left to right, progressively modifying the output. -A run's input is normally the set of all tiddler titles in the wiki (in no particular order), but the `+` prefix can change this. +A run's input is normally a list of all the non-shadow tiddler titles in the wiki (in no particular order). But the `+` prefix can change this. -* If a run has no `+` or `-` prefix, its output strings are [[dominantly appended|Dominant Append]] to the filter's output. -* If a run has a `-` prefix, its output strings are <<.em removed>> from the filter's output (if they were present). +* If a run has no `+` or `-` prefix, its output titles are [[dominantly appended|Dominant Append]] to the filter's output. +* If a run has a `-` prefix, its output titles are <<.em removed>> from the filter's output (if they were present). * If a run has a `+` prefix, it receives the filter's output so far as its input. The filter's output is then completely <<.em replaced>> by the run's output. Any subsequent run reverts to receiving all tiddler titles as its input, unless it too has a `+` prefix. In concise technical terms: diff --git a/editions/tw5.com/tiddlers/filters/addprefix.tid b/editions/tw5.com/tiddlers/filters/addprefix.tid index 5b692b951..f06ca4ca0 100644 --- a/editions/tw5.com/tiddlers/filters/addprefix.tid +++ b/editions/tw5.com/tiddlers/filters/addprefix.tid @@ -1,16 +1,16 @@ created: 20140410103123179 -modified: 20150118182915000 +modified: 20150119192731000 tags: [[Filter Operators]] [[String Operators]] title: addprefix Operator type: text/vnd.tiddlywiki caption: addprefix -purpose: extend each input item with a prefix +purpose: extend each input title with a prefix -<<.operator-def -input:"a [[set|Tiddler Sets]] of strings" -parameter:"a prefix to be added" -paramName:"p" -output:"a copy of the input, but with the prefix added to the start of each string" ->> +<$macrocall $name=".operator-def" +input="a [[title selection|Title Selections]]" +parameter="a prefix to be added" +paramName="p" +output="a copy of the input, but with <<.place p>> added to the start of each title" +/> <<.operator-examples "addprefix">> diff --git a/editions/tw5.com/tiddlers/filters/addsuffix.tid b/editions/tw5.com/tiddlers/filters/addsuffix.tid index 24a11c26b..a50f01051 100644 --- a/editions/tw5.com/tiddlers/filters/addsuffix.tid +++ b/editions/tw5.com/tiddlers/filters/addsuffix.tid @@ -1,16 +1,16 @@ created: 20140828133830424 -modified: 20150118182957000 +modified: 20150119192734000 tags: [[Filter Operators]] [[String Operators]] title: addsuffix Operator type: text/vnd.tiddlywiki caption: addsuffix -purpose: extend each input item with a suffix +purpose: extend each input title with a suffix -<<.operator-def -input:"a [[set|Tiddler Sets]] of strings" -parameter:"a suffix to be added" -paramName:"p" -output:"a copy of the input, but with the suffix added to the end of each string" ->> +<$macrocall $name=".operator-def" +input="a [[title selection|Title Selections]]" +parameter="a suffix to be added" +paramName="p" +output="a copy of the input, but with <<.place p>> added to the end of each title" +/> <<.operator-examples "addsuffix">> diff --git a/editions/tw5.com/tiddlers/filters/after.tid b/editions/tw5.com/tiddlers/filters/after.tid index 0ac8a6a42..1dba30173 100644 --- a/editions/tw5.com/tiddlers/filters/after.tid +++ b/editions/tw5.com/tiddlers/filters/after.tid @@ -1,18 +1,18 @@ created: 20140512103123179 -modified: 20150118183000000 +modified: 20150119192331000 tags: [[Filter Operators]] [[List Operators]] title: after Operator type: text/vnd.tiddlywiki caption: after -purpose: get the successor of an input item +purpose: get the title that follows a particular one in the input <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of strings" -parameter="one of those strings" +input="a [[title selection|Title Selections]]" +parameter="one of those titles" paramName="p" -output="the string that immediately follows <<.place p>> in the input set" +output="the title that immediately follows <<.place p>> in the input" /> -If <<.place p>> is not present in the input set, or is the last item, then the output is empty. +If <<.place p>> is not present in the input, or is the last item there, then the output is empty. <<.operator-examples "after">> diff --git a/editions/tw5.com/tiddlers/filters/all.tid b/editions/tw5.com/tiddlers/filters/all.tid index 327e179eb..ed08432f8 100644 --- a/editions/tw5.com/tiddlers/filters/all.tid +++ b/editions/tw5.com/tiddlers/filters/all.tid @@ -1,6 +1,6 @@ created: 20140410103123179 -modified: 20150118183004000 -tags: [[Filter Operators]] [[Common Operators]] [[Absolute Operators]] [[Link Operators]] +modified: 20150119191633000 +tags: [[Filter Operators]] [[Common Operators]] [[Absolute Operators]] [[Category Operators]] title: all Operator type: text/vnd.tiddlywiki caption: all @@ -10,24 +10,26 @@ purpose: get all tiddlers of a basic category input="ignored, unless <<.place p>> is empty" parameter="see below" paramName="p" -output="the [[set|Tiddler Sets]] of tiddler titles that belong to one or more basic categories" +output="the complete [[selection|Title Selections]] of tiddler titles that belong to one or more basic categories" /> -The parameter specifies categories using the following syntax: +The parameter specifies tiddler categories using the following syntax: <$railroad text=""" [{: ("current" | "missing" |: "orphans" | "shadows" | "tiddlers" ) +"+" }] """/> |!Category |!Members |!Sorted | -|^`current`|just the [[current tiddler|CurrentTiddler]]|^--| -|^`missing`|all non-existent tiddlers to which there is at least one [[observable link|Observable Links]]|^no| -|^`orphans`|all tiddlers to which there are <<.em no>> observable links|^by title| -|^`shadows`|all the [[shadow tiddlers|ShadowTiddlers]] that exist, including any that have been overridden with non-shadow tiddlers|^no| -|^`tiddlers`|all the non-shadow tiddlers that exist|no| +|^`current` |just the [[current tiddler|CurrentTiddler]] |^-- | +|^`missing` |all non-existent tiddlers to which there is at least one [[observable link|Observable Links]] |^no | +|^`orphans` |all tiddlers to which there are <<.em no>> observable links |^by title | +|^`shadows` |all the [[shadow tiddlers|ShadowTiddlers]] that exist, including any that have been overridden with non-shadow tiddlers |^no | +|^`tiddlers` |all the non-shadow tiddlers that exist |no | -If the parameter specifies more than one category, they are processed from left to right. The overall output is initially empty, and each parameter's output is [[dominantly appended|Dominant Append]] to it in turn. +If the parameter specifies more than one category, they are processed from left to right. The overall output is initially empty, and each category's output is [[dominantly appended|Dominant Append]] to it in turn. Unrecognised categories contribute nothing to the output. As a special case, if there is no parameter, the output is simply a copy of the input. This can be useful when the parameter is [[supplied indirectly|Filter Parameters]]. +The <<.op is>> operator is similar, but its scope is restricted to its input tiddlers. + <<.operator-examples "all">> diff --git a/editions/tw5.com/tiddlers/filters/backlinks.tid b/editions/tw5.com/tiddlers/filters/backlinks.tid index 7e47e73ef..5a5161ebf 100644 --- a/editions/tw5.com/tiddlers/filters/backlinks.tid +++ b/editions/tw5.com/tiddlers/filters/backlinks.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118183008000 +modified: 20150119192416000 tags: [[Filter Operators]] [[Link Operators]] title: backlinks Operator type: text/vnd.tiddlywiki @@ -7,11 +7,11 @@ caption: backlinks purpose: get the tiddlers that link to each input tiddler <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[title selection|Title Selections]]" parameter="none" output="the titles of any non-system tiddlers that contain [[Observable Links]] to the input tiddlers" /> -Each input tiddler is processed in turn. Its corresponding set of backlinks is generated, sorted by title, and then [[dominantly appended|Dominant Append]] to the operator's overall output. +Each input tiddler is processed in turn. Its corresponding list of backlinks is generated, sorted by title, and then [[dominantly appended|Dominant Append]] to the operator's overall output. <<.operator-examples "backlinks">> diff --git a/editions/tw5.com/tiddlers/filters/before.tid b/editions/tw5.com/tiddlers/filters/before.tid index 5c8016779..2c4b38791 100644 --- a/editions/tw5.com/tiddlers/filters/before.tid +++ b/editions/tw5.com/tiddlers/filters/before.tid @@ -1,18 +1,18 @@ created: 20140512103123179 -modified: 20150118183011000 +modified: 20150119192411000 tags: [[Filter Operators]] [[List Operators]] caption: before title: before Operator type: text/vnd.tiddlywiki -purpose: get the predecessor of an input item +purpose: get the title that precedes a particular one in the input <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of strings" -parameter="one of those strings" +input="a [[title selection|Title Selections]]" +parameter="one of those titles" paramName="p" -output="the string that immediately precedes <<.place p>> in the input set" +output="the title that immediately precedes <<.place p>> in the input" /> -If <<.place p>> is not present in the input set, or is the first item, then the output is empty. +If <<.place p>> is not present in the input, or is the first title there, then the output is empty. <<.operator-examples "before">> diff --git a/editions/tw5.com/tiddlers/filters/butlast.tid b/editions/tw5.com/tiddlers/filters/butlast.tid index e4b297642..e9fdbf0a1 100644 --- a/editions/tw5.com/tiddlers/filters/butlast.tid +++ b/editions/tw5.com/tiddlers/filters/butlast.tid @@ -1,16 +1,16 @@ created: 20140410103123179 -modified: 20150118183022000 +modified: 20150119192424000 tags: [[Filter Operators]] [[Sequence Operators]] title: butlast Operator type: text/vnd.tiddlywiki caption: butlast -purpose: get all the but last <<.place n>> input items +purpose: get all the but last <<.place n>> input titles <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of strings" +input="a [[title selection|Title Selections]]" parameter="an integer, defaulting to 1" paramName="n" -output="all but the last <<.place n>> strings from the input set" +output="all but the last <<.place n>> titles from the input" /> <<.operator-examples "butlast">> diff --git a/editions/tw5.com/tiddlers/filters/commands.tid b/editions/tw5.com/tiddlers/filters/commands.tid index ae55ecbbe..4152f8266 100644 --- a/editions/tw5.com/tiddlers/filters/commands.tid +++ b/editions/tw5.com/tiddlers/filters/commands.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118183026000 +modified: 20150119191708000 tags: [[Filter Operators]] [[Non-Tiddler Operators]] [[Absolute Operators]] title: commands Operator type: text/vnd.tiddlywiki @@ -9,7 +9,7 @@ purpose: get all the Node.js commands <$macrocall $name=".operator-def" input="ignored" parameter="none" -output="the set of [[commands|Commands]] that can be given to [[TiddlyWiki on Node.js]]" +output="the [[selection|Title Selections]] of [[commands|Commands]] that can be given to [[TiddlyWiki on Node.js]]" /> <<.operator-examples "commands">> diff --git a/editions/tw5.com/tiddlers/filters/each.tid b/editions/tw5.com/tiddlers/filters/each.tid index 2dc69b024..b6c15b1d5 100644 --- a/editions/tw5.com/tiddlers/filters/each.tid +++ b/editions/tw5.com/tiddlers/filters/each.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118183030000 +modified: 20150119192427000 tags: [[Filter Operators]] [[Group Operators]] title: each Operator type: text/vnd.tiddlywiki @@ -7,10 +7,10 @@ caption: each purpose: get one of each group of input tiddlers by field value <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[title selection|Title Selections]]" parameter="the name of a [[field|TiddlerFields]]" paramName="f" -output="a set containing the first tiddler with each distinct value for field <<.place f>>" +output="a [[selection|Title Selections]] containing the first tiddler found with each distinct value for field <<.place f>>" /> Each input tiddler is processed in turn. The value of field <<.place f>> in that tiddler is examined, and as long as the value has not been encountered before, the tiddler's title is appended to the output set. diff --git a/editions/tw5.com/tiddlers/filters/eachday.tid b/editions/tw5.com/tiddlers/filters/eachday.tid index 4800f8b07..86fb3659d 100644 --- a/editions/tw5.com/tiddlers/filters/eachday.tid +++ b/editions/tw5.com/tiddlers/filters/eachday.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118183035000 +modified: 20150119192430000 tags: [[Filter Operators]] [[Group Operators]] title: eachday Operator type: text/vnd.tiddlywiki @@ -7,12 +7,12 @@ caption: eachday purpose: get one of each group of input tiddlers by date <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[selection|Title Selections]] of tiddler titles" parameter="the name of a [[date field|DateFields]]" paramName="f" -output="a set containing the first tiddler with each distinct value (ignoring time of day) for field <<.place f>>" +output="a [[selection|Title Selections]] containing the first tiddler found with each distinct value (ignoring times of day) for field <<.place f>>" /> -Each input tiddler is processed in turn. The value of field <<.place f>> in that tiddler is examined, and as long as this indicates a day that has not been encountered before, the tiddler's title is appended to the output set. +Each input tiddler is processed in turn. The value of field <<.place f>> in that tiddler is examined, and as long as this indicates a date that has not been encountered before, the tiddler's title is appended to the output set. <<.operator-examples "eachday">> diff --git a/editions/tw5.com/tiddlers/filters/editiondescription.tid b/editions/tw5.com/tiddlers/filters/editiondescription.tid index 55c0c6d05..68c5b1401 100644 --- a/editions/tw5.com/tiddlers/filters/editiondescription.tid +++ b/editions/tw5.com/tiddlers/filters/editiondescription.tid @@ -1,5 +1,5 @@ created: 20150111145738451 -modified: 20150118183039000 +modified: 20150119192433000 tags: [[Filter Operators]] [[Non-Tiddler Operators]] [[Node.js Operators]] title: editiondescription Operator type: text/vnd.tiddlywiki @@ -7,9 +7,11 @@ caption: editiondescription purpose: get the descriptions of the input ~TiddlyWiki editions <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of ~TiddlyWiki edition names" +input="a [[selection|Title Selections]] of edition names" parameter="none" output="the description string of each edition in the input" /> +Each input title is processed in turn, ignoring any that is not the name of a ~TiddlyWiki edition. + <<.node-only-operator>> diff --git a/editions/tw5.com/tiddlers/filters/examples/indexes.tid b/editions/tw5.com/tiddlers/filters/examples/indexes.tid new file mode 100644 index 000000000..b60e14f5c --- /dev/null +++ b/editions/tw5.com/tiddlers/filters/examples/indexes.tid @@ -0,0 +1,8 @@ +created: 20150119125815000 +modified: 20150119191028000 +tags: [[indexes Operator]] [[Operator Examples]] +title: indexes Operator (Examples) +type: text/vnd.tiddlywiki + +<<.operator-example 1 "[{$:/palette}indexes[]sort[title]]" "all the colours defined in the current [[colour palette|ColourPalettes]]">> +<<.operator-example 2 "[[$:/HistoryList]indexes[]]" "integer output because the [[history list|$:/HistoryList]] is an array">> diff --git a/editions/tw5.com/tiddlers/filters/examples/is.tid b/editions/tw5.com/tiddlers/filters/examples/is.tid new file mode 100644 index 000000000..d81a9bf77 --- /dev/null +++ b/editions/tw5.com/tiddlers/filters/examples/is.tid @@ -0,0 +1,13 @@ +created: 20150119133413000 +modified: 20150119134652000 +tags: [[is Operator]] [[Operator Examples]] +title: is Operator (Examples) +type: text/vnd.tiddlywiki + +<<.operator-example 1 "[is[tag]]">> +<<.operator-example 2 "[!is[tag]]">> +<<.operator-example 3 "[all[shadows]!is[system]]" "shadow tiddlers that don't start with `$:/`">> +<<.operator-example 4 "[is[system]tag[$:/tags/Stylesheet]]" "system stylesheets">> +<<.operator-example 5 "[all[shadows]is[system]tag[$:/tags/Stylesheet]]" "shadow system stylesheets">> +<<.operator-example 6 "[is[shadow]]" "overridden shadow tiddlers">> +<<.operator-example 7 "[is[missing]]" "empty because its input contains only tiddlers that exist">> diff --git a/editions/tw5.com/tiddlers/filters/examples/last.tid b/editions/tw5.com/tiddlers/filters/examples/last.tid new file mode 100644 index 000000000..2aec8e58d --- /dev/null +++ b/editions/tw5.com/tiddlers/filters/examples/last.tid @@ -0,0 +1,11 @@ +created: 20150118134611000 +modified: 20150119182151000 +tags: [[last Operator]] [[Operator Examples]] +title: last Operator (Examples) +type: text/vnd.tiddlywiki + +<<.using-days-of-week>> + +<<.operator-example 1 "[list[Days of the Week]last[]]">> +<<.operator-example 2 "[list[Days of the Week]last[5]]">> +<<.operator-example 3 "[tag[Concepts]!sort[title]last[3]]">> diff --git a/editions/tw5.com/tiddlers/filters/field.tid b/editions/tw5.com/tiddlers/filters/field.tid index 8ac452321..215048838 100644 --- a/editions/tw5.com/tiddlers/filters/field.tid +++ b/editions/tw5.com/tiddlers/filters/field.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118183046000 +modified: 20150119192437000 tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] title: field Operator type: text/vnd.tiddlywiki @@ -7,12 +7,12 @@ caption: field purpose: filter the input tiddlers by field value <$macrocall $name=".operator-def-suffix" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[title selection|Title Selections]]" suffix="the name of a field" suffixName="f" parameter="a potential value for field <<.place f>>" paramName="p" -output="the subset of the input tiddlers in which field <<.place f>> has the value <<.place p>>" +output="the [[subselection|Title Selections]] of the input tiddlers in which field <<.place f>> has the value <<.place p>>" /> If <<.place p>> is empty, <<.op field>> will match both of the following: @@ -21,7 +21,7 @@ If <<.place p>> is empty, <<.op field>> will match both of the following: * tiddlers in which field <<.place f>> exists but has an empty value ;Negation -: `!field` outputs the subset of the input tiddlers in which field <<.place f>> does <<.em not>> have the value <<.place p>>. +: `!field` outputs the subselection of the input tiddlers in which field <<.place f>> does <<.em not>> have the value <<.place p>>. The [[Filter Syntax]] treats any unrecognised [[filter operator|Filter Operators]] as if it was the suffix to the <<.olink field>> operator. See the second example below. diff --git a/editions/tw5.com/tiddlers/filters/fields.tid b/editions/tw5.com/tiddlers/filters/fields.tid index 59854b39f..9f037fd86 100644 --- a/editions/tw5.com/tiddlers/filters/fields.tid +++ b/editions/tw5.com/tiddlers/filters/fields.tid @@ -1,5 +1,5 @@ created: 20140924115616653 -modified: 20150118183051000 +modified: 20150119192440000 tags: [[Filter Operators]] [[Field Operators]] title: fields Operator type: text/vnd.tiddlywiki @@ -7,11 +7,11 @@ caption: fields purpose: get all fields of the input tiddlers <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[selection|Title Selections]] of tiddler titles" parameter="none" -output="the [[set|Tiddler Sets]] of all field names contained in the input tiddlers" +output="the [[selection|Title Selections]] of all field names contained in the input tiddlers" /> -Each input item is processed in turn. Its set of field names is retrieved (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output. +Each input title is processed in turn. Its list of field names is retrieved (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output. <<.operator-examples "fields">> diff --git a/editions/tw5.com/tiddlers/filters/first.tid b/editions/tw5.com/tiddlers/filters/first.tid index 01f18a989..45011e60e 100644 --- a/editions/tw5.com/tiddlers/filters/first.tid +++ b/editions/tw5.com/tiddlers/filters/first.tid @@ -1,16 +1,16 @@ created: 20140410103123179 -modified: 20150118183055000 +modified: 20150119192443000 tags: [[Filter Operators]] [[List Operators]] title: first Operator type: text/vnd.tiddlywiki caption: first -purpose: get the first <<.place n>> input items +purpose: get the first <<.place n>> input titles <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of strings" +input="a [[selection|Title Selections]] of titles" parameter="an integer, defaulting to 1" paramName="n" -output="the first <<.place n>> items from the input set" +output="the first <<.place n>> titles from the input" /> <<.operator-examples "first">> diff --git a/editions/tw5.com/tiddlers/filters/get.tid b/editions/tw5.com/tiddlers/filters/get.tid index e7001bd62..d89ad6d37 100644 --- a/editions/tw5.com/tiddlers/filters/get.tid +++ b/editions/tw5.com/tiddlers/filters/get.tid @@ -1,5 +1,5 @@ created: 20140426183123179 -modified: 20150118183058000 +modified: 20150119192446000 tags: [[Filter Operators]] [[Field Operators]] title: get Operator type: text/vnd.tiddlywiki @@ -7,7 +7,7 @@ caption: get purpose: get the values of a field from all input tiddlers <$macrocall $name=".operator-def" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[selection|Title Selections]] of tiddler titles" parameter="the name of a [[field|TiddlerFields]]" paramName="f" output="the values of field <<.place f>> in each of the input tiddlers" diff --git a/editions/tw5.com/tiddlers/filters/has.tid b/editions/tw5.com/tiddlers/filters/has.tid index 2c766cfa7..ed13e935e 100644 --- a/editions/tw5.com/tiddlers/filters/has.tid +++ b/editions/tw5.com/tiddlers/filters/has.tid @@ -1,5 +1,5 @@ created: 20140410103123179 -modified: 20150118183102000 +modified: 20150119192449000 tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] title: has Operator type: text/vnd.tiddlywiki @@ -8,10 +8,10 @@ purpose: filter the input tiddlers by field existence <$macrocall $name=".operator-def" syntax="has[f]" -input="a [[set|Tiddler Sets]] of tiddler titles" +input="a [[selection|Title Selections]] of tiddler titles" parameter="the name of a field" paramName="f" -output="the subset of the input tiddlers that have a value in field <<.place f>>" +output="the [[subselection|Title Selections]] of the input tiddlers that have a value in field <<.place f>>" /> <<.op has>> filters out both of the following: diff --git a/editions/tw5.com/tiddlers/filters/indexes.tid b/editions/tw5.com/tiddlers/filters/indexes.tid index 5a54ef334..105974d41 100644 --- a/editions/tw5.com/tiddlers/filters/indexes.tid +++ b/editions/tw5.com/tiddlers/filters/indexes.tid @@ -1,14 +1,19 @@ created: 20140410103123179 -modified: 20140410103123179 -tags: Filters -title: FilterOperator: indexes -caption: indexes +modified: 20150119192453000 +tags: [[Filter Operators]] +title: indexes Operator type: text/vnd.tiddlywiki +caption: indexes +purpose: get all properties of the input data tiddlers -The ''indexes'' filter operator returns a list of all the property indexes found in the DataTiddlers in the current list. Tiddlers that are not DataTiddlers are ignored. +<$macrocall $name=".operator-def" +input="a [[selection|Title Selections]] of tiddler titles" +parameter="none" +output="the [[selection|Title Selections]] of all property names contained in the input data tiddlers" +/> -For example: +Each input title is processed in turn, and is ignored if it does not denote a [[data tiddler|DataTiddlers]]. The list of property names is retrieved from the data tiddler (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output. -|!Filter String |!Description | -|`[[MyData]indexes[]]` |Returns the indexes of all properties in the data tiddler `MyData` | -|`[{$:/palette}indexes[]sort[title]]` |Returns the names of all the colours defined in the current [[colour palette|ColourPalettes]] | +Where a tiddler's [[content is JSON|JSONTiddlers]] with an array as its root, the <<.op indexes>> operator retrieves a selection of integer indexes instead. + +<<.operator-examples "indexes">> diff --git a/editions/tw5.com/tiddlers/filters/is.tid b/editions/tw5.com/tiddlers/filters/is.tid index 2e9a21e15..5269acf04 100644 --- a/editions/tw5.com/tiddlers/filters/is.tid +++ b/editions/tw5.com/tiddlers/filters/is.tid @@ -1,29 +1,37 @@ created: 20140410103123179 -modified: 20150118182931000 -tags: Filters CommonFilters -caption: is +modified: 20150119192457000 +tags: [[Filter Operators]] [[Common Operators]] [[Category Operators]] title: is Operator type: text/vnd.tiddlywiki +caption: is +purpose: filter the input tiddlers by basic category -The ''is'' filter operator selects tiddlers from the current list according to their membership of the category specified in the operand: +<$macrocall $name=".operator-def" +input="a [[selection|Title Selections]] of titles" +parameter="see below" +paramName="p" +output="the [[subselection|Title Selections]] of the input tiddlers that belong to the specified basic category" +/> -* `[is[current]]` - returns any tiddler that matches the title of the current tiddler -* `[is[image]]` - tiddlers that contain an image (eg, GIF, JPEG, PNG etc.) -* `[is[missing]]` - MissingTiddlers that are referenced but undefined -* `[is[orphan]]` - OrphanTiddlers that are not referenced from any other tiddler -* `[is[shadow]]` - tiddlers that are ShadowTiddlers -* `[is[system]]` - tiddlers that are SystemTiddlers -* `[is[tiddler]]` - tiddlers that are not MissingTiddlers -* `[is[tag]]` - tiddlers that are being used as tags +The parameter is one of the following categories: -For example: +|!Category |!Matches any tiddler that... | +|^`current`|is the [[current tiddler|CurrentTiddler]] | +|^`image`|has an image ContentType | +|^`missing` |does not exist (other than possibly as a non-shadow tiddler), regardless of whether there are any links it | +|^`orphan` |has no [[Observable Links]] to it | +|^`shadow` |is a [[shadow tiddler|ShadowTiddlers]], regardless of whether it has been overridden with a non-shadow tiddler | +|^`system` |is a [[system tiddler|SystemTiddlers]], i.e. its title starts with `$:/` | +|^`tag` |is in use as a tag | +|^`tiddler` |exists as a non-shadow tiddler | -|!Filter String |!Description | -|`[tag[task]is[shadow]]` |Returns ShadowTiddlers tagged `task` | -|`[tag[task]!is[system]]` |Returns non-SystemTiddlers tagged `task` | -|`[is[shadow]]` |Returns ShadowTiddlers that have been overridden by a 'real' tiddler | -|`[!is[shadow]]` |Returns ordinary tiddlers that are not shadow tiddlers | -|`[!is[tag]]` |Returns all tiddlers that are not being used as tags | -|`[is[missing]]` |Returns an empty list (see note below) | +;Negation +: `!is` outputs the subselection of the input tiddlers that are <<.em not>> in the specified category. `!is[tiddler]` is a synonym for `is[missing]`, and vice versa. -Note that the ''is'' filter operator strictly filters the current list by choosing whether or not to include each one in the output. It never adds tiddlers to the results that are not already listed. This means that when used at the start of a run of filter operators the ''is'' operator will be choosing from the currently existing tiddlers, and so will never return missing tiddlers, or shadow tiddlers that haven't been overridden. +An unrecognised category outputs an error string. + +When <<.op is[missing]>> is the first operator in a [[run|Filter Syntax]], its output is always empty. And when <<.op is[shadow]>> comes first, it outputs only those shadow tiddlers that have been overridden. This is because the [[initial input to a run|Filter Syntax]] contains only <<.em non>>-shadow tiddlers. + +The <<.op all>> operator is similar, but its scope is the whole wiki. + +<<.operator-examples "is">> diff --git a/editions/tw5.com/tiddlers/filters/last.tid b/editions/tw5.com/tiddlers/filters/last.tid index 20459fd68..0a993eb9d 100644 --- a/editions/tw5.com/tiddlers/filters/last.tid +++ b/editions/tw5.com/tiddlers/filters/last.tid @@ -1,14 +1,16 @@ created: 20140410103123179 -modified: 20140410103123179 -tags: Filters -caption: last -title: FilterOperator: last +modified: 20150119192502000 +tags: [[Filter Operators]] [[List Operators]] +title: last Operator type: text/vnd.tiddlywiki +caption: last +purpose: get the last <<.place n>> input titles -The ''last'' filter operator returns the last entries in the current list. The optional operand specifies the number of entries to return. +<$macrocall $name=".operator-def" +input="a [[selection|Title Selections]] of titles" +parameter="an integer, defaulting to 1" +paramName="n" +output="the last <<.place n>> titles from the input" +/> -For example: - -|!Filter String |!Description | -|`one two three +[last[]]` |Returns `three` | -|`one two three +[last[2]]` |Returns `two`, `three` | +<<.operator-examples "last">> diff --git a/editions/tw5.com/tiddlers/howtos/Tagging.tid b/editions/tw5.com/tiddlers/howtos/Tagging.tid index 12a6edb27..158ad7fe7 100644 --- a/editions/tw5.com/tiddlers/howtos/Tagging.tid +++ b/editions/tw5.com/tiddlers/howtos/Tagging.tid @@ -1,5 +1,5 @@ created: 20140904075400000 -modified: 20150118182337000 +modified: 20150119191356000 tags: [[Working with TiddlyWiki]] Concepts title: Tagging type: text/vnd.tiddlywiki @@ -35,7 +35,7 @@ You can use the [[tag manager|$:/TagManager]], found on the ''Tags'' tab under ' By default, tagged tiddlers are listed in the order they were added to the wiki. The <<.olink sort>> operator can change the order to alphabetical. -If you want any other order, add a [[field called ''list''|ListField]] to the tag tiddler, and set its value to be a [[TitleList]] of the tiddlers in that order. +If you want any other order, add a [[field called ''list''|ListField]] to the tag tiddler, and set its value to be a [[list of the tiddlers|Title Lists]] in that order. The ''list'' field doesn't have to mention all of the tiddlers. Here are the precise rules ~TiddlyWiki uses to order tagged tiddlers: diff --git a/editions/tw5.com/tiddlers/system/operator-macros.tid b/editions/tw5.com/tiddlers/system/operator-macros.tid index 30e281cd5..55ab81cb4 100644 --- a/editions/tw5.com/tiddlers/system/operator-macros.tid +++ b/editions/tw5.com/tiddlers/system/operator-macros.tid @@ -1,5 +1,5 @@ created: 20150117152607000 -modified: 20150118181923000 +modified: 20150119193041000 title: $:/editions/tw5.com/operator-macros tags: $:/tags/Macro @@ -8,7 +8,7 @@ tags: $:/tags/Macro input $input$ -parameter <<.place "$paramName$">> +parameter<$macrocall $name=".if" cond="$paramName$" then=" <<.place '$paramName$'>>"/> $parameter$ output @@ -21,10 +21,10 @@ tags: $:/tags/Macro input $input$ -suffix <<.place "$suffixName$">> +suffix <<.place "$suffixName$">> $suffix$ -parameter <<.place "$paramName$">> +parameter<$macrocall $name=".if" cond="$paramName$" then=" <<.place '$paramName$'>>"/> $parameter$ output @@ -37,7 +37,7 @@ tags: $:/tags/Macro \define .operator-example(n,eg,ie)
`$eg$` -<<.if cond:"$ie$" then:"
i.e. $ie$
">> +<<.if cond:"$ie$" then:"
$ie$
">> <$list filter="[title<.state-prefix>addsuffix{!!title}addsuffix[/]addsuffix[$n$]]" variable=".state"> <$reveal state=<<.state>> type="nomatch" text="show">
diff --git a/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid b/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid index 47f87b23d..495b3c5fd 100644 --- a/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid +++ b/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid @@ -1,5 +1,5 @@ created: 20141010093214683 -modified: 20141125123700243 +modified: 20150119191403000 tags: [[Working with TiddlyWiki]] title: Creating journal tiddlers type: text/vnd.tiddlywiki @@ -29,7 +29,7 @@ For example, you might be reviewing a tiddler called ''Oxford Street'' and reali To configure how new journal entries are created, visit the ''Basics'' tab under ''Info'' in the [[control panel|$:/ControlPanel]]: * "Title of new journal tiddlers" specifies how these tiddlers should be named, as a [[date format string|DateFormat]]. The default setting of `DDth MMM YYYY` causes new entries to have titles of the form "10th October 2014" -* "Tags for new journal tiddlers" [specifies|TitleList] tags that will automatically appear on new journal entries. For example: `Journal [[Summer vacation]]` +* "Tags for new journal tiddlers" [specifies|Title Lists] tags that will automatically appear on new journal entries. For example: `Journal [[Summer vacation]]` Hint: if you want to create a separate journal tiddler whenever you click ''new journal'' (even if you do this several times in the same day), you can include the clock time in the title format. Specify something like `YYYY-0MM-0DD at 0hhh0mm'0ss''` as the date format.