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.buck...@oracle.com<mailto:alex.buck...@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
