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

Thu Nov 17 12:56:24 UTC 2022

Updating.

> On Nov 16, 2022, at 5:41 PM, Alex Buckley <alex.buckley at oracle.com> wrote:
> 
> The first line says StringTemplates, should say StringTemplate.
> 
> The paragraph about the `process(ValidatingProcessor)` method is confusing -- it's not an alternative to using template expressions if the example needs to show a template expression before invoking `process`. I think you mean to say something about supporting deferred evaluation of a template expression, in conjunction with the RAW processor?
> 
> The implNote: "Libraries may produce StringTemplate instances as long as they conform to the requirements of this interface." -- there's no need to say this if the requirements (e.g. for immutability) are spelled out in the normative specs (keep reading).
> 
> The immutability of lists returned from `fragments()` and `values()` is mentioned both in the user-level spec ("Returns this StringTemplate's immutable list ...") and in the implementer-level spec ("The list returned is immutable."). That's a recipe for confusion. Better to drop the @implNote and commit to immutability as core to the method's result:
> 
> ---
> Returns a list of the fragment literals for this StringTemplate.
> 
> The fragment literals are the character sequences preceding each of the embedded expressions in source code, plus the character sequence following the last embedded expression. Such character sequences may be zero-length if an embedded expression appears at the beginning or end of a template, or if two embedded expressions are directly adjacent in a template.
> 
> The list is immutable.  [I'm not sure why this is important, but OK.]
> ---
> 
> The spec of the `interpolate` method has a stray dot and an example which calls `interpolation()`. Please rename `string` to `result`. Say: @return A string denoting the interpolation of this `StringTemplate`'s fragments and values.
> 
> Alex
> 
> On 11/16/2022 12:06 PM, Jim Laskey wrote:
>> 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 <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> <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> <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> <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://openjdk.org/jeps/430 <https://openjdk.org/jeps/430>> https://bugs.openjdk.org/browse/JDK-8273943 <https://bugs.openjdk.org/browse/JDK-8273943> <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> <https://bugs.openjdk.org/browse/JDK-8296302 <https://bugs.openjdk.org/browse/JDK-8296302>>
>>>> Thank you.
>>>> Cheers,
>>>> — Jim