JEP 430 String Templates, some weird scenarios feedback

[Stephen Colebourne]

On Sat, 17 Jun 2023 at 14:40, Brian Goetz <brian.goetz at oracle.com> wrote:

We have three descriptions of "template" so far:
1) a "thing with holes"
2) *a thing to be filled in* (an empty Mad Lib)
3) a completed Mad Lib

The first two are the same surely? An immutable thing with specific
places that data needs adding. My view is clear - when you fill in a
Mad Lib, it is no longer a template.

(You can fill in a template, but once filled in it is no longer a
template, it is a customized document. If the template is mutable,
like a piece of paper with a Mad Lib on it, then it ceases to be a
template as soon as you write anything on it, because it ceases to be
reusable. It is the aspect of reusability which is core here, so you
can merge multiple different sets of values into the same template.)

More importantly than our own opinions is that Java has had plenty of
other libraries involving templates, which I contend match my
definition of reusability:

- JSP [1]
- Freemarker [2]
- Velocity [3]
- Thymeleaf [4]
- Antlr StringTemplate [5]

[1] https://www.caucho.com/resin-3.1/doc/jsp-templates.xtp
[2] https://freemarker.apache.org/
[3] https://velocity.apache.org/engine/2.3/developer-guide.html#the-fundamental-pattern
[4] https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#what-kind-of-templates-can-thymeleaf-process
[5] https://github.com/antlr/stringtemplate4/blob/master/doc/introduction.md#groups-of-templates

All of these are about separating the template from the
values/data/context. They vary in how the separation occurs, some are
mutable, some allow embedded code or expressions  The way I've always
used it is that you start with a template and add in the actual values
you want - the template is reusable for many different sets of values.
(Some of these libraries are mutable, thus the values end up alongside
the original template

I really do think this API is pushing against a *lot* of Java history
in calling the main class `StringTemplate` and the language feature a
"template expression".

> At root, I think what you're saying is "I think BoundTemplate or
> FilledInTemplate or TemplateWithValues might be a better name than
> StringTemplate", which is a totally reasonable opinion!

Any of those three names, or others would be a lot clearer.

Separately, I'm arguing that the "unbound" template should be exposed
as well through the API. If you wanted to defer that, you could do so
long as the terminology adopted now was "bound template" or similar.


> No one would be surprised in the least that when we eventually call
> toSTring on the StringBuilder, that we captured the value 2 rather than
> the variable x.

Agreed. But it is well understood because it looks like a method call.

So there are two parts to the point here:
1) You've called it a template, which implies that the things inside
are placeholder (aka variables), not values
2) It doesn't look like a method call, so the learned knowledge of
values doesn't apply

> Suggestions [...] welcome.

My suggestion is to address the two points above:
1) Stop calling it a template (calling it bound template would be OK)
2) Provide a matching API where the values are passed into a method,
then equate the expression as a kind of syntax sugar for the API.


> So, what I take away from this discussion is that you'd like to consider
> some other names for [..] interpolate?

describe() would be a lot clearer.


> There's also a
> valid opinion about whether RAW is the right name for the processor that
> yields a StringTemplate; other candidates include LAZY or DEFER or QUOTED.

It is tricky to grasp. Because RAW and STR produce different things
when they look similar - one is the result type and one the bound
template type. Of course its not actually different at all, but it
sure looks that way. I'm not convinced that changing to
LAZY/DEFER/QUOTED makes any difference to the mental model issue.


> >   // alternative API design - StringTemplate only contains the fragments
> Unfortunately this is not just an alternate API design; it's an
> alternate language design, because (among other reasons) \{} is not
> allowed in string literals today.

True. Good job this is a preview feature then :-)

FWIW I do feel the UPPER."" part of the syntax of this feature isn't
helping understanding. But I'll avoid making a syntax suggestion
unless asked to.


thanks
Stephen