Updating.
> On Nov 16, 2022, at 5:41 PM, Alex Buckley <alex.buck...@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.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>
>>>> <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
