Specify FutureOr.

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  \\
 {5th edition draft}\\
 {\large Version 1.15.0}}
 
 % For information about Location Markers (and in particular the
 % commands \LMHash and \LMLabel), see the long comment at the
 % end of this file.
 
 % CHANGES
 % =======
 % Significant changes to the specification.
 %
 % 1.15
 % - Change how language specification describes control flow.
 % - Object initialization now specifies initialization order correctly.
 % - Specifies that leaving an await-for loop must wait for the subscription
 %   to be canceled.
 % - An await-for loop only pauses the subscription if it does something async.
 % - Assert statements may now also include a "message" operand.
 % - The Null type is now considered a subtype of all types in most cases.
+% - Specified the FutureOf type.

[eernst, 2017/02/01 16:54:30]

`FutureOr`. Also, it seems to be the standard style to use double quotes around
literal source code, which makes it `"FutureOr"`.

 %
 % 1.14
 % - The call "C()" where "C" is a class name, is a now compile-time error.
 % - Changed description of rewrites that depended on a function literal.
 %   In many cases, the rewrite wasn't safe for asynchronous code.
 % - Removed generalized tear-offs.
 % - Allow "rethrow" to also end a switch case. Allow braces around switch cases.
 % - Allow using '=' as default-value separator for named parameters.
 % - Make it a compile-time error if a library includes the same part twice.
 % - Now more specific about the return types of sync*/async/async* functions
@@ skipping 7179 matching lines @@
  \begin{grammar}
 {\bf type:}
       typeName typeArguments?
     .
 
 {\bf typeName:}
       qualified
     .
 
 {\bf typeArguments:}
-      '<' typeList '>'
+      `<' typeList `>'
     .
 
 {\bf typeList:}
-      type (',' type)*
+      type (`,' type)*
     .
  \end{grammar}
 
 \LMHash{}
 A Dart implementation must provide a static checker that detects and reports exactly those situations this specification identifies as static warnings and only those situations. However:
 \begin{itemize}
 \item Running  the static checker on a program $P$ is not required for compiling and running $P$.
 \item Running the static checker on a program $P$ must not prevent successful compilation of $P$ nor may it prevent the execution of $P$, regardless of whether any static warnings occur.
 \end{itemize}
 
@@ skipping 400 matching lines @@
 (3) \code{typedAPI(new G\lt{String}\gt());}
 
 This forces users to write type information in their client code just because they are calling a typed API.  We do not want to impose this on Dart programmers, some of which may be blissfully unaware of types in general, and genericity in particular.
 
 What of static checking? Surely we would want to flag (2) when users have explicitly asked for static typechecking? Yes, but the reality is that the Dart static checker is likely to be running in the background by default. Engineering teams typically desire a ``clean build'' free of warnings and so the checker is designed to be extremely charitable. Other tools can interpret the type information more aggressively and warn about violations of conventional (and sound) static type discipline.
 }
 
 \LMHash{}
 The name \DYNAMIC{} denotes a \cd{Type} object even though \DYNAMIC{} is not a class.
 
+\LMHash{}
+The built-in type declaration \code{FutureOr},
+which is declared in the library \code{dart:async},
+defines a generic type with one type parameter (\ref{generics}).
+If the \code{FutureOr} type, optionally followed by type arguments,
+is used as a type, it denotes the \DYNAMIC{} type.
+As such, the \code{FutureOr} type cannot be used where \DYNAMIC{} cannot be
+used as a type.
+If the type arguments applied to \code{FutureOr} would issue static warnings
+if applied to a normal generic class with one type parameter,
+the same warnings are issued for \code{FutureOr},
+even though the type arguments are otherwise ignored.
+The name \code{FutureOr} denotes the same \cd{Type} object as \DYNAMIC{}.

[eernst, 2017/02/01 16:54:30]

This raises the question: So what's the semantics of applying `\code{FutureOr}`
to a list of type arguments? I'd say that we always do this (either the
arguments are provide explicitly, or the compiler adds them), and the type
arguments are ignored (it's like the constant type level function (x) =>
dynamic). With that, `\code{FutureOr<T>}` evaluated as an expression denotes the
same type object as `\DYNAMIC{}` for all `T`.

Or do we want to make it a semantic primitive that a generic class can be
evaluated to a type "when needed", without passing any arguments? I think that
would be more confusing and more complex to handle.

[Lasse Reichstein Nielsen, 2017/02/02 06:45:47]

I'm not sure what this is suggesting.
You can't evaluate `FutureOr<T>` as an expression, type literals don't take type
parameters at all.

+
+\rationale{
+The \code{FutureOr} type is reserved for future use,
+for cases where a value can be either an instance of the type \metavar{type}
+or the type \code{Future<\metavar{type}>}. Such cases occur naturally
+in asynchronous code.
+Using \code{FutureOr} instead of \DYNAMIC{} will allow some tools
+to provide a more precise type analysis.
+}
 %\rationale {
 %Type objects reify the runtime types of instances. No instance ever has type \DYNAMIC{}.
 %}
 
 \subsection{Type Void}
 \LMLabel{typeVoid}
 
 \LMHash{}
 The special type \VOID{} may only be used as the return type of a function: it is a compile-time error to use \VOID{} in any other context.
 
@@ skipping 423 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.
 
 ----------------------------------------------------------------------