Specification adjustments for covariant overrides in Dart 1.

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 376 matching lines @@
 
 \section{Variables}
 \LMLabel{variables}
 
 \LMHash{}
 Variables are storage locations in memory.
 
 \begin{grammar}
 {\bf variableDeclaration:}
       declaredIdentifier (`,' identifier)*
-      .
+    .
 
 {\bf declaredIdentifier:}
       metadata finalConstVarOrType identifier
     .
 
 {\bf finalConstVarOrType:}\FINAL{} type?;
-           \CONST{} type?;
-        varOrType
+      \CONST{} type?;
+      varOrType
     .
 
- {\bf varOrType:}\VAR{};
-        type
+{\bf varOrType:}\VAR{};
+      type
     .
 
- {\bf initializedVariableDeclaration:}
+{\bf initializedVariableDeclaration:}
       declaredIdentifier (`=' expression)? (`,' initializedIdentifier)* % could do top level here
     .
 
 {\bf initializedIdentifier:}
       identifier (`=' expression)? % could do top-level here
     .
 
 {\bf initializedIdentifierList:}
       initializedIdentifier (`,' initializedIdentifier)*
     .
-
-
-
-
-  \end{grammar}
+\end{grammar}
 
 \LMHash{}
 A variable that has not been initialized has the initial value \NULL{} (\ref{null}).
 
 \LMHash{}
 A variable declared at the top-level of a library is referred to as either a {\em library variable} or simply a top-level variable.
 
 \LMHash{}
 A {\em static variable} is a variable that is not associated with a particular instance, but rather with an entire library or class.  Static variables include library variables and class variables. Class variables are variables whose declaration is immediately nested inside a class declaration and includes the modifier \STATIC{}. A library variable is implicitly static. It is a compile-time error to preface a top-level variable declaration with the built-in identifier  (\ref{identifierReference}) \STATIC{}.
 
@@ skipping 319 matching lines @@
 
 \LMHash{}
 A {\em required formal parameter} may be specified in one of three ways:
 \begin{itemize}
 \item By means of a function signature that names the parameter and describes its type as a function type (\ref{functionTypes}).  It is a compile-time error if any default values are specified in the signature of such a function type.% explain what the type is in this case? Where is this described in general?
 \item As an initializing formal, which is only valid as a parameter to a generative constructor (\ref{generativeConstructors}). % do we need to say this, or anything more?
 \item Via an ordinary variable declaration (\ref{variables}).
 \end{itemize}
 
 \begin{grammar}
-{\bf normalFormalParameter:}functionSignature;
+{\bf normalFormalParameter:}functionFormalParameter;
       fieldFormalParameter;
       simpleFormalParameter
- .
+    .
 
-{\bf simpleFormalParameter:}declaredIdentifier;
-      metadata identifier
+{\bf functionFormalParameter:}
+      metadata \COVARIANT{}? returnType? identifier formalParameterList
+    .
+
+{\bf simpleFormalParameter:}
+      metadata \COVARIANT{}? finalConstVarOrType? identifier;
     .
 
 {\bf fieldFormalParameter:}
    metadata finalConstVarOrType? \THIS{} `{\escapegrammar .}' identifier formalParameterList?
    .
 \end{grammar}
 
+\LMHash{}
+It is possible to include the modifier \COVARIANT{} in some forms of parameter declarations.
+This modifier has no effect.
+
+\rationale{
+The modifier \COVARIANT{} is used in strong mode.
+The modifier is allowed here even though it has no effect, such that source code can be used in both contexts.
+}
+
+\LMHash{}
+It is a compile-time error if the modifier \COVARIANT{} occurs on a parameter of a function which is not an instance method, instance setter, or instance operator.
+
 %\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
  %\end{grammar}
 
@@ skipping 110 matching lines @@
       \STATIC{}? functionSignature;
       \STATIC{}? getterSignature;
       \STATIC{}? setterSignature;
       operatorSignature
     .
 
 {\bf declaration:}constantConstructorSignature (redirection $|$ initializers)?;
       constructorSignature (redirection $|$ initializers)?;
       \EXTERNAL{} constantConstructorSignature;
       \EXTERNAL{} constructorSignature;
       ((\EXTERNAL{} \STATIC{} ?))? getterSignature;

[Lasse Reichstein Nielsen, 2017/02/25 11:57:32]

Remove space before '?' (just for consistency).

[eernst, 2017/03/02 12:43:01]

Done.

       ((\EXTERNAL{} \STATIC{}?))? setterSignature;
       \EXTERNAL{}? operatorSignature;
-       ((\EXTERNAL{} \STATIC{}?))? functionSignature;
+      ((\EXTERNAL{} \STATIC{}?))? functionSignature;
       \STATIC{} (\FINAL{} $|$ \CONST{}) type? staticFinalDeclarationList;
 %      \CONST{} type? staticFinalDeclarationList;
       \FINAL{} type? initializedIdentifierList;
-      \STATIC{}? (\VAR{} $|$ type) initializedIdentifierList
+      (\STATIC{} $|$ \COVARIANT{})? (\VAR{} $|$ type) initializedIdentifierList
     .
 
 {\bf staticFinalDeclarationList:}
     staticFinalDeclaration (`,' staticFinalDeclaration)*
     .
 
 {\bf staticFinalDeclaration:}
       identifier `=' expression
     .
 
 \end{grammar}
 
 \LMHash{}
+It is possible to include the modifier \COVARIANT{} in some forms of declarations.
+This modifier has no effect.
+
+\rationale{
+The modifier \COVARIANT{} is used in strong mode.
+The modifier is allowed here even though it has no effect, such that source code can be used in both contexts.
+}
+
+\LMHash{}
 A class has constructors,  instance members and static members. The instance members of a class are its instance methods, getters, setters and instance variables. The static members of a class are its static methods, getters, setters and static variables. The members of a class are its static and instance members.
 
 \LMHash{}
 A class has several scopes:
 \begin{itemize}
 \item A {\em type-parameter scope}, which is empty if the class is not generic (\ref{generics}).  The enclosing scope of the type-parameter scope of a class is the enclosing scope of the class declaration.
 \item A {\em static scope}. The enclosing scope of the static scope of a  class is the type parameter scope (\ref{generics}) of the class.
 \item  An {\em instance scope}.
 The enclosing scope of a class' instance scope is the class' static scope.
 \end{itemize}
@@ skipping 1468 matching lines @@
 
 
 \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)?)*

[Lasse Reichstein Nielsen, 2017/02/25 11:57:32]

Shouldn't we allow type-parameters for the class here?

[eernst, 2017/03/02 12:43:01]

That's not related to the overall contents of the CL, and it would have
implications for implementations. However, the tools dart, dart2js, and
dartanalyzer allow for this:

  class C<X> { final X x; const C(this.x); }
  const c = const C<String>('Hello!');
  @c main() {}

So they can all handle it "semantically", just not syntactically. Just checked
with the ANTLR grammar, and it does not create any ambiguities or other parsing
issues there.

All tools that I could think of (including, e.g., dartfmt) reject the type
arguments, which just shows that they follow the current grammar in the spec.

This means that we can just do it, and then request an implementation from
various tool groups, but I'll take that to a separate CL, and leave the text
as-is here for now.

     .
 \end{grammar}
 
 \LMHash{}
 Metadata consists of a series of annotations, each of which begin with the character @, followed by  a constant expression that starts with an identifier. It is a compile time error if the expression is not one of the following:
 \begin{itemize}
 \item A reference to a compile-time constant variable.
 \item A call to a constant constructor.
 \end{itemize}
 
@@ skipping 2909 matching lines @@
 An assignable expression of the form \code{\SUPER{}[$e_2$]} is equivalent to the method invocation  \code{\SUPER{}.[]($e_2$)}.
 
 \subsection{ Identifier Reference}
 \LMLabel{identifierReference}
 
 \LMHash{}
 An {\em identifier expression} consists of a single identifier; it provides access to an object via an unqualified name.
 
 \begin{grammar}
 {\bf identifier:}
-     IDENTIFIER
-     .
+      IDENTIFIER
+    .
 
-
- {\bf IDENTIFIER\_NO\_DOLLAR:}
+{\bf IDENTIFIER\_NO\_DOLLAR:}
       IDENTIFIER\_START\_NO\_DOLLAR IDENTIFIER\_PART\_NO\_DOLLAR*
     .
 
 {\bf IDENTIFIER:}
       IDENTIFIER\_START IDENTIFIER\_PART*
     .
 
-{\bf BUILT\_IN\_IDENTIFIER:} \ABSTRACT{};
-     \AS{};
-     \DEFERRED{};
-     \DYNAMIC{};
-     \EXPORT{};
-     \EXTERNAL{};
-     \FACTORY{};
-     \GET{};
-     \IMPLEMENTS{};
-     \IMPORT{};
-     \LIBRARY{};
-     \OPERATOR{};
-     \PART{};
+{\bf BUILT\_IN\_IDENTIFIER:}\ABSTRACT{};
+      \AS{};
+      \COVARIANT{};
+      \DEFERRED{};
+      \DYNAMIC{};
+      \EXPORT{};
+      \EXTERNAL{};
+      \FACTORY{};
+      \GET{};
+      \IMPLEMENTS{};
+      \IMPORT{};
+      \LIBRARY{};
+      \OPERATOR{};
+      \PART{};
       \SET{};
       \STATIC{};
-     \TYPEDEF{}
+      \TYPEDEF{}
     .
 
  {\bf IDENTIFIER\_START:}IDENTIFIER\_START\_NO\_DOLLAR;
       `\$'
     .
 
 {\bf IDENTIFIER\_START\_NO\_DOLLAR:}LETTER;
       `\_'
     .
 
 {\bf  IDENTIFIER\_PART\_NO\_DOLLAR:}IDENTIFIER\_START\_NO\_DOLLAR;
       DIGIT
     .
 
-
 {\bf IDENTIFIER\_PART:}IDENTIFIER\_START;
       DIGIT
     .
 
-
-
 {\bf qualified:}
       identifier (`{\escapegrammar .}' identifier)?
-      .
+    .
 \end{grammar}
 
 \LMHash{}
 A built-in identifier is one of the identifiers produced by the production {\em BUILT\_IN\_IDENTIFIER}. It is a compile-time error if a built-in identifier is used as the declared name of a prefix, class, type parameter or type alias. It is a compile-time error to use a built-in identifier other than \DYNAMIC{} as a type annotation or type parameter.
 
 \rationale{
 Built-in identifiers are identifiers that are used as keywords in Dart, but are not reserved words in Javascript. To minimize incompatibilities when porting Javascript code to Dart, we do not make these into reserved words. A built-in identifier may not be used to name a class or type. In other words, they are treated as reserved words when used as types.  This eliminates many confusing situations without causing compatibility problems. After all, a Javascript program has no type declarations or annotations so no clash can occur.  Furthermore, types should begin with an uppercase letter (see the appendix) and so no clash should occur in any Dart user program anyway.
 }
 
 \LMHash{}
@@ skipping 2701 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.
 
 ----------------------------------------------------------------------