ECMA modifications and minor fixes since.

docs/language/dartLangSpec.tex

 \documentclass{article}
 \usepackage{epsfig}
 \usepackage{dart}
 \usepackage{bnf}
 \usepackage{hyperref}
 \newcommand{\code}[1]{{\sf #1}}
 \title{Dart Programming Language  Specification \\
-{\large Version 1.3}}
+{\large Version 1.4}}
 %\author{The Dart Team}
 \begin{document}
 \maketitle
 \tableofcontents
 
 
 \newpage
 
 \pagestyle{myheadings}
 \markright{Dart Programming Language Specification}
@@ skipping 1033 matching lines @@
 \label{generativeConstructors}
 
 A {\em generative constructor} consists of a constructor name, a constructor parameter list, and either a redirect clause or an  initializer list and an optional body.
 
 \begin{grammar}
 {\bf constructorSignature:}
       identifier (`{\escapegrammar .}' identifier)? formalParameterList
     .
  \end{grammar}
 
-A {\em constructor parameter list} is a parenthesized, comma-separated list of formal constructor parameters. A {\em formal constructor parameter} is either a formal parameter (\ref{formalParameters}) or an initializing formal. An {\em initializing formal} has the form \code{\THIS{}.id}, where \code{id} is the name of an instance variable of the immediately enclosing class. It is a compile-time error if an initializing formal is used by a function other than a non-redirecting generative constructor. 
+A {\em constructor parameter list} is a parenthesized, comma-separated list of formal constructor parameters. A {\em formal constructor parameter} is either a formal parameter (\ref{formalParameters}) or an initializing formal. An {\em initializing formal} has the form \code{\THIS{}.id}, where \code{id} is the name of an instance variable of the immediately enclosing class.  It is a compile-time error if \code{id} is not an instance variable of the immediately enclosing class. It is a compile-time error if an initializing formal is used by a function other than a non-redirecting generative constructor. 
 
 If an explicit type is attached to the initializing formal, that is its static type. Otherwise, the type of an initializing formal named \code{id} is $T_{id}$, where $T_{id}$ is the type of the field named \code{id} in the immediately enclosing class. It is a static warning if the static type of \code{id} is not assignable to $T_{id}$.
 
 Using an initializing formal \code{\THIS{}.id} in a formal parameter list does not introduce a formal parameter name into the scope of the constructor. However, the initializing formal does effect the type of the constructor function exactly as if a formal parameter  named \code{id}  of the same type were introduced in the same position. 
 
 Initializing formals are executed during the execution of generative constructors detailed below. Executing an initializing formal  \code{\THIS{}.id} causes the field \code{id} of the immediately surrounding class to be assigned the value of the corresponding actual parameter, unless $id$ is a final variable that has already been initialized, in which case a runtime error occurs.
 
 
 \commentary{
 The above rule allows initializing formals to be used as optional parameters:
@@ skipping 834 matching lines @@
 Even where type parameters are in scope there are numerous restrictions at this time:
 \begin{itemize}
 \item A type parameter cannot be used to name a constructor in an instance creation expression (\ref{instanceCreation}).
 \item A type parameter cannot be used as a superclass or superinterface (\ref{superclasses}, \ref{superinterfaces}, \ref{interfaceSuperinterfaces}).
 \item A type parameter cannot be used as a generic type.
 \end{itemize}
 
 The normative versions of these  are given in the appropriate sections of this specification. Some of these restrictions may be lifted in the future.
 }
 
+%The {\em induced type set}, $S$, of a parameterized type $T$ is the set consisting of 
+%\begin{itemize}
+%\item The supertypes of any type in $S$.
+%\item The type arguments of any parameterized type in $S$.
+%\end{itemize}
 
+%Let $P$ be the instantiation of a generic type with its own type parameters. It is a compile-time error if the induced type set of $P$ is not finite.
+
+%\rationale {A typical recursive type declaration such as}
+
+%\begin{dartCode}
+%\CLASS{} B$<$S$>$ \{\}
+%\CLASS{} D$<$T$>$ \EXTENDS{} B$<$D$<$T$>>$ \{\}
+%\end{dartCode}
+
+%\rationale{
+%poses no problem under this rule. The instantiation \cd{D$<$T$>$} has an induced
+%set consisting of: \cd{B$<$D$<$T$>>$, Object, D$<$T$>$, T}. However, the following variant
+%}
+
+%\begin{dartCode}
+%\CLASS{} B$<$S$>$ \{\}
+%\CLASS{} D$<$T$>$ \EXTENDS{} B$<$D$<$D$<$T$>>>$ \{\}
+%\end{dartCode}
+
+%\rationale{
+%is disallowed. Consider again the instantiation \cd{D$<$T$>$}. It leads to the
+%superclass \cd{B$<$D$<$D$<$T$>>>$}, and so adds \cd{D$<$D$< $T$>>$} to the induced set. The latter in turn leads to  \cd{B$<$D$<$D$<$D$<$T$>>>>$} and \cd{D$<$D$<$D$<$T$>>>$}
+%and so on ad infinitum.}
+
+%\commentary{
+%The above requirement does not preclude the use of arbitrary recursive types in the body of a generic class. }
 %A generic has a type parameter scope. The enclosing scope of a type parameter scope of a generic G  is the enclosing scope of G.
 
 
 %class T {...}
 
 %class G<T> extends T;
 
 %By current rules, this is illegal. Make sure we preserve this.
 
 
@@ skipping 638 matching lines @@
         % identifier `{\escapegrammar :}' expression;
         expression `{\escapegrammar :}' expression 
     .
 \end{grammar}
 
 A {\em map literal} consists of zero or more entries. Each entry has a {\em key} and a {\em value}.  Each key and each value is denoted by an expression. 
  
 If a map literal begins with the reserved word \CONST{}, it is a {\em constant map literal} which is a compile-time constant (\ref{constants}) and therefore evaluated at compile-time. Otherwise, it is a {\em run-time map literal} and it is evaluated at run-time. Only run-time map literals can be mutated
 after they are created. Attempting to mutate a constant map literal will result in a dynamic error.
 
-It is a compile-time error if either a key or a value of an entry in a constant map literal is not a compile-time constant. It is a compile-time error if the key of an entry in a constant map literal is an instance of a class that implements the operator $==$ unless the key is a string or integer. It is a compile-time error if the type arguments of a constant map literal include a type parameter. 
+It is a compile-time error if either a key or a value of an entry in a constant map literal is not a compile-time constant. It is a compile-time error if the key of an entry in a constant map literal is an instance of a class that implements the operator $==$ unless the key is a 
+%symbol, 
+string, an integer, literal symbol or the result of invoking a constant constructor of class \cd{Symbol}. It is a compile-time error if the type arguments of a constant map literal include a type parameter. 
 
 The value of a constant map literal  \CONST{}$ <K, V>\{k_1:e_1\ldots k_n :e_n\}$ is an object $m$ whose class implements the built-in class $Map<K, V>$. The entries of $m$ are $u_i:v_i, i \in 1 .. n$, where $u_i$ is the value of the compile-time expression $k_i$ and $v_i$ is the value of the compile-time expression $e_i$.  The value of a constant map literal  \CONST{} $\{k_1:e_1\ldots k_n :e_n\}$ is defined as the value of a constant map literal \CONST{} $<\DYNAMIC{}, \DYNAMIC{}>\{k_1:e_1\ldots k_n :e_n\}$.
 
 Let $map_1 =$ \CONST{}$ <K, V>\{k_{11}:e_{11} \ldots k_{1n} :e_{1n}\}$ and  $map_2 =$  \CONST{}$ <J, U>\{k_{21}:e_{21} \ldots k_{2n} :e_{2n}\}$ be two constant map literals. Let the keys of $map_1$ and $map_2$ evaluate to  $s_{11} \ldots  s_{1n}$  and   $s_{21} \ldots  s_{2n}$ respectively, and let the elements of $map_1$ and $map_2$ evaluate to $o_{11} \ldots  o_{1n}$ and $o_{21} \ldots  o_{2n}$ respectively. Iff \code{identical($o_{1i}$, $o_{2i}$)}  and \code{identical($s_{1i}$, $s_{2i}$)} for $i \in 1.. n$, and $K = J, V = U$ then \code{identical($map_1$, $map_2$)}. 
 
 \commentary{In other words, constant map literals are canonicalized.}
 
 A runtime map literal $<K, V>\{k_1:e_1\ldots k_n :e_n\}$  is evaluated as follows:
 \begin{itemize}
 \item
@@ skipping 519 matching lines @@
 
 Let $T_i$ be the static type of $a_i$, let $S_i$ be the type of $p_i, i \in 1 .. h+k$ and let $S_q$ be the type of the named parameter $q$ of $f$.  It is a static warning if $T_j$ may not be assigned to $S_j, j \in 1..m$.  It is a static warning if $m < h$ or if $m > n$. Furthermore, each $q_i, 1 \le i \le l$,  must have a corresponding named parameter in the set $\{p_{n+1}, \ldots, p_{n +k}\}$ or a static warning occurs.  It is a static warning if $T_{m+j}$ may not be assigned to $S_{q_j}, j \in 1 .. l$.
 
 \subsubsection{ Unqualified Invocation}
 \label{unqualifiedInvocation}
 
 An unqualified function invocation $i$ has the form 
 
 $id(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$, 
 
-where $id$ is an identifier. 
+where $id$ is an identifier or an identifier qualified with a library prefix. 
 
 If there exists a lexically visible declaration named $id$, let $f_{id}$ be the innermost such declaration. Then:
 \begin{itemize}
 \item
  If $f_{id}$ is a local function, a library function, a library or static getter or a variable then $i$ is interpreted as a function expression invocation (\ref{functionExpressionInvocation}).
  \item
 Otherwise, if $f_{id}$ is a static method of the enclosing class $C$, $i$ is equivalent to $C.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$.
 \item Otherwise, $f_{id}$ is considered equivalent to the ordinary method invocation $\THIS{}.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$.
 \end{itemize}
 
 %Otherwise, if there is an accessible (\ref{privacy}) static method named $id$ declared in a superclass $S$ of the immediately enclosing class $C$ then i is equivalent to the static method invocation $S.id(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$.  
 
 %\rationale{
 %Unqualified access to static methods of superclasses is inconsistent with the idea that static methods are not inherited. It is not particularly necessary and  may be restricted in future versions.
 %}
 
 Otherwise, if $i$ occurs inside a top level or static function (be it function, method, getter,  or setter) or variable initializer, evaluation of $i$ causes a \cd{NoSuchMethodError} to be thrown.
 
 If $i$ does not occur inside a top level or static function, $i$ is equivalent to $\THIS{}.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$.
 
+% Should also say:
+% It is a static warning if $i$  occurs inside a top level or static function (be it function, method, getter,  or setter) or variable initializer and there is no lexically visible declaration named $id$ in scope.
+
+
+
 
 
 \subsubsection{ Function Expression Invocation}
 \label{functionExpressionInvocation}
 
 A function expression invocation $i$ has the form 
 
 $e_f(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$, 
 
 where $e_f$ is an expression. If $e_f$ is an identifier $id$, then $id$ must necessarily denote a local function, a library function, a library or static getter or a variable as described above, or $i$ is not considered a function expression invocation. If $e_f$ is a property extraction expression (\ref{propertyExtraction}), then $i$ is is not a function expression invocation and is instead recognized as an ordinary method invocation (\ref{ordinaryInvocation}). 
@@ skipping 396 matching lines @@
 
 
 {\bf logicalAndExpression:}
       equalityExpression (`\&\&' equalityExpression)*
 %      bitwiseOrExpression (`\&\&' bitwiseOrExpression)*
     .
  \end{grammar}
  
 A {\em logical boolean expression} is either an equality expression (\ref{equality}), or an invocation of a logical boolean operator on an expression $e_1$ with argument $e_2$.
  
-Evaluation of a logical boolean expression $b$ of the form $e_1 || e_2$ causes the evaluation of $e_1$; if $e_1$ evaluates to true, the result of evaluating $b$ is true, otherwise $e_2$ is evaluated to an object $o$, which is then subjected to boolean conversion (\ref{booleanConversion}) producing an object $r$, which is the value of $b$. 
+Evaluation of a logical boolean expression $b$ of the form $e_1 || e_2$ causes the evaluation of $e_1$ and then subjected to boolean conversion, yielding an object $o_1$; if $o_1$ is true, the result of evaluating $b$ is true, otherwise $e_2$ is evaluated to an object $o_2$, which is then subjected to boolean conversion (\ref{booleanConversion}) producing an object $r$, which is the value of $b$. 
 
-Evaluation of a logical boolean expression $b$ of the form $e_1 \&\& e_2$ causes the evaluation of $e_1$; if $e_1$ does not evaluate to true, the result of evaluating $b$ is false, otherwise $e_2$ is evaluated to an object $o$, which is then subjected to boolean conversion producing an object $r$, which is the value of $b$. 
+Evaluation of a logical boolean expression $b$ of the form $e_1 \&\& e_2$ causes the evaluation of $e_1$ and then subjected to boolean conversion, yielding an object $o_1$; if $o_1$ is not  true, the result of evaluating $b$ is false, otherwise $e_2$ is evaluated to an object $o_2$, which is then subjected to boolean conversion producing an object $r$, which is the value of $b$. 
 
 A logical boolean expression $b$ of the form $e_1 \&\& e_2$ shows that a variable $v$ has type 
 $T$ if all of the following conditions hold:
 \begin{itemize}
 \item Either $e_1$ shows that $v$ has type $T$ or $e_2$ shows that $v$ has type $T$.
 \item $v$ is a local variable or formal parameter.
 \item The variable $v$ is not mutated in $e_2$ or within a closure.
 \end{itemize}
 
 Furthermore, if all of the following hold:
 \begin{itemize}
 \item $e_1$ shows that $v$ has type $T$.
 \item $v$ is not mutated in either $e_1$, $e_2$ or within a closure.
 \item If the variable $v$ is accessed by a closure in $e_2$ then the variable $v$ is not potentially mutated anywhere in the scope of $v$. 
 \end{itemize}
 then the type of $v$ is known to be $T$ in $e_2$.
 
-It is a static warning if the static types of both $e_1$ and $e_2$ may not be assigned to \cd{bool}. The static type of a logical boolean expression is \code{bool}.
+It is a static warning if the static type of $e_1$ may not be assigned to \cd{bool} or if the static type of $e_2$ may not be assigned to \cd{bool}. The static type of a logical boolean expression is \code{bool}.
 
      
  \subsection{ Equality}
  \label{equality}
  
 Equality expressions test objects for equality.
 
  \begin{grammar}
 {\bf equalityExpression:}relationalExpression (equalityOperator relationalExpression)?;
       \SUPER{} equalityOperator relationalExpression
@@ skipping 876 matching lines @@
  it is a compile-time error if the expressions $e_k$ are not compile-time constants for all  $k \in 1..n$.  It is a compile-time error if the values of the expressions $e_k$ are not either:
  \begin{itemize}
  \item instances of the same class $C$, for all $k \in 1..n$,  or 
  \item instances of a class that implements \cd{int}, for all $k \in 1..n$,  or 
  \item instances of a class that implements \cd{String}, for all $k \in 1..n$. 
  \end{itemize}
  
 \commentary{In other words,  all the expressions in the cases evaluate to constants of the exact same user defined class or are of certain known types.  Note that the values of the expressions are known at compile-time, and are independent of any static type annotations.
 }
 
-It is a compile-time error if the class $C$ has an implementation of the operator $==$ other than the one inherited from \code{Object} unless the value of the expression is a string or an integer.
+It is a compile-time error if the class $C$ has an implementation of the operator $==$ other than the one inherited from \code{Object} unless the value of the expression is a string, an integer, literal symbol or the result of invoking a constant constructor class \cd{Symbol}.
  
  \rationale{
  The prohibition on user defined equality allows us to implement the switch efficiently for user defined types. We could formulate matching in terms of identity instead with the same efficiency. However, if a type defines an equality operator, programmers would find it quite surprising that equal objects did not match.
  
  }
 
 \commentary{
 The \SWITCH{}  statement should only be used in very limited situations (e.g., interpreters or scanners).  
 }
 
@@ skipping 223 matching lines @@
 
 The statement $s_1$ is executed in the dynamic scope of the exception handler defined by the try statement. Then, the \FINALLY{} clause is executed.
 
 \commentary{
 Whether any of the \ON{}-\CATCH{} clauses is executed depends on whether a matching exception has been raised by $s_1$ (see the specification of the throw statement). 
 
 If $s_1$ has raised an exception, it will transfer control to the try statement's handler, which will examine the catch clauses in order for a match as specified above. If no matches are found, the handler will execute the \FINALLY{} clause. 
 
 If a matching \ON{}-\CATCH{} was found, it will execute first, and then the \FINALLY{} clause will be executed. 
 
-If an exception is raised during execution of an \ON{}-\CATCH{} clause, this will transfer control to the handler for the \FINALLY{} clause, causing the \FINALLY{} clause to execute in this case as well. 
+If an exception is thrown during execution of an \ON{}-\CATCH{} clause, this will transfer control to the handler for the \FINALLY{} clause, causing the \FINALLY{} clause to execute in this case as well. 
 
 If no exception was raised, the \FINALLY{} clause is also executed. Execution of the \FINALLY{} clause could also raise an exception, which will cause transfer of control to the next enclosing handler. 
 }
 
 A try statement of the form \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$;} is equivalent to the statement \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$ \FINALLY{} $\{\}$;}.
  
 
 \subsection{ Return}
 \label{return}
 
@@ skipping 318 matching lines @@
 
 \rationale {
 Whereas normal conflicts are resolved at deployment time, the functionality of \code{dart:} libraries is injected into an application at run time, and may vary over time as browsers are upgraded.  Thus, conflicts with \code{dart:} libraries can arise at runtime, outside the developerÕs control. To avoid breaking deployed applications in this way, conflicts with the \code{dart:} libraries are treated specially.
 
 It is recommended that tools that deploy Dart code produce output in which all imports use show clauses to ensure that additions to the namespace of a library never impact deployed code.
 }
 
 If a name $N$ is referenced by a library $L$ and $N$ is  introduced into  the top level scope of $L$ by more than one import, and not all the imports denote the same declaration, then:
 \begin{itemize}
 \item A static warning occurs.
-\item If $N$ is referenced as a function, getter or setter, a \code{NoSuchMethodError} is raised. 
+\item If $N$ is referenced as a function, getter or setter, a \code{NoSuchMethodError} is thrown. 
 \item  If $N$ is referenced as a type, it is treated as a malformed type.
 
 \end{itemize}
 
 We say that the namespace $NS$ {\em has been imported into} $L$.
 
 \commentary{
 It is neither an error nor a warning if  $N$ is introduced by two or more imports but never referred to.
 }
 
@@ skipping 549 matching lines @@
 \rationale{From a usability perspective, we want to ensure that the checker does not issue errors everywhere an unknown type is used. The definitions above ensure that no secondary errors are reported when accessing an unknown type. 
 
 The current rules say that missing type arguments are treated as if they were the type  \DYNAMIC{}.  An alternative is to consider them as meaning \code{Object}.  This would lead to earlier error detection in checked mode, and more aggressive errors during static typechecking. For example:
 
 (1)  \code{typedAPI(G\lt{String}\gt g)\{...\}} 
 
 
 (2)  \code{typedAPI(new G()); }
 
 
-Under the alternative rules, (2) would cause a runtime error in checked mode. This seems desirable from the perspective of error localization. However, when a dynamic error is raised at (2), the only way to keep running is rewriting (2) into
+Under the alternative rules, (2) would cause a runtime error in checked mode. This seems desirable from the perspective of error localization. However, when a dynamic error is thrown at (2), the only way to keep running is rewriting (2) into
 
 (3) \code{typedAPI(new G\lt{String}\gt());}
 
 This forces users to write type information in their client code just because they are calling a typed API.  We do not want to impose this on Dart programmers, some of which may be blissfully unaware of types in general, and genericity in particular.
 
 What of static checking? Surely we would want to flag (2) when users have explicitly asked for static typechecking? Yes, but the reality is that the Dart static checker is likely to be running in the background by default. Engineering teams typically desire a ``clean build'' free of warnings and so the checker is designed to be extremely charitable. Other tools can interpret the type information more aggressively and warn about violations of conventional (and sound) static type discipline.
 }
 
 The name \DYNAMIC{} denotes a \cd{Type} object even though \DYNAMIC{} is not a class.
 
@@ skipping 254 matching lines @@
 \item The names of compile time constant variables never use lower case letters. If they consist of multiple words, those words are separated by underscores. Examples: PI,  I\_AM\_A\_CONSTANT.
 \item The names of functions (including getters, setters, methods and local or library functions) and non-constant variables begin with a lowercase letter. If the name consists of multiple words, each  word (except the first) begins with an uppercase letter.  No other uppercase letters are used. Examples: camlCase, dart4TheWorld
 \item The names of types (including classes and type aliases) begin with an upper case letter.  If the name consists of multiple words, each  word  begins with an uppercase letter.  No other uppercase letters are used. Examples: CamlCase, Dart4TheWorld.
 \item The names of type variables are short (preferably single letter). Examples: T, S, K, V , E.
 \item The names of libraries or library prefixes never use upper case letters. If they consist of multiple words, those words are separated by underscores. Example: my\_favorite\_library.
 \end{itemize}
 }
 
 
 \end{document}