Fix specification of multiline strings.

docs/language/dartLangSpec.tex

 \documentclass{article}
 \usepackage{epsfig}
 \usepackage{color}
 \usepackage{dart}
 \usepackage{bnf}
 \usepackage{hyperref}
 \usepackage{lmodern}
 \usepackage[T1]{fontenc}
 \newcommand{\code}[1]{{\sf #1}}
 \title{Dart Programming Language  Specification  \\
 {5th edition draft}\\
 {\large Version 1.15.0}}
 
 % For information about Location Markers (and in particular the
 % commands \LMHash and \LMLabel), see the long comment at the
 % end of this file.
 
 % CHANGES
 % =======
 % Significant changes to the specification.
 %
 % 1.15
 % - Change how language specification describes control flow.
 % - Object initialization now specifies initialization order correctly.
 % - Specifies that leaving an await-for loop must wait for the subscription
 %   to be canceled.
 % - An await-for loop only pauses the subscription if it does something async.
 % - Assert statements may now also include a "message" operand.
 % - The Null type is now considered a subtype of all types in most cases.
+% - Specify what NEWLINE means in multiline strings.
 %
 % 1.14
 % - The call "C()" where "C" is a class name, is a now compile-time error.
 % - Changed description of rewrites that depended on a function literal.
 %   In many cases, the rewrite wasn't safe for asynchronous code.
 % - Removed generalized tear-offs.
 % - Allow "rethrow" to also end a switch case. Allow braces around switch cases.
 % - Allow using '=' as default-value separator for named parameters.
 % - Make it a compile-time error if a library includes the same part twice.
 % - Now more specific about the return types of sync*/async/async* functions
@@ skipping 2760 matching lines @@
 \rationale{
 This decision was made for compatibility with web browsers and Javascript. Earlier versions of the specification required a string to be a sequence of valid Unicode code points.  Programmers should not depend on this distinction.
 }
 
 \begin{grammar}
 {\bf stringLiteral:}(multilineString $|$ singleLineString)+
     .
 \end{grammar}
 
 \LMHash{}
-A string can be either a sequence of single line strings or a multiline string.
+A string can be a sequence of single line strings and multiline strings.
 
 \begin{grammar}
  {\bf singleLineString:}`{\escapegrammar \code{"}}' stringContentDQ* `{\escapegrammar \code{"}}';
        `{\escapegrammar \code{'}}' stringContentSQ* `{\escapegrammar \code{'}}';
       `r' `{\escapegrammar \code{'}}' (\~{}( `{\escapegrammar \code{'}}' $|$ NEWLINE ))* `{\escapegrammar \code{'}}';
       `r' `{\escapegrammar \code{"}}' (\~{}( `{\escapegrammar \code{"}}' $|$ NEWLINE ))* `{\escapegrammar \code{"}}'
     .
 \end{grammar}
 
 \LMHash{}
 A single line string is delimited by either matching single quotes or matching double quotes.
 
 \commentary{
 Hence, `abc' and ``abc'' are both legal strings, as are `He said ``To be or not to be'' did he not?'  and ``He said `To be or not to be' didn't he''. However  ``This ` is not a valid string, nor is `this''.
 }
 
 \commentary{The grammar ensures that a single line string cannot span more than one line of source code, unless it includes an interpolated expression that spans multiple lines.
 }
 
 \LMHash{}
-Adjacent
-%single line
-strings are implicitly concatenated to form a single string literal.
-%, and so are adjacent multiline strings, but the two forms may not be mixed.
+Adjacent strings are implicitly concatenated to form a single string literal.
 
 
 \commentary{Here is an example}
 
 \begin{dartCode}
 print("A string" "and then another"); // prints: A stringand then another
 \end{dartCode}
 
 \rationale{Dart also supports the operator + for string concatenation.
 
 The + operator on Strings requires a String argument. It does not coerce its argument into a string. This helps avoid puzzlers such as
 }
 
 \begin{dartCode}
 print("A simple sum: 2 + 2 = " +
             2 + 2);
 \end{dartCode}
 
 \rationale{ which this prints  'A simple sum: 2 + 2 = 22' rather than 'A simple sum: 2 + 2 = 4'.
-However, the use the concatenation operation is still  discouraged for efficiency reasons. Instead, the recommended Dart idiom is to use string interpolation.
+However, the use the concatenation operation is still discouraged for efficiency reasons. Instead, the recommended Dart idiom is to use string interpolation.

[eernst, 2017/01/31 08:52:47]

'the use [of?] the'

[Lasse Reichstein Nielsen, 2017/01/31 09:23:41]

Done.

 }
 
 \begin{dartCode}
 print("A simple sum: 2 + 2 =  \$\{2+2\}");
 \end{dartCode}
 
 
 \rationale{String interpolation works well for most cases. The main situation where it is not fully satisfactory is for string literals that are too large to fit on a line. Multiline strings can be useful, but in some cases, we want to visually align the code. This can be expressed by writing smaller strings separated by whitespace, as shown here:}
 
 
 
 
 \begin{dartCode}
 'Imagine this is a very long string that does not fit on a line. What shall we do? '
 'Oh what shall we do? '
 'We shall split it into pieces '
 'like so'.
 \end{dartCode}
 
 
 
 
 
 \begin{grammar}
- {\bf multilineString:}`{\escapegrammar \texttt{"""}}' stringContentTDQ*   `{\escapegrammar \texttt{"""}}';
-      `{\escapegrammar \code{'}\code{'}\code{'}}' stringContentTSQ* `{\escapegrammar \code{'}\code{'}\code{'}}';
-      `r' `{\escapegrammar \texttt{"""}}'  (\~{} `{\escapegrammar \texttt{"""}}')*   `{\escapegrammar \texttt{"""}}';
-      `r' `{\escapegrammar \code{'}\code{'}\code{'}}' (\~{} `{\escapegrammar \code{'}\code{'}\code{'}}')* `{\escapegrammar \code{'}\code{'}\code{'}}'
-    .
+  {\bf multilineString:}`{\escapegrammar \texttt{"""}}' stringContentTDQ* `{\escapegrammar \texttt{"""}}';
+    `{\escapegrammar \code{'}\code{'}\code{'}}' stringContentTSQ* `{\escapegrammar \code{'}\code{'}\code{'}}';
+    `r' `{\escapegrammar \texttt{"""}}' (\~{} `{\escapegrammar \texttt{"""}}')* `{\escapegrammar \texttt{"""}}';
+    `r' `{\escapegrammar \code{'}\code{'}\code{'}}' (\~{} `{\escapegrammar \code{'}\code{'}\code{'}}')* `{\escapegrammar \code{'}\code{'}\code{'}}'
+  .
 
 
-    {\bf ESCAPE\_SEQUENCE:} `$\backslash$ n';
+  {\bf ESCAPE\_SEQUENCE:}`$\backslash$ n';
     `$\backslash$ r';
-   `$\backslash$ f';
-   `$\backslash$ b';
-  `$\backslash$ t';
-   `$\backslash$ v';
-  `$\backslash$ x' HEX\_DIGIT HEX\_DIGIT;
-   `$\backslash$ u' HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT;
-   `$\backslash$ u\{' HEX\_DIGIT\_SEQUENCE `\}'
+    `$\backslash$ f';
+    `$\backslash$ b';
+    `$\backslash$ t';
+    `$\backslash$ v';
+    `$\backslash$ x' HEX\_DIGIT HEX\_DIGIT;
+    `$\backslash$ u' HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT;
+    `$\backslash$ u\{' HEX\_DIGIT\_SEQUENCE `\}'
   .
 
 {\bf HEX\_DIGIT\_SEQUENCE:}
      HEX\_DIGIT HEX\_DIGIT? HEX\_DIGIT? HEX\_DIGIT? HEX\_DIGIT? HEX\_DIGIT?
     .
 
 \end{grammar}
 
 \LMHash{}
-Multiline strings are delimited by either matching triples of single quotes or matching triples of double quotes. If the first line of a multiline string consists solely of the whitespace characters defined by the production {\em WHITESPACE}  \ref{lexicalRules}), possibly prefixed by $\backslash$, then that line is ignored, including the new line at its end.
+Multiline strings are delimited by either matching triples of single quotes or matching triples of double quotes. If the first line of a multiline string consists solely of the whitespace characters defined by the production {\em WHITESPACE} \ref{lexicalRules}), possibly prefixed by $\backslash$, then that line is ignored, including the line break at its end.
 
-
- \rationale{
- The idea is to ignore whitespace, where whitespace is defined as tabs, spaces and newlines. These can be represented directly, but since for most characters prefixing by backslash is an identity, we allow those forms as well.
- }
+\rationale{
+The idea is to ignore a whitespace-only first line of a multiline string, where whitespace is defined as tabs, spaces and the final line break. These can be represented directly, but since for most characters prefixing by backslash is an identity in a non-raw string, we allow those forms as well.
+}
 
  % could be clearer. Is the first line in  """\t
  %    """ ignored not. It depends if we mean whitespace before escapes are interpreted,
  % or after, or both.  See https://code.google.com/p/dart/issues/detail?id=23020
 
 \LMHash{}
 Strings support escape sequences for special characters. The escapes are:
 \begin{itemize}
-\item  $\backslash$n for newline, equivalent to $\backslash$x0A.
+\item $\backslash$n for newline, equivalent to $\backslash$x0A.
 \item $\backslash$r for carriage return, equivalent to $\backslash$x0D.
 \item $\backslash$f for form feed, equivalent to $\backslash$x0C.
 \item $\backslash$b for backspace, equivalent to $\backslash$x08.
 \item $\backslash$t for tab, equivalent to $\backslash$x09.
 \item $\backslash$v for vertical tab, equivalent to $\backslash$x0B
 \item $\backslash$x $HEX\_DIGIT_1$ $HEX\_DIGIT_2$, equivalent to
 
 $\backslash$u\{$HEX\_DIGIT_1$ $HEX\_DIGIT_2$\}.
 \item $\backslash$u $HEX\_DIGIT_1$ $HEX\_DIGIT_2$ $HEX\_DIGIT_3$ $HEX\_DIGIT_4$, equivalent to $\backslash$u\{$HEX\_DIGIT_1$ $HEX\_DIGIT_2$ $HEX\_DIGIT_3$ $HEX\_DIGIT_4$\}.
 \item $\backslash$u\{$HEX\_DIGIT\_SEQUENCE$\} is the Unicode code point represented by the $HEX\_DIGIT\_SEQUENCE$. It is a compile-time error if the value of the $HEX\_DIGIT\_SEQUENCE$ is not a valid Unicode code point.
 \item \$ indicating the beginning of an interpolated expression.
 \item Otherwise, $\backslash k$ indicates the character $k$ for any $k$ not in $\{n, r, f, b, t, v, x, u\}$.
  \end{itemize}
 
 \LMHash{}
 Any string may be prefixed with the character `r', indicating that it is a {\em raw string}, in which case no escapes or interpolations are recognized.
 
 \LMHash{}
+Line breaks in a multiline string are represented by the {\em NEWLINE} production.
+A line break introduces a single newline character into the string value.
+
+\LMHash{}
 It is a compile-time error if a non-raw string literal contains a character sequence of the form $\backslash$x that is not followed by a sequence of two hexadecimal digits. It is a compile-time error if a non-raw string literal  contains a character sequence of the form $\backslash$u that is not followed by either a sequence of four hexadecimal digits, or by curly brace delimited sequence of hexadecimal digits.
 
 
 
 \begin{grammar}
  {\bf stringContentDQ:}\~{}( `$\backslash$' $|$ `{\escapegrammar \texttt{"}}' $|$ `\$' $|$ NEWLINE );
       `$\backslash$'  \~{}( NEWLINE );
      stringInterpolation
     .
 
  {\bf stringContentSQ:}\~{}( `$\backslash$' $|$ `{\escapegrammar \texttt{'}}' $|$ `\$' $|$ NEWLINE );
       `$\backslash$'  \~{}( NEWLINE );
      stringInterpolation
     .
 
 
  {\bf stringContentTDQ:}\~{}( `$\backslash$' $|$  `{\escapegrammar \texttt{"""}}' $|$ `\$');
      stringInterpolation
     .
 
  {\bf stringContentTSQ:}\~{}( `$\backslash$' $|$ `{\escapegrammar \code{'}\code{'}\code{'}}' $|$ `\$');
      stringInterpolation
     .
 
 {\bf NEWLINE:}$\backslash$ n;
-      $\backslash$ r
+      $\backslash$ r;
+      $\backslash$ r $\backslash$ n
     .
 
  \end{grammar}
 
 \LMHash{}
 All string literals evaluate to instances of the built-in class \code{String}.
 It is a compile-time error for a class to extend, mix in or implement \code{String}.
 The static type of a string literal is \code{String}.
 
 \subsubsection{String Interpolation}
@@ skipping 5114 matching lines @@
 
 The invariant that each normative paragraph is associated with a line
 containing the text \LMHash{} should be maintained.  Extra occurrences
 of \LMHash{} can be added if needed, e.g., in order to make
 individual \item{}s in itemized lists addressable.  Each \LM.. command
 must occur on a separate line.  \LMHash{} must occur immediately
 before the associated paragraph, and \LMLabel must occur immediately
 after the associated \section{}, \subsection{} etc.
 
 ----------------------------------------------------------------------