From a467ee0816d12f24a91f4c973dbac08bd68663ce Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Wed, 30 Jul 2025 14:52:13 +0100 Subject: [PATCH 1/6] Docs: Update to filter syntax history --- .../tiddlers/about/Filter Syntax History.tid | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/editions/tw5.com/tiddlers/about/Filter Syntax History.tid b/editions/tw5.com/tiddlers/about/Filter Syntax History.tid index b51a62f07a..05770d6533 100644 --- a/editions/tw5.com/tiddlers/about/Filter Syntax History.tid +++ b/editions/tw5.com/tiddlers/about/Filter Syntax History.tid @@ -4,15 +4,27 @@ modifier: Jeremy Ruston In response to [[a discussion|https://talk.tiddlywiki.org/t/filter-syntax-history/13058]] about the filter syntax in TiddlyWiki5 I posted this brief personal history. -For context, before TiddlyWikIi, I only had practical experience of a very small number of languages: machine code, assembly language, BASIC, FORTH, C, C++ and of course JavaScript. I had a smattering of Java, Pascal and one or two other ancient languages but no experience of actor based languages like Erlang, or modern functional languages. +For context, before TiddlyWiki, I only had practical experience of a very small number of languages: machine code, assembly language, BASIC, FORTH, C, C++ and of course JavaScript. I had a smattering of Java, Pascal and one or two other ancient languages but no experience of actor based languages like Erlang, or modern functional languages. -The story starts with the double square bracket syntax used in wikitext for links. In 2004 this was already an established usage in wikis. However, I switched the ordering of pretty links because I thought Wikipedia's `[[link address|link text]]` was the wrong way around. It broke up sentences: `The file is [[https://site.com/thing|here]]` seems less readable than `The file is [[here|https://site.com/thing]]`. For a long time I regretted this decision, and wished that I had just gone with Wikipedia's established usage. Others have since pointed out that TiddlyWiki's ordering is consistent with [[Markdown]]. +The story starts with the double square bracket syntax used in wikitext for links. In 2004 this was already an established usage in wikis. However, I switched the ordering of pretty links because I thought Wikipedia's `[[link address|link text]]` was the wrong way around. It broke up sentences: `The file is [[https://site.com/thing|here]]` seems less readable than `The file is [[here|https://site.com/thing]]`. For a long time I regretted this decision, and wished that I had just gone with Wikipedia's established usage. Others have since pointed out that TiddlyWiki's ordering is actually consistent with [[Markdown]], which might be regarded as the winner of the markup wars. -One way to look at the double square bracket link syntax is that it establishes a way to quote page/tiddler titles so that they may contain spaces, and don't have to use CamelCase. Thus, in TiddlyWiki Classic, when I was implementing the DefaultTiddlers feature it was natural to use double square brackets to quote titles containing spaces. +I looked at the double square bracket link syntax is that it establishes a way to quote page/tiddler titles so that they may contain spaces, and don't have to use CamelCase. Thus, right at the start of TiddlyWiki Classic when I was implementing the first iteration of the DefaultTiddlers feature it was natural to use double square brackets to quote titles containing spaces, making a list of titles to be opened at startup. -Then, when I was starting to think about TiddlyWiki 5 I wanted to extend the implementation of DefaultTiddlers so that more complex logic could be expressed while retaining backwards compatibility. A trick that I am apt to use in such situations is to try to engineer things so that the current behaviour is re-interpreted as a shortcut syntax for a new, richer syntax that provides more flexibility. In this case, the idea was that in filters we would interpret `[[mytiddler]]` as a shortcut for `[title[mytiddler]]`. Then we could put any keywords we like in place of "title", giving us an infinitely extensible syntax. A similar example is the way that we implemented filter run prefixes by retrospectively defining the absence of a prefix as implying a default prefix. +Soon, I wanted to extend the implementation of DefaultTiddlers so that it could be used to open all tiddlers with a particular tag while retaining backwards compatibility. -We implemented a very, very simple first version of the filter syntax in TiddlyWiki Classic that supported things like `[tag[mytag]]`, but it wasn't until TiddlyWiki 5 that it evolved into something approaching a programming language. As others have probably expressed much more eloquently, a characteristic of the programming languages that I love is that they start with a small number of principles that are consistently applied and combined. In the case of TiddlyWiki, the list would be very roughly: +A trick that I am apt to use in such situations is to try to engineer things so that the current behaviour is re-interpreted as a shortcut syntax for a new, richer syntax that provides more flexibility. In this case, the idea was that in filters we would interpret `[[mytiddler]]` as a shortcut for `[title[mytiddler]]`. Then we could put any keywords we like in place of "title", giving us an infinitely extensible syntax. A similar example is the way that we implemented filter run prefixes by retrospectively defining the absence of a prefix as implying a default prefix. + +The new syntax was first [introduced in 2007] (see [this commit](https://github.com/TiddlyWiki/TiddlyWikiClassic/commit/1928962ea6811b1ca67378ed3cd62059a9806ae9)), with a simplified syntax that only supported a single `tag` operator but was just about sufficient for intended purpose. The only documentation was a comment in the source code (complete with a typo): + +``` +// Filter a list of tiddlers +//# filter - filter expression (eg "tidlertitle [[multi word tiddler title]] [tag[systemConfig]]") +//# Returns an array of Tiddler() objects that match the filter expression +``` + +Provision to combine the filter operators had been on my mind from the beginning. When TiddlyWiki 5 started in 2011 I reused the simple implementation from TiddlyWiki Classic. Smashing operators [was finally implemented in May 2012](https://github.com/TiddlyWiki/TiddlyWiki5/commit/8b0703b694e982b2bc448bdb133742164723dd8a). By the time of the launch the filter language had grown into pretty much what it is today -- see the [documentation for TiddlyWiki v5.1.0](https://tiddlywiki.com/archive/full/TiddlyWiki-5.1.0#Introduction%20to%20Filters). + +The filter syntax had undoubtedly evolved into something approaching a programming language. As others have probably expressed much more eloquently, a characteristic of the programming languages that I love is that they start with a small number of principles that are consistently applied and combined. In the case of TiddlyWiki, the list would be very roughly: * Double square brackets for linking and quoting * Curly braces for transclusion From 3597e6542d47e0230306f670024d4c2c0f7bb623 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Wed, 30 Jul 2025 15:45:13 +0100 Subject: [PATCH 2/6] Docs: Update modified/created dates --- editions/tw5.com/tiddlers/about/Filter Syntax History.tid | 2 ++ editions/tw5.com/tiddlers/about/History of TiddlyWiki.tid | 3 ++- editions/tw5.com/tiddlers/about/The Story of TiddlyWiki.tid | 2 ++ editions/tw5.com/tiddlers/about/TiddlyWiki Anniversaries.tid | 2 ++ 4 files changed, 8 insertions(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/about/Filter Syntax History.tid b/editions/tw5.com/tiddlers/about/Filter Syntax History.tid index 05770d6533..a5fc669271 100644 --- a/editions/tw5.com/tiddlers/about/Filter Syntax History.tid +++ b/editions/tw5.com/tiddlers/about/Filter Syntax History.tid @@ -1,6 +1,8 @@ title: Filter Syntax History tags: [[History of TiddlyWiki]] modifier: Jeremy Ruston +created: 20250730154331065 +modified: 20250730154331065 In response to [[a discussion|https://talk.tiddlywiki.org/t/filter-syntax-history/13058]] about the filter syntax in TiddlyWiki5 I posted this brief personal history. diff --git a/editions/tw5.com/tiddlers/about/History of TiddlyWiki.tid b/editions/tw5.com/tiddlers/about/History of TiddlyWiki.tid index ca95216d40..80f9aeeb32 100644 --- a/editions/tw5.com/tiddlers/about/History of TiddlyWiki.tid +++ b/editions/tw5.com/tiddlers/about/History of TiddlyWiki.tid @@ -1,9 +1,10 @@ created: 20140908114400000 -modified: 20241016125145988 +modified: 20250730154331065 tags: About title: History of TiddlyWiki type: text/vnd.tiddlywiki + Here is a brief history of TiddlyWiki, its origins and its evolution since it was first released on 20th September 2004. Contributions and reminiscences are welcome. * [[The Story of TiddlyWiki]] – a personal account of the story of TiddlyWiki, its origins and evolution diff --git a/editions/tw5.com/tiddlers/about/The Story of TiddlyWiki.tid b/editions/tw5.com/tiddlers/about/The Story of TiddlyWiki.tid index 84e99e7d59..2af0fb4a69 100644 --- a/editions/tw5.com/tiddlers/about/The Story of TiddlyWiki.tid +++ b/editions/tw5.com/tiddlers/about/The Story of TiddlyWiki.tid @@ -1,6 +1,8 @@ title: The Story of TiddlyWiki tags: [[History of TiddlyWiki]] modifier: Jeremy Ruston +created: 20140908114400000 +modified: 20250730154331065 This is a personal account of the story of TiddlyWiki, its origins and its evolution since it was first released on 20th September 2004. diff --git a/editions/tw5.com/tiddlers/about/TiddlyWiki Anniversaries.tid b/editions/tw5.com/tiddlers/about/TiddlyWiki Anniversaries.tid index b9ccbbff2f..3ee1a9db70 100644 --- a/editions/tw5.com/tiddlers/about/TiddlyWiki Anniversaries.tid +++ b/editions/tw5.com/tiddlers/about/TiddlyWiki Anniversaries.tid @@ -1,5 +1,7 @@ title: TiddlyWiki Anniversaries tags: [[History of TiddlyWiki]] +created: 20250730154331065 +modified: 20250730154331065 ! Twentieth Anniversary of TiddlyWiki From 113eadf265b2ea07f1fd5894d29b384c3ee6ab94 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Thu, 31 Jul 2025 10:16:10 +0100 Subject: [PATCH 3/6] Fix filter run syntax diagram Thank you @CrossEye --- editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid index c5e9c8a345..aba77556e6 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid @@ -9,11 +9,11 @@ type: text/vnd.tiddlywiki \end none ( "[" { [[<"Filter Step">|"Filter Step"]] } "]" | - [:{/"anything but [ ] or whitespace"/}] + {[:/"anything but [ ] or whitespace"/]} | - '"' [:{/'anything but "'/}] '"' + '"' {[:/'anything but "'/]} '"' | - "'" [:{/"anything but '"/}] "'" + "'" {[:/"anything but '"/]} "'" ) """/> From 9617a6d6d85730b07f28290d9b29a624c2b2cf45 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Thu, 31 Jul 2025 10:49:33 +0100 Subject: [PATCH 4/6] Revert "Fix filter run syntax diagram" This reverts commit 113eadf265b2ea07f1fd5894d29b384c3ee6ab94. Apologies @CrossEye I hadn't seen #9204 --- editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid index aba77556e6..c5e9c8a345 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Run.tid @@ -9,11 +9,11 @@ type: text/vnd.tiddlywiki \end none ( "[" { [[<"Filter Step">|"Filter Step"]] } "]" | - {[:/"anything but [ ] or whitespace"/]} + [:{/"anything but [ ] or whitespace"/}] | - '"' {[:/'anything but "'/]} '"' + '"' [:{/'anything but "'/}] '"' | - "'" {[:/"anything but '"/]} "'" + "'" [:{/"anything but '"/}] "'" ) """/> From 4080268887c572ee056c5ccc627bf7945055bc04 Mon Sep 17 00:00:00 2001 From: Christian Byron <32885785+CeeBeeTree@users.noreply.github.com> Date: Tue, 5 Aug 2025 20:27:34 +1000 Subject: [PATCH 5/6] Update cla-individual.md (#9223) --- licenses/cla-individual.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/licenses/cla-individual.md b/licenses/cla-individual.md index be4743ccd6..04c76a59ef 100644 --- a/licenses/cla-individual.md +++ b/licenses/cla-individual.md @@ -625,3 +625,5 @@ Markus Sauermann, @Sauermann, 2025/06/20 @bobjoe12131, 2025/07/01 Ioannis Anthymidis (Ιωάννης Ανθυμίδης), @superuser-does, 2025/07/06 + +Christian Byron, @CeeBeeTree, 2025/08/05 From 23a23d9caccf8cc512ffdb34d51c50f3542c64bd Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Wed, 6 Aug 2025 11:53:31 +0200 Subject: [PATCH 6/6] [Docs] Fix Filter Step Railroad diagram (#9205) --- editions/tw5.com/tiddlers/filters/syntax/Filter Step.tid | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Step.tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Step.tid index 73b58524ad..12a4f44152 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Step.tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Step.tid @@ -1,5 +1,5 @@ created: 20150124182127000 -modified: 20230710074414361 +modified: 20250731101041336 tags: [[Filter Run]] title: Filter Step type: text/vnd.tiddlywiki @@ -11,10 +11,10 @@ In programming terms, it is akin to a function call to which the step's input is <$railroad text=""" \start none \end none -[:"!"] +["!"] ( / "if omitted, defaults to: title" /|: -( - | :[[operator|"Filter Operators"]] ) -{ [:":" [[suffix|"Filter Operators"]] ] } ) +( :[[operator|"Filter Operators"]] ) +[ {":" [: [[suffix|"Filter Operators"]] ] }] ) { [[parameter|"Filter Parameter"]] + "," } """/>