From d99b1897c3072ff07ca6316ea23a91693104e5ef Mon Sep 17 00:00:00 2001 From: btheado Date: Mon, 31 Jul 2023 07:13:37 -0400 Subject: [PATCH] Refactor variable invocation docs (#7642) * Factored out variable invocation tiddlers into separate tiddlers * Document the variable attribute value behavior more completely --------- Co-authored-by: btheado --- ...pends on how the variable was declared.tid | 52 +++++++++++++++++++ ...ed via filter expression function call.tid | 10 ++++ ... invoked via filter operator parameter.tid | 11 ++++ ... variables invoked via normal wikitext.tid | 11 ++++ ...ariables invoked via widget attributes.tid | 11 ++++ .../tiddlers/variables/Variable Usage.tid | 50 ++---------------- .../wikitext/Variable Attribute Values.tid | 7 ++- 7 files changed, 103 insertions(+), 49 deletions(-) create mode 100644 editions/tw5.com/tiddlers/variables/Behaviour of invoked variables depends on how the variable was declared.tid create mode 100644 editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter expression function call.tid create mode 100644 editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter operator parameter.tid create mode 100644 editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via normal wikitext.tid create mode 100644 editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via widget attributes.tid diff --git a/editions/tw5.com/tiddlers/variables/Behaviour of invoked variables depends on how the variable was declared.tid b/editions/tw5.com/tiddlers/variables/Behaviour of invoked variables depends on how the variable was declared.tid new file mode 100644 index 000000000..319bf2c78 --- /dev/null +++ b/editions/tw5.com/tiddlers/variables/Behaviour of invoked variables depends on how the variable was declared.tid @@ -0,0 +1,52 @@ +created: 20230726145210484 +modified: 20230726145757234 +tags: [[Variable Usage]] +title: Behaviour of invoked variables depends on how the variable was declared +type: text/vnd.tiddlywiki + +\define m1(a1) $a1$ - <<__a1__>> - <> +\procedure p1(a1) $a1$ - <<__a1__>> - <> +\function f1(a1) "$a1$" "-" [<__a1__>] ="-" [] :and[join[ ]] + +Invoked in normal wikitext context: `<$transclude $variable=macro/>` or `<>` + +{{Behaviour of variables invoked via normal wikitext}} + +Invoked via widget attribute: `
>/>` + +{{Behaviour of variables invoked via widget attributes}} + +Invoked via filter operator parameter: `[]` + +{{Behaviour of variables invoked via filter operator parameter}} + +Invoked via function call in a filter expression: `[function[macro]]` + +{{Behaviour of variables invoked via filter expression function call}} + +!! Examples + +Below is an example macro, procedure and function definition. All three forms of parameter substitution `$a1$`, `<<__a1__>>`, and `<>` are included in each definition. The output helps illustrate when each form of substitution will or will not have affect. + +``` +\define m1(a1) $a1$ - <<__a1__>> - <> +\procedure p1(a1) $a1$ - <<__a1__>> - <> +\function f1(a1) $a1$ "-" [<__a1__>] ="-" [] :and[join[ ]] +``` + +| !Variable transclusion|!output | +| `<>`|<>| +| `<>`|<>| +| `<>`|<>| +| !Widget attribute|!output | +| `<$text text=<>/>`|<$text text=<>/>| +| `<$text text=<>/>`|<$text text=<>/>| +| `<$text text=<>/>`|<$text text=<>/>| +| !Filter operator parameter|!output | +| `[]`|<$text text={{{[]}}}/>| +| `[]`|<$text text={{{[]}}}/>| +| `[]`|<$text text={{{[]}}}/>| +| !Function call in filter expression|!output | +| `[function[m1],[foo]]`|<$text text={{{[function[m1],[foo]]}}}/>| +| `[function[p1],[foo]]`|<$text text={{{[function[p1],[foo]]}}}/>| +| `[function[f1],[foo]]`|<$text text={{{[function[f1],[foo]]}}}/>| \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter expression function call.tid b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter expression function call.tid new file mode 100644 index 000000000..52d44c9fd --- /dev/null +++ b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter expression function call.tid @@ -0,0 +1,10 @@ +created: 20230726143929233 +modified: 20230726150604831 +tags: [[Variable Usage]] +title: Behaviour of variables invoked via filter expression function call +type: text/vnd.tiddlywiki + +|tc-first-col-min-width|k +|!how declared|!behaviour| +|\define, <<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Every function is a variable, but only variables defined using \function are invokable using the <<.olink function>> filter operator. Attempts to use a non-function variable is the same as if the function doesn't exist. The behavior in this case is like the identity function. All filter input is passed unchanged to the output.| +|\function|The body text of the function is treated as a filter expression and evaluated. This filter expression can itself contain a function call. Filter expressions can be factored out into functions arbitrarily deep.| \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter operator parameter.tid b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter operator parameter.tid new file mode 100644 index 000000000..8c652488b --- /dev/null +++ b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter operator parameter.tid @@ -0,0 +1,11 @@ +created: 20230726143617389 +modified: 20230726150625716 +tags: [[Variable Usage]] +title: Behaviour of variables invoked via filter operator parameter +type: text/vnd.tiddlywiki + +|tc-first-col-min-width|k +|!how declared|!behaviour| +|\define|Textual substitution of parameters is performed on the body text. No further processing takes place. The result after textual substitution is used as the filter operator's parameter.| +|<<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Body text is retrieved as-is and used as the filter operator's parameter.| +|\function|The body text of the function is treated as a filter expression and evaluated. The first result is passed to the operator as a parameter. The remaining results are discarded.| \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via normal wikitext.tid b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via normal wikitext.tid new file mode 100644 index 000000000..0caa74c26 --- /dev/null +++ b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via normal wikitext.tid @@ -0,0 +1,11 @@ +created: 20230726142925020 +modified: 20230726150648189 +tags: [[Variable Usage]] +title: Behaviour of variables invoked via normal wikitext +type: text/vnd.tiddlywiki + +|tc-first-col-min-width|k +|!how declared|!behaviour| +|\define|All wikitext and variable substitution and textual substitution takes place| +|<<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|All wikitext and variable substitution takes place| +|\function|Invoking a function in this way (`<>`) is a synonym for `<$text text={{{[function[macro]]}}}/>`. As with any filtered transclusion (i.e. triple curly braces), all results except the first are discarded| \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via widget attributes.tid b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via widget attributes.tid new file mode 100644 index 000000000..3bf06e219 --- /dev/null +++ b/editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via widget attributes.tid @@ -0,0 +1,11 @@ +created: 20230726143332803 +modified: 20230726150616232 +tags: [[Variable Usage]] +title: Behaviour of variables invoked via widget attributes +type: text/vnd.tiddlywiki + +|tc-first-col-min-width|k +|!how declared|!behaviour| +|\define|Textual substitution of parameters is performed on the body text. No further processing takes place. The result after textual substitution is used as the attribute's value| +|<<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Body text is retrieved as-is and used as the attribute's value.| +|\function|When a function is invoked as `
>/>`, it is a synonym for `
`. As with any filtered transclusion (i.e. triple curly braces), all results except the first are discarded. That first result is used as the attribute's value. Note that functions are recursively processed even when invoked in this form. In other words a filter expression in a function can invoke another function and the processing will continue| \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/variables/Variable Usage.tid b/editions/tw5.com/tiddlers/variables/Variable Usage.tid index 9db23a456..962137e68 100644 --- a/editions/tw5.com/tiddlers/variables/Variable Usage.tid +++ b/editions/tw5.com/tiddlers/variables/Variable Usage.tid @@ -1,13 +1,9 @@ created: 20230421020225031 -modified: 20230422144812613 +modified: 20230726145912019 tags: title: Variable Usage type: text/vnd.tiddlywiki -\define m1(a1) $a1$ - <<__a1__>> - <> -\procedure p1(a1) $a1$ - <<__a1__>> - <> -\function f1(a1) "$a1$" "-" [<__a1__>] ="-" [] :and[join[ ]] - !Ways to define variables and parameters |! how declared|! how parameters are defined|! accessing parameter values in the body| |\define|`()`|`$param$, <<__param__>>`| @@ -100,50 +96,10 @@ These examples are meant to provide insight into the various ways of defining an -!Behavior of invoked variables depends on how the variable was declared +!Behaviour of invoked variables depends on how the variable was declared -|!how invoked|!how declared|!behavior| -|`<$transclude $variable=macro/>` or `<>` in normal wikitext context|\define|All wikitext and variable substitution and textual substitution takes place| -|~|<<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|All wikitext and variable substitution takes place| -|~|\function|Invoking a function in this way (`<>`) is a synonym for `<$text text={{{[function[macro]]}}}/>`. As with any filtered transclusion (i.e. triple curly braces), all results except the first are discarded.| -|||| -|widget attribute: `
>/>`|\define|Textual substitution of parameters is performed on the body text. No further processing takes place. The result after textual substitution is used as the attribute's value| -|~|<<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Body text is retrieved as-is and used as the attribute's value.| -|~|\function|When a function is invoked as `
>/>`, it is a synonym for `
`. As with any filtered transclusion (i.e. triple curly braces), all results except the first are discarded. That first result is used as the attribute's value. Note that functions are recursively processed even when invoked in this form. In other words a filter expression in a function can invoke another function and the processing will continue| -|||| -|filter operator parameter: `[]`|\define|Textual substitution of parameters is performed on the body text. No further processing takes place. The result after textual substitution is used as the filter operator's parameter.| -|~|<<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Body text is retrieved as-is and used as the filter operator's parameter.| -|~|\function|The body text of the function is treated as a filter expression and evaluated. The first result is passed to the operator as a parameter. The remaining results are discarded| -|||| -|function call in a filter expression: `[function[macro]]`|\define, <<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Every function is a variable, but only variables defined using \function are invokable using the <<.olink function>> filter operator. Attempts to use a non-function variable is the same as if the function doesn't exist. The behavior in this case is like the identity function. All filter input is passed unchanged to the output.| -|~|\function|The body text of the function is treated as a filter expression and evaluated. This filter expression can itself contain a function call. Filter expressions can be factored out into functions arbitrarily deep.| +{{Behaviour of invoked variables depends on how the variable was declared}} -!! Examples - -Below is an example macro, procedure and function definition. All three forms of parameter substitution `$a1$`, `<<__a1__>>`, and `<>` are included in each definition. The output helps illustrate when each form of substitution will or will not have affect. - -``` -\define m1(a1) $a1$ - <<__a1__>> - <> -\procedure p1(a1) $a1$ - <<__a1__>> - <> -\function f1(a1) $a1$ "-" [<__a1__>] ="-" [] :and[join[ ]] -``` - -| !Variable transclusion|!output | -| `<>`|<>| -| `<>`|<>| -| `<>`|<>| -| !Widget attribute|!output | -| `<$text text=<>/>`|<$text text=<>/>| -| `<$text text=<>/>`|<$text text=<>/>| -| `<$text text=<>/>`|<$text text=<>/>| -| !Filter operator parameter|!output | -| `[]`|<$text text={{{[]}}}/>| -| `[]`|<$text text={{{[]}}}/>| -| `[]`|<$text text={{{[]}}}/>| -| !Function call in filter expression|!output | -| `[function[m1],[foo]]`|<$text text={{{[function[m1],[foo]]}}}/>| -| `[function[p1],[foo]]`|<$text text={{{[function[p1],[foo]]}}}/>| -| `[function[f1],[foo]]`|<$text text={{{[function[f1],[foo]]}}}/>| !Namespaces diff --git a/editions/tw5.com/tiddlers/wikitext/Variable Attribute Values.tid b/editions/tw5.com/tiddlers/wikitext/Variable Attribute Values.tid index d65d81871..e233feb5a 100644 --- a/editions/tw5.com/tiddlers/wikitext/Variable Attribute Values.tid +++ b/editions/tw5.com/tiddlers/wikitext/Variable Attribute Values.tid @@ -1,5 +1,5 @@ created: 20230615045239825 -modified: 20230615045312961 +modified: 20230726151053593 tags: [[Widget Attributes]] WikiText title: Variable Attribute Values type: text/vnd.tiddlywiki @@ -11,4 +11,7 @@ Variable attribute values are indicated with double angle brackets around a [[ma ...
``` -<<.warning "The text from the definition of the macro will be retrieved and text substitution will be performed (i.e. <<.param $param$>> and <<.param $(...)$>> syntax). The value of the attribute value will be the resulting text. Any wiki syntax in that text (including further macro calls and variable references) will be left as-is.">> \ No newline at end of file + +The behaviour of variables invoked via widget attributes is not the same as when they are [[invoked via normal wikitext|Behaviour of variables invoked via normal wikitext]]. In addition, the behaviour depends on how the variable is declared: + +{{Behaviour of variables invoked via widget attributes}}