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 can be introduced by declarations of functions (\ref{functionDeclarations}), methods (\ref{instanceMethods}, \ref{staticMethods}), getters (\ref{getters}), setters (\ref{setters}), and constructors (\ref{constructors}); and they can be introduced by function literals (\ref{functionExpressions}).

[Lasse Reichstein Nielsen, 2017/03/06 15:09:34]

"Functions can be introduce by declarations of functions" sounds odd and
circular.
I think it would be better as:
"Functions can be introduced by function declarations (...), method
decalarations (...), ..."
It makes it clear that a "function declaration" is not a function itself, it's a
"declaration", whereas "declarations of functions" separates the two.

To make it slightly shorter, maybe:
"Functions can be introduced by function declarations (...), function
expressions (...), and by declarations of setters (...), ... , and constructors
(...)".

 
 \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 function declarations include a signature, and some include a body.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:34]

Here "function declarations" looks like it only refers to
\ref{functionDeclarations} - and the suggested rewrite above just makes it
worse.

Maybe "All declarations of functions ... " (because here it talks about the
declarations above that introduced the functions).

+The signature describes the formal parameter part of the function, its name, and possibly its return type, with the exceptions that a getter has no formal parameter part and a function literal has no name.
+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/03/06 15:09:33]

"formal type parameter list" - that wording rubs me the wrong way. Maybe because
it emphasizes the "list", which is a grammatical concept. Maybe just "its formal
type parameters".
Similarly for its formal parameters, which are not a list (unless optional
parameters are considered a single element?)

+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.
+The current scope for the function's signature is the scope that encloses the formal parameter scope.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:34]

The type parameter list is part of the signature, so that sentence doesn't seem
correct (or is it recursively the current scope for itself?)

+
+\commentary{
+This means that in a generic function, the return type and parameter type annotations can use the formal type parameters, but the formal parameters are not in scope in the signature.
+}
 
 \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{}
+Some function declarations may include a {\em formal type parameter list} (\ref{functions}), in which case we say that it is a {\em generic function}.
+A {\em non-generic function} is a function which is not generic.
+
+\commentary{
+The following exceptions exist:
+Getter, setter, operator, and constructor declarations cannot be generic.
+}
+
+\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.
+
+\commentary{
+This enables the use of F-bounded type parameters.
+Moreover, 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{}
+{ \def\Derased{\ensuremath{D_{\mbox{\scriptsize erased}}}}
+{\em Generic function erasure} takes as input a generic function declaration $D$ and either yields a non-generic function declaration \Derased{} or terminates with a compile-time error.
+\Derased{} is identical to $D$ except for the following replacements:
+\begin{itemize}
+\item The \GrammarSymbol{formalParameterPart} of \Derased{} is identical to the \GrammarSymbol{formalParameterList} of $D$.
+  \commentary{That is, the type parameter list is erased.}
+\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.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:34]

Should we include `on` clauses?

[Lasse Reichstein Nielsen, 2017/03/06 15:09:34]

I'm actually not sure what a "type literal" really is. I can't find a definition
in the spec (only references to it), but I'm guessing that it only applies to
class names, not type variables. (That's probably contrary to something I've
said earlier, but the more you read, the less you know :)
Or maybe it is a type literal, and the distinction is between "type literal" and
"constant type literal". Not sure.

So, just to be safe, "as a type literal" -> "as an identifier expression".

+  \item In all other cases, the location corresponding to $id$ in \Derased{} contains \DYNAMIC{}.
+  \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.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:33]

and in things like `x is Foo<T>`, which is neither annotation nor instance
creation - either just say that it's everywhere, expand the list to be
exhaustive, or say that it's just examples. This is commentary anyway.

+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{}.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:33]

The "finally" here sounds like it's a separate thing, but isn't it just the
conclusion to the previous sentence. That is, maybe change "Finally" to "So"?

+}
 
 \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.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:33]

That sounds like you actually pass something. As I read the previous text, you
actually ignore the type arguments and don't pass anything. So maybe: "passed to
$f$" -> "in the invocation of $f$" (it's the syntactic occurrence we refer to,
it has no semantics).

+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 expression is always parsed as a generic function invocation.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:33]

The ambiguity is not just in argument lists, it's everywhere you have
comma-separated expressions. That also includes list literals and for-loop
increments.

var x = [a<b,c>(d)]
for (;; a<b,c(d));  // Admittedly useless, but we should be consistent.

+
+% 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.

[Lasse Reichstein Nielsen, 2017/03/06 15:09:34]

We should specify which programs are valid, and what they mean.

If we have a disambiguation rule that is different from the paragraph above
(which is clear and precise - and doesn't match this disabmiguation rule), then
we need to write it *instead* of the previous paragraph.


We can take the easy way out (which is what we did above) and say that whenever
there is a parsing ambiguity where one option is a generic method invocation, we
resolve it to the generic function invocation. The problem is that it doesn't
help parsing very much - it has to actually parse both versions and only reduce
when you have successfully parsed a function invocation. Something like 
  foo<bar,baz.qux>(42) 
is a function invocation but 
  foo<bar,baz.qux.fip>(42) 
is not (baz.qux.fib can't be a "type").

On the other hand, specifying the rule that:
  e1<e2,e3>(  
where < and > are matching, always implies a method invocation
... requires us to *specify* what it means for < and > to be matching, in such a
way that we don't miss foo<int,List<int>>(42) which ends in the token '>>' not
'>'. I would prefer not to define this (what if e2 contains List<int>, what if
e2 contains a << operator, what if e2 contains a + operator, what about
f(x<<y,z>>(w)), what about f(x < a << 2, y >> 3 > (4))?)

It's also annoying that  foo((a)<(b), (c)>(d))  is taken as an (invalid)
function invocation when it so obviously isn't. That expression only matches one
production, and we want to somehow disallow it. The "if there is an ambiguity"
rule can't do that since there is no ambiguity.

What do the current implementations do?

I think we should stay with the "if there is ambiguity, prefer invocation" and
let parsers use the "matching < and > followed by (" as a hint to which parsing
to try first, with an option to backtrack and try again.

+
+\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/03/06 15:09:33]

Nitpick: You don't know the type is `bool`, operator< is user definable.

+Note that the ambiguity may be eliminated by omitting the parentheses around the expression $d$, or adding parentheses around one of the relational expressions.
+}
+
+\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.
 
 ----------------------------------------------------------------------