Ensure warnings are given on logical boolean expressions and for loops where booleans are expected …

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}}
 %\author{The Dart Team}
 \begin{document}
@@ skipping 715 matching lines @@
 
 {\bf declaration:}constantConstructorSignature (redirection $|$ initializers)?;
       constructorSignature (redirection $|$ initializers)?;
       \EXTERNAL{} constantConstructorSignature;
       \EXTERNAL{} constructorSignature;
       ((\EXTERNAL{} \STATIC{} ?))? getterSignature;
       ((\EXTERNAL{} \STATIC{}?))? setterSignature;
       \EXTERNAL{}? operatorSignature;
        ((\EXTERNAL{} \STATIC{}?))? functionSignature;
       \STATIC{} (\FINAL{} $|$ \CONST{}) type? staticFinalDeclarationList;
-      \CONST{} type? staticFinalDeclarationList;
+%      \CONST{} type? staticFinalDeclarationList;
       \FINAL{} type? initializedIdentifierList;
       \STATIC{}? (\VAR{} $|$ type) initializedIdentifierList
     .
 
 {\bf staticFinalDeclarationList:}
     staticFinalDeclaration (`,' staticFinalDeclaration)*
     .
 
 {\bf staticFinalDeclaration:}
       identifier `=' expression
@@ skipping 406 matching lines @@
 \commentary{The  initializer list may of course contain an initializer for any  instance variable declared by the immediately surrounding class, even if it is not final. 
 }
 
  It is a compile-time error if a  generative constructor of class \code{Object} includes a superinitializer. 
 
 Execution of a generative constructor $k$ is always done with respect to a set of bindings for its formal parameters and with  \THIS{} bound to a fresh instance $i$ and the type parameters of the immediately enclosing class bound to a set of actual type arguments $V_1, \ldots , V_m$. 
 
 \commentary{These bindings are usually determined by the instance creation expression that invoked the constructor (directly or indirectly). However, they may also be determined by a reflective call,.
 }
 
-If $k$ is redirecting, then its redirect clause has the form 
+If $k$ is redirecting then its redirect clause has the form 
 
 \THIS{}$.g(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$ 
 
 where $g$ identifies another  generative constructor of the immediately surrounding class. Then execution of $k$ proceeds by evaluating the argument list $(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$, and then executing $g$ with respect to the bindings resulting from the evaluation of $(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$ and with  \THIS{} bound to $i$ and the type parameters of the immediately enclosing class bound to $V_1, \ldots , V_m$. 
 
 Otherwise, execution  proceeds as follows:
 
 %First, a fresh instance (\ref{generativeConstructors}) $i$ of the immediately enclosing class is allocated.  Next, the instance variable declarations of the immediately enclosing class are visited in the order they appear in the program text. For each such declaration $d$, if $d$ has the form  \code{$finalConstVarOrType$ $v$ = $e$; } then the instance variable $v$ of $i$ is bound to the value of $e$ (which is necessarily a compile-time constant).
 %Next, a
 Any initializing formals declared in $k$'s parameter list are executed in the order they appear in the program text.  
@@ skipping 164 matching lines @@
 The above refers to both locally declared and inherited instance variables.
 }
 
 The superinitializer that appears, explicitly or implicitly, in the initializer list of a constant constructor must specify a constant constructor of the superclass of the immediately enclosing class or a compile-time error occurs.
 
 Any expression that appears within the initializer list of a constant constructor must be a potentially constant expression, or a compile-time error occurs. 
 
 A {\em potentially constant expression} is an expression $e$ that would be a valid constant expression if all formal parameters of $e$'s immediately enclosing constant constructor were treated as compile-time constants that were guaranteed to evaluate to an integer, boolean or string value as required by their immediately enclosing superexpression.
 
 \commentary{
+Note that a parameter that is not used in an superexpression that is restricted to certain types can be a constant of any type. For example}

[Lasse Reichstein Nielsen, 2014/03/21 08:29:00]

Long sentence. Add comma after "certain types"?

+
+\begin{dartCode}
+\CLASS{} A \{
+  \FINAL{} m;
+  \CONST{} A(this.m);
+\}
+\end{dartCode}
+
+\commentary{can be instantiated via \cd{\CONST{} A(\CONST []);}}
+
+
+
+\commentary{
 The difference between a potentially constant expression and a compile-time constant expression (\ref{const}) deserves some explanation. 
 
 The key issue is whether one treats the formal parameters of a constructor as compile-time constants. 
 
 If a constant constructor is invoked from a constant object expression, the actual arguments will be required to be compile-time constants. Therefore, if we were assured that constant constructors were always invoked from constant object expressions, we could assume that the formal parameters of a constructor were compile-time constants.
 
 However, constant constructors can also be invoked from ordinary instance creation expressions (\ref{new}), and so the above assumption is not generally valid.
 
 Nevertheless, the use of the formal parameters of a constant constructor within the constructor is of considerable utility. The concept of potentially constant expressions is introduced to facilitate limited use of such formal parameters. Specifically, we allow the usage of the formal parameters of a constant constructor for expressions that involve built-in operators, but not for constant objects, lists and maps. This allows for constructors such as:
 }
@@ skipping 528 matching lines @@
 \CLASS{} Sorter$<$T \EXTENDS{} Ordered$<$T$>>$ \{
    sort(List$<$T$>$ l) {... l[n] $<$ l[n+1] ...}
 \}
 
 \end{dartCode}
 
 \commentary{
 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}).

[Lasse Reichstein Nielsen, 2014/03/21 08:29:00]

Or a mixin?

[gbracha, 2014/03/21 21:53:23]

That is always implied. A mixin always acts as a superclass.

+\item A type parameter cannot be used as a generic.

[Lasse Reichstein Nielsen, 2014/03/21 08:29:00]

A generic what? "Generic" is generally used as an adjective in this spec. It's
not clear what it means as a noun.

[gbracha, 2014/03/21 21:53:23]

I'll add 'class" in the next rev.

 \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.
 }
 
 %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 {...}
 
@@ skipping 332 matching lines @@
 
 \commentary{
 It follows that the two boolean literals are the only two instances of \code{bool}. 
 }
 
 Invoking the getter \code{runtimeType} on a boolean literal returns the \code{Type} object that is the value of the expression \code{bool}. The static type of a boolean literal is \code{bool}.
 
 \subsubsection{Boolean Conversion}
 \label{booleanConversion}
 
-{\em Boolean conversion} maps any object $o$ into a boolean. Boolean conversion is  defined by the function 
+{\em Boolean conversion} maps any object $o$ into a boolean. Boolean conversion is  defined by the function application
 
 \begin{dartCode}
 (bool v)\{
          \ASSERT{}(v != \NULL{});
 %       \IF{} (\NULL{} == v) \{ \THROW{} \NEW{} AssertionError('null is not a bool')\};
          \RETURN{} identical(v, \TRUE{});
 \}(o)
 \end{dartCode}
 
 \rationale{
@@ skipping 1245 matching lines @@
 If all of the following hold:
 \begin{itemize}
 \item $e_1$ shows that a variable $v$ has type $T$.
 \item $v$ is not potentially mutated in $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 type warning if the type of $e_1$ may not be assigned to \code{bool}.  The static type of $c$ is the least upper bound (\ref{leastUpperBounds}) of the static type of $e_2$ and the static type of $e_3$.
+ It is a static type warning if the static type of $e_1$ may not be assigned to \code{bool}.  The static type of $c$ is the least upper bound (\ref{leastUpperBounds}) of the static type of $e_2$ and the static type of $e_3$.
   
 
 \subsection{ Logical Boolean Expressions}
 \label{logicalBooleanExpressions}
 
 The logical boolean expressions combine boolean objects using the boolean conjunction and disjunction operators.
 
 \begin{grammar}
 {\bf logicalOrExpression:}
       logicalAndExpression (`$||$' logicalAndExpression)*
@@ skipping 21 matching lines @@
 \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$.
 
-The static type of a logical boolean expression is \code{bool}.
+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}.
 
      
  \subsection{ Equality}
  \label{equality}
  
 Equality expressions test objects for equality.
 
  \begin{grammar}
 {\bf equalityExpression:}relationalExpression (equalityOperator relationalExpression)?;
       \SUPER{} equalityOperator relationalExpression
@@ skipping 331 matching lines @@
  {\bf IDENTIFIER\_NO\_DOLLAR:}
       IDENTIFIER\_START\_NO\_DOLLAR IDENTIFIER\_PART\_NO\_DOLLAR*
     .
 
 {\bf IDENTIFIER:}
       IDENTIFIER\_START IDENTIFIER\_PART*
     .
 
 {\bf BUILT\_IN\_IDENTIFIER:} \ABSTRACT{};
      \AS{};
-%     \ASSERT{};
      \DEFERRED{};
      \DYNAMIC{};
      \EXPORT{};
      \EXTERNAL{};
      \FACTORY{};
      \GET{};
      \IMPLEMENTS{};
      \IMPORT{};
      \LIBRARY{};
      \OPERATOR{};
      \PART{};
       \SET{};
       \STATIC{};
      \TYPEDEF{}
     .
 
  {\bf IDENTIFIER\_START:}IDENTIFIER\_START\_NO\_DOLLAR;
-      '\$'
+      `\$'
     .
 
 {\bf IDENTIFIER\_START\_NO\_DOLLAR:}LETTER;
-      '\_'
+      `\_'
     .
 
 {\bf  IDENTIFIER\_PART\_NO\_DOLLAR:}IDENTIFIER\_START\_NO\_DOLLAR;
       DIGIT
     .
 
 
 {\bf IDENTIFIER\_PART:}IDENTIFIER\_START;
       DIGIT
     .
@@ skipping 384 matching lines @@
 The expression $[v^{\prime\prime}/v]e$ is evaluated, and the process recurses at step
   \ref{beginFor}.
 \end{enumerate}
 
 \rationale{
 The definition above is intended to prevent the common error where users create a closure inside a for loop, intending to close over the current binding of the loop variable, and find (usually after a painful process of debugging and learning) that all the created closures have captured the same value - the one current in the last iteration executed.
 
 Instead, each iteration has its own distinct variable.  The first iteration uses the variable created by the initial declaration. The expression executed at the end of each iteration uses a fresh variable $v^{\prime\prime}$, bound to the value of the current iteration variable, and then modifies $v^{\prime\prime}$ as required for the next iteration.
 }
 
-
+It is a static warning if the static type of $c$ may not be assigned to \cd{bool}.
 
 %A for statement of the form \code{ \FOR{} ($d$ ; $c$; $e$) $s$} is equivalent to the the following code:
 
 %\code{
 %\{$d$;
 %\WHILE{} ($c$) \{
 %   \{$s$\}
 %   $e$;
 %\}\}
 %}
@@ skipping 26 matching lines @@
 \begin{grammar}
 {\bf whileStatement:}
       \WHILE{} `(' expression `)' statement  % could do top level here, and in for
 .
  \end{grammar}
  
  Execution of a while statement of the form \code{\WHILE{} ($e$) $s$;} proceeds as follows: 
 
 The expression $e$ is evaluated to an object $o$. Then, $o$ is  subjected to boolean conversion (\ref{booleanConversion}), producing an object $r$.  If $r$ is \TRUE{}, then the statement $\{s\}$ is executed and then the while statement is re-executed recursively. If $r$ is \FALSE{}, execution of the while statement is complete.
 
-It is a static type warning if the type of $e$ may not be assigned to \code{bool}.
+It is a static type warning if the static type of $e$ may not be assigned to \code{bool}.
     
 
 \subsection{Do}
 \label{do}
 
 The do statement supports conditional iteration, where the condition is evaluated after the loop.
 
 \begin{grammar}
 {\bf doStatement:}
     \DO{} statement \WHILE{} `(' expression `)' `{\escapegrammar ;}'% could do top level here
       .
  \end{grammar}
 
     
 Execution of a do statement of the form \code{\DO{} $s$ \WHILE{} ($e$);} proceeds as follows: 
 
 The statement $\{s\}$ is executed. Then, the expression $e$ is evaluated to an object $o$. Then, $o$ is  subjected to boolean conversion (\ref{booleanConversion}), producing an object $r$. If $r$ is \FALSE{}, execution of the do statement is complete. If $r$ is \TRUE{}, then the do statement is re-executed recursively. 
 
-It is a static type warning if the type of $e$ may not be assigned to \code{bool}. 
+It is a static type warning if the static type of $e$ may not be assigned to \code{bool}. 
 
 \subsection{Switch}
 \label{switch}
 
 The {\em switch statement} supports dispatching control among a large number of cases.
 
  \begin{grammar}
 {\bf switchStatement:}
       \SWITCH{} `(' expression `)' `\{' switchCase* defaultCase? `\}'% could do top level here and in cases
     .
@@ skipping 460 matching lines @@
  \begin{grammar}
 {\bf topLevelDefinition:}classDefinition;
 %      classDefinitionOrInterfaceInjection;
 %      interfaceDefinitionOrInterfaceInjection;
  %     mixinApplication;
       typeAlias;
       \EXTERNAL{}? functionSignature `{\escapegrammar ;}';
       \EXTERNAL{}? getterSignature `{\escapegrammar ;}';
       \EXTERNAL{}? setterSignature `{\escapegrammar ;}';      
       functionSignature functionBody;
-      returnType? getOrSet identifier formalParameterList functionBody;
+      returnType? \GET{} identifier functionBody;
+      returnType? \SET{} identifier formalParameterList functionBody;
       (\FINAL{} $|$ \CONST{}) type? staticFinalDeclarationList `{\escapegrammar ;}';
       variableDeclaration `{\escapegrammar ;}'
     .
     
     {\bf getOrSet:} \GET{};
       \SET{}
     .
 
 %    classDefinitionOrInterfaceInjection:
  %     classDefinition;
@@ skipping 974 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}