Map Filter Run Prefix (Examples): TiddlyWiki Pre-release

Map Filter Run Prefix (Examples)

5th March 2023 at 12:54pm

Replace the input titles with the caption field if it exists, otherwise preserve the input title:

[tag[Widgets]] :map[get[caption]else{!!title}]

Tip

The above example is equivalent to [tag[Widgets]] :map[{!!caption}!is[blank]else{!!title}]. Note that referencing a field as a text reference such as {!!caption} returns an empty string for a non-existent or empty caption field. Therefore a check for is[blank] is needed before the else operator

For each title in a shopping list, calculate the total cost of purchasing each item:

[tag[shopping]] :map[get[quantity]else[0]multiply{!!price}]

Get the tags of all tiddlers tagged Widget:

[tag[Widgets]] :map:flat[tagging[]] :and[!is[blank]unique[]]

Tip

Without the flat suffix the :map filter run only returns the first result for each input title

Comparison between `:map` with and without the `flat` suffix

The :map filter run will return at least as many outputs as given in the input. By default one input item will result in exactly one output item. When the filter run transforms an input item into an empty result, the output for that item will be an empty string. When the filter run transforms an input item into multiple items, only the first item will appear in the output. This behavior can be overridden by providing the flat suffix. The flat suffix will cause all the items to appear in the output.

`:map`	`:map:flat`
`[range[4]] :map[match[this matches nothing]]`	`[range[4]] :map:flat[match[this matches nothing]]`
`[range[4]] :map[range<currentTiddler>]`	`[range[4]] :map:flat[range<currentTiddler>]`
`[range[4]] :map[range<currentTiddler>]`	`[range[4]] :map:flat[range<currentTiddler>first[]]`
`[range[4]] :map[range<currentTiddler>sum[]]`	`[range[4]] :map:flat[range<currentTiddler>sum[]]`
`[[1,2,3]] [[4,5]] :map[split[,]]`	`[[1,2,3]] [[4,5]] :map:flat[split[,]]`
`[[1,2,3]] [[4,5]] :map[split[,]]`	`[[1,2,3]] [[4,5]] :map:flat[split[,]first[]]`

Comparison between `:map` and `:and`/`+` filter run prefixes

The functionality of the :map filter run prefix has some overlap with the :and prefix (alias +). They will sometimes return the same results as each other. In at least these cases, the results will be different:

The :and filter run can modify the number of items (either increase or decrease). The :map run will never alter the number of items.
The number of items in the :and filter run will also decrease due to de-duplication. The :map run will not de-duplicate.
Explicit references to the "currentTiddler" variable will behave differently
Implicit references to the "currentTiddler" using TextReference will behave differently.

results are the same
`:map`	`:and`
`[range[5]] :map[add[1]]`	`[range[5]] :and[add[1]]`
`[range[5]] :map[addsuffix[ hello]]`	`[range[5]] :and[addsuffix[ hello]]`
`[tag[shopping]] :map[get[quantity]]`	`[tag[shopping]] :and[get[quantity]]`
decrease in the number of items
`[range[5]] :map[sum[]]`	`[range[5]] :and[sum[]]`
`[range[5]] :map[join[,]]`	`[range[5]] :and[join[,]]`
increase in the number of items
`[[1,2,3]] [[4,5]] :map[split[,]]`	`[[1,2,3]] [[4,5]] :and[split[,]]`
de-duplication
`[range[5]] :map[[hello]]`	`[range[5]] :and[[hello]]`
currentTiddler
`[tag[shopping]] :map[<currentTiddler>]`	`[tag[shopping]] :and[<currentTiddler>]`
`[tag[shopping]] :map[{!!quantity}]`	`[tag[shopping]] :and[{!!quantity}]`