Change how the language specification describes control flow.

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 306 matching lines @@
 a program that interfaces between the engine and the surrounding computing environment. The embedder will often be a web browser, but need not be; it may be a C++ program on the server for example. When an isolate fails with a compile-time error as described above, control returns to the embedder, along with an exception describing the problem.  This is necessary so that the embedder can clean up resources etc. It is then the embedder's decision whether to terminate the isolate or not.
 }
 
 \LMHash{}
 {\em Static  warnings} are those errors reported by the static checker. They have no effect on execution. Many, but not all, static warnings relate to types, in which case they are known as {\em static type warnings.} Static warnings must be provided by Dart compilers used during development such as those incorporated in IDEs or otherwise intended to be used by developers for developing code. Compilers that are part of runtime execution environments such as virtual machines should not issue static warnings.
 
 \LMHash{}
 {\em Dynamic type errors} are type errors reported in checked mode.
 
 \LMHash{}
-{\em Run-time errors} are exceptions raised during execution. Whenever we say that an exception $ex$ is {\em raised} or {\em thrown}, we mean that a throw expression  (\ref{throw}) of the form: \code{\THROW{} $ex$;} was implicitly evaluated or that a rethrow statement (\ref{rethrow}) of the form \code{\RETHROW} was executed. When we say that {\em a} $C$ {\em is thrown}, where $C$ is a class, we mean that an instance of class $C$ is thrown. When we say that a stream raises an exception, we mean that an exception occurred while computing the value(s) of the stream.
+{\em Run-time errors} are exceptions raised during execution. Whenever we say that an exception $ex$ is {\em raised} or {\em thrown}, we mean that a throw expression  (\ref{throw}) of the form: \code{\THROW{} $ex$;} was implicitly evaluated or that a rethrow statement (\ref{rethrow}) of the form \code{\RETHROW} was executed. When we say that {\em a} $C$ {\em is thrown}, where $C$ is a class, we mean that an instance of class $C$ is thrown. When we say that a stream raises an exception, we mean that the stream emits the exception and its associated stack trace as an error event.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

I'd be quite happy if we only every said "raised" or else "thrown" and never
mixed the two.  It's a bit circular to use "an exception was thrown" here and
"throw an exception" as a possible outcome of expression evaluation.

I don't know in what context "an exception $ex$ is raised" can mean that a
rethrow statement was executed, so this at least needs to be more specific.

I prefer to just say directly here what happens when an exception is raised and
then just say that 'throw' does that thing, rather than saying here that raising
an exception is implicitly evaluating an expression and putting the details in
the evaluation of throw.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

I thought about removing the `rethrow` part, but apparently forgot.

The only reason I didn't rewrite this to directly say that it "throws expression
and stack trace as if an expression has thrown" was that I then also needed to
duplicate the part about creating a stack trace corresponding to the current
state..
(This comment is probably already about as long as that, so that one saving
didn't pay for itself).

I'll remove "raise" and just use "throw", and rewrite this section.

 
 \LMHash{}
 If an uncaught exception is thrown by a running isolate $A$, $A$ is immediately suspended.
 
 
 \section{Variables}
 \LMLabel{variables}
 
 \LMHash{}
 Variables are storage locations in memory.
@@ skipping 869 matching lines @@
 
 % The enclosing scope of a generative constructor is the instance scope of the class in which it is declared (but what about redirecting?)
 
 \LMHash{}
 Iff no constructor is specified for a class $C$, it implicitly has a default constructor \code{C() : \SUPER{}() \{\}}, unless $C$ is class \code{Object}.
 
 \subsubsection{Generative Constructors}
 \LMLabel{generativeConstructors}
 
 \LMHash{}
-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.
+A {\em generative constructor} is executed to initialize a freshly allocated object.
+It 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}
 
 \LMHash{}
 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.
 
@@ skipping 51 matching lines @@
 
 \LMHash{}
 A generative constructor may be {\em redirecting}, in which case its only action is to invoke another generative constructor.  A redirecting constructor has no body; instead, it has a redirect clause that specifies which constructor the invocation is redirected to, and with what arguments.
 
 \begin{grammar}
 {\bf redirection:}
      `{\escapegrammar :}' \THIS{} (`{\escapegrammar .}' identifier)? arguments
     .
 \end{grammar}
 
+A redirecting generative constructor is executed to initialize an object $o$ as
+follows:
+
+Let $C$ be the class containing the redirecting generative constructor.
+Let $k$ the target generative constructor specified by either \THIS{} (the constructor named $C$) or $\THIS{}.id$ (the constructor named $C.id$).
+Evaluate \code{arguments} to an argument list.
+Then bind the argument list to the formal parameters of $k$ and
+execute $k$ on the fresh object $o$.
+
+
 % Need to specify exactly how executing a redirecting constructor works
 
 
 %\Q{We now have generative constructors with no bodies as well.}
 
 \paragraph{Initializer Lists}
 \LMLabel{initializerLists}
 
 \LMHash{}
 An initializer list begins with a colon, and consists of a comma-separated list of individual {\em initializers}. There are two kinds of initializers.
@@ skipping 20 matching lines @@
 
 \end{grammar}
 
 \LMHash{}
 Let $k$ be a generative constructor.  Then $k$ may include at most one  superinitializer in its initializer list or a compile-time error occurs. If no superinitializer is provided, an implicit superinitializer of the form \SUPER{}() is added at the end of $k$'s initializer list, unless the enclosing class is class \code{Object}. It is a compile-time error if more than one initializer corresponding to a given instance variable appears in $k$'s initializer list. It is a compile-time error if $k$'s initializer list contains an initializer for a variable that is initialized by means of an initializing formal of $k$. % It is a compile-time error if  $k$'s initializer list contains an initializer for a final variable $f$ whose declaration includes an initialization expression.
 
 \LMHash{}
 Each final instance variable $f$ declared in the immediately enclosing class must have an initializer in $k$'s initializer list unless it has already been initialized by one of the following means:
  \begin{itemize}
  \item Initialization at the declaration of $f$.
- \item Initialization by  means of an initializing formal of $k$.
+ \item Initialization by means of an initializing formal of $k$.
  \end{itemize}
 
 or a static warning occurs. It is a compile-time error if $k$'s initializer list contains an initializer for a variable that is not an instance variable declared in the immediately surrounding class.
 
 
 \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.
 }
 
 \LMHash{}
  It is a compile-time error if a  generative constructor of class \code{Object} includes a superinitializer.
 
 \LMHash{}
-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$.
+Execution of a generative constructor $k$ to initialize a fresh instance $i$
+is always done with respect to a set of bindings for its formal parameters
+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,.
 }
 
+
 \LMHash{}
 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$.
+where $g$ identifies another  generative constructor of the immediately surrounding class. Then execution of $k$ to initialize $i$ 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$ to initialize $i$ 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$.
 
 \LMHash{}
 Otherwise, execution  proceeds as follows:
 
 \LMHash{}
-%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).
+%First, a fresh instance (\ref{generativeConstructors}) $i$ of the immediately enclosing class is allocated.
+
+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 $e$ is evaluated to an object $o$
+and the instance variable $v$ of $i$ is bound to $o$.
+
 %Next, a
 Any initializing formals declared in $k$'s parameter list are executed in the order they appear in the program text.
 % In fact, this order is unobservable; this could be done any time prior to running the body, since
 % these only effect \THIS{}.
-Then, $k$'s  initializers are executed in the order they appear in the program.
+Then, $k$'s initializers are executed to initialize $i$
+in the order they appear in the program.
 
-\rationale {We could observe the order by side  effecting external routines called. So we need to specify the order.}
+\rationale {We could observe the order by side effecting external routines called. So we need to specify the order.}
+
+Then if any instance variable of $i$ declared by the immediately enclosing class
+is not yet bound to a value,
+it is a dynamic error if such a variable is a \FINAL{} variable,
+otherwise all such variables are initialized with the \NULL{} value.
+
+After this, unless the enclosing class is \code{Object}, the super constructor call implicitly or explicitly specified in $k$'s initializers, is now executed to further initialize $i$, as specified below.
+
+\commentary{
+The super constructor call can be written anywhere in the initializers of $k$, but the actual call always happens after all initializers have been processed.
+It is not equivalent to moving the super call to the end of the initializers
+because the argument expressions may have visible side effects
+which must happen in the order the expressions occur in the program text.
+}
 
 \LMHash{}
-After all the initializers  have completed, the body of $k$ is executed  in a scope where \THIS{} is bound to $i$. Execution of the body begins with execution of the body of the superconstructor  with \THIS{} bound to $i$, the type parameters of the immediately enclosing class bound to a set of actual type arguments $V_1, \ldots , V_m$ and the formal parameters bindings determined by the argument list of the superinitializer of $k$.
+After all superclass constructors have completed, the body of $k$ is executed in a scope where \THIS{} is bound to $i$.
 
 \rationale{
 This process ensures that no uninitialized final field is ever seen by code. Note that \THIS{} is not in scope on the right hand side of an initializer (see \ref{this}) so no instance method can execute during initialization: an instance method cannot be directly invoked, nor can  \THIS{} be passed into any other code being invoked in the initializer.
 }
 
 \LMHash{}
-Execution of an initializer of the form \code{\THIS{}.$v$ = $e$} proceeds as follows:
+Execution of an initializer of the form \code{\THIS{}.$v$ = $e$} to initialize an object $i$ proceeds as follows:
 
 \LMHash{}
-First, the expression $e$ is evaluated to an object $o$. Then, the instance variable $v$ of the object denoted by \THIS{} is bound to $o$, unless $v$ is a final variable that has already been initialized, in which case a runtime error occurs. 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 of the field $v$.
+First, the expression $e$ is evaluated to an object $o$. Then, the instance variable $v$ of $i$ is bound to $o$, unless $v$ is a final variable that has already been initialized, in which case a runtime error occurs. 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 of the field $v$.
 
 \LMHash{}
 An initializer of the form \code{$v$ = $e$} is equivalent to an initializer of the form  \code{\THIS{}.$v$ = $e$}.
 
 \LMHash{}
 Execution of a superinitializer of the form
 
 \SUPER{}$(a_1, \ldots, a_n,  x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$
 
 (respectively  \SUPER{}$.id(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$
 
 proceeds as follows:
 
 \LMHash{}
 First, the argument list $(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$ is evaluated.
+This evaluated argument list is remembered until after the entire initializer list has been evaluated, at which point the constructor is executed as follows:
 
 \LMHash{}
 Let $C$ be the class in which the superinitializer appears and let $S$ be the superclass of $C$.  If $S$ is generic (\ref{generics}), let $U_1, , \ldots, U_m$ be the actual type arguments passed to $S$ in the superclass clause of $C$.
 
 \LMHash{}
-Then, the initializer list of the constructor $S$ (respectively $S.id$) is executed with respect to the bindings that resulted from the evaluation of the argument list,  with \THIS{} bound to the current binding of \THIS{}, and  the type parameters (if any) of class $S$ bound to the current bindings of $U_1, , \ldots, U_m$.
+The generative constructor $S$ (respectively $S.id$) of $S$ is executed to initialize $i$ with respect to the bindings that resulted from the evaluation of the argument list, and the type parameters (if any) of class $S$ bound to the current bindings of $U_1, , \ldots, U_m$.
 
 \LMHash{}
 It is a compile-time error if class $S$ does not declare a generative constructor named $S$ (respectively $S.id$).
 
 \subsubsection{Factories}
 \LMLabel{factories}
 
 \LMHash{}
 A {\em factory} is a constructor prefaced by the built-in identifier  (\ref{identifierReference})   \FACTORY{}.
 
@@ skipping 12 matching lines @@
 \LMHash{}
 It is a compile-time error if $M$ is not the name of the immediately enclosing class.
 
 \LMHash{}
 In checked mode, it is a dynamic type error if a factory returns a non-null object whose type is not a subtype of its actual (\ref{actualTypeOfADeclaration}) return type.
 
 \rationale{It seems useless to allow a factory to return null. But it is more uniform to allow it, as the rules currently do.}
 
 \rationale{Factories address classic weaknesses associated with constructors in other languages.
 Factories can produce instances that are not freshly allocated: they can come from a cache. Likewise, factories can return instances of different classes.
-
 }
 
 \paragraph{Redirecting Factory Constructors}
 \LMLabel{redirectingFactoryConstructors}
 
 \LMHash{}
 A {\em redirecting factory constructor} specifies a call to a constructor of another class that is to be used whenever the redirecting constructor is called.
 
 \begin{grammar}
 {\bf redirectingFactoryConstructorSignature:}
@@ skipping 889 matching lines @@
 \LMHash{}
 The constant expression given in an annotation  is type checked and evaluated in the scope surrounding the declaration being annotated.
 
 
 \section{Expressions}
 \LMLabel{expressions}
 
 \LMHash{}
 An {\em expression} is a fragment of Dart code that can be evaluated at run time to yield a {\em value}, which is always an object. Every expression has an associated static type (\ref{staticTypes}). Every value has an associated dynamic type (\ref{dynamicTypeSystem}).
 
+Expressions can also {\em throw} an exception object and an associated stack trace.
+
+Evaluation of an expression will always either {\em yield a value} or it will {\em throw an exception} along with an associated stack trace.
+
+If evaluation of an expression is defined in terms of evaluation of another
+expression, and the evaluation of the other expression throws an exception,
+if nothing else is stated, the evaluation of the first expression stops
+at that point and throws the same exception.
+
 
 \begin{grammar}
 
 {\bf expression:}assignableExpression assignmentOperator expression;
        conditionalExpression cascadeSection*;
        throwExpression
     .
 
 
 {\bf expressionWithoutCascade:}assignableExpression assignmentOperator expressionWithoutCascade;
@@ skipping 182 matching lines @@
       listLiteral
     .
  \end{grammar}
 
 
 
 \subsection{Null}
 \LMLabel{null}
 
 \LMHash{}
 The reserved word \NULL{} denotes the {\em null object}.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

"denotes" ==> "evaluates to"

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

 %\Q{Any methods, such as \code{isNull}?}
 
 \begin{grammar}
 {\bf nullLiteral:}
       \NULL{}
 .
 \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}.
@@ skipping 29 matching lines @@
       `0X' HEX\_DIGIT+
     .
 
  {\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 contains only decimal digits, it denotes a decimal integer.  Otherwise, the numeric literal contains either a decimal point or an exponent part and it denotes a 64 bit double precision floating point number as specified by the IEEE 754 standard.

[Kevin Millikin (Google), 2016/10/13 12:18:38]

"denotes" => "evaluates to"

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Rewritten entire section. Not sure it makes complete sense yet - it's hard to
distinguish concrete syntax (sequence of characters), abstract numerals
(sequence of digits), integers (Z) and `int` instances (objects) without being
confusing.

 
 \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.
 
 \commentary{
 For example, implementations may choose to limit the range to facilitate efficient compilation to Javascript. These limitations should be relaxed as soon as technologically feasible.
 }
 
 \LMHash{}
 It is a compile-time error for a class to attempt to extend, mix in or implement \code{int}. It is a compile-time error for a class to attempt to extend, mix in or implement \code{double}. It is a compile-time error for any type other than the types \code{int} and \code{double} to attempt to extend, mix in or implement \code{num}.
 
 \LMHash{}
 An {\em integer literal} is either a hexadecimal integer literal or a  decimal integer literal. Invoking the getter \code{runtimeType} on an integer literal returns the \code{Type} object that is the value of the expression \code{int}. The static type of an integer literal is \code{int}.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

Definitely outside the scope of this change: do we intend the part about
runtimeType to apply to integer values, or only integer literals?  I think
values otherwise we end up with some strange cases such as identical(42, true ?
42 : 42) but 42.runtimeType not required to be the same as (true ? 42 :
42).runtimeType.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

It should apply to all integers, and the spec is imposing itself on the
libraries unnecessarily here. 

An *integer value* (or object) is an instance of the class `int`, and
unsurprisingly, its runtimeType returns the Type object corresponding to the
`int` class. There is no reason to say that. 

So I removed them all.

[eernst, 2016/10/19 13:37:04]

I actually think the spec carefully tries to _avoid_ imposing itself on the
libraries here! ;)

The spec needs to specify the syntax and semantics of Dart programs, so in
particular it needs to specify all possible syntactic expressions including
`int` literals. They need to have a static type. It would be possible to omit
the information about its dynamic type, but we wouldn't want to have an
implementation where `42` evaluates to a list or a future, so that bit is there
to rule out crazy stuff: We require every implementation to behave in such a
manner that integer literals evaluate to instances of `int`, and then it's up to
the standard libraries to define all the properties that such `int` values have.

The reference to `runtimeType` looks messy because that method may in general be
overridden, but the spec, \section{Overview}, states that 'The run-time type of
every object is represented as an instance of class \code{Type} which can be
obtained by calling the getter  \code{runtimeType}..', which means that the spec
_intends_ `runtimeType` to deliver the actual runtime type. We may wish to
reword that everywhere (and we may wish to have a different kind of support for
obtaining the runtime type of an object that cannot be overridden), but let's
just accept for now that this is how the spec says "the runtime type of an
object".

With that, it is _not_ necessary to say that the runtime type of an integer
value is `int`: That just states or confirms the meaning of "integer value",
i.e., that it is an instance of `int`; and such an entity must return the value
of the expression `int` as its dynamic type.

My conclusion is: We should say that integer literals have that dynamic type
(needed to avoid crazy stuff), but not that integer values have that dynamic
type (redundant), so the wording is OK as it is today.

 
 \LMHash{}
 A {\em literal double} is a numeric literal that is not an integer literal. Invoking the getter \code{runtimeType} on a literal double returns the \code{Type} object that is the value of the expression \code{double}.
 The static type of a literal double is \code{double}.
 
 \subsection{Booleans}
 \LMLabel{booleans}
 
 \LMHash{}
 The reserved words \TRUE{} and \FALSE{} denote objects that represent the boolean values true and false respectively. They are the {\em boolean literals}.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

"denote" => "evaluate to"

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Rewritten to distinguish syntax from `bool` instances and abstract logical
values.

 
 \begin{grammar}
 {\bf booleanLiteral:}\TRUE{};
         \FALSE{}
     .
 \end{grammar}
 
 \LMHash{}
 Both  \TRUE{} and \FALSE{} implement the built-in class \code{bool}.  It is a compile-time error for a class to attempt to extend, mix in or implement\code{ bool}.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

A class can implement an interface and we sometimes say a type can implement an
interface, but a value cannot implement an interface (nor can a reserved word). 
I think this has to be that the run-time types of the true and false values
implement the built-in class bool (the static type is of course, bool).

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Changed to "are instances of".

The spec is a little inconsistent about that phrase. Sometimes it means
"somthing that would satisfy an `is` check" (aka, subtype of) but I also *think*
that in a few cases it means "instance of that exact class, not a subclass".

 
 \commentary{
 It follows that the two boolean literals are the only two instances of \code{bool}.
 }
 
 \LMHash{}
 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}.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

"literal" ==> "value" or "object"?

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Removed.

 
 \subsubsection{Boolean Conversion}
 \LMLabel{booleanConversion}
 
 \LMHash{}
 {\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{});
@@ skipping 180 matching lines @@
      stringInterpolation
     .
 
 {\bf NEWLINE:}$\backslash$ n;
       $\backslash$ r
     .
 
  \end{grammar}
 
 \LMHash{}
 All string literals implement the built-in class \code{String}. It is a compile-time error for a class to attempt to extend, mix in or implement \code{String}. Invoking the getter \code{runtimeType} on a string literal returns the \code{Type} object that is the value of the expression \code{String}. The static type of a string literal is \code{String}.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

A literal can't implement an interface.  A literal is syntax and I think these
requirement applies to string values.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

 
 \subsubsection{String Interpolation}
 \LMLabel{stringInterpolation}
 
 \LMHash{}
 It is possible to embed expressions within non-raw string literals, such that these expressions are evaluated, and the resulting values are converted into strings and concatenated with the enclosing string. This process is known as {\em string interpolation}.
 
  \begin{grammar}
 {\bf stringInterpolation:}`\$' IDENTIFIER\_NO\_DOLLAR;
       `\$' `\{' expression `\}' % could be top level expression, no?
     .
  \end{grammar}
 
 \commentary{The reader will note that the expression inside the interpolation could itself include strings, which could again be interpolated recursively.
 }
 
 \LMHash{}
 An unescaped \$ character in a string signifies the beginning of an interpolated expression.  The \$ sign may be followed by either:
 \begin{itemize}
 \item A single identifier $id$ that must not contain the \$ character.
 \item An expression $e$ delimited by curly braces.
 \end{itemize}
 
 \LMHash{}
 The form \code{\$id} is equivalent to the form \code{\$\{id\}}.  An interpolated string \code{`$s_1$\$\{$e$\}$s_2$'}  is equivalent to the concatenation of the  strings \code{`$s_1$'},  \code{$e$.toString()} and  \code{$`s_2$'}. Likewise an interpolated string \code{``$s_1$\$\{e\}$s_2$''} is equivalent to the concatenation of the strings \code{``$s_1$''}, \code{$e$.toString()} and  \code{``$s_2$''}.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

Note that this doesn't explicitly impose a left-to-right evaluation order, which
makes a difference if an expression throws.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

And it doesn't cover the case where e.toString doesn't return a string.
Rewritten completely, PTAL.

 
 \subsection{Symbols}
 \LMLabel{symbols}
 
 \LMHash{}
 A {\em symbol literal} denotes the name of a declaration in a Dart program.
 
 \begin{grammar}
 {\bf symbolLiteral:}
       `\#'  (operator $|$ (identifier (`{\escapegrammar .}' identifier)*))  .
@@ skipping 168 matching lines @@
      \THROW{} expression
     .
 
    {\bf throwExpressionWithoutCascade:}
      \THROW{} expressionWithoutCascade
     .
 
  \end{grammar}
 
 \LMHash{}
- The {\em current exception} is the last exception raised and not subsequently caught at a given moment during runtime.
-
-\LMHash{}
- Evaluation of a throw expression of the form  \code{\THROW{} $e$;} proceeds as follows:
+Evaluation of a throw expression of the form  \code{\THROW{} $e$;} proceeds as follows:
 
 \LMHash{}
 The expression $e$ is evaluated yielding a value $v$.
 
 \commentary{
 There is no requirement that the expression $e$ evaluate to a special kind of exception or error object.
 }
 
 \LMHash{}
-If $e$ evaluates to \NULL{} (\ref{null}), then a \code{NullThrownError} is thrown. Otherwise the current exception is set to $v$ and the current return value (\ref{return}) becomes undefined.
-
-\rationale{The current exception and the current return value must never be simultaneously defined, as they represent mutually exclusive options for exiting the current function.
-}
+If $e$ evaluates to \NULL{} (\ref{null}), then a \code{NullThrownError} is thrown. Otherwise let $t$ be a stack trace corresponding to the current execution state, and the \THROW{} statement aborts by {\em throwing} with $e$ as exception object and $t$ as stack trace.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

$e$ evaluates to ==> $v$ is

Throw is an expression so this has to be:

Otherwise let $t$ be a stack trace corresponding to the current execution state.
 The \THROW{} expression {\em throws} the value $v$ as exception and $t$ as
stack trace.

(Note that we probably want "throws the value v" because "throws v" will look
weird when they are both italicized.)

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

-> If $v$ is the null value
(as you correctly point out elsewhere \NULL is syntax, not value).

-> throws (\ref{completion}) with $v$ as exception and $t$ as stack trace.
That's the pattern I'm generally using for throwing.

 
 \LMHash{}
-Let $f$ be the immediately enclosing function.
-
-\LMHash{}
-If $f$ is synchronous (\ref{functions}), control is transferred to the nearest dynamically enclosing exception handler.
+If $e$ is an instance of class \code{Error} or a subclass thereof, its \code{stackTrace} getter will return the stack trace captured at the point where the object was first thrown.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

$e$ ==> $v$

Maybe captured isn't quite right, we don't speak of stack traces as being
captured.  Above they correspond to execution state so the language here should
parallel: "...return the stack trace corresponding to the execution state at the
point...".

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

Rewritten.

 
 \commentary{
-If $f$ is marked \SYNC* then a dynamically enclosing exception handler encloses the call to \code{moveNext()} that initiated the evaluation of the throw expression.
+If the same \code{Error} object is thrown more than once, its \code{stackTrace} getter will return the stack trace captured the {\em first} time it was thrown.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

Same comment about captured.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

captured->from

 }
 
 \LMHash{}
-If $f$ is asynchronous  then if there is a dynamically enclosing exception handler $h$  (\ref{try}) introduced by the current activation, control is transferred to $h$, otherwise $f$  terminates.
-
-\rationale{
-The rules for where a thrown exception will be handled must necessarily differ between the synchronous and asynchronous cases. Asynchronous functions cannot transfer control to an exception handler defined outside themselves.  Asynchronous generators post exceptions to their stream. Other asynchronous functions report exceptions via their future.
-}
-
-\LMHash{}
-If the object being thrown is an instance of class \code{Error} or a subclass thereof, its \code{stackTrace} getter will return the stack trace current at the point where the object was first thrown.
-
-\LMHash{}
 The static type of a throw expression is $\bot$.
 
 
 \subsection{ Function Expressions}
 \LMLabel{functionExpressions}
 
 \LMHash{}
 A {\em function literal} is an object that encapsulates an executable unit of code.
 
 \begin{grammar}
@@ skipping 241 matching lines @@
 First, the argument list $(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$ is evaluated.
 
 \LMHash{}
 If $T$ is a deferred type with prefix $p$, then if $p$ has not been successfully loaded, a dynamic error occurs.
 
 \LMHash{}
 Then, if $q$ is a non-factory constructor of an abstract class then an \code{AbstractClassInstantiationError} is thrown.
 
 \LMHash{}
 If $T$  is malformed or if $T$ is a type variable a dynamic error occurs. In checked mode, if $T$ or any of its superclasses is malbounded a dynamic error occurs.
- Otherwise, if $q$ is not defined or not accessible, a \code{NoSuchMethodError} is thrown.  If $q$ has  less than $n$ positional parameters or more than $n$ required parameters, or if $q$ lacks any of the keyword parameters $\{ x_{n+1}, \ldots, x_{n+k}\}$ a \code{NoSuchMethodError} is thrown.
+Otherwise, if $q$ is not defined or not accessible, a \code{NoSuchMethodError} is thrown.  If $q$ has  less than $n$ positional parameters or more than $n$ required parameters, or if $q$ lacks any of the keyword parameters $\{ x_{n+1}, \ldots, x_{n+k}\}$ a \code{NoSuchMethodError} is thrown.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

less ==> fewer

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

 
 \LMHash{}
 Otherwise, if $q$ is a generative constructor (\ref{generativeConstructors}), then:
 
 \commentary{Note that it this point we are assured that the number of actual type arguments match the number of formal type parameters.}
 
 \LMHash{}
-A fresh instance (\ref{generativeConstructors}), $i$,  of class $R$ is allocated. For each instance variable $f$ of $i$,  if the variable declaration of $f$ has an initializer expression $e_f$, then $e_f$ is evaluated, with the type parameters (if any) of $R$ bound to the actual type arguments $V_1, \ldots, V_l$, to an object $o_f$ and $f$ is bound to $o_f$. Otherwise $f$ is bound to \NULL{}.
+A fresh instance (\ref{generativeConstructors}), $i$, of class $R$ is allocated.
+Then $q$ is executed to initialize $i$ with its formal parameters bound to the evaluated argument list and, if $R$ is a generic class, with its type parameters bound to $V_1 \ldots V_m$.
 
-\commentary{
-Observe that \THIS{} is not in scope in $e_f$. Hence, the initialization cannot depend on other properties of the object being instantiated.
-}
-
-\LMHash{}
-Next,  $q$ is executed  with \THIS{} bound to $i$,  the type parameters (if any) of $R$ bound to the actual type arguments $V_1, \ldots, V_l$ and the formal parameter bindings that resulted from the evaluation of the argument list. The result of the evaluation of $e$ is $i$.
+If execution of $q$ completes normally, $e$ evaluates to $i$.
 
 \LMHash{}
 Otherwise, $q$ is a factory constructor (\ref{factories}). Then:
 
 \LMHash{}
 If $q$ is a redirecting factory constructor of the form $T(p_1, \ldots, p_{n+k}) = c;$ or of the form  $T.id(p_1, \ldots, p_{n+k}) = c;$ then the result of the evaluation of $e$ is equivalent to evaluating the expression
 
-$[V_1,  \ldots, V_m/T_1,  \ldots, T_m]($\code{\NEW{} $c(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k}))$}.  If evaluation of $q$ causes $q$ to be re-evaluated cyclically, a runtime error occurs.
+$[V_1,  \ldots, V_m/T_1,  \ldots, T_m]($\code{\NEW{} $c(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k}))$}.  If evaluation of $q$ causes $q$ to be re-evaluated cyclically, with only factory constructor redirections in-between, a runtime error occurs.
+% Used to not have the "in-between" clause, which would disallow a factory constructor redirecting to another constructor which conditionally calls the original factory constructor again with different arguments.
 
 
 \LMHash{}
-Otherwise, the body of $q$ is executed with respect to the bindings that resulted from the evaluation of the argument list and the type parameters (if any) of $q$ bound to the actual type arguments $V_1, \ldots, V_l$ resulting in an object $i$. The result of the evaluation of $e$ is $i$.
+Otherwise, the body of $q$ is executed with respect to the bindings that resulted from the evaluation of the argument list and the type parameters (if any) of $q$ bound to the actual type arguments $V_1, \ldots, V_l$.
+If this execution {\em returns} or {\em completes normally} (\ref{completion}),
+let $i$ be the value {\em returned} by this execution, or \NULL{} if the execution returns without a value or it completes normally.
+The result of the evaluation of $e$ is $i$.
 
 \LMHash{}
 It is a static warning if $q$ is a constructor of an abstract class and $q$ is not a factory constructor.
 
 \commentary{The above gives precise meaning to the idea that instantiating an abstract class leads to a warning.
 A similar clause applies to constant object creation in the next section.
 }
 
 \rationale{In particular, a factory constructor can be declared in an abstract class and used safely, as it will either produce a valid instance or lead to a warning inside its own declaration.
 }
@@ skipping 143 matching lines @@
 
 
 
 \subsection{ Function Invocation}
 \LMLabel{functionInvocation}
 
 \LMHash{}
 Function invocation occurs in the following cases: when a function expression  (\ref{functionExpressions}) is invoked (\ref{functionExpressionInvocation}), when a method (\ref{methodInvocation}), getter (\ref{topLevelGetterInvocation}, \ref{propertyExtraction}) or setter (\ref{assignment}) is invoked or when a constructor is invoked (either via instance creation (\ref{instanceCreation}), constructor redirection (\ref{redirectingConstructors}) or super initialization). The various kinds of function invocation differ as to how the function to be invoked, $f$,  is determined, as well as whether \THIS{} (\ref{this}) is bound. Once $f$ has been determined, the formal parameters of $f$ are bound to corresponding actual arguments. When the body of $f$ is executed it will be executed with the aforementioned bindings.
 
 \LMHash{}
-If $f$ is marked \ASYNC{} (\ref{functions}), then a fresh instance (\ref{generativeConstructors}) $o$ implementing the built-in class \code{Future} is associated with the invocation and immediately returned to the caller. The body of $f$ is scheduled for execution at some future time. The future $o$ will complete when $f$ terminates. The value used to complete $o$ is the current return value (\ref{return}), if it is defined, and the current exception (\ref{throw}) otherwise.
+If $f$ is marked \ASYNC{} (\ref{functions}), then a fresh instance (\ref{generativeConstructors}) $o$ implementing the built-in class \code{Future} is associated with the invocation and immediately returned to the caller. The body of $f$ is scheduled for execution at some future time. The future $o$ will complete when execution of $f$ completes (\ref{completion}). If $f$ completes by {\em returning} a value, that value used to complete $o$, if it {\em completes normally} or by {\em returning} with no value, $o$ is completed with \NULL{}, and if it completes by {\em throwing} an exception $e$ and stack trace $t$, $o$ is completed with $e$ and stack trace $t$ as an error.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

I think this has to be "when execution of the body of $f completes" because it
is the body that is scheduled for execution at some future time and the
execution of $f$ seems to complete immediately (synchronously).

Note that we still have in Section 9 that function bodies have return appended
to them, so I think it is impossible for the body of f to complete normally. 
However, I would be quite happy if we got rid of the part about appending return
in Section 9.

Have you considered what the possibility of "returning no value" might do to the
type system?  Do we just not care about checked mode any more?

We need to avoid splitting 'o is completed ... as an error' up because it reads
like the future is completing with a stack trace.  The API docs are nice in this
regard, they use "complete with a value" and "complete with an error".

It's a bigger change, but it seems nicer to start with the synchronous case in
this section rather than async.

I suggest mentioning that the possibilities break and continue are impossible
because it is a compile time error for a function to contain them wherever they
would complete the function body.

It is very unfortunate that this is written in terms of "(the function) f"
completing.  That might lead to a reading where if the body of the function f
completes, than all futures associated with any invocation of f are completed.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

I ignored the added return of section 9 because I consider removing it. This is
"defensive specification", handling even cases that can't happen (which is a bad
idea in general, but I hadn't decided on removing the extra return).
Keeping it does mean that I can avoid handling the "completes normally" case for
function invocations, and there is some consistency to not being able to "fall
through" the bottom of a function body - all jumps between functions are
explicit.
Still not decided. I'll remove either one before committing, if I can decide on
which.

Good point about distinguishing invocation of function from execution of body
(and there really is no "execution of function").

"Returning no value" cannot leak a function invocation - it is converted into a
`null` value at the point where the "return with no value" reaches the end of
the function body and becomes the value of an invocation.
Still, I don't think the distinction between returning null and returning with
no value is needed, so I'll just remove the "returning with no value" option and
just "return null" instead.
I initially thought I needed the distinction for generative constructors, but
they're syntactically constrained from containing `return e;` so I don't have to
care.

Changed order to sync, sync*, async, async*.

 
 \LMHash{}
-If $f$ is marked \ASYNC* (\ref{functions}), then a fresh instance $s$ implementing the built-in class \code{Stream} is associated with the invocation and immediately returned. When $s$ is listened to, execution of the body of $f$ will begin.  When $f$ terminates:
+If $f$ is marked \ASYNC* (\ref{functions}), then a fresh instance $s$ implementing the built-in class \code{Stream} is associated with the invocation and immediately returned. When $s$ is listened to, execution of the body of $f$ will begin.  When $f$ completes:

[Kevin Millikin (Google), 2016/10/13 12:18:38]

When the body of f completes.  We also should find language making it clear that
it is the execution of the body of f associated with s that we care about, not
when the function f generally completes.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

 \begin{itemize}
-\item If the current return value is defined then, if $s$ has been canceled then its cancellation future is completed with \NULL{} (\ref{null}).
-\item If the current exception $x$ is defined:
+\item If $f$ {\em completes normally}, then if $s$ has been canceled then its cancellation future is completed with \NULL{} (\ref{null}).

[Kevin Millikin (Google), 2016/10/13 12:18:36]

the body of f

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

+\item If $f$ {\em throws} exception $e$ and stack trace $t$:

[Kevin Millikin (Google), 2016/10/13 12:18:37]

the body of f

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

Done.

   \begin{itemize}
-  \item $x$ is added to $s$.
-  \item If $s$ has been canceled then its cancellation future is completed with $x$ as an error.
+  \item $e$ and $t$ are added to $s$ as an error.
+  \item If $s$ has been canceled then its cancellation future is completed with $e$ and $t$ as an error.
   \end{itemize}
 \item $s$ is closed.
 \end{itemize}

[Kevin Millikin (Google), 2016/10/13 12:18:37]

Perhaps here mention that the possibilities break, continue, and returning a
value are impossible.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

 
 \rationale{
 When an asynchronous generator's stream has been canceled, cleanup will occur in the \FINALLY{} clauses (\ref{try}) inside the generator. We choose to direct any exceptions that occur at this time to the cancellation future rather than have them be lost.
 }
 
-\LMHash{}
-If $f$ is asynchronous then, when $f$ terminates, any open stream subscriptions associated with any asynchronous for loops  (\ref{asynchronousFor-in}) or yield-each statements  (\ref{yieldEach}) executing within $f$ are canceled, in the order of their nesting, innermost first.
-
-\rationale{Such streams may be left open by for loops that were escaped when an exception was thrown within them for example.
-}
-
 %\LMHash{}
 %When a stream is canceled, the implementation must wait for the cancelation future returned by \cd{cancell()} to complete before proceeding.
 
 \LMHash{}
 If $f$ is marked \SYNC* (\ref{functions}), then a fresh instance $i$ implementing the built-in class \code{Iterable} is associated with the invocation and immediately returned.
 
 
 \commentary{
 A Dart implementation will need to provide a specific implementation of \code{Iterable} that will be returned by \SYNC* methods. A typical strategy would be to produce an instance of a subclass of class \code{IterableBase} defined in \code{dart:core}. The only method that needs to be added by the Dart implementation in that case is \code{iterator}.
 }
 
 \LMHash{}
 The iterable implementation must comply with the contract of \code{Iterable} and should not take any steps identified as exceptionally efficient in that contract.
 
 \commentary {
 The contract explicitly mentions a number of situations where certain iterables could be more efficient than normal. For example, by precomputing their length. Normal iterables must iterate over their elements to determine their length. This is certainly true in the case of a synchronous generator, where each element is computed by a function. It would not be acceptable to pre-compute the results of the generator and cache them, for example.
 }
 
 \LMHash{}
-When iteration over the iterable is started, by getting an iterator $j$ from the iterable and calling \code{moveNext()}, execution of the body of $f$ will begin. When $f$ terminates, $j$ is positioned after its last element, so that its current value is \NULL{} and the current call to \code{moveNext()} on $j$ returns false, as will all further calls.
+When iteration over the iterable is started, by getting an iterator $j$ from the iterable and calling \code{moveNext()}, execution of the body of $f$ will begin. When $f$ completes (\ref{completion},

[Kevin Millikin (Google), 2016/10/13 12:18:38]

the body of f

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

+\begin{itemize}
+\item If $f$ {\em completes normally}, $j$ is positioned after its last element, so that its current value is \NULL{} and the current call to \code{moveNext()} on $j$ returns false, as will all further calls.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

the body of f

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

Done.

+\item If $f$ {\em throws} exception $e$ and stack trace $t$ then the current value is \NULL{} and the current call to \code{moveNext()} throws $e$ and $t$ as well. Further calls must return false.

[Kevin Millikin (Google), 2016/10/13 12:18:38]

the body of f

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

+\end{itemize}
 
 Each iterator starts a separate computation. If the \SYNC* function is impure, the sequence of values yielded by each iterator may differ.
 
 \commentary{
 One can derive more than one iterator from a given iterable.   Note that operations on the iterable itself can create distinct iterators. An example would be \code{length}.  It is conceivable that different iterators might yield sequences of different length. The same care needs to be taken when writing \SYNC* functions as when
 writing an \code{Iterator} class. In particular, it should handle multiple
 simultaneous iterators gracefully. If the iterator depends on external state
 that might change, it should check that the state is still valid after every
 yield (and maybe throw a \code{ConcurrentModificationError} if it isn't).
 }
 
 \LMHash{}
 Each iterator runs with its own shallow copies of all local variables; in particular, each iterator has the same initial arguments, even if their bindings are modified by the function.
 \commentary{
 Two executions of an iterator interact only via state outside the function.
 }
 % The alternative would be to cache the results of an iterator in the iterable, and check the cache at each \YIELD{}.  This would have strange issues as well. The yielded value might differ from the expression in the yield. And it is a potential memory leak as the cache is kept alive by any iterator.
 
 
 \LMHash{}
-If $f$ is synchronous and is not a generator (\ref{functions}) then execution of the body of $f$ begins immediately.  When $f$ terminates the current return value is returned to the caller.
+If $f$ is synchronous and is not a generator (\ref{functions}) then execution of the body of $f$ begins immediately.
+When $f$ completes (\ref{completion}) by returning a value, that value is returned to the caller.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

When ==> If

that value is returned to the caller ==> the value of the function invocation is
that value

Perhaps name the value v so you can mention it less awkwardly.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

+If $f$ completes by returning without a value or by completing normally, \NULL{} is returned to the callee.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

Definitely not callee :)

null is returned ==> the value of the function invocation (alternately:
invocation of f) is null.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

-> the invocation evaluates to \code{null}.

+If $f$ completes by {\em throwing}, the invoking call expression throws the same exception object and stack trace.
 
-
-\LMHash{}
-Execution of $f$ terminates when the first of the following occurs:
-\begin{itemize}
-\item An exception is thrown and not caught within the current function activation.
-\item A return statement (\ref{return}) immediately nested in the body of $f$ is executed and not intercepted in a \FINALLY{} (\ref{try}) clause.
-\item The last statement of the body completes execution.
-\end{itemize}
-
-
-
+\commentary{
+A function body can never {\em abort} by {\em breaking} or {\em continuing}

[Kevin Millikin (Google), 2016/10/13 12:18:36]

abort ==> complete

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

+because any \BREAK{} or \CONTINUE{} statement must occur inside a statement
+which will handle the \BREAK{} or \CONTINUE{},
+either by declaring the same label, if the \BREAK{} or \CONTINUE{} has a label,
+or merely by being a loop or \SWITCH{} statement.
+This means that a function body can only abort by {\em throwing} or by {\em returning} a value, so a function call expression can always propagate the behavior of the called function's body.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

abort ==> complete

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

Done.

+}
 
 \subsubsection{ Actual Argument List Evaluation}
 \LMLabel{actualArguments}
 
 \LMHash{}
 Function invocation involves evaluation of the list of actual arguments to the function and binding of the results to the function's formal parameters.
 
 \begin{grammar}
 {\bf arguments:}
       `(' (argumentList  `,'?)? `)'
@@ skipping 1379 matching lines @@
  \begin{grammar}
 {\bf awaitExpression:}
       \AWAIT{} unaryExpression
  \end{grammar}
 
 \LMHash{}
 Evaluation of an await expression $a$ of the form \AWAIT{} $e$ proceeds as follows:
 First, the expression $e$ is evaluated. Next:
 
 \LMHash{}
-If $e$ raises an exception $x$, then an instance $f$ of class \code{Future} is allocated and later completed with $x$. Otherwise, if $e$ evaluates to an object $o$ that is not an instance of \code{Future}, then let $f$ be the result of calling \code{Future.value()} with $o$ as its argument; otherwise let $f$ be the result of evaluating $e$.
+% NOTICE: Removed the requirement that an error thrown by $e$ is caught in a

[Kevin Millikin (Google), 2016/10/13 12:18:36]

Thank you!

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Acknowledged.

+% future. There is no reason $var x = e; await x;$ and $await e$ should behave
+% differently, and no implementation actually implemented it.
+If $e$ evaluates to an object $o$ that is not an instance of \code{Future}, then let $f$ be the result of creating a new object using the constructor \code{Future.value()} with $o$ as its argument; otherwise let $f$ be the result of evaluating $e$.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

The result of evaluating e is o (or maybe an exception, but you can't let f be
the result of that because it's a pair).  I think we want:

If $e$ evaluates to an object $o$, and if $o$ is not an instance of
\code{Future}, then let $f$ be the result of creating a new object using the
constructor \code{Future.value()} with $o$ as its argument; otherwise let $f$ be
$o$.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Done.

 
 \LMHash{}
-Next,  execution of the function $m$ immediately enclosing $a$ is suspended until after $f$ completes. The stream associated with the innermost enclosing asynchronous for loop (\ref{asynchronousFor-in}), if any, is paused. At some time after $f$ is completed, control returns to the current invocation. The stream associated with the innermost enclosing asynchronous for loop  (\ref{asynchronousFor-in}), if any, is resumed. If $f$ has completed with an exception $x$, $a$ raises $x$. If $f$ completes with a value $v$, $a$ evaluates to $v$.
+Next, the stream associated with the innermost enclosing asynchronous for loop (\ref{asynchronousFor-in}), if any, is paused. Execution of the function $m$ immediately enclosing $a$ is suspended until after $f$ completes. At some time after $f$ is completed, control returns to the current invocation. If $f$ has completed with an exception $x$ and stack trace $t$, $a$ {\em throws} $x$ and $t$. If $f$ completes with a value $v$, $a$ evaluates to $v$.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

I would say that we're not really executing the function $m$, we are executing
its body.  The actual function $m$ has already returned.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Reworded.

 
 %Otherwise, the value of $a$ is the value of $e$. If evaluation of $e$ raises an exception $x$, $a$ raises $x$.
 
 \commentary{
 It is a compile-time error if  the function  immediately enclosing  $a$  is not declared asynchronous.  However, this error is simply a syntax error, because in the context of a normal function, \AWAIT{} has no special meaning.
+% TODO(lrn): Update this, it's not actually correct,
+% the expression "await(expr)" is valid non-async syntax *and* a valid
+% async await expression.
 }
 
 \rationale{
 An await expression has no meaning in a synchronous function. If such a function were to suspend waiting for a future, it would no longer be synchronous.
 }
 
 \commentary{
 It is not a static warning if the type of $e$ is not a subtype of \code{Future}. Tools may choose to give a hint in such cases.
 }
 
@@ skipping 384 matching lines @@
 \LMHash{}
 The expression $e$ is evaluated to a value $v$. Then, if $T$ is a malformed or deferred type (\ref{staticTypes}), a dynamic error occurs. Otherwise, if the interface of the class of $v$ is a subtype of $T$, the cast expression evaluates to $v$. Otherwise, if $v$ is \NULL{}, the cast expression evaluates to $v$.
 In all other cases,  a \code{CastError} is thrown.
 
 \LMHash{}
 The static type of a cast expression  \code{$e$ \AS{} $T$}  is $T$.
 
 
 \section{Statements}
 \LMLabel{statements}
+A {\em statement} is a fragment of Dart code that can be executed at runtime. Statements, unlike expressions, do not evaluate to a value, but are instead executed for their effect on the program state.
+Some statements can affect control flow, in particular \BREAK{}, \CONTINUE{}, \RETURN{} and \THROW{} statements.

[Kevin Millikin (Google), 2016/10/13 12:18:38]

Throw is not a statement, but rethrow is.  If you want to mention throw, you
will need something like 'statements containing throw expressions'.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Reworded.

+
+\LMLabel{completion}
+Execution of a statement can {\em complete} in two ways: either it {\em completes normally} or it {\em aborts}. It can {\em abort} in one of four ways: Either it {\em breaks} or it {\em continues} (either to a label or without a label), it {\em returns}, either with a value or without one, or it {\em throws} an exception object and an associated stack trace.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

Instead of two possibilities, one of which is four possibilities, how about just
five possibilities?

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

+
+In the description of statement execution, the default is that the execution
+{\em completes normally} unless otherwise stated.
+
+If the execution of a statement, $s$, is defined in terms of executing
+another statement,
+like the body of a loop or the branches of an \IF{} statement,
+and the execution of that other statement {\em aborts},
+then, unless otherwise stated, the execution of $s$ stops
+at that point and aborts in the same way.
+
+If the execution of a statement is defined in terms of evaluating an expression,
+like the condition expression of an \IF{} statement or the value of a \RETURN{},
+and the evaluation of that expression throws,
+then, unless otherwise stated, the execution of the statement stops
+at that point and throws the same exception object and stack trace.
+
+\LMHash{}
 
  \begin{grammar}
 {\bf statements:}
       statement*
     .
 
 
 {\bf statement:}
       label* nonLabelledStatement
     .
@@ skipping 15 matching lines @@
       expressionStatement;
       assertStatement;
       localFunctionDeclaration
     .
  \end{grammar}
 
  \subsection{Blocks}
  \LMLabel{blocks}
 
 \LMHash{}
- A {\em block statement} supports sequencing of code.
+A {\em block statement} supports sequencing of code.
 
 \LMHash{}
 Execution of a block statement $\{s_1, \ldots,  s_n\}$ proceeds as follows:
 
 \LMHash{}
 For $i \in 1 .. n, s_i$ is executed.
 
 \LMHash{}
 A block statement introduces a new scope, which is nested in the lexically enclosing scope in which the block statement appears.
 
-
-
- \subsection{Expression Statements}
- \LMLabel{expressionStatements}
+\subsection{Expression Statements}
+\LMLabel{expressionStatements}
 
 \LMHash{}
 An {\em expression statement} consists of an expression other than a non-constant map literal (\ref{maps}) that has no explicit type arguments.
 
 \rationale{
 The restriction on maps  is designed to resolve an ambiguity in the grammar, when a statement begins with \{.
 }
 
  \begin{grammar}
 {\bf expressionStatement:}
@@ skipping 106 matching lines @@
 % elaborate on function identity and equality, runtime type. Likewsie in function expressions (closures) and declarations
 
 \subsection{If}
 \LMLabel{if}
 
 \LMHash{}
 The {\em if statement} allows for conditional execution of statements.
 
 \begin{grammar}
 {\bf ifStatement:}
-      \IF{} `(' expression `)' statement ( \ELSE{} statement)? % we could allow top level expression
+      \IF{} `(' expression `)' statement ( \ELSE{} statement)?
     .
- \end{grammar}
+\end{grammar}
 
 Execution of an if statement of the form  \code {\IF{} (}$b$\code{)}$s_1$ \code{\ELSE{} } $s_2$ proceeds as follows:
 
 \LMHash{}
- First, the expression $b$ 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_1\}$ is executed, otherwise statement $\{s_2\}$ is executed.
-
+ First, the expression $b$ 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_1\}$ is executed, otherwise statement $\{s_2\}$ is executed.
 
  \commentary {
  Put another way, \code {\IF{} (}$b$\code{)}$s_1$ \code{\ELSE{} } $s_2$ is equivalent to
  \code {\IF{} (}$b$\code{)}$\{s_1\}$ \code{\ELSE{} } $\{s_2\}$
  }
 
  \rationale {
  The reason for this equivalence is to catch errors such as
  }
  \begin{dartCode}
@@ skipping 61 matching lines @@
 \LMHash{}
 If $c$ is empty then let $c^\prime$ be \TRUE{} otherwise let  $c^\prime$ be $c$.
 
 \LMHash{}
 First the variable declaration statement \VAR{} $v = e_0$ is executed. Then:
 \begin{enumerate}
 \item
 \label{beginFor}
 If this is the first iteration of the for loop, let $v^\prime$ be $v$. Otherwise,  let $v^\prime$ be the variable $v^{\prime\prime}$ created in the previous execution of step \ref{allocateFreshVar}.
 \item
 The expression $[v^\prime/v]c$ is evaluated and subjected to boolean conversion (\ref{booleans}). If the result is \FALSE{}, the for loop completes. Otherwise, execution continues at step

[Kevin Millikin (Google), 2016/10/13 12:18:38]

completes ==> completes normally

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

 \ref{beginIteration}.
 \item
 \label{beginIteration}
 The statement $[v^\prime/v]\{s\}$ is executed.
-\item
+
+If this execution {\em continues} without a label,
+or with a label that this \FOR{} statement is labeled with (\ref{labels}),
+then the statement is treated as if it had completed normally.
+If it aborts in any other way,
+execution of the for loop stops and aborts in the same way.
+
 \label{allocateFreshVar}
 Let $v^{\prime\prime}$ be a fresh variable.  $v^{\prime\prime}$ is bound to the value of $v^\prime$.
 \item
 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.
 
@@ skipping 23 matching lines @@
 
 \begin{dartCode}
 var n0 = $e$.iterator;
 \WHILE{} (n0.moveNext()) \{
    $finalConstVarOrType?$ id = n0.current;
    $s$
 \}
 \end{dartCode}
 where \code{n0} is an identifier that does not occur anywhere in the program, except that for purposes of static typechecking, it is checked under the assumption that $n0$ is declared to be of type $T$, where $T$ is the static type of $e.iterator$.
 
-
-
 \subsubsection{Asynchronous For-in}
 \LMLabel{asynchronousFor-in}
 
 \LMHash{}
 A for-in statement may be asynchronous. The asynchronous form is designed to iterate over streams. An asynchronous for loop is distinguished by the keyword \AWAIT{} immediately preceding the keyword \FOR.
 
 \LMHash{}
-Execution of a for-in statement of the form  \code{\AWAIT{} \FOR{} (finalConstVarOrType? id \IN{} $e$) $s$} proceeds as follows:
+Execution of a for-in statement, $f$, of the form \code{\AWAIT{} \FOR{} (finalConstVarOrType? id \IN{} $e$) $s$} proceeds as follows:

[eernst, 2016/10/19 13:37:04]

We do have a couple of occurrences of `id` as a meta-variable occurring in a
`\code{..}` context (rather than math mode as in `$id$`).

However, these cases are clearly the exception (and some of them seem to be
motivated by being in a non-normative context, where the use of math mode
clashes with plain italic to make everything look like regular text). In this
context we already have $e$ and $s$, and there are lots of similar elements
saying "syntactic meta-symbols use math mode".

It is a bit messy to use multi-letter symbols in math mode, but `id` isn't that
bad (something like $buffer$ is much worse because of the big difference between
$f$ and \itshape{f}), and we also have $type$, $inherited$, $overrides$, and
more.

So I'd suggest that we use $id$.

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Done.

 
 \LMHash{}
-The expression $e$ is evaluated to an object $o$. It is a dynamic error if $o$ is not an instance of a class that implements \code{Stream}. Otherwise, the expression \code{\AWAIT{} $v_f$}  (\ref{awaitExpressions}) is evaluated, where $v_f$ is a fresh variable whose value is a fresh instance (\ref{generativeConstructors}) $f$ implementing the built-in class \code{Future}.
+The expression $e$ is evaluated to an object $o$.
+It is a dynamic error if $o$ is not an instance of a class that implements \code{Stream}.
 
 \LMHash{}
-The stream $o$ is listened to,  and on each data event in $o$ the statement $s$ is executed with \code{id} bound to the value of the current element of the stream. If $s$ raises an exception, or if $o$ raises an exception, then $f$ is completed with that exception. Otherwise, when all events in the stream $o$ have been processed, $f$ is completed with \NULL{}  (\ref{null}).
+The stream associated with the innermost enclosing asynchronous for loop, if any, is paused.
+The stream $o$ is listened to, producing a stream subscription $u$,

[eernst, 2016/10/19 13:37:04]

Yes, thank you! The spec mentions stream subscriptions a few times, but they
haven't been introduced anywhere.

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Acknowledged.

+and execution of the asynchronous for-in loop is suspended
+until a stream event is available.
+This allows other asynchronous events to execute while this loop is waiting for stream events.

[eernst, 2016/10/19 13:37:05]

This sentence should not be normative, but it might work well as a \rationale{}.

[Lasse Reichstein Nielsen, 2016/10/19 14:34:32]

I'm not sure where we define "suspend", so I thought it important to say what it
means to suspend the execution.
I'll make this a rationale.

+
+Pausing an asynchronous for loop means pausing the associated stream subscription.
+A stream subscription is paused by calling its \code{pause} method.
+\commentary{
+The \code{pause} call can throw, although that should never happen for a correctly implemented stream.
+}
+If the subscription is already paused, the \code{pause} call may be omitted.

[eernst, 2016/10/19 13:37:05]

I think it gets too difficult to distinguish commentary and normative text if
they occur together (the font difference doesn't scream it out). 

I did find exceptions (and I was surprised to find them), but it is very nearly
consistently enforced that commentary is put into its own paragraph.

I'd prefer if we maintain that style.

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Done.

 
 \LMHash{}
-Let $u$ be the stream associated with the immediately enclosing asynchronous for loop or generator function (\ref{functions}), if any. If another event $e_u$ of $u$ occurs before execution of $s$ is complete, handling of $e_u$ must wait until $s$ is complete.
+For each {\em data event} from $u$,
+the statement $s$ is executed with \code{id} bound to the value of the current data event.

[eernst, 2016/10/19 13:37:05]

\code{id} --> $id$

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Done.

 
-\rationale{
-The future $f$ and the corresponding \AWAIT{} expression ensure that execution suspends as an asynchronous for loop begins and resumes after the \FOR{} statement when it ends. They also ensure that the stream of any enclosing asynchronous \FOR{} loop is paused for the duration of this loop.
+\LMHash{}
+If another event $e_u$ of $u$ occurs before execution of $s$ is complete, handling of $e_u$ must wait until $s$ is complete.

[eernst, 2016/10/19 13:37:04]

This could be commentary, but for normative text we otherwise have a style where
actions are described, not constraints on actions that "must wait" or anything
like that. (Basically, we don't usually tolerate normative language which is so
far removed from a "typical" intended implementation).

Is there an operational way to specify the same behavior? 

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

We can pause the source stream. That will definitely ensure that we do wait
until $s$ is complete.
On the other hand, it also enforces pausing even when it isn't necessary, which
is what this text tries to avoid.

However, the way the spec is currently written, we can just say nothing, and
then any async operation inside $s$ *will* pause the stream. Then it's just a
corollary that the next event will be delayed, and this can be a commentary. 

Except for badly implemented streams that fire during synchronous execution.
Or that ignore pause and cancel calls. We can't save the world from that, so the
question is how precisely we must specify the semantics - must all programs have
a completely specified semantics, so you can derive what happens even for a
completely broken stream, or do we leave it implementation dependent what
happens if you don't follow the stream semantics. The former is doable, but will
require quite complicated implementations that duplicate a lot of the logic of
correct streams. The latter is probably all you need in practice.

I'm going for the latter.

+
+\LMHash{}
+If execution of $s$ {\em continues} with no label, or with a label that prefixes the asynchronous for statement (\ref{labels}), then the execution of $s$ is treated as if it had completed normally.

[eernst, 2016/10/19 13:37:05]

I still think that it's messy to add `{\em ..}` in order to point out that the
word `continues` is special. Surely lots of people will still read it to mean
simply that "the execution continues", and then they'll get really confused.


The messy bit is that italic is otherwise used in normative text to indicate
that a particular occurrence of a word is the defining occurrence. People know
that this is what they need to find in order to get to know what that word
means.

Update after lunch: Let's use these words (throws, continues, throwing,
continuing, and similar forms) without an explicit `completes`, but then
_rigidly_ follow the scheme that they must be followed by `(\ref{completion})`.

I think that will be sufficient to ensure that even `if execution .. continues`
can be parsed correctly by the reader.

Woo-hoo!

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Removing all the {\em's}.

+
+If execution of $s$ {\em aborts} in any other way, the subscription $u$ is canceled by evaluating \code{\AWAIT{} v.cancel()} where $v$ is a fresh variable referencing the stream subscription $u$.
+If that evaluation throws,
+execution of $f$ throws the same exception and stack trace.
+Otherwise execution of $f$ aborts in the same way as the execution of $s$.
+% Notice: The previous specification was unclear about what happened when
+% a subscripton is canceled. This text is explicit, and existing
+% implementations may not properly await the cancel call.
+
+Otherwise the execution of $f$ is suspended again, waiting for the next stream subscription event, and $u$ is resumed if it has been paused.
+If $u$ has been paused more than once, the \code{resume} method is called
+until $u$ is no longer paused.

[eernst, 2016/10/19 13:37:05]

Couldn't we mandate the interpretation that '$u$ is resumed' must resume $u$,
and it is an implementation dependent property that some stream subscriptions
will need multiple invocations of \code{resume}? (That is, couldn't we just
remove that sentence?)

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Let's do that.

+\commentary{
+The \code{resume} call can throw, in which case it aborts the asynchronous for
+loop. That should never happen for a correctly implemented stream.
 }
 
 \LMHash{}
+On the first {\em error event} from $u$,
+with error object $e$ and stack trace $st$,
+the subscription $u$ is canceled by evaluating \code{\AWAIT{} v.cancel()}
+where $v$ is a fresh variable referencing the stream subscription $u$.
+If that evaluation throws,
+execution of $f$ throws the same exception object and stack trace.
+Otherwise execution of $f$ throws with $e$ as exception object and $st$ as stack trace.
+
+\LMHash{}
+When $u$ is done, execution of $f$ completes normally.
+
+\LMHash{}
 It is a compile-time error if an asynchronous for-in statement appears inside a synchronous function (\ref{functions}). It is a compile-time error if a traditional for loop  (\ref{forLoop}) is prefixed by the \AWAIT{}  keyword.
 
 \rationale{An asynchronous loop would make no sense within a synchronous function, for the same reasons that an await expression makes no sense in a synchronous function.}
 
 
 \subsection{While}
 \LMLabel{while}
 
 \LMHash{}
 The while statement supports conditional iteration, where the condition is evaluated prior to the loop.
 
 \begin{grammar}
 {\bf whileStatement:}
       \WHILE{} `(' expression `)' statement  % could do top level here, and in for
 .
  \end{grammar}
 
 \LMHash{}
- Execution of a while statement of the form \code{\WHILE{} ($e$) $s$;} proceeds as follows:
+Execution of a while statement of the form \code{\WHILE{} ($e$) $s$;} proceeds as follows:
 
 \LMHash{}
-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.
+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.
+If that execution completes normally or it {\em continues} with no label or with a label that prefixes the \WHILE{} statement (\ref{labels}), then the while statement is re-executed.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

For 'for' we have the language "a label that this \FOR{} statement is labeled
with".  Here is is prefixed.  It should be exactly parallel whatever we settle
on.

Also, for 'for' we mention explicitly the other possibilities, here we rely on
the convention that they aren't mentioned so the while statement does the same
thing.  We should be consistent one way or the other (it's fine to not mention
them).

\ref{labels} should be on "a label" or "no label", it looks weird on "while
statement".

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

It seems "prefixes" is the wording used in most other places, so I'll go for
that for now.

The label is referring to what it means to prefix a statement, so I think it is
located correctly. 

The a label or no label should refer \ref{completion} because those terms are
defined there.

[eernst, 2016/10/19 13:37:05]

New style: 'completes normally or it continues with no label (\ref{labels}) or
with a label that prefixes the \WHILE{} statement (\ref{completion}),`

+
+If $r$ is \FALSE{}, then execution of the while statement completes normally.

[eernst, 2016/10/19 13:37:04]

+` (\ref{completion})`

 
 \LMHash{}
 It is a static type warning if the static type of $e$ may not be assigned to \code{bool}.
 
 
 \subsection{Do}
 \LMLabel{do}
 
 \LMHash{}
 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}
 
 
 \LMHash{}
 Execution of a do statement of the form \code{\DO{} $s$ \WHILE{} ($e$);} proceeds as follows:
 
 \LMHash{}
-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.
+The statement $\{s\}$ is executed.
+If that execution {\em continues} with no label, or with a label that prefixes the do statement (\ref{labels}), then the execution of $s$ is treated as if it had completed normally.

[eernst, 2016/10/19 13:37:05]

The usual stuff: `If that execution continues with no label (\ref{labels}) or
with a label that prefixes the do statement (\ref{completion}),`

I would prefer `\DO{} statement` in order to avoid phrases where the words
referring to syntax may be misinterpreted as "normal" words, but I can see that
other locations also use `do statement` and `while statement` and similar stuff.

+
+\LMHash{}
+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 completes normally.

[eernst, 2016/10/19 13:37:05]

+` (\ref{completion})`

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Do we need this reference when we had one in the previous paragraph?

+If $r$ is \TRUE{}, then the do statement is re-executed.
 
 \LMHash{}
 It is a static type warning if the static type of $e$ may not be assigned to \code{bool}.
 
 \subsection{Switch}
 \LMLabel{switch}
 
 \LMHash{}
 The {\em switch statement} supports dispatching control among a large number of cases.
 
- \begin{grammar}
+\begin{grammar}
 {\bf switchStatement:}
       \SWITCH{} `(' expression `)' `\{' switchCase* defaultCase? `\}'% could do top level here and in cases
     .
 
 
 {\bf switchCase:}
       label* \CASE{} expression `{\escapegrammar :}' statements
     .
 
 {\bf defaultCase:}
@@ skipping 63 matching lines @@
 \SWITCH{} ($e$) \{
    $label_{11} \ldots label_{1j_1}$ \CASE{} $e_1: s_1$
    $\ldots$
    $label_{n1} \ldots label_{nj_n}$ \CASE{} $e_n: s_n$
 \}
 \end{dartCode}
 
 proceeds as follows:
 
 \LMHash{}
 The statement \code{\VAR{} id = $e$;} is evaluated, where \code{id} is a variable whose name is distinct from any other variable in the program. In checked mode, it is a run time error if the value of $e$ is not an instance of the same class as the constants $e_1 \ldots e_n$.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

Since you've explicitly defined matching against a value (parameterized over the
value, instead of explicitly against id) we do not need to introduce this fresh
variable id any more.  Just say e is evaluated to v.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

We actually do use `id` below in the expression $e_k == id$. This is shorter
than having to unfold the definition of `==` operator (which is not just calling
the `operator==` method - it also checks both sides for null, and in non-checked
mode that can happen).

It's definitely not perfect, but I won't try to fix this now.

 
 \commentary{Note that if there are no case clauses ($n = 0$), the type of $e$ does not matter.}
 
 \LMHash{}
-Next, the case clause \CASE{} $e_{1}: s_{1}$ is executed if it exists. If \CASE{} $e_{1}: s_{1}$ does not exist, then if there is a  \DEFAULT{} clause it is executed by executing $s_{n+1}$.
+Next, the case clause \CASE{} $e_{1}: s_{1}$ is matched against {\code id} if it exists. If \CASE{} $e_{1}: s_{1}$ does not exist, then if there is a \DEFAULT{} clause, its statements, if any, are executed (\ref{case-execute}).

[Kevin Millikin (Google), 2016/10/13 12:18:37]

It sounds like id might not exist.  I would say something like: if the case
clause ... exists it is matched against v.

[eernst, 2016/10/19 13:37:04]

I suggested switching the order, which would handle that issue as well: 

`Next, $id$ is matched against the case clause \CASE{} $e_{1}: s_{1}$, if it
exists. Otherwise, the statements $s_{n+1}$ of the \DEFAULT{} case are executed,
if there is a \DEFAULT{} case. Otherwise, the switch statements completes
normally (\ref{completion}).`

 
 \LMHash{}
 A case clause introduces a new scope, nested in the lexically surrounding scope. The scope of a case clause ends immediately after the case clause's statement list.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Removed

 
 \LMHash{}
-Execution of a \CASE{} clause \CASE{} $e_{k}: s_{k}$ of a  switch statement
+Matching of a \CASE{} clause \CASE{} $e_{k}: s_{k}$ of a switch statement
 
 \begin{dartCode}
 \SWITCH{} ($e$) \{
    $label_{11} \ldots label_{1j_1}$ \CASE{} $e_1: s_1$
    $\ldots$
    $label_{n1} \ldots label_{nj_n}$ \CASE{} $e_n: s_n$
    $label_{(n+1)1} \ldots label_{(n+1)j_{n+1}}$ \DEFAULT{}: $s_{n+1}$
 \}
 \end{dartCode}
 
-proceeds as follows:
+against a value {\code id} proceeds as follows:
 
 \LMHash{}
 The expression \code{$e_k$ == id} is evaluated to an object $o$ which is then subjected to boolean conversion yielding a value $v$.
-If $v$ is not  \TRUE{} the following case,  \CASE{} $e_{k+1}: s_{k+1}$ is executed if it exists. If  \CASE{} $e_{k+1}: s_{k+1}$ does not exist, then the \DEFAULT{} clause is executed by executing $s_{n+1}$.
-If $v$ is \TRUE{},   let $h$ be the smallest number such that $h \ge k$ and $s_h$ is non-empty. If no such $h$ exists, let $h = n + 1$. The  sequence of statements $s_h$ is then executed.
-If execution reaches the point after $s_h$  then  a runtime error occurs, unless $h = n+1$.
+If $v$ is not \TRUE{} the following case, \CASE{} $e_{k+1}: s_{k+1}$ is matched against {\code id} if it exists. If \CASE{} $e_{k+1}: s_{k+1}$ does not exist, then the \DEFAULT{} clause's statements are executed (\ref{case-execute}).

[Kevin Millikin (Google), 2016/10/13 12:18:36]

Again, it sounds like id might not exist.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

[eernst, 2016/10/19 13:37:05]

I'd suggest a similar rewrite as the previous one (but I can't see the result of
'Done' anywhere, so it may have happened already).

[Lasse Reichstein Nielsen, 2016/10/31 16:54:43]

Rewritten again to not say "if such a thing exists" but just "if k < n" - which
amounts to the same thing.

+If $v$ is \TRUE{}, let $h$ be the smallest number such that $h \ge k$ and $s_h$ is non-empty. If no such $h$ exists, let $h = n + 1$. The statements $s_h$ are then executed (\ref{case-execute}).
 
 \LMHash{}
-Execution of a \CASE{} clause \CASE{} $e_{k}: s_{k}$ of a  switch statement
+Matching of a \CASE{} clause \CASE{} $e_{k}: s_{k}$ of a switch statement
 
 \begin{dartCode}
 \SWITCH{} ($e$) \{
    $label_{11} \ldots label_{1j_1}$ \CASE{} $e_1: s_1$
    $\ldots$
    $label_{n1} \ldots label_{nj_n}$ \CASE{} $e_n: s_n$
 \}
 \end{dartCode}
 
+against a value {\code id} proceeds as follows:
+
+\LMHash{}
+The expression \code{$e_k$ == id} is evaluated to an object $o$ which is then subjected to boolean conversion yielding a value $v$.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

Note that there may be zero cases, so you need the "if it exists" langauge here
too.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

I don't think that is necessary, it's handled at the "call" point for this
sub-execution. The "matching a value against an case clause" is only invoked
above or below in the case where such a case clause exists (due to the "if such
a clause exists" text), so we only get here if there is one.

+If $v$ is not  \TRUE{} the following case,  \CASE{} $e_{k+1}: s_{k+1}$ is matched against {\code id} if it exists.
+If $v$ is \TRUE{}, let $h$ be the smallest integer such that $h \ge k$ and $s_h$ is non-empty. The sequence of statements $s_h$ is executed if it exists (\ref{case-execute}).
+
+\LMHash{}
+\subsection{ Executing the statements of a switch case}

[Kevin Millikin (Google), 2016/10/13 12:18:38]

Should be a subsubsection of switch I think.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

Absolutely, and should have a more consistent name too. Other section/subsection
names are shorter.

+\LMLabel{case-execute}
+Execution of the statements $s_h$ of a switch statement
+
+\begin{dartCode}
+\SWITCH{} ($e$) \{
+   $label_{11} \ldots label_{1j_1}$ \CASE{} $e_1: s_1$
+   $\ldots$
+   $label_{n1} \ldots label_{nj_n}$ \CASE{} $e_n: s_n$
+\}
+\end{dartCode}
+
+or a switch statement
+
+\begin{dartCode}
+\SWITCH{} ($e$) \{
+   $label_{11} \ldots label_{1j_1}$ \CASE{} $e_1: s_1$
+   $\ldots$
+   $label_{n1} \ldots label_{nj_n}$ \CASE{} $e_n: s_n$
+   $label_{(n+1)1} \ldots label_{(n+1)j_{n+1}}$ \DEFAULT{}: $s_{n+1}$
+\}
+\end{dartCode}
+
 proceeds as follows:
 
 \LMHash{}
-The expression \code{$e_k$ == id} is evaluated to an object $o$ which is then subjected to boolean conversion yielding a value $v$.
-If $v$ is not  \TRUE{} the following case,  \CASE{} $e_{k+1}: s_{k+1}$ is executed if it exists.
-If $v$ is \TRUE{},   let $h$ be the smallest integer such that $h \ge k$ and $s_h$ is non-empty. The  sequence of statements $s_h$ is  executed if it exists.
-If execution reaches the point after $s_h$  then  a runtime error occurs, unless $h = n$.
-
+Execute $\{s_h\}$.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

Note that the language about how a case clause introduce a new scope, and where
that scope ends, is actually now unnecessary.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:24]

Done.

+If this execution completes normally, and if $s_h$ is not the statements of the last case of the switch ($h = n$ if there is no \DEFAULT{} clause, $h = n+1$ if there is a \DEFAULT{} clause), then the execution of the switch case aborts by throwing a runtime error. Otherwise $s_h$ are the last statements of the switch case, and execution of the switch case completes normally.

[Kevin Millikin (Google), 2016/10/13 12:18:38]

aborts ==> completex

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

Done.

 
 \commentary{
 In other words, there is no implicit fall-through between non-empty cases. The last case in a switch (default or otherwise) can `fall-through' to the end of the statement.
 }
 
+If execution of $\{s_h\}$ aborts by {\em breaking} with no label, or with a label that prefixes the switch statement, then the execution of the switch statement completes normally.
+
+If execution of $\{s_h\}$ aborts with a continue with a label, and the label is $label_{ij}$, where $1 \le i \le n+1$ if the \SWITCH{} statement has a \DEFAULT{}, or $1 \le i \le n$ if there is no \DEFAULT{}, and where $1 \le j \le j_{i}$, then
+execution of the switch statement continues with the case labeled by that label.
+let $h$ be the smallest number such that $h \ge i$ and $s_h$ is non-empty. If no such $h$ exists, and let $h = n + 1$ if the \SWITCH{} statement has a \DEFAULT{}, otherwise let $h = n$.
+The statements $s_h$ are then executed (\ref{case-execute}).
+
+If execution of $\{s_h\}$ aborts in any other way, execution of the \SWITCH{} statement aborts in the same way.
+
 \LMHash{}
 It is a static warning if the type of $e$ may not be assigned to the type of $e_k$. It is a static warning if the last statement of the statement sequence $s_k$ is not a \BREAK{}, \CONTINUE{}, \RETURN{} or \THROW{} statement.

[Kevin Millikin (Google), 2016/10/13 12:18:36]

This paragraph and the rest of this section is out of place in the subsection
about executing statements.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:22]

Moved it to before the subsection.

 
 \rationale{
 The behavior of switch cases intentionally differs from the C tradition.  Implicit fall through is a known cause of programming errors and therefore disallowed.  Why not simply break the flow implicitly at the end of every case, rather than requiring explicit code to do so?  This would indeed be cleaner.  It would also be cleaner to insist that each case have a single (possibly compound) statement.  We have chosen not to do so in order to facilitate porting of switch statements from other languages.  Implicitly breaking the control flow at the end of a case would silently alter the meaning of ported code that relied on fall-through, potentially forcing the programmer to deal with subtle bugs. Our design ensures that the difference is immediately brought to the coder's attention.  The programmer will be notified at compile-time if they forget to end a case with a statement that terminates the straight-line control flow. We could make this warning a compile-time error, but refrain from doing so because do not wish to force the programmer to deal with this issue immediately while porting code.  If developers ignore the warning and run their code, a run time error will prevent the program from misbehaving in hard-to-debug ways (at least with respect to this issue).
 
 The sophistication of the analysis of fall-through is another issue. For now, we have opted for a very straightforward syntactic requirement. There are obviously situations where code does not fall through, and yet does not conform to these simple rules, e.g.:
 }
 
 \begin{dartCode}
 \SWITCH{} (x) \{
   \CASE{} 1: \TRY{} \{ $\ldots$ \RETURN{};\} \FINALLY{} \{ $\ldots$ \RETURN{};\}
@@ skipping 34 matching lines @@
 Execution of a \code{\RETHROW{}} statement proceeds as follows:
 
 \LMHash{}
 Let $f$ be the immediately enclosing function, and let \code{\ON{} $T$ \CATCH{} ($p_1$, $p_2$)}  be the immediately enclosing catch clause (\ref{try}).
 
 \rationale{
 A \RETHROW{} statement always appears inside a \CATCH{} clause, and any \CATCH{} clause is semantically equivalent to some \CATCH{} clause of the form \code{\ON{} $T$ \CATCH{} (p1, p2)}.  So we can assume that the \RETHROW{} is enclosed in a \CATCH{} clause of that form.
 }
 
 \LMHash{}
-The current exception (\ref{throw}) is set to $p_1$, the current return value (\ref{return}) becomes undefined, and the active stack trace (\ref{try}) is set to $p_2$.
-
-\LMHash{}
-If $f$ is marked \ASYNC{} or \ASYNC* (\ref{functions}) and there is a dynamically enclosing exception handler (\ref{try}) $h$ introduced by the current activation, control is transferred to $h$, otherwise $f$  terminates.
-
-\rationale{
-In the case of an asynchronous function, the dynamically enclosing exception handler is only relevant within the function. If an exception is not caught within the function, the exception value is channelled through a future or stream rather than propagating via exception handlers.
-}
-
-\LMHash{}
-Otherwise, control is transferred to the  innermost enclosing exception handler.
-
-\commentary{The change in control may result in multiple functions terminating if these functions do not catch the exception via a \CATCH{} or \FINALLY{} clause, both of which introduce a dynamically enclosing exception handler.}
+The \RETHROW{} statement aborts by {\em throwing} with $p_1$ as the exception object and $p_2$ as the stack trace.
 
 \LMHash{}
 It is a compile-time error if a  \code{\RETHROW{}} statement is not enclosed within an \ON-\CATCH{} clause.
 
 
-
 \subsection{ Try}
 \LMLabel{try}
 
 \LMHash{}
 The try statement supports the definition of exception handling code in a structured way.
 
 \begin{grammar}
 {\bf tryStatement:}
       \TRY{} block (onPart+ finallyPart? $|$ finallyPart)
     .
 
  {\bf onPart:}catchPart block;
     \ON{} type catchPart? block
    .
 
 {\bf catchPart:}
       \CATCH{} `(' identifier (`,' identifier)? `)'
     .
 
 {\bf finallyPart:}
       \FINALLY{} block
     .
  \end{grammar}
 
 \LMHash{}
- A try statement consists of a block statement, followed by at least one of:
- \begin{enumerate}
- \item
-A set of \ON{}-\CATCH{} clauses, each of which specifies  (either explicitly or implicitly) the type of exception object to be handled, one or two exception parameters and a block statement.
+A try statement consists of a block statement, followed by at least one of:
+\begin{enumerate}
+\item
+A set of \ON{}-\CATCH{} clauses, each of which specifies (either explicitly or implicitly) the type of exception object to be handled, two exception parameters and a block statement.
 \item
 A \FINALLY{} clause, which consists of a block statement.
 \end{enumerate}
 
 \rationale{
 The syntax is designed to be upward compatible with existing Javascript programs. The \ON{} clause can be omitted, leaving what looks like a Javascript catch clause.
 }
 
 \LMHash{}
-An \ON{}-\CATCH{} clause of the form   \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$}  {\em matches} an object $o$  if the type of $o$ is a subtype of $T$.  If $T$ is a malformed or deferred type  (\ref{staticTypes}), then performing a match causes a run time error.
+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{} $\{\}$}.
 
-\commentary {
-It is of course a static warning if $T$ is a deferred or malformed type.
-}
+\LMHash{}
+An \ON{}-\CATCH{} clause of the form  \code{\ON{} $T$ \CATCH{} ($p_1$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$} where $p_2$ is an identifier that does not occur anywhere else in the program.
+
+\LMHash{}
+An \ON{}-\CATCH{} clause of the form  \code{\ON{} $T$ $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$} where $p_1$ and $p_2$ are identifiers that do not occur anywhere else in the program.
+
+\LMHash{}
+An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p$) $s$} is equivalent to an \ON{}-\CATCH{} clause \code{\ON{} \DYNAMIC{} \CATCH{} ($p$, $p_2$) $s$} where $p_2$ is an identifier that does not occur anywhere else in the program.
+
+An \ON{}-\CATCH{} clause of the form \code{\CATCH{} ($p_1, p_2$) $s$} is equivalent to an \ON{}-\CATCH{} clause \code{\ON{} \DYNAMIC{} \CATCH{} ($p_1, p_2$) $s$}.
 
 \LMHash{}
 An \ON{}-\CATCH{} clause of the form   \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$} introduces a new scope $CS$ in which final local variables specified by $p_1$ and $p_2$ are defined. The statement $s$ is enclosed within $CS$. The static type of $p_1$ is $T$ and the static type of $p_2$ is \code{StackTrace}.
 
 
 \LMHash{}
-An \ON{}-\CATCH{} clause of the form  \code{\ON{} $T$ \CATCH{} ($p_1$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$} where $p_2$ is an identifier that does not occur anywhere else in the program.
-
+Execution of a \TRY{} statement $s$ on the form:
+\begin{dartCode}
+\TRY{} b
+\ON{} $T_1$ \CATCH{} ($e_1$, $t_1$) c_1
+\ldots{}
+\ON{} $T_n$ \CATCH{} ($e_n$, $t_n$) c_n
+\FINALLY{} f
+\end{dartCode}
+proceeds as follows:
 
 \LMHash{}
-An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} \DYNAMIC{} \CATCH{} ($p$) $s$}. An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p_1, p_2$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} \DYNAMIC{} \CATCH{} ($p_1, p_2$) $s$}.
+First $b$ is executed.
+If execution of $b$ aborts by throwing with exception object $e$ and stack trace $t$, then $e$ and $t$ are matched against the \ON{}-\CATCH{} clauses to yield a new completion (\ref{on-catch}).
 
+Then, even if execution of $b$ aborted or matching against the \ON{}-\CATCH{} clauses aborted, the $f$ block is executed.
 
-%If an explicit type is associated with of $p_2$, it is a static warning if that type is not \code{Object} or \DYNAMIC{}.
+If execution of $f$ aborts, execution of the \TRY{} statement aborts in
+the same way.
+Otherwise if execution of $b$ threw, the \TRY{} statement completes in the same way as the matching against the \ON{}-\CATCH{} clauses.
+Otherwise the \TRY{} statement completes in the same way as the execution of $b$.
+
+\subsubsection{Matching against \ON{}-\CATCH{} clauses}
+\LMHash{}
+Matching an exception object $e$ and stack trace $t$ against a (potentially empty) sequence of \ON{}-\CATCH{} clauses on the form:
+\begin{dartCode}
+\ON{} $T_1$ \CATCH{} ($e_1$, $st_1$) \{ $s_1$ \}
+\ldots
+\ON{} $T_n$ \CATCH{} ($e_n$, $st_n$) \{ $s_n$ \}
+\end{dartCode}
 
 \LMHash{}
-The {\em active stack trace} is an object whose \code{toString()} method produces a string that is a record of exactly those function activations within the current isolate that had not completed execution at the point where the current exception (\ref{throw}) was thrown.
-%\begin{enumerate}
-%\item Started execution after the currently executing function.
-%\item Had not completed execution at the point where the exception caught by the currently executing  \ON{}-\CATCH{} clause was initially thrown.
-%\commentary{The active stack trace contains the frames between the exception handling code and the original point when an exception is thrown, not where it was rethrown.}
-%\end{enumerate}
+If there are no \ON{}-\CATCH{} clauses ($n = 0$), matching completes by {\em throwing} the exception object $e$ and stack trace $t$.
 
- \commentary{
-This implies that no synthetic function activations may be added to the trace, nor may any source level activations be omitted.
-This means, for example, that any inlining of functions done as an optimization must not be visible in the trace. Similarly, any synthetic routines used by the implementation must not appear in the trace.
+Otherwise the exception is matched against the first clause.
+\LMHash{}
 
-Nothing is said about how any native function calls may be represented in the trace.
- }
-
-\commentary{
-Note that we say nothing about the identity of the stack trace, or what notion of equality is defined for stack traces.
-}
-
-% Sadly, the info below cannot be computed efficiently. It would need to be computed at the throw point, since at latte points it might be destroyed. Native code in calling frames executes relative to the stack pointer, which therefore needs to be reset as each frame is unwound.  This means that the
-% OS kernel can dispose of this stack memory - it is not reliably preserved. And such code must execute if only to test if the exception should be caught or sent onward.
-
-% For each such function activation, the active stack trace includes the name of the function, the bindings of all its formal parameters, local variables and \THIS{}, and the position at which the function was executing.
-
- % Is this controversial? We were thinking of viewing the trace as a List<Invocation>,
- % but that won't capture the receiver or the locals. More generally, we need a standard interface that describes these traces, so one can type the stack trace variable in the catch.
-
- \commentary{The term position should not be interpreted as a line number, but rather as a precise position - the exact character index of the  expression that raised  the exception. }
-
- % A position can be represented via a Token. If we make that part of the core reflection facility, we can state this here.
-
-\LMHash{}
-A try statement \TRY{} $s_1$ $on-catch_1 \ldots  on-catch_n$ \FINALLY{} $s_f$  defines an exception handler $h$ that executes as follows:
-
-\LMHash{}
-The \ON{}-\CATCH{} clauses are examined in order, starting with $catch_1$, until either an \ON{}-\CATCH{} clause that matches the current exception (\ref{throw}) is found, or the list of \ON{}-\CATCH{} clauses has been exhausted. If an \ON{}-\CATCH{} clause $on-catch_k$ is found, then $p_{k1}$ is bound to the current exception,  $p_{k2}$, if declared,  is bound to the active stack trace, and then $catch_k$ is executed. If no \ON{}-\CATCH{} clause is found, the \FINALLY{} clause is executed. Then, execution resumes at the end of the try statement.
-
-
-\LMHash{}
-A finally clause \FINALLY{} $s$ defines an exception handler $h$ that executes as follows:
-
-\LMHash{}
-Let $r$ be the current return value (\ref{return}). Then the current return value becomes undefined. Any open streams associated with any asynchronous for loops (\ref{asynchronousFor-in}) and yield-each (\ref{yieldEach}) statements executing within the dynamic scope of $h$ are canceled, in the order of their nesting, innermost first.
-
-\rationale{
-Streams left open by for loops that were escaped for whatever reason would be canceled at function termination, but it is best to cancel them as soon as possible.
+If $T_1$ is a malformed or deferred type (\ref{staticTypes}), then performing a match causes a run time error.
+\commentary {
+It is of course a static warning if $T_i$, $1 \le i \le n$ is a deferred or malformed type.
 }
 
 \LMHash{}
-Then the \FINALLY{} clause is executed. Let $m$ be the immediately enclosing function. If $r$ is defined then the current return value is set to $r$ and then:
-\begin{itemize}
-\item
- if there is a dynamically enclosing error handler $g$ defined by a \FINALLY{} clause in $m$, control is transferred to $g$.
- \item
-Otherwise $m$ terminates.
-\end{itemize}
-
-Otherwise, execution resumes at the end of the try statement.
+Otherwise, if the type of $e$ is a subtype of $T_1$, then the first clause matches, and then $e_1$ is bound to the exception object $e$ and $t_1$ is bound to the stack trace $t$, and $s_1$ is executed in this scope.
+The matching completes in the same way as this execution.
 
 \LMHash{}
-Execution of an \ON{}-\CATCH{} clause \code{\ON{} $T$ \CATCH{} ($p_1$, $p_2$)} $s$ of a try statement $t$ proceeds as follows: The statement $s$ is executed in the dynamic scope of the exception handler defined by the finally clause of $t$. Then, the current exception and active stack trace both become undefined.
-
-\LMHash{}
-Execution of a \FINALLY{} clause \FINALLY{} $s$ of a try statement proceeds as follows:
-
-\LMHash{}
-Let $x$ be the current exception and let $t$ be the active stack trace. Then the current exception and the active stack trace both become undefined. The statement $s$ is executed. Then, if $x$ is defined,  it is rethrown as if by a rethrow statement (\ref{rethrow}) enclosed in a \CATCH{} clause of the form \code{\CATCH{} ($v_x$, $v_t$)} where $v_x$ and $v_t$ are fresh variables bound to $x$ and $t$ respectively.
-
-
-\LMHash{}
-Execution of a try statement of the form \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$ \FINALLY{} $s_f$;}  proceeds as follows:
-
-\LMHash{}
-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 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.
-}
-
-\LMHash{}
-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{} $\{\}$}.
+Otherwise, if the first clause did not match $e$, $e$ and $t$ are recursively matched against the remaining \ON{}-\CATCH{} clauses:
+\begin{dartCode}
+\ON{} $T_2$ \CATCH{} ($e_2$, $t_2$) \{ $s_2$ \}
+\ldots
+\ON{} $T_n$ \CATCH{} ($e_n$, $t_n$) \{ $s_n$ \}
+\end{dartCode}
 
 
 \subsection{ Return}
 \LMLabel{return}
 
 \LMHash{}
 The {\em return statement} returns a result to the caller of a synchronous function,  completes the future associated with an asynchronous function or terminates the stream or iterable associated with a generator (\ref{functions}).
 
 
  \begin{grammar}
 {\bf returnStatement:}
     \RETURN{} expression? `{\escapegrammar ;}' % could do top level here
     .
  \end{grammar}
 
- \commentary{
- Due to \FINALLY{} clauses, the precise behavior of \RETURN{} is a little more involved. Whether the value a return statement is supposed to return is actually returned depends on the behavior of any \FINALLY{} clauses in effect when executing the return. A \FINALLY{} clause may choose to return another value, or throw an exception, or even redirect control flow leading to other returns or throws. All a return statement really does is set a value that is intended to be returned when the function terminates.
- }
-
-\LMHash{}
-The {\em current return value} is a unique value specific to a given function activation. It is undefined unless explicitly set in this specification.
-
 \LMHash{}
 Executing a return statement \code{\RETURN{} $e$;} proceeds as follows:
 
 \LMHash{}
-First the expression $e$ is evaluated, producing an object $o$. Next:
-\begin{itemize}
-\item
-The current return value is set to $o$ and the current exception (\ref{throw}) and active stack trace (\ref{try}) become undefined.
-\item
-Let $c$ be the \FINALLY{} clause of the innermost enclosing try-finally statement (\ref{try}), if any. If $c$ is defined, let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$.
-\item
-Otherwise execution of the current method terminates.
-\end{itemize}
-
-\commentary{
-In the simplest case, the immediately enclosing function is an ordinary, synchronous non-generator, and upon function termination, the current return value is given to the caller.  The other possibility is that the function is marked \ASYNC{}, in which case the current return value is used to complete the future associated with the function invocation. Both these scenarios are specified in section \ref{functionInvocation}.
-The enclosing function cannot be marked as generator (i.e, \ASYNC* or \SYNC*), since generators are not allowed to contain a statement of the form \code{\RETURN{} $e$;} as discussed below.
-}
+First the expression $e$ is evaluated, producing an object $o$.
+Then the return statement completes by \em{returning} $o$.
 
 \LMHash{}
 Let $T$ be the static type of $e$ and let $f$ be the immediately enclosing function.
 
 \LMHash{}
 It is a static type warning if the body of $f$ is marked \ASYNC{} and the type \code{Future$<$flatten(T)$>$} (\ref{functionExpressions}) may not be assigned to the declared return type of $f$.    Otherwise, it is a static type warning if $T$ may not be assigned to the declared return type of $f$.
 
 \LMHash{}
-Let $S$ be the runtime type of $o$. In checked mode:
-\begin{itemize}
-\item  If the body of $f$ is marked \ASYNC{} (\ref{functions}) it is a dynamic type error if $o$ is not \NULL{} (\ref{null}) and \code{Future$<$flatten(S)$>$} is not a subtype of the actual return type  (\ref{actualTypeOfADeclaration}) of $f$.
-\item Otherwise, it is a dynamic type error if $o$ is not \NULL{} and the runtime type of $o$ is not a subtype of the actual return type of $f$.
-\end{itemize}
-
-\LMHash{}
 It is a compile-time error if a return statement of the form \code{\RETURN{} $e$;} appears in a generative constructor (\ref{generativeConstructors}).
 
 \rationale{
 It is quite easy to forget to add the factory prefix for a constructor, accidentally converting a factory into a generative constructor. The static checker may detect a type mismatch in some, but not all, of these cases. The rule above helps catch such errors, which can otherwise be very hard to recognize. There is no real downside to it, as returning a value from a generative constructor is meaningless.
 }
 
 \LMHash{}
 It is a compile-time error if a return statement of the form \code{\RETURN{} $e$;} appears in a generator function.
 
 \rationale{
 In the case of a generator function, the value returned by the function is the iterable or stream associated with it, and individual elements are added to that iterable using yield statements, and so returning a value makes no sense.
 }
 
 \LMHash{}
 Let $f$ be the function immediately enclosing a return statement of the form \RETURN{}; It is a static warning  $f$ is neither a generator nor a generative constructor and either:
 \begin{itemize}
 \item  $f$ is synchronous and the return type of $f$ may not be assigned to \VOID{} (\ref{typeVoid}) or,
 \item  $f$ is asynchronous and the return type of $f$ may not be assigned to \code{Future$<$Null$>$}.
 \end{itemize}
 
  \commentary{
 Hence, a static warning will not be issued if $f$ has no declared return type, since the return type would be  \DYNAMIC{} and  \DYNAMIC{} may be assigned to \VOID{} and to \code{Future$<$Null$>$}. However, any synchronous non-generator function that declares a return type must return an expression explicitly.
 }
 \rationale{This helps catch situations where users forget to return a value in a return statement.}
 
 \rationale{ An asynchronous non-generator always returns a future of some sort. If no expression is given, the future will be completed with \NULL{} and this motivates the requirement above.} \commentary{Leaving the return type of a function marked \ASYNC{}  blank will be interpreted as \DYNAMIC{} as always, and cause no type error. Using \code{Future} or \code{Future$<$Object$>$} is acceptable as well, but any other type will cause a warning, since \NULL{} has no subtypes.}
 
 \LMHash{}
-A return statement with no expression, \code{\RETURN;} is executed as follows:
+A return statement with no expression, \code{\RETURN;} is executed
+by {\em returning} with no value (\ref{completion}).
 
-\LMHash{}
-If the immediately enclosing function $f$ is a generator, then:
-\begin{itemize}
-\item
-The current return value is set to \NULL{}.
-\item
-Let $c$ be the \FINALLY{} clause of the innermost enclosing try-finally statement, if any. If $c$ is defined,  let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$.
-\item
-Otherwise, execution of the current method terminates.
-\end{itemize}
-
-\LMHash{}
-Otherwise the return statement is executed by executing the statement  \code{\RETURN{} \NULL{};} if it occurs inside a method, getter, setter or factory; otherwise, the return statement necessarily occurs inside a generative constructor, in which case it is executed by executing  \code{\RETURN{} \THIS{};}.
-
-\commentary{Despite the fact that \code{\RETURN{};} is executed as if by a \code{\RETURN{} $e$;}, it is important to understand that it is not a static warning to include a statement of the form \code{\RETURN{};}
-%in a \VOID{} function; neither is it illegal
-in a generative constructor. The rules relate only to the specific syntactic form \code{\RETURN{} $e$;}.
-}
-
-
-\rationale{
-The motivation for formulating \code{\RETURN{};} in this way stems from the basic requirement that all function invocations indeed return a value. Function invocations are expressions, and we cannot rely on a mandatory typechecker to always prohibit use of \VOID{} functions in expressions. Hence, a return statement must always return a value, even if no expression is specified.
-
-The question then becomes, what value should a return statement return when no return expression is given. In a generative constructor, it is obviously the object being constructed (\THIS{}). A void function is not expected to participate in an expression, which is why it is marked \VOID{} in the first place. Hence, this situation is a mistake which should be detected as soon as possible. The static rules help here, but if the code is executed, using \NULL{} leads to fast failure, which is desirable in this case. The same rationale applies for function bodies that do not contain a return statement at all.
-}
 
 \LMHash{}
 It is a static warning if a  function contains both one or more explicit return statements of the form \code{\RETURN;} and one or more return statements of the form \code{\RETURN{} $e$;}.
 
 
-
-
 \subsection{ Labels}
 \LMLabel{labels}
 
 \LMHash{}
 A {\em label} is an identifier followed by a colon. A {\em labeled statement} is a statement prefixed by a label $L$.  A {\em labeled case clause} is a case clause within a switch statement (\ref{switch}) prefixed by a label $L$.
 
 \rationale{The sole role of labels is to provide targets for the break (\ref{break}) and continue (\ref{continue}) statements.}
 
 %\Q{Are labels in a separate namespace? Bug 49774299}
 
  \begin{grammar}
 {\bf label:}
       identifier `{\escapegrammar :}'
     .
  \end{grammar}
 
 \LMHash{}
- The semantics of a labeled statement $L: s$ are identical to those of the statement $s$. The namespace of labels is distinct from the one used for types, functions and variables.
+Execution a labeled statement $s$, $label: s_l$, consists of executing $s_l$.
+If execution of $s_l$ aborts by {\em breaking} with the label $label$,
+then execution of $s$ completes normally,
+otherwise execution of $s$ aborts in the same ways as $sl$.
+
+The namespace of labels is distinct from the one used for types, functions and variables.
 
 \LMHash{}
 The scope of a label that labels a statement $s$ is $s$. The scope of a label that labels a case clause of a switch statement $s$ is $s$.
 
 \rationale{Labels should be avoided by programmers at all costs. The motivation for including labels in the language is primarily making Dart a better target for code generation.
 }
 
 
 \subsection{ Break}
 \LMLabel{break}
 
 \LMHash{}
 The {\em break statement} consists of the reserved word \BREAK{} and an optional label (\ref{labels}).
 
 \begin{grammar}
 {\bf breakStatement:}
      \BREAK{} identifier? `{\escapegrammar ;}'
     .
  \end{grammar}
 
 \LMHash{}
-Let $s_b$ be a \BREAK{} statement. If $s_b$ is of the form  \code{\BREAK{} $L$;}, then let $s_E$ be the innermost labeled statement with label $L$ enclosing $s_b$. If $s_b$ is of the form \code{\BREAK{};},  then let $s_E$ be the innermost  \DO{} (\ref{do}), \FOR{} (\ref{for}), \SWITCH{} (\ref{switch}) or \WHILE{} (\ref{while}) statement enclosing  $s_b$. It is a compile-time error if no such statement $s_E$ exists within the innermost function in which  $s_b$ occurs.  Furthermore, let $s_1, \ldots, s_n$ be those \TRY{} statements that are both enclosed in $s_E$ and that enclose  $s_b$, and that have a \FINALLY{} clause. Lastly, let $f_j$ be the \FINALLY{} clause of $s_j, 1 \le j \le n$.   Executing  $s_b$ first executes $f_1, \ldots,  f_n$ in innermost-clause-first  order and then terminates $s_E$.
+Let $s_b$ be a \BREAK{} statement. If $s_b$ is of the form  \code{\BREAK{} $L$;}, then let $s_E$ be the innermost labeled statement with label $L$ enclosing $s_b$. If $s_b$ is of the form \code{\BREAK{};},  then let $s_E$ be the innermost  \DO{} (\ref{do}), \FOR{} (\ref{for}), \SWITCH{} (\ref{switch}) or \WHILE{} (\ref{while}) statement enclosing  $s_b$. It is a compile-time error if no such statement $s_E$ exists within the innermost function in which  $s_b$ occurs.
 
 \LMHash{}
-If $s_E$ is an asynchronous for loop (\ref{asynchronousFor-in}), its associated stream subscription is canceled. Furthermore, let $a_k$ be the set of asynchronous for loops  and yield-each statements (\ref{yieldEach}) enclosing $s_b$ that are enclosed in $s_E , 1 \le k \le m$, where $a_k$ is enclosed in $a_{k+1}$.   The stream subscriptions associated with $a_j$ are canceled, $1 \le j \le m$, innermost first, so that $a_j$ is canceled before $a_{j+1}$.
+Execution of a \BREAK{} statement \code{\BREAK{} label;} completes by {\em breaking} with the label \code{label} (\ref{completion}).
 
+Execution of a \BREAK{} statement \code{\BREAK{};} completes by {\em breaking} without a label (\ref{completion}).
 
 
 \subsection{ Continue}
 \LMLabel{continue}
 
 \LMHash{}
 The {\em continue statement} consists of the reserved word \CONTINUE{} and an optional label (\ref{labels}).
 
 \begin{grammar}
 {\bf continueStatement:}
     \CONTINUE{} identifier? `{\escapegrammar ;}'
         .
  \end{grammar}
 
 \LMHash{}
- Let $s_c$ be a \CONTINUE{} statement. If $s_c$ is of the form  \code{\CONTINUE{} $L$;}, then let $s_E$ be the innermost labeled \DO{} (\ref{do}), \FOR{} (\ref{for}) or \WHILE{} (\ref{while}) statement or case clause with label $L$ enclosing $s_c$. If $s_c$ is of the form \code{\CONTINUE{};}  then let $s_E$ be the innermost  \DO{} (\ref{do}), \FOR{} (\ref{for}) or \WHILE{} (\ref{while}) statement enclosing  $s_c$. It is a compile-time error if no such statement or case clause $s_E$ exists within the innermost function in which  $s_c$ occurs.  Furthermore, let $s_1, \ldots, s_n$ be those \TRY{} statements that are both enclosed in $s_E$ and that enclose  $s_c$, and that have a \FINALLY{} clause. Lastly, let $f_j$ be the \FINALLY{} clause of $s_j, 1 \le j \le n$.   Executing  $s_c$ first executes $f_1, \ldots,  f_n$ in innermost-clause-first  order. Then, if $s_E$ is a case clause, control is transferred to the case clause. Otherwise, $s_E$ is necessarily a loop and execution resumes after the last statement in the loop body.
+Let $s_c$ be a \CONTINUE{} statement. If $s_c$ is of the form  \code{\CONTINUE{} $L$;}, then let $s_E$ be the innermost labeled \DO{} (\ref{do}), \FOR{} (\ref{for}) or \WHILE{} (\ref{while}) statement or case clause with label $L$ enclosing $s_c$. If $s_c$ is of the form \code{\CONTINUE{};}  then let $s_E$ be the innermost  \DO{} (\ref{do}), \FOR{} (\ref{for}) or \WHILE{} (\ref{while}) statement enclosing  $s_c$. It is a compile-time error if no such statement or case clause $s_E$ exists within the innermost function in which  $s_c$ occurs.
 
- \commentary{
- In a while loop, that would be the boolean expression before the body. In a do loop, it would be the boolean expression after the body. In a for loop, it would be the increment clause.  In other words, execution continues to the next iteration of the loop.
- }
+Execution of a \CONTINUE{} statement \code{\CONTINUE{} label;} completes by {\em continuing} with the label \code{label} (\ref{completion}).
+
+Execution of a \CONTINUE{} statement \code{\CONTINUE{};} completes by {\em continuing} without a label (\ref{completion}).
+
+
+\subsection{ Yield and Yield-Each}
+\LMLabel{yieldAndYieldEach}
+
+\subsubsection{ Yield}
+\LMLabel{yield}
 
 \LMHash{}
- If $s_E$ is an asynchronous for loop (\ref{asynchronousFor-in}), let $a_k$ be the set of asynchronous for loops and yield-each statements (\ref{yieldEach}) enclosing $s_c$ that are enclosed in $s_E , 1 \le k \le m$, where $a_k$ is enclosed in $a_{k+1}$.   The stream subscriptions associated with $a_j$ are canceled, $1 \le j \le m$, innermost first, so that $a_j$ is canceled before $a_{j+1}$.
+The {\em yield statement} adds an element to the result of a generator function (\ref{functions}).
 
- \subsection{ Yield and Yield-Each}
- \LMLabel{yieldAndYieldEach}
-
- \subsubsection{ Yield}
- \LMLabel{yield}
-
-\LMHash{}
- The {\em yield statement} adds an element to the result of a generator function (\ref{functions}).
-
- \begin{grammar}
+\begin{grammar}
 {\bf yieldStatement:}
    \YIELD{} expression `{\escapegrammar ;}'
       .
 \end{grammar}
 
 \LMHash{}
 Execution of a statement $s$ of the form \code{\YIELD{} $e$;}  proceeds as follows:
 
 \LMHash{}
-First, the expression $e$ is evaluated to an object $o$. If the enclosing function $m$ is marked \ASYNC* (\ref{functions}) and the stream $u$ associated with $m$ has been paused,  then execution of $m$ is suspended until $u$ is resumed or canceled.
+First, the expression $e$ is evaluated to an object $o$. If the enclosing function $m$ is marked \ASYNC* (\ref{functions}) and the stream $u$ associated with $m$ has been paused, then the nearest enclosing asynchronous for loop (\ref{asynchronousFor-in}), if any, is paused and execution of $m$ is suspended until $u$ is resumed or canceled.
 
 \LMHash{}
 Next, $o$ is added to the iterable or stream associated with the immediately enclosing function.
 
 \LMHash{}
-If the enclosing function $m$ is marked \ASYNC* and the stream $u$ associated with $m$ has been canceled, then let $c$ be the \FINALLY{} clause (\ref{try}) of the innermost enclosing try-finally statement, if any. If $c$ is defined, let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$. If $h$ is undefined, the immediately enclosing function terminates.
+If the enclosing function $m$ is marked \ASYNC* and the stream $u$ associated with $m$ has been canceled, then the \YIELD{} statement completes by {\em returning} without a value (\ref{completion}), otherwise it completes normally.
 
 \rationale{
 The stream associated with an asynchronous generator could be canceled by any code with a reference to that stream at any point where the generator was passivated.  Such a cancellation constitutes an irretrievable error for the generator. At this point, the only plausible action for the generator is to clean up after itself via its \FINALLY{} clauses.
 }
 
 \LMHash{}
-Otherwise, if the enclosing function $m$ is marked \ASYNC* (\ref{functions}) then the enclosing function may suspend.
+Otherwise, if the enclosing function $m$ is marked \ASYNC* (\ref{functions}) then the enclosing function may suspend, in which case the nearest enclosing asynchronous for loop (\ref{asynchronousFor-in}), if any, is paused first.
 
 \rationale {
 If a \YIELD{} occurred inside an infinite loop and the enclosing function never suspended, there might not be an opportunity for consumers of the  enclosing stream to run and access the data in the stream.  The stream might then accumulate an unbounded number of elements. Such a situation is untenable. Therefore, we allow the enclosing function to be suspended when a new value is added to its associated stream. However, it is not essential (and in fact, can be quite costly) to suspend the function on every \YIELD{}. The implementation is free to decide how often to suspend the enclosing function. The only requirement is that consumers are not blocked indefinitely.
 }
 
 
 \LMHash{}
 If the enclosing function $m$ is marked \SYNC* (\ref{functions}) then:
 \begin{itemize}
 \item
@@ skipping 32 matching lines @@
 
 \LMHash{}
 First, the expression $e$ is evaluated to an object $o$.
 
 \LMHash{}
 If the immediately enclosing function $m$ is marked \SYNC* (\ref{functions}), then:
 \begin{enumerate}
 \item It is a dynamic error if the class of $o$ does not implement \code{Iterable}.  Otherwise
 \item The method \cd{iterator} is invoked upon $o$ returning an object $i$.
 \item \label{moveNext} The \cd{moveNext} method of $i$ is invoked on it with no arguments. If \cd{moveNext} returns \FALSE{} execution of $s$ is complete. Otherwise
-\item The getter \cd{current} is invoked on $i$. If the invocation raises an exception $ex$, execution of $s$ throws $ex$. Otherwise, the result $x$ of the getter invocation is added to the iterable associated with $m$.
+\item The getter \cd{current} is invoked on $i$. If the invocation {\em throws} an exception $ex$, execution of $s$ aborts in the same way. Otherwise, the result $x$ of the getter invocation is added to the iterable associated with $m$.

[Kevin Millikin (Google), 2016/10/13 12:18:37]

I've always thought that calling current here is weird, because nobody has yet
called current on the outer iterator.

This has the consequence that if we have yield* e, and calling current throws
for some reason, we can never get the rest of the stuff from e because the
yield* has completed.

[Lasse Reichstein Nielsen, 2016/10/17 10:08:23]

This is the *simple* implementation which is basically equivalent to:
  for (var $ in e) yield $;

The behavior you are asking for is more involved. It requires the execution to
maintain extra state at all times - the "current yield* iterator". While that is
set, the sync* function body is suspended.

Any call to "moveNext" must first check if there is a current iterator, and if
there is, call its moveNext. Then, if that call returns true, return true,
otherwise clear the current yield* iterator and resume the sync* function body
(the yield8 either completes normally or throws, depending on what moveNext
did).

When you call the "current" getter of the sync* iterator, it first checks if
there is a current iterator, and if there is, it calls the "current" getter of
that iterator instead (and either returns or throws the same way), otherwise it
returns the current value last yielded by the sync* funtion body.

It's doable, but we need to specify the behavior of the returned Iterator for
both "current" and "moveNext", we can't just pretend there is a "current" value
that we can assign to.

I'm not sure this other behavior is better. 
It requires on extra field of storage, and one extra check at the beginning of
"moveNext" and "current", but that's small potatoes compared to the rest of the
sync* machinery, especially the way it's currently implemented. It makes the
specification more complicated (but then, I could make it less complicated by
saying that "yield* e;" is equivalent to "for (var $ in e) yield $;", which
would be completely true for the current specification, and I haven't done
that).

I'm not sure it'll actually help any user to make the change, but I can be
convinced. It's a prettier model that yield* just forwards moveNext and current
to the new stream, and it might enable a more efficient implementation strategy
(not that I have one in mind).

 Execution of the function $m$ immediately enclosing $s$ is suspended until the nullary method \code{moveNext()} is invoked upon the iterator used to initiate the current invocation of $m$, at which point execution of $s$ continues at \ref{moveNext}.
 \item
 The current call to \code{moveNext()} returns \TRUE.
 \end{enumerate}
 
 \LMHash{}
 If $m$ is marked \ASYNC* (\ref{functions}), then:
 \begin{itemize}
 \item  It is a dynamic error if the class of $o$ does not implement \code{Stream}. Otherwise
-\item For each element $x$ of $o$:
+\item The nearest enclosing asynchronous for loop (\ref{asynchronousFor-in}), if any, is paused.
+\item The $o$ stream is listened to, creating a subscription $s$, and for each event $x$, or error $e$ with stack trace $t$, of $s$:
 \begin{itemize}
 \item
-If the stream $u$ associated with $m$ has been paused,  then execution of $m$ is suspended until $u$ is resumed or canceled.
- \item
-If the stream $u$ associated with $m$ has been canceled, then let $c$ be the \FINALLY{} clause (\ref{try}) of the innermost enclosing try-finally statement, if any. If $c$ is defined,  let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$. If $h$ is undefined, the immediately enclosing function terminates.
+If the stream $u$ associated with $m$ has been paused, then execution of $m$ is suspended until $u$ is resumed or canceled.
 \item
-Otherwise,  $x$ is added to the stream associated with $m$ in the order it appears in $o$.  The function $m$ may suspend.
+If the stream $u$ associated with $m$ has been canceled,
+then $s$ is canceled by evaluating \code{\AWAIT{} v.cancel()} where $v$ is a fresh variable referencing the stream subscription $s$.
+Then, if the cancel completed normally, the stream execution of $s$ aborts by {\em returning} with no value (\ref{completion}).
+\item
+Otherwise, $x$, or $e$ with $t$, are added to the stream associated with $m$ in the order they appears in $o$.  The function $m$ may suspend.
 \end{itemize}
-\item If the stream $o$ is done, execution of $s$ is complete.
+\item If the stream $o$ is done, execution of $s$ completes normally.
 \end{itemize}
 
 
 \LMHash{}
 It is a compile-time error if a yield-each statement appears in a function that is not a generator function.
 
 \LMHash{}
 Let $T$ be the static type of $e$ and let $f$ be the immediately enclosing function.  It is a static type warning if $T$ may not be assigned to the declared return type of $f$.  If $f$ is synchronous it is a static  type warning if $T$ may not be assigned to \code{Iterable}.  If $f$ is asynchronous it is a static  type warning if $T$ may not be assigned to \code{Stream}.
 
 
 \subsection{ Assert}
 \LMLabel{assert}
 
 \LMHash{}
 An {\em assert statement} is used to disrupt normal execution if a given boolean condition does not hold.
 
 \begin{grammar}
 {\bf assertStatement:}
    assert `(' expression `)' `{\escapegrammar ;}'
       .
 \end{grammar}
 
 \LMHash{}
 The assert statement has no effect in production mode. In checked mode, execution of an assert statement \code{\ASSERT{}($e$);} proceeds as follows:
 
 \LMHash{}
 The expression $e$ is evaluated to an object $o$. If the class of $o$ is a subtype of \code{Function} then let $r$ be the result of invoking $o$ with no arguments. Otherwise, let $r$ be $o$.
-It is a dynamic type error if $o$ is not of type \code{bool} or of type \code{Function}, or if $r$ is not of type \code{bool}.  If $r$ is \FALSE{}, we say that the assertion failed. If $r$ is \TRUE{}, we say that the assertion succeeded. If the assertion succeeded, execution of the assert statement is complete. If the assertion failed, an \code{AssertionError} is thrown.
+It is a dynamic type error if $o$ is not of type \code{bool} or of type \code{Function}, or if $r$ is not of type \code{bool}.  If $r$ is \FALSE{}, we say that the assertion failed. If $r$ is \TRUE{}, we say that the assertion succeeded. If the assertion succeeded, execution of the assert statement is complete. If the assertion failed, the execution {\em throws} an \code{AssertionError} with a stack trace corresponding to the \ASSERT{} statement.
 
 %\Q{Might be cleaner to define it as \code{if (!$e$) \{\THROW{} \NEW{} AssertionError();\}} (in checked mode only).
 %What about an error message as part of the assert?}
 
 \LMHash{}
  It is a static type warning if the type of $e$ may not be assigned to either  \code{bool} or $() \rightarrow$ \code{bool}.
 
 \rationale{Why is this a statement, not a built in function call? Because it is handled magically so it has no effect and no overhead in production mode. Also, in the absence of final methods. one could not prevent it being overridden (though there is no real harm in that).  It cannot be viewed as a function call that is being optimized away because the argument might have side effects.
 }
 
@@ skipping 1390 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.
 
 ----------------------------------------------------------------------