List of (soft) recommendations or "best practices" for implementations

[jgonggrijp]

The spec describes what an implementation should do in order to ensure that templates are portable. Besides that, there could also exist a more informal and optional list of guidelines, which describe how an implementation could make itself convenient for users. Credits to @bobthecow for suggesting this in #156 (comment).

Right now, I can think of three candidates for such a list:

• ambient context (Ambient context, a.k.a. helpers #156);
• liberated lambdas (Power lambdas (suggestions for a better name welcome) #155 (reply in thread));
• pragma tags (I've seen these mentioned in past comments by @bobthecow and @groue).

If we were to make such a list, I think it should be "free for all", i.e., not subject to review or consensus. Partly because implementers are free to ignore the recommendations anyway, partly because we must not burden ourselves with new processes that need to be controlled. Everyone can add and nobody should remove.

I think the wiki might be a suitable place for such a list.

[agentgt]

I firmly believe a best practice is providing some data variable that is a boolean of first and last while in a list section.

Whether that is @first or @last or -first or -last I think doesn't really matter when it comes to a "best practice".

That is most Mustache implementations should provide a means to create a comma separated list without inducing an aneurism of having to dig in various complicated implementation tricks.

In traditional HTML where you also have Javascript and CSS at play knowing first and last was not as important.

Now that React and various Javascript frameworks have taken over a good portion of web site rendering Mustache's target output media I think is becoming more mixed and varied than just HTML.

For example I use Mustache a great deal for Java/SQL code generation and code generation in so many cases requires generating a list separated by commas in them where a trailing , is not allowed (for example SQL).

Every time I reach for JMustache or now JStachio (both which have virtual keys) for this problem because it is not obvious how to do this instantly with Mustache.java (the other reason is JMustache/JStachio has more consistent whitespace).

[agentgt]

To put it simpler my thoughts on filters and some mechanism to achieve or first/last do not have to be at odds. I do not care if it is virtual keys or filters that solve the problem and I doubt most users do.

What they do not want to do is go figure out how wire in that EnumeratedValue into the mustache engine. Even though it is shown to be easy with Mustache PHP it is not so obvious or easy in other languages/implementations. The best practice part is implementers should make that possible, documented (in the case of Mustache.java) and/or on by default.

Also filters are inherently more complicated. You need to first find the filter (and or register) and then figure out what it returns and then make sure it call its bindings all of which is implementation specific.

Then you have... well should explain what filters are or what is happening with {{#list | enumerate}}.

I think most people can safely describe first/last/index in less than a paragraph. I don't think filters as they are currently being proposed can be described so easily: #153 (comment)

Perhaps the above will be remedied over time with simpler description but currently it is a lot more than just this key that is available while in a list.

Then there is implementation questions revolving filters that I can go add to #153 like how much | short circuited?

I'm definitely a fan of filters and can probably get a single | (pipe) working but multiple piping has some evaluation order (e.g. lazy or eager) and static type checking that I may not be able to easily resolve.

[jgonggrijp]

I agree with @agentgt that trailing commas are currently needlessly difficult in Mustache, especially if you want to stay portable (because then the only option is to decorate the data before passing them to the template).

I agree with @bobthecow that a recommendation to have "some kind of solution" for this will not really address the problem. In fact, it will make templates less portable, because users will rely on a feature that one implementation provides but the other does not.

For example, suppose that Wontache implements virtual keys that go -index, -this, -first, -last and Mustache.php implements virtual keys that go @index, @current, @first, @last. We both follow the recommendations, but users cannot bring their templates from Wontache to Mustache.php without editing them.

To really address the problem, we would either specify the exact virtual keywords and their meanings, or we would specify some other, more general feature that can be used to solve trailing commas.

By the way, at this point I think that the trailing comma problem should probably have a discussion of its own.

If, for the sake of argument, we assume that we specify filters, then there is some room for a soft recommendation again: to ship with a ready to use enumerate filter that can do first/last detection. Even if Mustache.php follows that recommendation but Wontache doesn't (or does but with slightly different semantics), users will still be able to reuse their templates. All they need to do, is port the Mustache.php version of enumerate to Wontache.

You express valid concerns with regard to the explainability and implementability of filters; I will reply to those in new comments in #153.

[agentgt]

I agree largely what you wrote however:

For example, suppose that Wontache implements virtual keys that go -index, -this, -first, -last and Mustache.php implements virtual keys that go @Index, @current, @FIRST, @last.

While perhaps not instantly portable it is much easier to port than a filter that does it. In fact in some places where we replaced JMustache with Handlebars we just did a simple to search and replace of (-first -> @first).

One con about the filter on porting is that decorating object returned by the enumerator may not do the correct thing for: {{.}}. That is a naive toString in @bobthecow implementation may not work or even be possible in some languages.

That is in some languages it is hard to make generic like functions that take any like objects. OCaml comes to mind.

In my implementation it is a big deal. The compiler will block you from trying to toString arbitrary objects.

That is assume EnumeratedValue is the current node.

{{.}}

Would fail. Not even at runtime but compile time. You can read about that more here: https://jstach.io/jstachio/io.jstach.jstache/io/jstach/jstache/JStacheFormatterTypes.html

So you would have to register EnumeratedValue as safe toString but how does EnumeratedValue know the contained object is safe toString?

One of my favorite things about Mustache is how safe it can be made to be.

[jgonggrijp]

I see what you mean. {{.}} and direct lookups like {{name}} instead of {{@value.name}} are problematic for portability. I kind of skipped over that the first time I read @bobthecow's code (he doesn't do the direct lookups but I mention it because Handlebars does support that).

I could implement those shortcuts in Wontache, but I honestly don't want to. I was planning to leave off the @ markers and just force users to write {{value}} and {{value.name}} (or {{#value}}...{{name}}...{{/value}}). It makes the implementation much simpler and the semantics within the template more straightforward.

If it comes to a soft recommendation for an enumerate-like filter, I suggest including the following. Implementations that support shortcuts like {{.}}, should clearly state in the documentation that this notation may not be portable. Users can then make an informed choice between notational convenience and portability, and implementers can provide necessary functionality without having to jump hoops.

[agentgt]

@bobthecow @jgonggrijp I showed a JStachio implementation of enumerate here: #153 (reply in thread)

It respects the original {{.}} however it is not a filter as currently defined.

[jgonggrijp]

#174 might be a subject for this list as well, although it probably deserves a hard rule in a 2.0 version of the spec.