Third draft spec for String Templates (JEP 430) now available

[Alex Buckley]

Ch.3 looks good.

Some points about 15.8.6:

1. This pair of sentences is very good and clear:

   A string template with n embedded expressions (n>0) consists of the 
alternate interleaving of n+1 fragments with the n embedded expressions. 
The first fragment is a StringTemplateBegin token (3.13); the next n-1 
fragments are StringTemplateMid tokens; the last fragment is a 
StringTemplateEnd token.

2. I think this sentence is a leftover and should be removed:

   A string template with n (n > 0) embedded expressions, consists of 
the alternate interleaving of n+1 fragments (one StringTemplateBegin 
token, n-1 StringTemplateMid tokens, and one StringTemplateEnd token ) 
with the n embedded expressions.

3. I think this sentence is correct but should be phrased as a pair of 
sentences, like in #1 above.

   A text block template with n (n > 0) embedded expressions, consists 
of the alternate interleaving of n+1 fragments (one 
TextBlockTemplateBegin token, n-1 TextBlockTemplateMid tokens, and one 
TextBlockTemplateEnd token) with the n embedded expressions.

4. Consider this sentence:

   A string template with n embedded expressions and n+1 fragments has 
n+1 fragment strings, where each fragment string is the content of the 
corresponding fragment (3.13).

(In the previous draft, we said the same thing, worded differently: From 
the fragments in a string template, a sequence of corresponding fragment 
strings is derived by taking the content of each fragment token (3.13).)

However, the _content_ of the corresponding fragment in 3.13 does not 
have its escape sequences interpreted. I'm pretty sure you want its 
escape sequences to have been interpreted. For that, you need 15.8.6's 
fragment strings to lean on this artifact from 3.13:

   The string represented by a StringTemplateBegin, StringTemplateMid, 
or StringTemplateEnd token is given by its content with every escape 
sequence interpreted, as if by execution of String.translateEscapes on 
the content.

5. I'm not a fan of the factoring whereby escape sequence interpretation 
happens for a string template's tokens in 3.13 but a text block 
template's tokens in 15.8.6. I realize why text block templates are more 
complicated, but I would like to avoid the reader flipping between the 
sections and saying "Didn't we do this already?" Perhaps we just defer 
string templates' escape sequence interpretation to 15.8.6. That said, 
refactoring this topic is not urgent, and can wait until after preview.

Alex

On 3/1/2023 6:17 AM, Gavin Bierman wrote:
> Thanks Alex (and apologies for missing your earlier email - don’t know 
> what happened there).
> 
> Updated spec available at:
> 
> https://cr.openjdk.org/~gbierman/jep430/latest/ 
> <https://cr.openjdk.org/~gbierman/jep430/latest/>
> 
> Thanks,
> Gavin
> 
>> On 28 Feb 2023, at 18:37, Alex Buckley <alex.buckley at oracle.com 
>> <mailto:alex.buckley at oracle.com>> wrote:
>>
>> 1. Escape sequences are legal in fragments, so 3.10.7 should open with 
>> something like:
>>
>> "In character literals, string literals, and text blocks (§3.10.4, 
>> §3.10.5, §3.10.6), +and in fragments of a template (3.13),+ the escape 
>> sequences allow for ..."
>>
>>
>> 2. 3.10.7 goes on to say that "An escape sequence in the content of a 
>> character literal, string literal, or text block is interpreted by 
>> ...". This statement constitutes one half of a two-part exposition of 
>> interpretation, the other half being found in 3.10.4/5/6 where 
>> `String.translateEscapes` is mentioned. Two-way exposition is hard to 
>> write, expensive to maintain, but helpful to read. 3.13 is upfront 
>> that StringTemplateBegin, StringTemplateMid, and StringTemplateEnd 
>> tokens enjoy interpretation, so let's get them named in 3.10.7. 3.13 
>> is less upfront about TextBlockTemplateBegin, TextBlockTemplateMid, 
>> and TextBlockTemplateEnd tokens, let me set them aside for now.
>>
>>
>> 3. 3.10.7 should end with a note that the character sequence \{ is not 
>> an escape sequence but rather has meaning in a template (3.13).
>>
>>
>> 4. In 3.13, consider "A fragment ~consists of~ +represents+ a 
>> non-expression part of a template."  (Ch.3 is big on "representing", 
>> or perhaps "denoting", things.)  This sentence would work well in the 
>> opening paragraph of the section.
>>
>>
>> 5. 15.8.6 needs more polishing, per the mail I sent about it last 
>> time. I'll discuss offline.
>>
>> Alex
>>
>> On 2/28/2023 8:15 AM, Gavin Bierman wrote:
>>> Following the feedback, a small update of the String Templates Spec 
>>> is now available:
>>> https://cr.openjdk.org/~gbierman/jep430/jep430-20230222/specs/string-templates-jls.html <https://cr.openjdk.org/~gbierman/jep430/jep430-20230222/specs/string-templates-jls.html> <https://cr.openjdk.org/~gbierman/jep430/jep430-20230222/specs/string-templates-jls.html <https://cr.openjdk.org/~gbierman/jep430/jep430-20230222/specs/string-templates-jls.html>>
>>> Any further comments welcomed!
>>> Thanks,
>>> Gavin
>>>> On 9 Feb 2023, at 15:28, Gavin Bierman <gavin.bierman at oracle.com 
>>>> <mailto:gavin.bierman at oracle.com> <mailto:gavin.bierman at oracle.com 
>>>> <mailto:gavin.bierman at oracle.com>>> wrote:
>>>>
>>>> Dear experts:
>>>>
>>>> A new, updated spec covering JEP 430 (String Templates) is now 
>>>> available at:
>>>>
>>>> https://cr.openjdk.java.net/~gbierman/jep430/latest 
>>>> <https://cr.openjdk.java.net/~gbierman/jep430/latest> 
>>>> <https://cr.openjdk.java.net/~gbierman/jep430/latest 
>>>> <https://cr.openjdk.java.net/~gbierman/jep430/latest>>
>>>>
>>>> This is a substantial rewrite: it now covers more fully how 
>>>> templates are tokenized, how to deal with ambiguities, and how text 
>>>> block templates are dealt with.
>>>>
>>>> Comments welcomed!
>>>> Gavin
>