Clarify that when a local variable hides a type before it is declared, it is stilla compile-time er…

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 Draft Version 0.71}}
 \author{The Dart Team}
 \begin{document}
@@ skipping 797 matching lines @@
 
 We say that a variable $v$ is {\em potentially mutated} in some scope $s$ if $v$ is not final or constant and an assignment to $v$ occurs in $s$.
 
 If a variable declaration does not explicitly specify a type, the type of the declared variable(s) is  \DYNAMIC{}, the unknown type (\ref{typeDynamic}). 
 
 Static and instance variable declarations always induce implicit getters and setters.
 The scope into which the implicit getters and setters are introduced depends on the kind of variable declaration involved. 
 
 A library variable introduces a getter and a setter into the top level scope of the enclosing library. A static class variable introduces a static getter and a static setter into the immediately enclosing class. An instance variable introduces an instance getter and an instance setter into the immediately enclosing class. 
 
-Local variables are added to the innermost enclosing scope.  They do not induce getters and setters.  A local variable may only be referenced at a source code location that is after its initializer, if any, is complete, or a a compile-time error occurs. 
+Local variables are added to the innermost enclosing scope.  They do not induce getters and setters.  A local variable may only be referenced at a source code location that is after its initializer, if any, is complete, or a compile-time error occurs.  The error may be reported either at the point where the premature reference occurs, or at the variable declaration.
+
+\rationale {
+We allow the error to be reported at the declaration to allow implementations to avoid an extra processing phase. 

[hausner, 2013/10/18 23:09:23]

True. But it is more important that the error is a compile-time error (vs.
runtime error) than where it is reported. The compiler can easily remember where
a name is first used and report the error there. However, if "reference before
declaration" is a runtime error, we would have to go back and potentially patch
all uses of the name if a shadowing declaration is found later.

+}
 
 \commentary{
 The example below illustrates the expected behavior.  A variable $x$ is declared at the library level, and another $x$ is declared inside the function $f$.
 }
 
 \begin{dartCode}
 \VAR{} x = 0;
 
 f(y) \{
   \VAR{} z = x; // compile-time error 
   if (y) \{
     x = x + 1; // two compile time errors
     print(x); // compile time error
   \}
  \VAR{} x = x++; // compile time error
  print(x);
 \}
 \end{dartCode}
 
 \commentary{
 The declaration inside $f$ hides the enclosing one.  So all references to $x$ inside $f$ refer to the inner declaration of $x$. However, many of these references are illegal, because they appear before the declaration. The assignment to $z$ is one such case. The assignment to $x$ in the \IF{} statement suffers from multiple problems. The right hand side reads $x$ before its declaration, and the left hand side assigns to $x$ before its declaration. Each of these are, independently, compile time errors.  The print statement inside the \IF{} is also illegal.
 
 The inner declaration of $x$ is itself erroneous because its right hand side attempts to read $x$ before the declaration has terminated.  The left hand side is not, technically, a reference or an assignment but a declaration and so is legal.  The last print statement is perfectly legal as well.
 }
 
 \commentary {
-As another example  \code{var x = 3, y = x;} is legal, because \code{x} is referenced after its initializer. 
+As another example  \code{\VAR{} x = 3, y = x;} is legal, because \code{x} is referenced after its initializer. 
 
+A particularly perverse example involves a local variable name shadowing a type. This is possible because Dart has a single namespace for types, functions and variables.
 }
 
+\begin{dartCode}
+\CLASS{} C \{\}
+perverse() \{
+   \VAR{} v = \NEW{} C(); // compile-time error
+   \C aC; // compile-time error
+   \VAR{} C = 10;
+\}
+
+\commentary {
+ Inside \cd{perverse()} \cd{C} denotes a local variable. The type \cd{C} is hidden by the variable of the same name. The attempt to instantiate \cd{C} causes a compile-time error because it references a local variable prior to its declaration. Similarly, for the declaration of \cd{aC} (even though it is only a type annotation).
+}
+
+\end{dartCode}
+
 % the grammar does not support local getters and setters. The local var discussion does not seem to mention getters and setters based semantics. It simply discusses the creation of the variable, not its access. Access is either assignment or identifiers. Identifiers ignore the getter story. 
 
 The following rules apply to all static and instance variables.
 
 A  variable declaration  of one of the forms \code{$T$ $v$;},  \code{$T$ $v$ = $e$;} ,  \code{\CONST{} $T$ $v$ = $e$;}, \code{\FINAL{} $T$ $v$;}  or \code{\FINAL{} $T$ $v$ = $e$;} always induces an implicit  getter function (\ref{getters}) with signature 
 
 $T$ \GET{} $v$
 
 whose invocation evaluates as described below (\ref{evaluationOfImplicitVariableGetters}).
 
@@ skipping 602 matching lines @@
 %\VOID{} \SET{} $v=(T$ $x)$
 
 %whose execution sets the value of $v$ to the incoming argument $x$.
 
 %A non-final instance variable declaration  of the form \code{\VAR{} $v$;} or the form  \code{\VAR{} $v$ = $e$;}   always induces an implicit setter function with signature 
 
 %\SET{} $v=(x)$
 
 %whose execution sets the value of $v$ to the incoming argument $x$.
 
-% It is a compile-time error/warning if a a class $C$ declares a final instance variable $v$ and $C$ inherits a setter $v=$.
+% It is a compile-time error/warning if a class $C$ declares a final instance variable $v$ and $C$ inherits a setter $v=$.
 
 
 \subsection{Constructors}
 \label{constructors}
 
 A {\em constructor} is a special function that is used in instance creation expressions (\ref{instanceCreation}) to produce objects. Constructors may be generative (\ref{generativeConstructors}) or they may be factories (\ref{factories}). 
 
 A {\em constructor name} always begins with the name of its immediately enclosing class, and may optionally be followed by a dot and an identifier $id$. It is a compile-time error if $id$ is the name of a member  declared in the immediately enclosing class. It is a compile-time error if the name of a  constructor is not a constructor name. 
 
 
@@ skipping 4649 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}