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
