New Filter Operations in TW 5.1.23

[Atronoush]

There are some updates, big fixes and new features for filter operators and filter operations in TW 5.1.23. While Saq has added documentation for new features but some of them needs more examples and explanations. I hope Saq or other super users understand filters very good answer these questions for clarification

1. What is the difference between filter and subfilter operator? Why we need both of them?

2. Why filter named prefixes are used? See https://tiddlywiki.com/prerelease/#Filter%20Expression ?

 

3. What is the difference of else, ~ and :else ?

Do you recommend any good scripting style? If I am right, it seems you can do the same filter operation using different operator and this may be confusing for newbies like me!

--Atro

[Saq Imtiaz]

Filter vs subfilter

In the below example, if you replace  filter<myfilter> with subfilter<myfilter>, you will output the text length rather than the tiddler titles. Go ahead and try that on tiddlywiki.com

The filter operator allows you to limit the output according to the criteria provided by its operand, without changing the input. The most common use case for subfilter is to be able to use a  text reference or variable as a filter.

<$vars myfilter="[get[text]length[]compare:integer:gteq[1000]]">
<$list filter="[tag[HelloThere]search[po]filter<myfilter>]">
<div>
<$link>
<$text text=<<currentTiddler>>/>
</$link>
</div>
</$list>
</$vars>

Why named filter run prefixes?

Simply put because we were running out of characters to use every time we want to add a new run prefix that adds new functionality. Background here: https://github.com/Jermolene/TiddlyWiki5/issues/4888#issuecomment-716663427

else vs ~ vs :else
As explained in the link above, existing filter run prefixes have also been made available as named prefixes for consistency. So ~ and :else are identical. (Moving forwards I would personally transition to only using named run prefixes, with the other single character prefixes being there for backwards compatibility.)

As for else vs :else, the former is a filter operator and used within a filter run and represents a single filter step, whereas the latter is a filter run prefix.  

Filter runs:

https://tiddlywiki.com/#Filter%20Run

https://tiddlywiki.com/#Filter%20Expression

Filter operators and filter steps:

https://tiddlywiki.com/#Filter%20Step

https://tiddlywiki.com/#Filter%20Operators

else can be used as a filter step to output a fixed string, variable or text reference, if the filter run so far has produced no value. (In the below filter the portion "else[yes]" is a filter step, where as the entire line is a single filter run.)

[[HelloThere]is[missing]else[yes]]

:else can be used to run an entire new filter run if the previous filter runs have provided no output.

[[HelloThere]is[missing]get[text]] :else[{config}get[text]]

The above filter expression consists of two filter runs, the second has the prefix :else.

I hope this helps. It's a bit tricky to know what needs explanation as I personally do find the existing documentation on filter syntax quite good, if read carefully and in its entirety. Hopefully others can fill in if there are still things that are unclear.

PRs with documentation improvements are always welcome.

Cheers,
Saq

[Atronoush]

Hi Saq,

 Many thanks for explanation and your good TW scripting style (use named run prefix)!

 As you said one needs to do some experiments and write several examples to understand filters correctly!

 I will bookmark this post for future reference.

--Atro