From a3ba6f9370ed4142e1b6a96655d88b424a6b5d47 Mon Sep 17 00:00:00 2001
From: "jeremy@jermolene.com" <jeremy@jermolene.com>
Date: Sun, 11 Sep 2022 10:49:02 +0100
Subject: [PATCH] Tests and docs for function operator

---
 .../tests/data/functions/FunctionOperator.tid | 24 +++++++++++++++++++
 .../tests/data/functions/MissingFunction.tid  | 15 ++++++++++++
 .../tw5.com/tiddlers/filters/function.tid     | 21 ++++++++++++++++
 3 files changed, 60 insertions(+)
 create mode 100644 editions/test/tiddlers/tests/data/functions/FunctionOperator.tid
 create mode 100644 editions/test/tiddlers/tests/data/functions/MissingFunction.tid
 create mode 100644 editions/tw5.com/tiddlers/filters/function.tid

diff --git a/editions/test/tiddlers/tests/data/functions/FunctionOperator.tid b/editions/test/tiddlers/tests/data/functions/FunctionOperator.tid
new file mode 100644
index 000000000..e2a0038dc
--- /dev/null
+++ b/editions/test/tiddlers/tests/data/functions/FunctionOperator.tid
@@ -0,0 +1,24 @@
+title: Functions/FunctionOperator
+description: Calling a function via the function operator
+type: text/vnd.tiddlywiki-multiple
+tags: [[$:/tags/wiki-test-spec]]
+
+title: Output
+
+\whitespace trim
+\function .dividebysomething(factor:0.5)
+[divide<factor>]
+\end
+
+\function multiplebysomething(first:ignored,factor:2)
+[multiply<factor>multiply[2].dividebysomething[0.25]]
+\end
+
+<$text text={{{ [[4]function[multiplebysomething]] }}}/>
+|
+<$text text={{{ [[6]function[multiplebysomething],[ignored],[4]] }}}/>
+
++
+title: ExpectedResult
+
+<p>64|192</p>
\ No newline at end of file
diff --git a/editions/test/tiddlers/tests/data/functions/MissingFunction.tid b/editions/test/tiddlers/tests/data/functions/MissingFunction.tid
new file mode 100644
index 000000000..25498e452
--- /dev/null
+++ b/editions/test/tiddlers/tests/data/functions/MissingFunction.tid
@@ -0,0 +1,15 @@
+title: Functions/MissingFunction
+description: Calling a missing function via the function operator
+type: text/vnd.tiddlywiki-multiple
+tags: [[$:/tags/wiki-test-spec]]
+
+title: Output
+
+\whitespace trim
+
+<$text text={{{ [[23]function[missing]] }}}/>
+
++
+title: ExpectedResult
+
+23
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/filters/function.tid b/editions/tw5.com/tiddlers/filters/function.tid
new file mode 100644
index 000000000..cbffbdc9b
--- /dev/null
+++ b/editions/tw5.com/tiddlers/filters/function.tid
@@ -0,0 +1,21 @@
+caption: function
+created: 20220909111836951
+modified: 20220909111836951
+op-input: a [[selection of titles|Title Selection]] passed as input to the function <<.place F>>
+op-output: the [[selection of titles|Title Selection]] returned from the function <<.place F>>
+op-parameter: first parameter is the [[function name|Functions]], subsequent parameters are passed to the function by position
+op-parameter-name: F
+op-purpose: apply a [[function|Functions]] to the input list, and return the result
+tags: [[Filter Operators]]
+title: function Operator
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.3.0">> The <<.op function>> operator applies a named [[function|Functions]] to the input titles, and returns the results from the function.
+
+The first parameter of the <<.op function>> operator specifies the name of the function to be called. Subsequent parameters are passed to the function.
+
+The mapping between the parameters is //positional//, with each consecutive parameter specified in the function call mapped to the corresponding parameter in the function definition. Any parameters that are not provided are given their default values.
+
+<<.tip "Compare with the similar [[filter|filter Operator]] and [[subfilter|subfilter Operator]] operators which take a filter strings as their parameter instead of a named function, and does not permit parameters to be passed">>
+
+<<.operator-examples "filter">>