Add trailing commas to argument and parameter lists.

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 637 matching lines @@
 
 %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.}
 
 \LMHash{}
 It is a compile-time error if a formal parameter is declared as a constant variable (\ref{variables}).
 
 \begin{grammar}
-{\bf formalParameterList:}`(' `)';
- `(' normalFormalParameters ( `,'  optionalFormalParameters)? `)';
-  `(' optionalFormalParameters `)'
+{\bf formalParameterList:}
+     `(' `)';
+     `(' normalFormalParameters `,'? `)';
+     `(' normalFormalParameters `,'  optionalFormalParameters `)';
+     `(' optionalFormalParameters `)'
    .
 %\end{grammar}
 %}
 
 %\begin{grammar}
 %formalParameterList:
 %      '(' restFormalParameter? ')';
 %      '(' namedFormalParameters ')';
  %     '(' normalFormalParameters normalFormalParameterTail? ')'
   %  .
 
 {\bf normalFormalParameters:}
       normalFormalParameter (`,' normalFormalParameter)*
     .
 
-{\bf optionalFormalParameters:}optionalPositionalFormalParameters;
+{\bf optionalFormalParameters:}
+      optionalPositionalFormalParameters;
       namedFormalParameters
     .
 
 {\bf optionalPositionalFormalParameters:}
-      `[' defaultFormalParameter (`,' defaultFormalParameter)* `]'
+      `[' defaultFormalParameter (`,' defaultFormalParameter)* `,'? `]'
     .
 {\bf namedFormalParameters:}
-      `\{' defaultNamedParameter (`,' defaultNamedParameter)* `\}'
+      `\{' defaultNamedParameter (`,' defaultNamedParameter)* `,'? `\}'
     .
 \end{grammar}
 
 %Formal parameters are always \FINAL{}.
 %\Q{We're awaiting some data on whether enforcing this would cause widespread pain.}
 %A formal parameter is always considered to be initialized.  \rationale{This is because it will always be initialized by the call - even if it is optional.}
 
 
 \subsubsection{Required Formals}
 \LMLabel{requiredFormals}
@@ skipping 2906 matching lines @@
 
 
 \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? `)'
+      `(' (argumentList  `,'?)? `)'
     .
 
-{\bf argumentList:}namedArgument (`,' namedArgument)*;
-  %    expressionList ',' spreadArgument;
+{\bf argumentList:}
+      namedArgument (`,' namedArgument)*;
       expressionList (`,' namedArgument)*

[eernst, 2016/06/14 09:08:32]

I think we should gather all the changes motivated by "this is a comment, and it
is not a TODO, so we just delete it" in a separate CL, such that we have a
reasonably easy target to search for those parts in case we do want to browse
them.

In that case, we should just leave them as they are now in this CL.

[Lasse Reichstein Nielsen, 2016/06/27 17:27:53]

Let's do that. Reinserted for now.

-%      spreadArgument
     .
 
 {\bf namedArgument:}
       label expression % could be top level expression?
     .
  \end{grammar}
 
 \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:
+(ignoring any trailing comma) proceeds as follows:

[eernst, 2016/06/14 09:08:33]

The given argument list serves as the basis for specifying the semantics, i.e.,
it is intended to be a template for all possible argument lists (rather than,
say, an example).

In order to uphold this interpretation, I think it might be better to say
'(omitting any trailing comma)', because we avoid giving the reader the
impression that anything is imprecise here because we 'ignore' some details.

But I think it would be better to say once and for all at the location where the
grammar introduces the trailing commas (at line 694 and 3626) that _all_
argument/parameter lists in the specification will use the form where no
trailing comma is present, and the addition of a trailing comma does not have
any effect on the semantics of the given construct.

The same issue would come up with 'Type of a Function' and a number of other
places, so we had better make sure it is handled collectively (and surely we
wouldn't want to make such a comma semantically significant anywhere).

 
 \LMHash{}
 The arguments $a_1, \ldots, a_{m+l}$ are evaluated in the order they appear in the program, yielding objects $o_1, \ldots, o_{m+l}$.
 
 \commentary{Simply stated, an argument list consisting of $m$ positional arguments and $l$ named arguments is evaluated from left to right.
 }
 
 
 \subsubsection{ Binding Actuals to Formals}
 \LMLabel{bindingActualsToFormals}
 
 \LMHash{}
 Let $f$ be a function with $h$ required parameters,  let $p_1 \ldots p_n$ be the positional parameters of $f$ and let $p_{h+1}, \ldots, p_{h+k}$ be the optional parameters declared by $f$.
 
 \LMHash{}
-An evaluated actual argument list $o_1 \ldots o_{m+l}$ derived from an actual argument list of the form $(a_1, \ldots, a_m, q_1: a_{m+1}, \ldots, q_l: a_{m+l})$ is bound to the formal parameters of $f$ as follows:
+An evaluated actual argument list $o_1 \ldots o_{m+l}$ derived from an actual argument list of the form $(a_1, \ldots, a_m, q_1: a_{m+1}, \ldots, q_l: a_{m+l})$ (ignoring any trailing comma) is bound to the formal parameters of $f$ as follows:

[eernst, 2016/06/14 09:08:33]

Same issue as line 3632.

 
 \commentary{
 We have an argument list consisting of $m$ positional arguments and $l$ named arguments. We have a function with $h$ required parameters and $k$ optional parameters. The number of positional arguments must be at least as large as the number of required parameters, and no larger than the number of positional parameters. All named arguments must have a corresponding named parameter. You may not provide a given named argument more than once.  If an optional parameter has no corresponding argument, it gets its default value. In checked mode, all arguments must belong to subtypes of the type of their corresponding formal.
 }
 
 \commentary{
 If $l > 0$, then it is necessarily the case that $n = h$, because a method cannot have both optional positional parameters and named parameters.
 }
 
 
@@ skipping 4224 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.
 
 ----------------------------------------------------------------------