Lambda arguments

[jgonggrijp]

This idea is not my own. In fact, I am not in favor of it. Still, I believe it deserves a dedicated discussion, because @determin1st is currently promoting it.

Several implementations extend the Mustache language by allowing template arguments, for example like this:

{{relativeDate article.published}}

If article.published is a value in the context with some language-specific representation of January 13 2024 and relativeDate is a lambda, then the above might output yesterday in implementations that support this notation.

Depending on the implementation, there might be one or more arguments. Arguments might be context references, literal values or a bit of both. In #135 (comment), @determin1st suggested allowing any arbitrary string as payload, leaving its interpretation to the lambda in question:

the crucial part of lambdas is the argument specification. the management of the stack, its values, rendering, substitution etc can be done by passing the mustache object or the interface to it as the first parameter to any lambda. the second argument should be reserved, string type for hints or additional arguments, the third should bear first section content (when applicable, not for inverted or variable)

function lambda(object $m, string $arg, string $sect);

He provided a rationale in #187 (comment):

lambdas are great, lambda argument is greater. the first is out of syntax definition (as it is bound to underlying language). almost every imaginable/discussed feature may be done with their combo.

* a wrap:

Hello {{#wrap <em>,</em>}}world{{/}}!

* an even/odd alternation

<table>
{{@array}}
  <tr background-color="{{#isEven _index}}white{{|}}gray{{/}}"><td>dummy</td></tr>
{{/}}
</table>

* checking array is not empty

{{^isEmpty array}}
  array is not empty
{{/}}
{{#isNotEmpty array}}
    array is not empty
{{/}}

* formatting

{{user.name}} joined at {{timestampToISO8601 user.created}}

* etc..

In order for the above examples to work with @determin1st's proposed API, Mustache would also need to give lambdas access to the context stack. In other words, it depends on (some of) features 1-3 of power lambdas (#155). I have dubbed "introspective lambdas" as a name for such lambdas in #155 (reply in thread). The main alternative for lambda arguments, as well as for introspective lambdas, is filters (#153).

[determin1st]

oke, ill try comment on and describe the lambda interface and the argument, how it's envisioned by sm-mustache terms

Several implementations extend the Mustache language by allowing template arguments, for example like this:

{{relativeDate article.published}}

yes, the whitespace should be the trigger for the (singular) argument:

{{

  relativeDate
  article.published

}}

should also work as lambda with article.published string argument, not a value auto-resolved from the path.
the actual implementation (in PHP) could be:

function relativeDate(object $m, string $a): string
{
  $v = $m->value($a);# here the value is obtained
  return date("Y-m-d H:i:s", $v);
}

Depending on the implementation, there might be one or more arguments. Arguments might be context references, literal values or a bit of both. In #135 (comment), @determin1st suggested allowing any arbitrary string as payload, leaving its interpretation to the lambda in question:

the crucial part of lambdas is the argument specification. the management of the stack, its values, rendering, substitution etc can be done by passing the mustache object or the interface to it as the first parameter to any lambda. the second argument should be reserved, string type for hints or additional arguments, the third should bear first section content (when applicable, not for inverted or variable)

function lambda(object $m, string $arg, string $sect);

i came to

function lambda(object $m, string $a);

variant. the return type must be fixed, one of boolean, number, string, array or object..
the first argument is a lambda facade to the mustache instance, it has:

function text(): string;# returns primary section's content
function value(string $path, mixed $val=null): mixed;# gets or sets a value on the context stack
# etc

which cover most of the needs

Hello {{#wrap <em>,</em>}}world{{/}}!

a wrap implementation could be

function wrap(object $m, string $a): string
{
  $delim = explode(",", $a);
  return $delim[0].$m->text().$delim[1];
}

authors are free to choice separators/behavior and how it composes into result - not a mustache's headache.

[jgonggrijp]

Passing a string argument to lambdas does not really make them any more powerful than they already are. I will illustrate with a modified version of the wrap example, which already works with extension lambdas as-is:

{
    wrap: function() {
        return {
            delim: function(content) {
                this.del = content.split(',');
                return '';
            },
            content: function(content) {
                return this.del[0] + content + this.del[1];
            }
        };
    }
}

Hello {{#wrap}}{{#delim}}<em>,</em>{{/delim}}{{#content}}world{{/content}}{{/wrap}}

Admittedly, the template is longer to write, but it is also more explicit.

You can see it live in action by copy-pasting the following savestate in the load/store box in the playground:

{"data":{"text":"{\n    wrap: function() {\n        return {\n            delim: function(content) {\n                this.del = content.split(',');\n                return '';\n            },\n            content: function(content) {\n                return this.del[0] + content + this.del[1];\n            }\n        };\n    }\n}"},"templates":[{"name":"","text":"Hello {{#wrap}}{{#delim}}<em>,</em>{{/delim}}{{#content}}world{{/content}}{{/wrap}}"}]}

Side note: since both the delimiters and the content are hardcoded into the template, there is no real need to use lambdas in the first place. You can just write this:

Hello <em>world</em>

[jgonggrijp]

@determin1st in #187 (reply in thread):

so here i disagree with the filters approach. although i also changed mind

Is this a "I might still change my mind" hint? 😉

cant see any advantage over lambda argument which has better/simplier syntax

I will give you two advantages. Firstly, lambdas-with-arguments burden the lambda author with the responsibility to perform context lookups. The lambda implementation requires knowledge about the API of the Mustache engine. Filters do not; they can just be straightforward data conversion functions. Contrast these two notations and their corresponding implementations:

{{relativeDate article.published}}

function relativeDate(object $m, string $a): string
{
  $v = $m->value($a);# here the value is obtained
  return date("Y-m-d H:i:s", $v);
}

{{article.published | relativeDate}}

function relativeDate($v): string
{
  return date("Y-m-d H:i:s", $v);
}

Secondly, filters can be easily composed while lambdas-with-arguments cannot. Suppose I sometimes want to start the relative date with an uppercase. With filters, I can just write this to get Red and Yesterday:

{{user.favoriteColor | capitalize}}

{{article.published | relativeDate | capitalize}}

Achieving the same effect with lambda arguments is either going to involve inconsistency, where you sometimes use the lambda with arguments and sometimes with section content,

{{capitalize user.favoriteColor}}

{{#capitalize}}{{relativeDate article.published}}{{/capitalize}}

or some kind of combinatorial explosion, where lambdas need to be aware of each other's implementations.

{{capitalize user.favoriteColor}}

{{relativeDateCapital article.published}}

{{relativeDate article.published capital=true}}

{{capitalizePassthrough relativeDate article.published}}

[determin1st]

Passing a string argument to lambdas does not really make them any more powerful than they already are. I will illustrate with a modified version of the wrap example, which already works with extension lambdas as-is:

Hello {{#wrap}}{{#delim}}<em>,</em>{{/delim}}{{#content}}world{{/content}}{{/wrap}}

Admittedly, the template is longer to write, but it is also more explicit.

Side note: since both the delimiters and the content are hardcoded into the template, there is no real need to use lambdas in the first place. You can just write this:

Hello <em>world</em>

that was your idea/example to wrap (emphasize) something with filters. i only showed how it's done with lambda argument, the wrap is more generic and may contain some advanced logic to be even more useful. to improve it a bit, it can become {{#htmlWrap em}}...{{/}}. you see your version as explicit only because it uses an older syntax, to me its more implicit than explicit, because you cant say what it does without looking at the code, my version has a hint that it is a lambda with the argument, its name says that it "wraps". yours say only that they are a set of blocks/sections.

I will give you two advantages. Firstly, lambdas-with-arguments burden the lambda author with the responsibility to perform context lookups..

you have to understand that there is no magic in the world, energy goes from one place to another, same is the burden, it doesn't disappear. it is a correct placement of the burden - into the code, out of template, according to logic-less principle.

The lambda implementation requires knowledge about the API of the Mustache engine. Filters do not; they can just be straightforward data conversion functions.

if you wish to write lambda, you need to know mustache api, if you only want to use lambda, you have to know what it does, how it is applied, a short description. same applies to filters.

Contrast these two notations and their corresponding implementations:

{{relativeDate article.published}}

{{article.published | relativeDate}}

well, not much of a contrast. westerners feel more comfortable working with LEFT-TO-RIGHT notations than arabic (or kind of.. are we in terminal?) RIGHT-TO-LEFT notations. but more importantly, the auto-resolution of the path closes the possibility of working with literals. reducing implementation by one line isnt a real profit.

Secondly, filters can be easily composed while lambdas-with-arguments cannot. Suppose I sometimes want to start the relative date with an uppercase. With filters, I can just write this to get Red and Yesterday:

{{user.favoriteColor | capitalize}}

{{article.published | relativeDate | capitalize}}

Achieving the same effect with lambda arguments is either going to involve inconsistency, where you sometimes use the lambda with arguments and sometimes with section content,
or some kind of combinatorial explosion, where lambdas need to be aware of each other's implementations.

well yeah, if you want to combine functions, you have to write lambda that combines them, although im not a fan of making such things in the template, it will look like

{{apply relativeDate,capitalize,article.published}}

if youre up to marry a | symbol, you can even replace the , with it, but again, lambda implementation is not a part of mustache with the lambda argument. i reserved the | sigil for alternative sections and reccomend to use , or another neutral symbol to separate literals

[jgonggrijp]

you have to understand that there is no magic in the world, energy goes from one place to another, same is the burden, it doesn't disappear. it is a correct placement of the burden - into the code, out of template, according to logic-less principle.

It is just as much in the template in both cases; the name is there. You mean into the lambda, out of the engine. But even that is not true, because the engine still has to perform the lookup. You just add a responsibility that would not need to exist with filters.

the auto-resolution of the path closes the possibility of working with literals.

It does not! Section lambdas can already accept literals by the current standard.

In fact, by having both current lambdas and filters, you can have a single data conversion function that works both for literals and for context values, by choosing the notation accordingly. That data conversion function can be just any straightforward function. It might be a standard function from a library that is not even aware of Mustache. Consider this:

{
    user: { favoriteColor: 'red' },
    capitalize: function(value) {
        return value[0].toUpperCase() + value.slice(1);
    }
}

{{user.favoriteColor | capitalize}} {{! Red }}

{{#capitalize}}world{{/capitalize}} {{! World }}

You can also combine them by using higher order functions. Really, there is nothing you can do with introspective lambdas and arguments that you cannot do with current lambdas and filters. Filters are easier and more flexible to implement, both for the user and for the engine.

[determin1st]

you have to understand that there is no magic in the world, energy goes from one place to another, same is the burden, it doesn't disappear. it is a correct placement of the burden - into the code, out of template, according to logic-less principle.

It is just as much in the template in both cases; the name is there. You mean into the lambda, out of the engine. But even that is not true, because the engine still has to perform the lookup. You just add a responsibility that would not need to exist with filters.

the auto-resolution of the path closes the possibility of working with literals.

It does not! Section lambdas can already accept literals by the current standard.

Yes it does, in this version:

{{user.favoriteColor | capitalize}} {{! Red }}

no literal is possible. to open the road to literals, the burden must grow up a bit, it costs one line of code for the lambda author. though, mustache implementer will have to sweat - the cost of a feature.

In fact, by having both current lambdas and filters, you can have a single data conversion function that works both for literals and for context values, by choosing the notation accordingly. That data conversion function can be just any straightforward function. It might be a standard function from a library that is not even aware of Mustache. Consider this:

its the road to inconsistency. a good lambda must bear a bunch of checks and balances. for example, an unpredictable result will arise from a free form of combinations - a function that expects a string input but gets another type, like {{user.name | capitalize | isGreaterThanZero | countArrayElements}}. only a centralized lambda may check if a set functions accepts the same type, like {{apply capitalize,isGreaterThanZero,countArrayElements,user.name}} may dismiss such a combination explicitly.

{{#capitalize}}world{{/capitalize}} {{! World }}

inconsistency meaning: the fact that someone or something cannot be trusted to stay the same in behaviour or quality in all situations - imo, a function (is it a function here or a boolean flag?) that applies differently conforms to that definition.
my lambda interface allows to distinguish between block/section and variable renders.

You can also combine them by using higher order functions. Really, there is nothing you can do with introspective lambdas and arguments that you cannot do with current lambdas and filters. Filters are easier and more flexible to implement, both for the user and for the engine.

im not a fan of combinatorics in the template, that brings more logic into template and makes author treat template language as a programming language. lambda argument empowers lambda implementer the first place. composing a set of unbound functions in the template wont add to readability or ease of use, but i agree that "filters" are easier to implement. it is also an imported idea (lets do like the other engines did, right-to-left, console terminals), foreign to mustache principle