Added generic method syntax to language specification.

docs/language/dartLangSpec.tex

 \documentclass{article}
 \usepackage{epsfig}
 \usepackage{color}
 \usepackage{dart}
 \usepackage{bnf}
 \usepackage{hyperref}
 \usepackage{lmodern}
 \usepackage[T1]{fontenc}
 \newcommand{\code}[1]{{\sf #1}}
 \title{Dart Programming Language  Specification  \\
@@ skipping 576 matching lines @@
 
 
 \section{Functions}
 \LMLabel{functions}
 
 \LMHash{}
 Functions abstract over executable actions.
 
 \begin{grammar}
 {\bf functionSignature:}
-    metadata returnType? identifier formalParameterList
+      metadata returnType? identifier formalParameterPart
+    .
+
+{\bf formalParameterPart:}
+      typeParameters? formalParameterList
     .
 
 {\bf returnType:}
       \VOID{};
       type
     .
 
 {\bf functionBody:} \ASYNC{}?  `={\escapegrammar \gt}' expression `{\escapegrammar ;}';
      (\ASYNC{} $|$ \ASYNC* $|$ \SYNC*)? block
     .
 
 {\bf block:}
       `\{' statements `\}'
     .
 
 \end{grammar}
 
 \LMHash{}
-Functions include  function declarations (\ref{functionDeclarations}), methods (\ref{instanceMethods},  \ref{staticMethods}), getters  (\ref{getters}), setters  (\ref{setters}), constructors  (\ref{constructors}) and function literals  (\ref{functionExpressions}).
+Functions include function declarations (\ref{functionDeclarations}), methods (\ref{instanceMethods}, \ref{staticMethods}), getters (\ref{getters}), setters (\ref{setters}), constructors (\ref{constructors}) and function literals (\ref{functionExpressions}).

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

Does "function" refer to the syntactic declaration or its semantic meaning?

If it's the former, consider changing "Functions" to "Function declarations".

[eernst, 2017/02/14 11:26:44]

This is one of several cases where I've removed spurious spaces from a line
which was modified during the writing process but at the end came back to the
original wording. I thought it wouldn't hurt to keep the space-normalization,
now that I had already done it. So now I'll reconsider that original wording.
;-)

I definitely think that the whole sentence fits in with the interpretation that
it is a list of syntactic constructs.

Adjusted the sentence such that the first word `Functions` refers to the
semantic entity, and says that it is `introduced by` all those syntactic forms.

 
 \LMHash{}
-All functions have a signature and a body. The signature describes the formal parameters of the function, and possibly its name and return type.  A function body is either:
+All functions have a signature and a body.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

... except abstract and external methods have no body, and neither does some
constructors.
(No rule without an exception :)

[eernst, 2017/02/14 11:26:44]

Maintaining the focus on syntax, and allowing for abstract and external
declarations via the word 'some'.

+The signature describes the formal parameter part of the function, its name, and possibly its return type.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

... except that function expressions do not have a name, so: "its name (if
any),"?

Is "signature" a lexical, static or dynamic concept? (which goes back to: is
"function" a lexical, static or dynamic concept?)

[eernst, 2017/02/14 11:26:44]

Adjusted to mention the exceptions (getter, literal).

I consider 'signature' to be a syntactic concept here. The coercion to a
semantic entity may happen implicitly here and there, but since it is never a
first class entity I believe that we can maintain "it's syntax" and tolerate the
excursions into semantics as needed.

Do you think we need to introduce explicit terminology for a semantic notion of
signatures? We do need to talk about the function type, but that's a separate
term already, and the spec explicitly specifies how to compute it.

+The formal parameter part optionally specifies the formal type parameter list of the function, and it specifies its formal parameter list.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

formal parameter list, if any.

(Getters have no formal parameter list, they are included in the list above).

[eernst, 2017/02/14 11:26:44]

I've mentioned the exception for getters above, so they should be out of the
picture at this point.

+The effect of a declaration $D$ of a function that includes a formal type parameter list is the same as the effect of the declaration obtained by the generic function erasure of $D$ (\ref{genericFunctionErasure}).
+A function body is either:
 \begin{itemize}
 \item A block statement  (\ref{blocks}) containing the statements  (\ref{statements}) executed by the function, optionally marked with one of the modifiers: \ASYNC, \ASYNC* or \SYNC*. In this case, if the last statement of a function is not a return statement (\ref{return}), the statement \code{\RETURN{};} is implicitly appended to the function body.
 
 \rationale{
 Because Dart is optionally typed, we cannot guarantee that a function that does not return a value will not be used in the context of an expression. Therefore, every function must return a value. A \RETURN{} without an expression returns \NULL{}. For generator functions, the situation is more subtle. See further discussion in section \ref{return}.
 }
 
 OR
 \item of the form   \code{=> $e$} which is equivalent to a body of the form \code{\{\RETURN{} $e$;\}} or the form \code{\ASYNC{} => $e$} which is equivalent to a body of the form \code{\ASYNC{} \{\RETURN{} $e$;\}}. \rationale{The other modifiers do not apply here, because they apply only to generators, discussed below, and generators do not allow the form \code{\RETURN{} $e$}; values are added to the generated stream or iterable using \YIELD{} instead.}
 
@@ skipping 60 matching lines @@
 When we say that a function $f_1$ {\em forwards} to another function $f_2$, we mean that  invoking $f_1$ causes $f_2$ to  be executed with the same arguments and/or receiver as $f_1$, and returns the result of executing $f_2$ to the caller of $f_1$, unless $f_2$ throws an exception, in which case $f_1$ throws the same exception. Furthermore, we only use the term for synthetic functions introduced by the specification.
 
 
 \subsection{Formal Parameters}
 \LMLabel{formalParameters}
 
 \LMHash{}
 Every function includes a {\em formal parameter list}, which consists of a list of required positional parameters (\ref{requiredFormals}), followed by any optional parameters (\ref{optionalFormals}). The optional parameters may be specified either as a set of named parameters or as a list of positional parameters, but not both.
 
 \LMHash{}
-The formal parameter list of a function introduces a new scope known as the function's {\em formal parameter scope}. The formal parameter scope of a function $f$  is enclosed in the scope where $f$ is declared.   Every formal parameter introduces a local variable into the formal parameter scope. However, the scope of a function's signature is the function's enclosing scope, not the formal parameter scope.
+The formal parameter list of a function introduces a new scope known as the function's {\em formal parameter scope}.
+The formal parameter scope of a non-generic function $f$ is enclosed in the scope where $f$ is declared.
+The formal parameter scope of a generic function $f$ is enclosed in the formal type parameter scope of $f$ (\ref{genericFunctionErasure}).
+Every formal parameter introduces a local variable into the formal parameter scope.
+However, the scope of a function's signature is the function's enclosing scope, not the formal parameter scope.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

What *is* a "signature"?

[eernst, 2017/02/14 11:26:44]

Line 712 is again something that I did not touch (but I split the long line into
one line per sentence, as usual).

I believe that a signature is syntax, and I'm not sure there is a semantic
entity for it. Semantics is relevant for complete functions and for function
types, but the function types do not include the name so that isn't exactly a
signature.

Scopes can apply to syntax because they are used during lookups, and lookups
refers to names (and even though you can claim that they are 'semantic names',
they are very nearly syntax).

I usually say 'scope S is the current scope for A' in order to say that the
specific scope S is the first one to be searched during lookups when a name is
encountered in the syntactic construct A, except for parts of A where further
nested scopes are active.

I believe Gilad is saying that the parameter names aren't in scope for terms in
the signature (so we could have `C foo(C C)` where the last `C` is the parameter
name, and the first two `C`s are a class `C` from the enclosing scope).

Changed line 712 to use the 'current' terminology. Added a commentary, too.

 
 \LMHash{}
 The body of a function introduces a new scope known as the function's {\em  body scope}. The body scope of a function $f$  is enclosed  in the scope introduced by the formal parameter scope of $f$.
 
 
 %The formal parameter scope of a function maps the name of each formal parameter $p$ to the value $p$ is bound to.
 
 % The formal parameters of a function are processed in the enclosing scope of the function.
 % \commentary{this means that the parameters themselves may not be referenced within the formal parameter list.}
 
@@ skipping 56 matching lines @@
 {\bf normalFormalParameter:}functionSignature;
       fieldFormalParameter;
       simpleFormalParameter
  .
 
 {\bf simpleFormalParameter:}declaredIdentifier;
       metadata identifier
     .
 
 {\bf fieldFormalParameter:}
-   metadata finalConstVarOrType? \THIS{} `{\escapegrammar .}' identifier formalParameterList?
-   .
+      metadata finalConstVarOrType? \THIS{} `{\escapegrammar .}' identifier formalParameterPart?
+    .
 \end{grammar}
 
 %\subsubsection{Rest Formals}
 %\LMLabel{restFormals}
 
 %A rest formal $R$ must be the last parameter in a formal parameter list.  If a  type $T$ is specified for $R$, it signifies that the type of $R$ is $T[]$.
 
 %\begin{grammar}
 %restFormalParameter:
 %      finalConstVarOrType? '{\escapegrammar ...}' identifier
@@ skipping 37 matching lines @@
 If we allowed named parameters to begin with an underscore, they would be considered private and inaccessible to callers from outside the library where it was defined. If a method outside the library overrode a method with a private optional name, it would not be a subtype of the original method. The static checker would of course flag such situations, but the consequence would be that adding a private named formal would break clients outside the library in a way they could not easily correct.
 }
 
 \subsection{Type of a Function}
 \LMLabel{typeOfAFunction}
 
 \LMHash{}
 If a function does not declare a return type explicitly, its return type is \DYNAMIC{} (\ref{typeDynamic}), unless it is a constructor function, in which case its return type is the immediately enclosing class.
 
 \LMHash{}
+A function may declare formal type parameters.
+The type of the function is the type of the corresponding function obtained by generic function erasure (\ref{genericFunctionErasure}).
+
+\commentary{
+Hence, formal type parameters are not mentioned in the following, but they are allowed to exist.
+}
+
+\LMHash{}
 Let $F$ be a function with required formal parameters $T_1$ $p_1 \ldots, T_n$ $p_n$, return type $T_0$ and no optional parameters. Then the type of $F$ is $(T_1 ,\ldots, T_n) \rightarrow T_0$.
 
 \LMHash{}
 Let $F$ be a function with required formal parameters $T_1$ $p_1 \ldots, T_n$ $p_n$, return type $T_0$ and positional optional parameters $T_{n+1}$ $p_{n+1}, \ldots, T_{n+k}$ $ p_{n+k}$. Then the type of $F$ is $(T_1 ,\ldots, T_n, [T_{n+1}$ $p_{n+1}, \ldots, T_{n+k}$  $p_{n+k}]) \rightarrow T_0$.
 
 \LMHash{}
 Let $F$ be a function with required formal parameters $T_1$ $p_1 \ldots, T_n$ $p_n$, return type $T_0$ and named optional parameters $T_{n+1}$ $p_{n+1}, \ldots, T_{n+k}$ $ p_{n+k}$. Then the type of $F$ is $(T_1 ,\ldots, T_n, \{T_{n+1}$ $p_{n+1}, \ldots, T_{n+k}$  $p_{n+k}\}) \rightarrow T_0$.
 
 \LMHash{}
 The run time type of a function object always implements the class \cd{Function}.
@@ skipping 1435 matching lines @@
 \end{dartCode}
 
 \commentary {
 It is also a compile-time error to subclass, mix-in or implement an enum or to explicitly instantiate an enum.  These restrictions are given in normative form in sections \ref{superclasses}, \ref{superinterfaces}, \ref{mixinApplication} and \ref{instanceCreation} as appropriate.
 }
 
 \section{Generics}
 \LMLabel{generics}
 
 \LMHash{}
-A class declaration (\ref{classes}) or type alias (\ref{typedef})
-$G$ may be {\em generic}, that is, $G$ may have formal type parameters declared. A generic declaration induces a family of declarations, one for each set of actual type parameters provided in the program.
+A class declaration (\ref{classes}), type alias (\ref{typedef}), or function (\ref{functions}) $G$ may be {\em generic}, that is, $G$ may have formal type parameters declared.
+A declaration of a generic class or a generic type alias induces a family of declarations, one for each actual type argument list provided in the program.
+The effect of a declaration $D$ of a generic function is the same as the effect of the declaration obtained by generic function erasure of $D$ (\ref{genericFunctionErasure}).
 
 \begin{grammar}
 {\bf typeParameter:}
      metadata identifier (\EXTENDS{} type)?
     .
 {\bf typeParameters:}
      `<' typeParameter (`,' typeParameter)* `>'
     .
 \end{grammar}
 
 \LMHash{}
-A type parameter $T$ may be suffixed with an \EXTENDS{} clause that specifies the {\em upper bound} for $T$. If no  \EXTENDS{} clause is present, the upper bound is \code{Object}.  It is a static type warning if a type parameter is a supertype of its upper bound. The bounds of type variables are a form of type annotation and have no effect on execution in production mode.
+A type parameter $T$ may be suffixed with an \EXTENDS{} clause that specifies the {\em upper bound} for $T$.
+If no \EXTENDS{} clause is present, the upper bound is \code{Object}.
+It is a static type warning if an actual type argument to a class or a type alias is not a subtype of its upper bound.
+The bounds of type variables are a form of type annotation and have no effect on execution in production mode.
 
 \LMHash{}
 Type parameters are declared in the type-parameter scope of a class.
 The type parameters of a generic $G$ are in scope in the bounds of all of the type parameters of $G$. The type parameters of a generic class declaration $G$ are also in scope in the \EXTENDS{} and \IMPLEMENTS{} clauses of $G$ (if these exist) and in the body of $G$.   However, a type parameter is considered to be a malformed type when referenced by a static member.
 
 \rationale{
 The restriction is necessary since a type variable has no meaning in the context of a static member, because statics are shared among all instantiations of a generic. However, a type variable may be referenced from an instance initializer, even though \THIS{} is not available.
 }
 
 \commentary{
@@ skipping 86 matching lines @@
 
 %\Q{When does an interface injection take effect? When the containing library is loaded?
 %What is the scope of such a declaration? Is it global, or only in the scope of the containing library? The scope of such a declaration is global.
 %An injection must be at top level. Who has the right to inject an interface $I$ into another class $C$? Anybody? But since this affects dynamic behavior, is this a weird security issue?
 %The current theory is that there is no security within an isolate, and one can never refer to a type from another isolate, so supposedly not an issue. This assumption (no mutually suspicious code in the same isolate) is suspect but it seems there is nothing to be done at this point.
 %If libs are first class, they get created dynamically in order, and new libs might modify the type relations among other libs types - but then it is clear when that happened and order is ok.
 %}
 
 %It is a compile-time error if a type $T$ appears more than once in the implements or eextends clause of  an interface  injection.
 
+\subsection{Generic Function Erasure}
+\LMLabel{genericFunctionErasure}
+
+\commentary{
+Generic functions will be fully supported in a future version of the language.
+The current level of support allows programs using generic functions to be written, compiled, and executed.
+The type checks and dynamic semantics essentially erase the formal type parameters and actual type arguments.
+With some extra care, the same source code can be used both in this language and in a version of the language with full support for generic functions.
+Type checking with full support for generic functions may then ensure some consistency properties which remain valid also in this context.
+This section explains how generic function erasure works.
+}
+
+\LMHash{}
+Many function declarations may include a {\em formal type parameter list} (\ref{functions}), in which case we say that it is a {\em generic function}.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

"Many" -> "Some".

[eernst, 2017/02/14 11:26:44]

Done.

+A {\em non-generic function} is a function which is not generic.
+
+\commentary{
+The exceptions are getter, setter, operator, and constructor declarations.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

"... , which cannot be generic."
(Didn't say what it was an exception of).

[eernst, 2017/02/14 11:26:44]

Done.

+}
+
+\LMHash{}
+The formal type parameter list of a function introduces a new scope known as the function's {\em formal type parameter scope}.
+The formal type parameter scope of a generic function $f$ is enclosed in the scope where $f$ is declared.
+Every formal type parameter introduces a type into the formal type parameter scope.
+
+\LMHash{}
+The formal type parameter scope of a function $f$ is the current scope for the return type of $f$, if any, and for the formal type parameter list itself.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

The type parameter list is in its own scope. What does that *mean*?
I understand that the bounds are in that scope, but what does it mean that the
type parameter identifier itself is in a scope where it's declared?

[eernst, 2017/02/14 11:26:44]

The declaring occurrence of a type parameter identifier is syntactically known
to be declaring, and applied occurrences in bounds are similarly known to be
applied. So the latter will be subject to lookups, but the former are not. Hence
it makes no difference which scope is the current scope for the declaring
occurrences. Hence it is a non-problem that their current scope is the formal
type parameter scope.

No changes performed in this case.

+
+\commentary{
+This enables the use of F-bounded type parameters (if you don't know what that is, see~\ref{generics}).

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

Drop this enitre sentence. It doesn't say anything important.

[eernst, 2017/02/14 11:26:44]

It was a stupid joke (referring to \ref{generics}: "Because type parameters are
in scope in their bounds, we support F-bounded quantification (if you don't know
what that is, don't ask).").

Deleted the joke, but kept the phrase mentioning F-bounded type parameters,
because this is part of a natural progression: First we talk about direct access
to the names of type parameters in this scope (F-bounds will find these names in
the current scope) and then we talk about indirect access (type annotations and
type arguments in the formal parameter list and in the body will find these
names in an enclosing scope).

+The formal type parameter scope is the enclosing scope for the formal parameter scope (\ref{formalParameters}), which enables usage of the type parameters in type annotations in the parameter list, and in the body of the function.
+}
+
+\LMHash{}
+{\em Generic function erasure} takes as input a generic function declaration $D$ and either yields a non-generic function declaration $D^{\prime}$ or terminates with a compile-time error.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

Do you need to super-script the \prime?
Consider using $D_E$ for the erased declaration. Do we use "prime" anywhere
else?

[eernst, 2017/02/14 11:26:44]

As far as I can see, we have 54 occurrences of `\prime` and they are all in
superscript. It may be unnecessary, but I guess this makes them a bit smaller,
which might look better. Haven't made any experiments.
Just checking for reasons: I believe `\prime` is used to describe auxiliar
looked-up or computed entities.

Line 1581: redirecting factory constructor, \prime is used to denote the target
constructor

Line 1886: for transitivity of subclassing, `S^\prime` is the intermediate
class.

Line 1915: `m^\prime` is a member which is overridden by a given member `m`,
used in a discussion about overriding rules.

Line 2100: more overriding stuff.

Line 5957: `c^\prime` is computed from `c`, which is the condition of a 'for'
statement.

Line 5964: `v^\prime` is the fresh variable which is created for each iteration
of a 'for' statement.

Especially the last ones fit quite well, because they are about program 
transformations used to specify the semantics of a given construct.

But after thinking about it, I guess it would be more readable to use
`D_{erased}`, so I'll do that.

+$D^{\prime}$ is identical to $D$ except for the following replacements:
+\begin{itemize}
+\item The formalParameterPart of $D^{\prime}$ is identical to the formalParameterList of $D$.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

Should "formalParameterPart" be styled in some way?

[eernst, 2017/02/14 11:26:44]

The grammar rules in text actually do not have any special font features,
they're just boldface when on the left hand side of a grammar rule. Using
boldface here, because that at least gives a hint of "grammar stuff".

We have many occurrences of words like 'identifier' that happen to be grammar
non-terminals as well as "normal words". I'm not sure whether there are any such
words which should be considered carefully in order to decide whether to
`\GrammarSymbol` them. Fixing only these two words at this point.

+  \commentary{That is, the type parameter list is erased.}

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

erased -> omitted

"erase" is a destructive operation, but we don't change the original, we create
a new one without some of the original parts.

[eernst, 2017/02/14 11:26:44]

True. I actually wrote `omitted` first because that's the direct way to say what
is going on; but later I changed it to `erased` because it is so similar to the
erasure which has been used in Java for many years. In that sense, it might push
the right button in the heads of readers who know about Java.

Still prefer `omitted`?

+\item Each occurrence in $D$ of an identifier $id$ which denotes a formal type parameter is processed as follows:
+  \begin{itemize}
+  \item If $id$ occurs as \code{$e$ \IS{} $id$} or \code{$e$ \IS{}! $id$} for some expression $e$, or if $id$ occurs as a type literal, a compile-time error occurs.
+  \item In all other cases, the location corresponding to $id$ in $D^{\prime}$ contains \DYNAMIC{}.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

... all other cases, the occurrence of $id$ in $D$ is replaced by \DYNAMIC{} in
$D_E$.

[eernst, 2017/02/14 11:26:44]

Frem og tilbage er lige langt. ;-D

In this case, 'the corresponding location contains' is completely declarative
(..that's just how it is, nobody is doing anything..), whereas 'replace' implies
mutation. In a sense, it contradicts the notion of having a $D$ and a
\Derased{}, and specifying the latter in terms of the similarities/differences
to the former, and hints at an editing process which operates on $D$ for a
while, at which point we rename it to \Derased{}.

Still `replace`? ;)

+  \end{itemize}
+\end{itemize}
+
+\commentary{
+This means that formal type parameters in a generic function work like \DYNAMIC{} when used as type annotations.
+This is also the case when they are used as type arguments, both in type annotations and in instance creation expressions.
+For example, \code{\RETURN{} <T>[];} will return a \code{List<\DYNAMIC{}>}.
+Finally, \code{$e$ \AS{} $id$} will work like \code{$e$ \AS{} \DYNAMIC{}}, i.e., the dynamic check associated with a cast is omitted, and the static type of the expression will be \DYMAMIC{}.
+}
+
+\rationale{
+The check associated with a cast to a type parameter of a generic function is omitted because such checks are almost always expected to succeed.
+This may introduce bugs in failure handling, so a more defensive style of programming may be needed around such casts.
+In contrast, an is-expression may yield \TRUE{} as well as \FALSE{} during normal processing, and it could silently introduce bugs into correct programs if we had chosen to always evaluate these is-expressions to a fixed value like \TRUE{}.
+Finally, it could silently introduce bugs into correct programs if we had chosen to let type literals evaluate to a fixed value, e.g., \DYNAMIC{}.
+}
 
 \section{Metadata}
 \LMLabel{metadata}
 
 \LMHash{}
 Dart supports metadata which is used to attach user defined annotations to program structures.
 
 \begin{grammar}
 {\bf metadata:}
       (`@' qualified ({\escapegrammar `.'} identifier)? (arguments)?)*
@@ skipping 803 matching lines @@
 
 
 \subsection{ Function Expressions}
 \LMLabel{functionExpressions}
 
 \LMHash{}
 A {\em function literal} is an object that encapsulates an executable unit of code.
 
 \begin{grammar}
 {\bf functionExpression:}
-    formalParameterList functionBody
+      formalParameterPart functionBody
     .
  \end{grammar}
 
 \LMHash{}
 The class of a function literal implements the built-in class \code{Function}.
 %Invoking the getter \code{runtimeType} on a function literal returns the \code{Type} object that is the value of the expression \code{Function}.
 % not necessarily
 
-
 %Q{Can anyone implement it? Then we should define things via call}
 
 \LMHash{}
 The static type of a function literal of the form
 
 $(T_1$ $a_1, \ldots, T_n$ $a_n, [T_{n+1}$ $x_{n+1} = d_1, \ldots,  T_{n+k}$ $x_{n+k} = d_k]) => e$
 is
 
 $(T_1 \ldots, T_n, [T_{n+1}$ $x_{n+1}, \ldots, T_{n+k}$ $x_{n+k}]) \rightarrow T_0$, where $T_0$ is the static type of $e$.
 
@@ skipping 420 matching lines @@
 \commentary{
 As discussed in section \ref{errorsAndWarnings}, the handling of a suspended isolate is the responsibility of the embedder.
 }
 
 
 
 \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.
+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.
+The actual type arguments passed to $f$, if any, have no effect.
+When the body of $f$ is executed it will be executed with the aforementioned bindings.
 
 \LMHash{}
 If $f$ is synchronous and is not a generator (\ref{functions}) then execution of the body of $f$ begins immediately.
 If the execution of the body of $f$ returns a value, $v$, (\ref{completion}), the invocation evaluates to $v$.
 If the execution completes normally or it returns without a value, the invocation evaluates to \NULL (\ref{null}).
 If the execution throws an exception object and stack trace, the invocation throws the same exception object and stack trace (\ref{evaluation}).
 
 \commentary{
 A complete function body can never break or contine (\ref{completion})
 because a \BREAK{} or \CONTINUE{} statement must always occur inside the statement that is the target of the \BREAK{} or \CONTINUE{}.
 This means that a function body can only either complete normally, throw, or return. Completing normally or returning without a value is treated the same as returning \NULL, so the result of executing a function body can always be used as the result of evaluating an expression, either by evaluating to a value or by the evaluation throwing.
 }
 
 
 \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 execution of the body of $f$ completes (\ref{completion},
+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 execution of the body of $f$ completes (\ref{completion}),
 \begin{itemize}
 \item If it returns without a value or it completes normally (\ref{completion}), $j$ is positioned after its last element, so that its current value is \code{null} and the current call to \code{moveNext()} on $j$ returns false, as must all further calls.
 \item If it throws an exception object $e$ and stack trace $t$ then the current value of $j$ is \NULL and the current call to \code{moveNext()} throws $e$ and $t$ as well. Further calls to \code{moveNext()} must return false.
 \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
@@ skipping 51 matching lines @@
   %    expressionList ',' spreadArgument;
       expressionList (`,' namedArgument)*
 %      spreadArgument
     .
 
 {\bf namedArgument:}
       label expression % could be top level expression?
     .
  \end{grammar}
 
-Argument lists allow an optional trailing comma after the last argument ($`,'?$). An argument list with such a trailing comma is equivalent in all ways to the same parameter list without the trailing comma. All argument lists in this specification are shown without a trailing comma, but the rules and semantics apply equally to the corresponding argument list with a trailing comma.
+\LMHash{}
+Argument lists allow an optional trailing comma after the last argument ($`,'?$).
+An argument list with such a trailing comma is equivalent in all ways to the same argument list without the trailing comma.
+All argument lists in this specification are shown without a trailing comma, but the rules and semantics apply equally to the corresponding argument list with a trailing comma.
+
+\LMHash{}
+When parsing an argument list, an ambiguity may arise because the same source code could be one generic function invocation, and it could be two or more relational expressions and/or shift expressions.
+In this situation, the parse as a generic function invocation is chosen.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

-> In this situation, the expression is always parsed as a generic function
invocation.

[eernst, 2017/02/14 11:26:44]

Done.

+
+% Should we specify the precise disambiguation rule here?:
+%   We have seen 'a', '<', a matching '>', and '(', where
+%   'a' is tricky because we can have things like 'new Foo().m<...>(...',
+%   'x..y(...).m<...>(...', etc, basically everything that can precede
+%   argumentPart in the grammar.
+
+\commentary{
+An example is \code{f(a<B, C>($d$))}, which may be an invocation of \code{f} passing two actual arguments of type \code{bool}, or an invocation of \code{f} passing the result returned by an invocation of the generic function \code{a}.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:32]

Why is $d$ in code, but not a, B or C?
I can see that B and C must be type names, but at least 'a' can also be an
arbitrary expression.

[eernst, 2017/02/14 11:26:44]

Right, but this is commentary and we just need a single example, so I was
thinking about `a`, `B`, and `C` as concrete identifiers, i.e., literal syntax,
and `d` as a more arbitrary expression, which could concretely create a need for
the parentheses. 

Maybe we should just make `d` concrete as well, and use `\code{a<B,
C>(d..foo()..bar())}`, which would create that need?

+Note that the ambiguity may be eliminated by omitting the parentheses around the expression $d$, or adding parentheses around one of the relational expressions.

[Lasse Reichstein Nielsen, 2017/02/13 10:26:31]

Or around \code{B} or \code{C}.

[eernst, 2017/02/14 11:26:44]

That wouldn't actually work, because we did not require for a commitment to
"this is a generic call" that the type arguments be syntactically correct, we
just required the matching angle brackets.

So `f(a<B, (C)>(d))` would be a syntax error because `(C)` is not a proper type
argument, because `a<.., ..>(` is enough to decide that it isn't two bool args.

+}
+
+\rationale{
+When the intention is to pass several relational or shift expressions as actual arguments and there is an ambiguity, the source code can easily be adjusted to a form which is unambiguous.
+Also, we expect that it will be more common to have generic function invocations as actual arguments than having relational or shift expressions that happen to match up and have parentheses at the end, such that the ambiguity arises.
+}
 
 \LMHash{}
 Evaluation of an actual argument list of the form
 
 $(a_1, \ldots, a_m, q_1: a_{m+1}, \ldots, q_l: a_{m+l})$
 
 proceeds as follows:
 
 \LMHash{}
 The arguments $a_1, \ldots, a_{m+l}$ are evaluated in the order they appear in the program, producing objects $o_1, \ldots, o_{m+l}$.
@@ skipping 279 matching lines @@
 
 \subsubsection{Cascaded Invocations}
 \LMLabel{cascadedInvocations}
 
 \LMHash{}
 A {\em cascaded method invocation} has the form \code{$e$..\metavar{suffix}}
 where $e$ is an expression and \metavar{suffix} is a sequence of operator, method, getter or setter invocations.
 
 \begin{grammar}
 {\bf cascadeSection:}
-      `{\escapegrammar ..}' (cascadeSelector arguments*) (assignableSelector arguments*)* (assignmentOperator expressionWithoutCascade)?
-      .
+      `{\escapegrammar ..}' (cascadeSelector argumentPart*) (assignableSelector argumentPart*)* (assignmentOperator expressionWithoutCascade)?
+    .
 
-{\bf cascadeSelector:}`['  expression `]';
+{\bf cascadeSelector:}`[' expression `]';
       identifier
-      .
+    .
+
+{\bf argumentPart:}
+      typeArguments? arguments
+    .
 \end{grammar}
 
 \LMHash{}
 Evaluation of a cascaded method invocation expression $e$ of the form \code{$e$..\metavar{suffix}} proceeds as follows:
 
 Evaluate $e$ to an object $o$.
 Let $t$ be a fresh variable bound to $o$.
 Evaluate \code{$t$.\metavar{suffix}} to an object.
 Then $e$ evaluates to $o$.
 
@@ skipping 1007 matching lines @@
  \begin{grammar}
 {\bf postfixExpression:}assignableExpression postfixOperator;
       primary selector*
     .
 
 {\bf postfixOperator:}
       incrementOperator
     .
 
 {\bf selector:}assignableSelector;
-      arguments
+      argumentPart
     .
 
 {\bf incrementOperator:}`++';
       `-{}-'
     .
 
  \end{grammar}
 
 \LMHash{}
  A {\em postfix expression} is either a primary expression, a function, method or getter invocation, or an invocation of a postfix operator on an expression $e$.
@@ skipping 159 matching lines @@
 This section describes how to evaluate these expressions when they do not constitute the complete left hand side of an assignment.
 
 \rationale{
 Of course, if assignable expressions always appeared {\em as} the left hand side, one would have no need for their value, and the rules for evaluating them would be unnecessary. However,  assignable expressions can be subexpressions of other expressions and therefore must be evaluated.
 }
 
 
 
 \begin{grammar}
 
-{\bf assignableExpression:}primary (arguments* assignableSelector)+;
+{\bf assignableExpression:}primary (argumentPart* assignableSelector)+;
       \SUPER{} unconditionalAssignableSelector;
       identifier
     .
 
 {\bf unconditionalAssignableSelector:}`[' expression `]'; % again, could be top level
-         `{\escapegrammar .}' identifier
+      `{\escapegrammar .}' identifier
     .
 
 {\bf assignableSelector:}
-         unconditionalAssignableSelector;
-         `{\escapegrammar ?.}' identifier
+      unconditionalAssignableSelector;
+      `{\escapegrammar ?.}' identifier
     .
-
 \end{grammar}
 
 
 \LMHash{}
 An {\em assignable expression} is either:
 \begin{itemize}
  \item An identifier.
 \item An invocation (possibly conditional) of a getter (\ref{getters}) or list access operator on an expression $e$.
 \item An invocation of a getter or list access operator on  \SUPER{}.
 \end{itemize}
@@ skipping 2790 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.
 
 ----------------------------------------------------------------------