spec copyedits

docs/language/dartLangSpec.tex

 \documentclass{article}
 \usepackage{epsfig}
 \usepackage{color}
 \usepackage{dart}
 \usepackage{bnf}
 \usepackage{hyperref}
 \usepackage{lmodern}
 \newcommand{\code}[1]{{\sf #1}}
 \title{Dart Programming Language  Specification  \\
 (4th edition draft)\\
@@ skipping 716 matching lines @@
  %\end{grammar}
 
 \subsubsection{Optional Formals}
 \LMLabel{optionalFormals}
 
 \LMHash{}
 Optional parameters may be specified and provided with default values.
 
 \begin{grammar}
 {\bf defaultFormalParameter:}
-      normalFormalParameter ('=' expression)?
+      normalFormalParameter (`=' expression)?
     .   
         
 {\bf defaultNamedParameter:}
       normalFormalParameter ( `{\escapegrammar :}' expression)?
     .   
 \end{grammar}
 
 \LMHash{}
 It is a compile-time error if the default value of an optional parameter is not a compile-time constant (\ref{constants}). If no default is explicitly specified for an optional parameter an implicit default of \NULL{} is provided.
 
@@ skipping 80 matching lines @@
       \STATIC{}? functionSignature;
       \STATIC{}? getterSignature;
       \STATIC{}? setterSignature;
       operatorSignature
     .
 
 {\bf declaration:}constantConstructorSignature (redirection $|$ initializers)?;
       constructorSignature (redirection $|$ initializers)?;
       \EXTERNAL{} constantConstructorSignature;
       \EXTERNAL{} constructorSignature;
-      ((\EXTERNAL{} \STATIC{} ?))? getterSignature;
-      ((\EXTERNAL{} \STATIC{}?))? setterSignature;
+      (\EXTERNAL{} \STATIC{}?)? getterSignature;
+      (\EXTERNAL{} \STATIC{}?)? setterSignature;
       \EXTERNAL{}? operatorSignature;
-       ((\EXTERNAL{} \STATIC{}?))? functionSignature;
+      (\EXTERNAL{} \STATIC{}?)? functionSignature;
       \STATIC{} (\FINAL{} $|$ \CONST{}) type? staticFinalDeclarationList;
 %      \CONST{} type? staticFinalDeclarationList;
       \FINAL{} type? initializedIdentifierList;
       \STATIC{}? (\VAR{} $|$ type) initializedIdentifierList
     .
 
 {\bf staticFinalDeclarationList:}
     staticFinalDeclaration (`,' staticFinalDeclaration)*
     .
 
@@ skipping 736 matching lines @@
 \commentary{
 The assignment to \code{x} is allowed under the assumption that \code{q} is a compile-time constant (even though \code{q} is not, in general a compile-time constant).  The assignment to \code{y} is similar, but raises additional questions. In this case, the superexpression of \code{p} is \code{p + 100}, and it requires that \code{p} be a numeric compile-time constant for the entire expression to be considered constant.  The wording of the specification allows us to assume that \code{p} evaluates to an integer. A similar argument holds for \code{p} and \code{q} in the assignment to \code{z}.
 
 However, the following constructors are disallowed:
 }
 
 \begin{dartCode}
 \CLASS{} D \{
   \FINAL{} w;
   \CONST{} D.makeList(p): w = \CONST{} [p];  // compile-time error
-  \CONST{} D.makeMap(p): w = \CONST{} \{``help'': q\}; // compile-time error
+  \CONST{} D.makeMap(p): w = \CONST{} \{"help": q\}; // compile-time error

[gbracha, 2015/12/21 19:06:53]

No, this comes out wrong/  Some of these changes are in fact corrections; some
are no-ops; but this one is wrong.

[Patrice Chalin, 2015/12/22 05:21:06]

I guess that you know that in several other dartCode environments in this spec,
both the single quote character (') and the double quote character (") are used
to enclose strings rather than the use of the LaTeX conventions of `...' and
``...''. E.g.:

L3470: \CONST{} A("x"); // compile-time error
L7100     print("yoyoma");

among others. Either way is fine I suppose, but consistency would be nice. (In
most other language documents I have worked on, the LaTeX string convention is
used in prose and single/double quote characters are used in code environments.)

   \CONST{} D.makeC(p): w = \CONST{} C(p, 12); // compile-time error
 \}
 \end{dartCode}
 
 \commentary{
 The problem is not that the assignments to \code{w} are not potentially constant; they are.  However, all these run afoul of the rules for constant lists (\ref{lists}), maps (\ref{maps}) and objects (\ref{const}), all of which independently require their subexpressions to be constant expressions.
 }
 
 \rationale{
 All of the illegal constructors of \code{D} above could not be sensibly invoked via \NEW{}, because an expression that must be constant cannot depend on a formal parameter, which may or may not be constant. In contrast, the legal examples make sense regardless of whether the constructor is invoked via \CONST{} or via \NEW{}.
@@ skipping 917 matching lines @@
 .
 \end{grammar}
 
 \LMHash{}
 The null object is the sole instance of the built-in class \code{Null}. Attempting to instantiate \code{Null} causes a run-time error. It is a compile-time error for a class to attempt to extend, mix in or implement \code{Null}. 
 Invoking a method on \NULL{}  yields a \code{NoSuchMethodError} unless the method is explicitly implemented by class \code{Null}.
 
 \LMHash{}
 The static type of \NULL{} is $\bot$.
 
-\rationale{The decision to use $\bot$ instead of \code{Null} allows \NULL{} to be be assigned everywhere without complaint by the static checker. 
+\rationale{The decision to use $\bot$ instead of \code{Null} allows \NULL{} to be assigned everywhere without complaint by the static checker. 
 }
 
 
 \subsection{Numbers}
 \LMLabel{numbers}
 
 \LMHash{}
 A {\em numeric literal} is either a decimal or hexadecimal integer of arbitrary size, or a decimal double.
 
 \begin{grammar}
 {\bf numericLiteral:}NUMBER;
       HEX\_NUMBER
     .
     
   {\bf NUMBER:} DIGIT+ (`{\escapegrammar.}' DIGIT+)? EXPONENT?;
-      {`\escapegrammar .}' DIGIT+ EXPONENT?
+      `{\escapegrammar .}' DIGIT+ EXPONENT?
     .
 
 {\bf  EXPONENT:}
-      (`e' $|$ `E') ('+' $|$ `-`)? DIGIT+
+      (`e' $|$ `E') (`+' $|$ `-')? DIGIT+
     .
 
 {\bf HEX\_NUMBER:}`0x' HEX\_DIGIT+;
       `0X' HEX\_DIGIT+
     .
 
- {\bf HEX\_DIGIT:}`a'{\escapegrammar ..}'f';
-      `A'{\escapegrammar ..}'F';
+ {\bf HEX\_DIGIT:}`a'{\escapegrammar ..}`f';
+      `A'{\escapegrammar ..}`F';
       DIGIT
     .
  \end{grammar}
  
 \LMHash{}
 If a numeric literal begins with the prefix `0x' or `0X', it denotes the hexadecimal integer represented by the part of the literal following `0x' (respectively `0X'). Otherwise, if the numeric literal does not include a decimal point  it denotes a decimal integer.  Otherwise, the numeric literal  denotes a 64 bit double precision floating point number as specified by the IEEE 754 standard. 
 
 \LMHash{}
 In principle, the range of integers supported by a Dart implementations is unlimited. In practice, it is limited by available memory. Implementations may also be limited by other considerations.
 
@@ skipping 264 matching lines @@
 
 \LMHash{}
 A {\em symbol literal} denotes the name of a declaration in a Dart program. 
 
 \begin{grammar}
 {\bf symbolLiteral:}
       `\#'  (operator $|$ (identifier (`{\escapegrammar .}' identifier)*))  .
 \end{grammar}
 
 \LMHash{}
-A symbol literal \code{\#id} where \code{id} does not begin with an underscore ('\code{\_}')  is equivalent to the expression \code{\CONST{} Symbol('id')}.  
+A symbol literal \code{\#id} where \code{id} does not begin with an underscore (`\code{\_}')  is equivalent to the expression \code{\CONST{} Symbol('id')}.  
 
 \LMHash{}
 A symbol literal \code{\#\_id} evaluates to the object that would be returned by the call \code{mirror.getPrivateSymbol('id')} where mirror is an instance of the class \code{LibraryMirror} defined in the library \code{dart:mirrors}, reflecting the current library.
 
 \rationale{
 One may well ask what is the motivation for introducing literal symbols? In some languages, symbols are canonicalized whereas strings are not. However literal strings are already canonicalized in Dart.  Symbols are slightly easier to type compared to strings and their use can become strangely addictive, but this is not nearly sufficient justification for adding a literal form to the language. The primary motivation is related to the use of reflection and a web specific practice known as minification. 
 
 Minification compresses identifiers consistently throughout a program in order to reduce download size.  This practice poses difficulties for reflective programs that refer to program declarations via strings. A string will refer to an identifier in the source, but the identifier will no longer be used in the minified code, and reflective code using these would fail.  Therefore, Dart reflection uses  objects of type \code{Symbol} rather than strings. Instances of \code{Symbol} are guaranteed to be stable with repeat to minification. Providing a literal form for symbols makes reflective code easier to read and write. The fact that symbols are easy to type and can often act as convenient substitutes for enums are secondary benefits.
 }
 
@@ skipping 615 matching lines @@
  \CONST{} IntPair(\THIS{}.x, \THIS{}.y);
  \FINAL{} int x;
  \FINAL{} int y;
  \OPERATOR *(v) $=>$ \NEW{} IntPair(x*v, y*v);
 \}
 
 \CONST{} A(\CONST{} IntPair(1,2)); // compile-time error: illegal in a subtler way
 \end{dartCode}
 
 \commentary{
-Due to the rules governing constant constructors, evaluating the constructor \code{A()} with the argument \code{''x''} or the argument \code{\CONST{} IntPair(1, 2)} would cause it to throw an exception, resulting in a compile-time error.
+Due to the rules governing constant constructors, evaluating the constructor \code{A()} with the argument \code{"x"} or the argument \code{\CONST{} IntPair(1, 2)} would cause it to throw an exception, resulting in a compile-time error.
 }
 
 
 \LMHash{}
 Given an instance creation expression of the form \CONST{} $q(a_1, \ldots , a_n)$ it is a static warning if $q$ is a constructor of an abstract class  (\ref{abstractInstanceMembers}) but $q$ is not a factory constructor.  
 
 
 \subsection{ Spawning an Isolate}
 \LMLabel{spawningAnIsolate}
 
@@ skipping 921 matching lines @@
 
 % add local functions per bug 23218
 
 \LMHash{}
 If $d$ is the declaration of a library variable, top level getter or top level setter, the expression $e$ is evaluated to an object $o$. Then the setter $v=$ is invoked with its formal parameter bound to $o$. The value of the assignment expression is $o$.  
 
 \LMHash{}
 Otherwise, if $d$ is the declaration of a static variable, static getter or static setter in class $C$, then the assignment is equivalent to the assignment \code{$C.v$ = $e$}.
 
 \LMHash{}
-Otherwise, If  $a$ occurs inside a top level or static function (be it function, method, getter,  or setter) or variable initializer, evaluation of $a$ causes $e$ to be evaluated, after which a \code{NoSuchMethodError} is thrown. 
+Otherwise, if $a$ occurs inside a top level or static function (be it function, method, getter,  or setter) or variable initializer, evaluation of $a$ causes $e$ to be evaluated, after which a \code{NoSuchMethodError} is thrown. 
 
 \LMHash{}
 Otherwise, the assignment is equivalent to the assignment \code{ \THIS{}.$v$ = $e$}. 
 
 \LMHash{}
 In checked mode, it is a dynamic type error if $o$ is not \NULL{} and the interface of the class of $o$ is not a subtype of the actual type (\ref{actualTypeOfADeclaration}) of $v$.
 
 \LMHash{}
 It is a static type warning if the static type of $e$ may not be assigned to the static type of $v$. The static type of the expression $v$ \code{=} $e$ is the static type of $e$.
 
@@ skipping 823 matching lines @@
 
 \LMHash{}
 Evaluation of an identifier expression $e$ of the form $id$ proceeds as follows:
 
 
 \LMHash{}
 Let $d$ be the innermost declaration in the enclosing lexical scope whose name is $id$ or $id=$.  If no such declaration exists in the lexical scope, let $d$ be the declaration of the inherited member named $id$ if it exists. 
 %If no such member exists, let $d$ be the declaration of the static member name $id$ declared in a superclass of the current class, if it exists.
 
 \begin{itemize}
-\item if $d$ is a prefix $p$, a compile-time error occurs unless the token immediately following $d$ is \code{'.'}.
+\item if $d$ is a prefix $p$, a compile-time error occurs unless the token immediately following $d$ is \code{`.'}.
 \item If $d$ is a class or type alias $T$, the value of $e$ is an instance of  class \code{Type} (or a subclass thereof) reifying $T$.
 \item If $d$ is a type parameter $T$, then the value of $e$ is the value of the actual type argument corresponding to $T$ that was  passed to the generative constructor that created the current binding of \THIS{}. If, however, $e$ occurs inside a static member, a compile-time error occurs.
 
 %\commentary{ We are assured that \THIS{} is well defined, because if we were in a static member the reference to $T$ is a compile-time error (\ref{generics}.)}
 %\item If $d$ is a library variable then:
 %  \begin{itemize}
 %  \item If $d$ is of one of the forms \code{\VAR{} $v$ = $e_i$;} , \code{$T$ $v$ = $e_i$;} , \code{\FINAL{} $v$ = $e_i$;}  or \code{\FINAL{} $T$ $v$ = $e_i$;} and no value has yet been stored into $v$ then the initializer expression $e_i$ is evaluated. If, during the evaluation of $e_i$, the getter for $v$ is referenced, a \code{CyclicInitializationError} is thrown. If the evaluation succeeded yielding an object $o$, let $r = o$, otherwise let $r = \NULL{}$. In any case, $r$ is stored into $v$. The value of $e$ is $r$. 
  \item  If $d$ is a constant variable of one of the forms  \code{\CONST{} $v$ = $e$;} or \code{\CONST{} $T$ $v$ = $e$;} then the value $id$ is the value of the compile-time constant $e$.
 %  Otherwise
 %  \item $e$ evaluates to the current binding of $id$.  
@@ skipping 183 matching lines @@
 
 \subsection{Local Variable Declaration}
 \LMLabel{localVariableDeclaration}
 
 
 \LMHash{}
 A {\em variable declaration statement }declares a new local variable.
 
  \begin{grammar}
 {\bf localVariableDeclaration:}
-    initializedVariableDeclaration {\escapegrammar';'}
+    initializedVariableDeclaration `{\escapegrammar ;}'
   .
  \end{grammar}
  
 \LMHash{}
  Executing a variable declaration statement of one of the forms  \VAR{} $v = e;$, $T$ $v = e; $, \CONST{}  $v = e;$, \CONST{} $T$ $v = e;$, \FINAL{}  $v = e;$ or \FINAL{} $T$ $v = e;$ proceeds as follows:
  
 \LMHash{}
  The expression $e$ is evaluated to an object $o$. Then, the variable $v$ is set to $o$.
  
 \LMHash{}
@@ skipping 1515 matching lines @@
  \begin{grammar}
 {\bf type:}
       typeName typeArguments?
     .
 
 {\bf typeName:}
       qualified 
     .
 
 {\bf typeArguments:}
-      '<' typeList '>'
+      `<' typeList `>'
     .
 
 {\bf typeList:}
-      type (',' type)*
+      type (`,' type)*
     .
  \end{grammar}
 
 \LMHash{}
 A Dart implementation must provide a static checker that detects and reports exactly those situations this specification identifies as static warnings and only those situations. However:
 \begin{itemize}
 \item Running  the static checker on a program $P$ is not required for compiling and running $P$.  
 \item Running the static checker on a program $P$ must not prevent successful compilation of $P$ nor may it prevent the execution of $P$, regardless of whether any static warnings occur.
 \end{itemize}
 
@@ skipping 84 matching lines @@
 
 \begin{dartCode}
 \VAR{} i;
 i  j; //  a variable j of type i (supposedly)
 main() \{
      j =  'I am not an i'; 
 \}
 \end{dartCode}
 
 \commentary{
-Since $i$ is not a type, a static warning will be issue at the declaration of $j$. However, the program can be executed without incident in production mode because he undeclared type $i$ is treated as \DYNAMIC{}. However, in checked mode, the implicit subtype test at the assignment will trigger an error at runtime.
+Since $i$ is not a type, a static warning will be issue at the declaration of $j$. However, the program can be executed without incident in production mode because the undeclared type $i$ is treated as \DYNAMIC{}. However, in checked mode, the implicit subtype test at the assignment will trigger an error at runtime.
 }
 
 
 \commentary{
 Here is an example involving malbounded types:
 }
 
 \begin{dartCode}
 \CLASS{} I$<$T \EXTENDS{} num$>$ \{\}
 \CLASS{} J \{\}
@@ skipping 338 matching lines @@
 
 
 
 \subsection{Parameterized Types}
 \LMLabel{parameterizedTypes} 
 
 \LMHash{}
 A {\em parameterized type} is an invocation of a generic type declaration.
 
 \LMHash{}
-Let $T$ be a parameterized type  $G<S_1,  \ldots, S_n>$. If $G$ is not a generic type, the type arguments $S_i$, $1 \le i \le n$ are discarded. If $G$ has $m \ne n$ type parameters, $T$ is treated as as a parameterized type with $m$ arguments, all of which are \DYNAMIC{}. 
+Let $T$ be a parameterized type  $G<S_1,  \ldots, S_n>$. If $G$ is not a generic type, the type arguments $S_i$, $1 \le i \le n$ are discarded. If $G$ has $m \ne n$ type parameters, $T$ is treated as a parameterized type with $m$ arguments, all of which are \DYNAMIC{}. 
 
 \commentary{In short, any arity mismatch results in all type arguments being dropped, and replaced with the correct number of type arguments, all set to \DYNAMIC{}. Of course, a static warning will be issued. 
 }
 
 \LMHash{}
 Otherwise, let
  $T_i$ be the type parameters of $G$ and let $B_i$ be the bound of $T_i,  i \in 1.. n$,. $T$ is {\em malbounded} iff either $S_i$ is malbounded  or $S_i$ is not a subtype of $[S_1,  \ldots, S_n/T_1, \ldots, T_n]B_i,   i \in 1.. n$. 
  
 \commentary{
 Note, that, in checked mode, it is a dynamic type error if a malbounded type is used in a type test as specified in \ref{dynamicTypeSystem}.
@@ skipping 374 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.
 
 ----------------------------------------------------------------------