RFR of JDK-8285932 Implementation of JEP-430 String Templates (Preview)

[Alex Buckley]

Below, a revised description for `StringTemplate`.


// High-level opener.

`StringTemplate` is the run-time representation of a string template or 
text block template in a template expression.

[Sidebar. The JEP says "An instance of StringTemplate represents the 
string template or text block template that appears either as the 
template in a template expression, or as a standalone literal." -- the 
'standalone literal' clause should be deleted.]

// Basic concepts. No need to spell out details like immutability or 
return types here; leave them for the method specs.

In the source code of a Java program, a string template or text block 
template contains an interleaved succession of _fragment literals_ and 
_embedded expressions_. The `fragments()` method returns the fragment 
literals, and the `values()` method returns the results of evaluating 
the embedded expressions. `StringTemplate` does not provide access to 
the source code of the embedded expressions themselves; it is not a 
compile-time representation of a string template or text block template.

// Usage

`StringTemplate` is primarily used in conjunction with a template 
processor to produce a string or other useful value. Evaluation of a 
template expression first produces an instance of `StringTemplate`, 
representing the template of the template expression, and then passes 
the instance to the template processor given by the template expression.

For example, the following code contains a template expression that uses 
the template processor `RAW`, which simply yields the `StringTemplate` 
passed to it:

int x = 10;
int y = 20;
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
List<String> fragments = st.fragments();
List<Object> values    = st.values();

`fragments` will be equivalent to `List.of(" + ", " = ")` and `values` 
will be the equivalent of `List.of(10, 20, 30)`.

The following code contains a template expression with the same template 
but a different template processor:

int x = 10;
int y = 20;
String s = STR."\{x} + \{y} = \{x + y}";

When the template expression is evaluated, an instance of 
`StringTemplate` is produced that returns the same lists from 
`fragments()` and `values()` as shown above. The `STR` template 
processor uses these lists to yield an interpolated string. `s` will be 
equivalent to `"10 + 20 = 30"`.

The `interpolate()` method provides a direct way to perform string 
interpolation of a `StringTemplate`. Template processors can use the 
following code pattern:

List<String> fragments = st.fragments();
List<Object> values    = st.values();
... check or manipulate the fragments and/or values ...
String result = StringTemplate.interpolate(fragments, values);

The `process(ValidatingProcessor)` method provides an alternative to 
using string template expressions.  [Sidebar. The example line of code 
which follows, is using a template expression. I'm not sure what was 
meant here.]

String result = RAW."\{x} + \{y} = \{x + y}".process(STR);

The factory methods `of(String)` and `of(List, List)` can be used to 
construct a `StringTemplate`.

@implNote: Implementations of `StringTemplate` must minimally implement 
the methods fragments() and values(). Instances of `StringTemplate` are 
considered immutable. To preserve the semantics of string templates and 
text block templates, the list returned by `fragments()` must be one 
element larger than the list returned by `values()`.

@jls 15.8.6


Alex

On 11/16/2022 4:49 AM, Jim Laskey wrote:
> May I get a final  (PR) review of JDK-8285932 Implementation of JEP-430 
> String Templates (Preview) from core-libs and compiler.
> 
> PR: https://github.com/openjdk/jdk/pull/10889 
> <https://github.com/openjdk/jdk/pull/10889>
> 
> 
> JBS: https://bugs.openjdk.org/browse/JDK-8285932 
> <https://bugs.openjdk.org/browse/JDK-8285932>
> CSR: https://bugs.openjdk.org/browse/JDK-8286021 
> <https://bugs.openjdk.org/browse/JDK-8286021>
> JEP: https://openjdk.org/jeps/430 <https://openjdk.org/jeps/430> 
> https://bugs.openjdk.org/browse/JDK-8273943 
> <https://bugs.openjdk.org/browse/JDK-8273943>
> SPEC: https://bugs.openjdk.org/browse/JDK-8296302 
> <https://bugs.openjdk.org/browse/JDK-8296302>
> 
> Thank you.
> 
> Cheers,
> 
> — Jim
> 
>