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

[Jim Laskey]

CSR and available docs have been changed to reflect these changes.

https://cr.openjdk.java.net/~jlaskey/templates/docs/api/java.base/java/lang/template/StringTemplate.html

Cheers,

— Jim


On Nov 16, 2022, at 3:10 PM, Alex Buckley <alex.buckley at oracle.com<mailto:alex.buckley at oracle.com>> wrote:

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20221116/ce91ad4c/attachment-0001.htm>