Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Wed, 23 Nov 2022 15:57:54 GMT, Roger Riggs wrote: >> Kind of blows the whole concept of embedded expressions. This is one of >> those, just because you can, doesn't mean you should. > > ok, still what is the behavior if the format includes an index? > The pattern scanner in FormatProcessor permits an index and does not cause an > error. > > Also, there might be a small benefit to using the existing compiled pattern > in Formatter.java. (make it package private and rename to uppercase). Currently it issues an `MissingFormatArgumentException` which I guess could be confusing. Changing to IllegalFormatFlagsException with a descriptive message. Re: Pattern - I was originally trying to minimize changes to Formatter, but considering what I did change... - PR: https://git.openjdk.org/jdk/pull/10889
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Tue, 22 Nov 2022 20:17:41 GMT, Jim Laskey wrote:
>> src/java.base/share/classes/java/util/FormatProcessor.java line 64:
>>
>>> 62: *
>>> 63: * @implSpec Since, values are found within the string template,
>>> argument indexing
>>> 64: * specifiers are unsupported.
>>
>> What is the behavior of a format that references an index? Ignored, throw?
>> I can see an argument for simplicity, but the values are a sequential list
>> similar to that of a varargs call to format("xx", x, y, z, ...) so it can be
>> well defined to what value an index in the format refers.
>
> Kind of blows the whole concept of embedded expressions. This is one of
> those, just because you can, doesn't mean you should.
ok, still what is the behavior if the format includes an index?
The pattern scanner in FormatProcessor permits an index and does not cause an
error.
Also, there might be a small benefit to using the existing compiled pattern in
Formatter.java. (make it package private and rename to uppercase).
-
PR: https://git.openjdk.org/jdk/pull/10889
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Tue, 22 Nov 2022 19:09:12 GMT, Roger Riggs wrote:
>> Jim Laskey has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> Seal Digits
>
> src/java.base/share/classes/java/lang/template/StringTemplate.java line 319:
>
>> 317: * This {@link StringProcessor} instance is conventionally used for
>> the string interpolation
>> 318: * of a supplied {@link StringTemplate}.
>> 319: *
>
> It should be mentioned that the string representations are created as if
> invoking {@link String#valueOf}.
> An perhaps a link/@see to `FMT` for control over formatting.
>
> Also include it in the javadoc for `interpolate`.
Changing.
> src/java.base/share/classes/java/util/FormatProcessor.java line 64:
>
>> 62: *
>> 63: * @implSpec Since, values are found within the string template,
>> argument indexing
>> 64: * specifiers are unsupported.
>
> What is the behavior of a format that references an index? Ignored, throw?
> I can see an argument for simplicity, but the values are a sequential list
> similar to that of a varargs call to format("xx", x, y, z, ...) so it can be
> well defined to what value an index in the format refers.
Kind of blows the whole concept of embedded expressions. This is one of those,
just because you can, doesn't mean you should.
-
PR: https://git.openjdk.org/jdk/pull/10889
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Tue, 22 Nov 2022 18:43:53 GMT, Roger Riggs wrote:
>> Jim Laskey has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> Seal Digits
>
> src/java.base/share/classes/java/lang/template/StringProcessor.java line 58:
>
>> 56: /**
>> 57: * Constructs a {@link String} based on the template fragments and
>> values in the
>> 58: * supplied {@link StringTemplate stringTemplate} object.
>
> When reading the javadoc, I expected the type name, not the variable name.
> Suggestion:
>
> * supplied {@link StringTemplate StringTemplate} object.
Changing.
-
PR: https://git.openjdk.org/jdk/pull/10889
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Tue, 22 Nov 2022 18:33:23 GMT, Roger Riggs wrote:
>> Jim Laskey has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> Seal Digits
>
> src/java.base/share/classes/java/lang/template/StringTemplate.java line 52:
>
>> 50: * given by the template expression.
>> 51: *
>> 52: * For example, the following code contains a template expression that
>> uses the template
>
> Though this is trying to explain the general mechanism, it might be more
> useful to readers to start with the most common use case, that of using a
> string processor. Swapping the order of the examples possibly.
The issue is that most users will not see a StringTemplate object. If they've
come here then they want to see the inner workings.
> src/java.base/share/classes/java/lang/template/StringTemplate.java line 63:
>
>> 61: * {@code fragments} will be equivalent to {@code List.of("", " + ", " =
>> ", "")},
>> 62: * which includes the empty first and last fragments. {@code values}
>> will be the
>> 63: * equivalent of {@code List.of(10, 20, 30)}.
>
> Find a way to capitalize the first word of the sentence.
> Suggestion:
>
> * The value of {@code fragments} will be equivalent to {@code List.of("", "
> + ", " = ", "")},
> * which includes the empty first and last fragments. The {@code values} will
> be the
> * equivalent of {@code List.of(10, 20, 30)}.
Changing.
> src/java.base/share/classes/java/lang/template/StringTemplate.java line 66:
>
>> 64: *
>> 65: * The following code contains a template expression with the same
>> template but a
>> 66: * different template processor:
>
> Suggestion:
>
> * The following code contains a template expression with the same template
> but a
> * string template processor:
Changing. Missing "with" as well.
> src/java.base/share/classes/java/lang/template/StringTemplate.java line 75:
>
>> 73: * produced that returns the same lists from {@link
>> StringTemplate#fragments()} and
>> 74: * {@link StringTemplate#values()} as shown above. The {@link
>> StringTemplate#STR} template
>> 75: * processor uses these lists to yield an interpolated string. {@code s}
>> will be equivalent to
>
> Suggestion:
>
> * processor uses these lists to yield an interpolated string. The value of
> {@code s} will be equivalent to
Changing.
> src/java.base/share/classes/java/util/FormatProcessor.java line 196:
>
>> 194: * format specifier.
>> 195: * StringTemplate expressions without a preceeding specifier, use
>> "%s" by
>> 196:
>
> Its worth specifying the locale that is used by FMT, is it `Locale.ROOT`?
> If it is `Locale.default`, the results may vary from run to run.
Okay.
-
PR: https://git.openjdk.org/jdk/pull/10889
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Tue, 22 Nov 2022 18:17:28 GMT, Roger Riggs wrote:
>> Jim Laskey has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> Seal Digits
>
> src/java.base/share/classes/java/lang/template/package-info.java line 57:
>
>> 55: *{@link java.lang.template.StringTemplate}. The end result of the
>> process template
>> 56: * expression is the value that is produced by invoking the processor's
>> 57: *{@link java.lang.template.ValidatingProcessor#process(StringTemplate)}
>
> I would reduce the use of "proper", it should be sufficient to describe them
> without the qualifier.
> The single use of "improper" is fine to warn of compilation errors.
>
> Also, add a space between "*" and "{".
Changing.
> src/java.base/share/classes/java/lang/template/package-info.java line 61:
>
>> 59: * improper processor arguments result in compilation errors.
>> 60: *
>> 61: * In the example, {@code STR."The result of adding \{x} and \{y} is \{x
>> + y}."},
>
> Maybe avoid the repetition of the example.
> Suggestion:
>
> * In the example above,
Changing.
> src/java.base/share/classes/java/lang/template/package-info.java line 76:
>
>> 74: * String literals and text blocks can be used as proper processor
>> arguments as
>> 75: * well. This is automatically facilitated by the Java compiler
>> converted the
>> 76: * strings to {@link java.lang.template.StringTemplate StringTemplate}
>> using the
>
> Suggestion:
>
> * well. This is automatically facilitated by the Java compiler converting the
> * strings to {@link java.lang.template.StringTemplate StringTemplate} using
> the
Changing.
> src/java.base/share/classes/java/lang/template/package-info.java line 79:
>
>> 77: * {@link java.lang.template.StringTemplate#of(String)} method.
>> 78: *
>> 79: * Users can create their own template processors by implementing either
>
> Suggestion:
>
> * Users can create their own template processors by implementing one of
Changing.
> src/java.base/share/classes/java/lang/template/package-info.java line 83:
>
>> 81: * {@link java.lang.template.TemplateProcessor} or
>> 82: * {@link java.lang.template.StringProcessor} interfaces.
>> 83: * See {@link java.lang.template.ValidatingProcessor} for examples and
>> details.
>
> I would give the reader a firm what to read next suggestion.
> It may be useful to mention and link to the `FMT` processor as a way to
> control the formatting of the values.
> Suggestion:
>
> * For more examples and details see {@link
> java.lang.template.StringTemplate} and
> * {@link java.lang.template.ValidatingProcessor}.
Changing.
-
PR: https://git.openjdk.org/jdk/pull/10889
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
On Mon, 21 Nov 2022 17:43:16 GMT, Jim Laskey wrote:
>> Enhance the Java programming language with string templates, which are
>> similar to string literals but contain embedded expressions. A string
>> template is interpreted at run time by replacing each expression with the
>> result of evaluating that expression, possibly after further validation and
>> transformation. This is a [preview language feature and
>> API](http://openjdk.java.net/jeps/12).
>
> Jim Laskey has updated the pull request incrementally with one additional
> commit since the last revision:
>
> Seal Digits
Javadoc suggestions around readability, linking.
src/java.base/share/classes/java/lang/template/StringProcessor.java line 58:
> 56: /**
> 57: * Constructs a {@link String} based on the template fragments and
> values in the
> 58: * supplied {@link StringTemplate stringTemplate} object.
When reading the javadoc, I expected the type name, not the variable name.
Suggestion:
* supplied {@link StringTemplate StringTemplate} object.
src/java.base/share/classes/java/lang/template/StringTemplate.java line 52:
> 50: * given by the template expression.
> 51: *
> 52: * For example, the following code contains a template expression that
> uses the template
Though this is trying to explain the general mechanism, it might be more useful
to readers to start with the most common use case, that of using a string
processor. Swapping the order of the examples possibly.
src/java.base/share/classes/java/lang/template/StringTemplate.java line 63:
> 61: * {@code fragments} will be equivalent to {@code List.of("", " + ", " =
> ", "")},
> 62: * which includes the empty first and last fragments. {@code values} will
> be the
> 63: * equivalent of {@code List.of(10, 20, 30)}.
Find a way to capitalize the first word of the sentence.
Suggestion:
* The value of {@code fragments} will be equivalent to {@code List.of("", " +
", " = ", "")},
* which includes the empty first and last fragments. The {@code values} will
be the
* equivalent of {@code List.of(10, 20, 30)}.
src/java.base/share/classes/java/lang/template/StringTemplate.java line 66:
> 64: *
> 65: * The following code contains a template expression with the same
> template but a
> 66: * different template processor:
Suggestion:
* The following code contains a template expression with the same template but
a
* string template processor:
src/java.base/share/classes/java/lang/template/StringTemplate.java line 75:
> 73: * produced that returns the same lists from {@link
> StringTemplate#fragments()} and
> 74: * {@link StringTemplate#values()} as shown above. The {@link
> StringTemplate#STR} template
> 75: * processor uses these lists to yield an interpolated string. {@code s}
> will be equivalent to
Suggestion:
* processor uses these lists to yield an interpolated string. The value of
{@code s} will be equivalent to
src/java.base/share/classes/java/lang/template/StringTemplate.java line 319:
> 317: * This {@link StringProcessor} instance is conventionally used for
> the string interpolation
> 318: * of a supplied {@link StringTemplate}.
> 319: *
It should be mentioned that the string representations are created as if
invoking {@link String#valueOf}.
An perhaps a link/@see to `FMT` for control over formatting.
Also include it in the javadoc for `interpolate`.
src/java.base/share/classes/java/lang/template/package-info.java line 57:
> 55: *{@link java.lang.template.StringTemplate}. The end result of the
> process template
> 56: * expression is the value that is produced by invoking the processor's
> 57: *{@link java.lang.template.ValidatingProcessor#process(StringTemplate)}
I would reduce the use of "proper", it should be sufficient to describe them
without the qualifier.
The single use of "improper" is fine to warn of compilation errors.
Also, add a space between "*" and "{".
src/java.base/share/classes/java/lang/template/package-info.java line 61:
> 59: * improper processor arguments result in compilation errors.
> 60: *
> 61: * In the example, {@code STR."The result of adding \{x} and \{y} is \{x
> + y}."},
Maybe avoid the repetition of the example.
Suggestion:
* In the example above,
src/java.base/share/classes/java/lang/template/package-info.java line 76:
> 74: * String literals and text blocks can be used as proper processor
> arguments as
> 75: * well. This is automatically facilitated by the Java compiler converted
> the
> 76: * strings to {@link java.lang.template.StringTemplate StringTemplate}
> using the
Suggestion:
* well. This is automatically facilitated by the Java compiler converting the
* strings to {@link java.lang.template.StringTemplate StringTemplate} using the
src/java.base/share/classes/java/lang/template/package-info.java line 79:
> 77: * {@link java.lang.template.StringTemplate#of(String)} method.
> 78: *
> 79: * Users can create their own
Re: RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]
> Enhance the Java programming language with string templates, which are > similar to string literals but contain embedded expressions. A string > template is interpreted at run time by replacing each expression with the > result of evaluating that expression, possibly after further validation and > transformation. This is a [preview language feature and > API](http://openjdk.java.net/jeps/12). Jim Laskey has updated the pull request incrementally with one additional commit since the last revision: Seal Digits - Changes: - all: https://git.openjdk.org/jdk/pull/10889/files - new: https://git.openjdk.org/jdk/pull/10889/files/f2562ab3..da3ea20d Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=10889=27 - incr: https://webrevs.openjdk.org/?repo=jdk=10889=26-27 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/10889.diff Fetch: git fetch https://git.openjdk.org/jdk pull/10889/head:pull/10889 PR: https://git.openjdk.org/jdk/pull/10889
