blob: 51da3d3d94674a2b23e66ed03571f47fa74e022e [file] [log] [blame]
 \documentclass{article} \usepackage{xspace} \usepackage{epsfig} \usepackage{color} \usepackage{syntax} \usepackage{dart} \usepackage{hyperref} \usepackage{lmodern} \usepackage[T1]{fontenc} \title{Dart Programming Language Specification\\ {5th edition draft}\\ {\large Version 2.1.0-dev}} \author{} % 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. % % 2.1 % - Remove 64-bit constraint on integer literals compiled to JavaScript numbers. % - Allow integer literals in a double context to evaluate to a double value. % - Specify dynamic error for a failing downcast in redirecting factory % constructor invocation. % - Specify that type arguments passed in a redirecting factory constructor % declaration must be taken into account during static checks. % - Disallow any expression statement starting with {, not just % those that are map literals. % - Define a notion of lookup that is needed for super invocations, adjust % specification of super invocations accordingly. % - Specify that it is a dynamic error to initialize a non-static variable % with a value that does not have the declared type (e.g., a failed cast). % - Specify for constructor initializers that target variable must exist and % the initializing expression must have a type which is assignable to its % type. % - Specify for superinitializers that the target constructor must exist and % the argument part must have a matching shape and pass type and value % arguments satisfying the relevant constraints. % - Reword rules about abstract methods and inheritance to use 'class % interface'. % - Specify that it is an error for a concrete class with no non-trivial % \code{noSuchMethod} to not have a concrete declaration for some member % in its interface, or to have one which is not a correct override. % - Use \ref{bindingActualsToFormals} in 3 locations, eliminating 2 extra % copies of nearly the same text. % - Add figure in \ref{bindingActualsToFormals} for improved readability. % - Introduce a notion of lookup which is needed for superinvocations. % - Use new lookup concept to simplify specification of getter, setter, method % lookup. % - Introduce several Case markers in order to improve % readability. % - Reorganize several sections to specify static analysis first and then % dynamic semantics; clarify many details along the way. The sections are: % \ref{variables}, \ref{new}, \ref{const}, \ref{bindingActualsToFormals}, % \ref{unqualifiedInvocation}, \ref{functionExpressionInvocation}, % \ref{superInvocations}, \ref{assignment}, \ref{compoundAssignment}, % \ref{localVariableDeclaration}, and \ref{return}. % - Corrected error involving multiple uses of the same part in the same % program such that it takes exports into account. % - Eliminate all references to checked and production mode, Dart 2 does % not have modes. % - Integrate feature specification on noSuchMethod forwarders. % % 2.0 % - Don't allow functions as assert test values. % - Start running "async" functions synchronously. % - It is a static warning and dynamic error to assign to a final local. % - Specify what "is equivalent to" means. % - Remove @proxy. % - Don't specify the exact object used for empty positionalArguments and % namedArguments on Invocation. % - Remove the, now unnecessary, handling of invalid overrides of noSuchMethod. % - Add >>> as overridable operator. % - If initializing formal has type annotation, require subtype of field type. % - Constant == operations now also allowed if just one operand is null. % - Make flatten not be recursive. % - Disallow implementing two instantiations of the same generic interface. % - Update "FutureOr" specification for Dart 2.0. % - Require that a top-level "main" declaration is a valid script-entry % function declaration. % - State that the return type of a setter or []= is void when not specified. % - Clarify that "noSuchMethod" must be implemented, not just redeclared % abstractly, to eliminate certain diagnostic messages. % - Add generic functions and methods to the language. % - Don't cause warning if a non-system library import shadows a system library. % - Update mixin application forwarding constructors to correctly handle % optional parameters and const constructors. % - Specify call for Dart 2 (no function type given to enclosing class). % - Clarify that an identifier reference denoting a top-level, static, or % local function evaluates to the closurization of that declaration. % - Make mixin and interface built-in identifiers. % - Make async *not* a reserved word inside async functions. % - Add 'Class Member Conflicts', simplifying and adjusting rules about % member declaration conflicts beyond "n declared twice in one scope". % - Specify that integer literals are limited to signed 64-bit values, % and that the int class is intended as signed 64-bit integer, but % that platforms may differ. % - Specify variance and super-bounded types. % - Introduce subterm and immediate subterm. % - Introduce top type. % - Specify configurable imports. % - Specify the dynamic type of the Iterable/Future/Stream returned from % invocations of functions marked sync*/async/async*. % - Add appendix listing the major differences between 64-bit integers % and JavaScript integers. % - Remove appendix on naming conventions. % - Make it explicit that "dynamic" is exported from dart:core. % - Remove "boolean conversion". It's just an error to not be a bool. % - Adjust cyclic subtype prevention rule for type variables. % - Clarify that it is an error to use FutureOr as a superinterface etc. % - Eliminate the notion of static warnings, all program faults are now errors. % - It is no longer an error for a getter to have return type void. % - Specify that each redirection of a constructor is checked, statically and % dynamically. % - Specify that it is an error for a superinitializer to occur anywhere else % than at the end of an initializer list. % - Update the potentially/compile-time constant expression definitions % so that "potentially constant" depends only on the grammar, not the types % of sub-expressions. % - Make == recognize null and make && and || short-circuit in constant % expressions. % - Add as and is expressions as constant expressions % - Make ^, | and & operations on bool constant operations. % % 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 allows a "message" operand and a trailing comma. % - The Null type is now considered a subtype of all types in most cases. % - Specify what NEWLINE means in multiline strings. % - Specified the FutureOf type. % - Asserts can occur in initializer lists. % % 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 % in relation to return statements. % - Allow Unicode surrogate values in String literals. % - Make an initializing formal's value accessible in the initializer list. % - Allow any expression in assert statements (was only conditionalExpression). % - Allow trailing commas in argument and parameter lists. % % 1.11 - ECMA 408 - 4th Edition % - Specify that potentially constant expressions must be valid expressions % if the parameters are non-constant. % - Make "??" a compile-time constant operator. % - Having multiple unnamed libraries no longer causes warnings. % - Specify null-aware operators for static methods. % % 1.10 % - Allow mixins to have super-classes and super-calls. % - Specify static type checking for the implicit for-in iterator variable. % - Specify static types for a number of expressions where it was missing. % - Make calls on the exact type "Function" not cause warnings. % - Specify null-aware behavior of "e?.v++" and similar expressions. % - Specify that package: URIs are treated in an implementation dependent way. % - Require warning if for-in is used on object with no "iterator" member. % % 1.9 - ECMA-408 - 3rd Edition % \begin{document} \maketitle \tableofcontents \newpage \pagestyle{myheadings} \markright{Dart Programming Language Specification} % begin Ecma boilerplate \section{Scope} \LMLabel{ecmaScope} \LMHash{} This Ecma standard specifies the syntax and semantics of the Dart programming language. It does not specify the APIs of the Dart libraries except where those library elements are essential to the correct functioning of the language itself (e.g., the existence of class \code{Object} with methods such as \code{noSuchMethod}, \code{runtimeType}). \section{Conformance} \LMLabel{ecmaConformance} \LMHash{} A conforming implementation of the Dart programming language must provide and support all the APIs (libraries, types, functions, getters, setters, whether top-level, static, instance or local) mandated in this specification. \LMHash{} A conforming implementation is permitted to provide additional APIs, but not additional syntax, except for experimental features in support of null-aware cascades that are likely to be introduced in the next revision of this specification. \section{Normative References} \LMLabel{ecmaNormativeReferences} \LMHash{} The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. \begin{enumerate} \item The Unicode Standard, Version 5.0, as amended by Unicode 5.1.0, or successor. \item Dart API Reference, https://api.dartlang.org/ \end{enumerate} \section{Terms and Definitions} \LMLabel{ecmaTermsAndDefinitions} \LMHash{} Terms and definitions used in this specification are given in the body of the specification proper. Such terms are highlighted in italics when they are introduced, e.g., we use the term {\em verbosity} to refer to the property of excess verbiage'. % End Ecma Boilerplate \section{Notation} \LMLabel{notation} \LMHash{} We distinguish between normative and non-normative text. Normative text defines the rules of Dart. It is given in this font. At this time, non-normative text includes: \begin{itemize} \item[Rationale] Discussion of the motivation for language design decisions appears in italics. \rationale{ Distinguishing normative from non-normative helps clarify what part of the text is binding and what part is merely expository. } \item[Commentary] Comments such as \commentary{The careful reader will have noticed that the name Dart has four characters}'' serve to illustrate or clarify the specification, but are redundant with the normative text. \commentary{ The difference between commentary and rationale can be subtle. } \rationale{ Commentary is more general than rationale, and may include illustrative examples or clarifications. } \item[Open questions] (\Q{in this font}). Open questions are points that are unsettled in the mind of the author(s) of the specification; expect them (the questions, not the authors; precision is important in a specification) to be eliminated in the final specification. \Q{Should the text at the end of the previous bullet be rationale or commentary?} \end{itemize} \LMHash{} Reserved words and built-in identifiers (\ref{identifierReference}) appear in {\bf bold}. \commentary{ Examples would be \SWITCH{} or \CLASS{}. } \LMHash{} Grammar productions are given in a common variant of EBNF. The left hand side of a production ends with a colon. On the right hand side, alternation is represented by vertical bars, and sequencing by spacing. As in PEGs, alternation gives priority to the left. Optional elements of a production are suffixed by a question mark like so: \code{anElephant?}. Appending a star to an element of a production means it may be repeated zero or more times. Appending a plus sign to a production means it occurs one or more times. Parentheses are used for grouping. Negation is represented by prefixing an element of a production with a tilde. Negation is similar to the not combinator of PEGs, but it consumes input if it matches. In the context of a lexical production it consumes a single character if there is one; otherwise, a single token if there is one. \commentary{ An example would be: } \begin{grammar} ::= \alt \alt \alt * \alt + \alt ? \alt ( ) \alt \~{} \alt aTerminal' \alt \end{grammar} \LMHash{} Both syntactic and lexical productions are represented this way. Lexical productions are distinguished by their names. The names of lexical productions consist exclusively of upper case characters and underscores. As always, within grammatical productions, whitespace and comments between elements of the production are implicitly ignored unless stated otherwise. Punctuation tokens appear in quotes. \LMHash{} Productions are embedded, as much as possible, in the discussion of the constructs they represent. \LMHash{} A {\em term} is a syntactic construct. It may be considered to be a piece of text which is derivable in the grammar, and it may be considered to be a tree created by such a derivation. An {\em immediate subterm} of a given term $t$ is a syntactic construct which corresponds to an immediate subtree of $t$ considered as a derivation tree. A {\em subterm} of a given term $t$ is $t$, or an immediate subterm of $t$, or a subterm of an immediate subterm of $t$. \LMHash{} A list $x_1, \ldots, x_n$ denotes any list of $n$ elements of the form $x_i, 1 \le i \le n$. Note that $n$ may be zero, in which case the list is empty. We use such lists extensively throughout this specification. \LMHash{} For $j \in 1 .. n$, let $y_j$ be an atomic syntactic entity (like an identifier), $x_j$ a composite syntactic entity (like an expression or a type), and $E$ again a composite syntactic entity. The notation $[x_1/y_1, \ldots, x_n/y_n]E$ then denotes a copy of $E$ in which each occurrence of $y_i, 1 \le i \le n$ has been replaced by $x_i$. \LMHash{} This operation is also known as substitution, and it is the variant that avoids capture. That is, when $E$ contains a construct that introduces $y_i$ into a nested scope for some $i \in 1 .. n$, the substitution will not replace $y_i$ in that scope. Conversely, if such a replacement would put an identifier \id{} (a subterm of $x_i$) into a scope where \id{} is declared, the relevant declarations in $E$ are systematically renamed to fresh names. \commentary{ In short, capture freedom ensures that the meaning'' of each identifier is preserved during substitution. } \LMHash{} We sometimes abuse list or map literal syntax, writing $[o_1, \ldots, o_n]$ (respectively $\{k_1: o_1, \ldots, k_n: o_n\}$) where the $o_i$ and $k_i$ may be objects rather than expressions. The intent is to denote a list (respectively map) object whose elements are the $o_i$ (respectively, whose keys are the $k_i$ and values are the $o_i$). \LMHash{} The specifications of operators often involve statements such as $x$ $op$ $y$ is equivalent to the method invocation $x.op(y)$. Such specifications should be understood as a shorthand for: \begin{itemize} \item $x$ $op$ $y$ is equivalent to the method invocation $x.op'(y)$, assuming the class of $x$ actually declared a non-operator method named $op'$ defining the same function as the operator $op$. \end{itemize} \rationale{ This circumlocution is required because x.op(y), where op is an operator, is not legal syntax. However, it is painfully verbose, and we prefer to state this rule once here, and use a concise and clear notation across the specification. } \LMHash{} When the specification refers to the order given in the program, it means the order of the program source code text, scanning left-to-right and top-to-bottom. \LMHash{} When the specification refers to a {\em fresh variable}, it means a variable with a name that doesn't occur anywhere in the current program. When the specification introduces a fresh variable bound to a value, the fresh variable is implicitly bound in a surrounding scope. \LMHash{} References to otherwise unspecified names of program entities (such as classes or functions) are interpreted as the names of members of the Dart core library. \commentary{ Examples would be the classes \code{Object} and \code{Type} representing the root of the class hierarchy and the reification of run-time types respectively. } \LMHash{} When the specification says that one piece of syntax {\em is equivalent to} another piece of syntax, it means that it is equivalent in all ways, and the former syntax should generate the same compile-time errors and have the same run-time behavior as the latter, if any. \commentary{ Error messages, if any, should always refer to the original syntax. } If execution or evaluation of a construct is said to be equivalent to execution or evaluation of another construct, then only the run-time behavior is equivalent, and compile-time errors apply only for the original syntax. \section{Overview} \LMLabel{overview} \LMHash{} Dart is a class-based, single-inheritance, pure object-oriented programming language. Dart is optionally typed (\ref{types}) and supports reified generics. The run-time type of every object is represented as an instance of class \code{Type} which can be obtained by calling the getter \code{runtimeType} declared in class \code{Object}, the root of the Dart class hierarchy. \LMHash{} Dart programs may be statically checked. Programs with compile-time errors do not have a specified dynamic semantics. This specification makes no attempt to answer additional questions about a library or program at the point where it is known to have a compile-time error. \commentary{ However, tools may choose to support execution of some programs with errors. For instance, a compiler may compile certain constructs with errors such that a dynamic error will be raised if an attempt is made to execute such a construct, or an IDE integrated runtime may support opening an editor window when such a construct is executed, allowing developers to correct the error. It is expected that such features would amount to a natural extension of the dynamic semantics of Dart as specified here, but, as mentioned, this specification makes no attempt to specify exactly what that means. } \LMHash{} As specified in this document, dynamic checks are guaranteed to be performed in certain situations, and certain violations of the type system throw exceptions at run time. \commentary{ An implementation is free to omit such checks whenever they are guaranteed to succeed, e.g., based on results from the static analysis. } \commentary{ The coexistence between optional typing and reification is based on the following: \begin{enumerate} \item Reified type information reflects the types of objects at run time and may always be queried by dynamic typechecking constructs (the analogs of instanceOf, casts, typecase etc.\ in other languages). Reified type information includes access to instances of class \code{Type} representing types, the run-time type (aka class) of an object, and the actual values of type parameters to constructors and generic function invocations. \item Type annotations declare the types of variables and functions (including methods and constructors). \item %% TODO(eernst): Change when integrating instantiate-to-bounds.md. Type annotations may be omitted, in which case they are generally filled in with the type \DYNAMIC{} (\ref{typeDynamic}). \end{enumerate} } %% TODO(eernst): Update when we add inference. \commentary{ Dart as implemented includes extensive support for inference of omitted types. This specification makes the assumption that inference has taken place, and hence inferred types are considered to be present in the program already. However, in some cases no information is available to infer an omitted type annotation, and hence this specification still needs to specify how to deal with that. A future version of this specification will also specify type inference. } \LMHash{} Dart programs are organized in a modular fashion into units called {\em libraries} (\ref{librariesAndScripts}). Libraries are units of encapsulation and may be mutually recursive. \commentary{ However they are not first class. To get multiple copies of a library running simultaneously, one needs to spawn an isolate. } \LMHash{} A dart program execution may occur with assertions enabled or disabled. The method used to enable or disable assertions is implementation specific. \subsection{Scoping} \LMLabel{scoping} \LMHash{} A {\em namespace} is a mapping of names denoting declarations to actual declarations. Let $NS$ be a namespace. We say that a name $n$ {\em is in }$NS$ if $n$ is a key of $NS$. We say a declaration $d$ {\em is in }$NS$ if a key of $NS$ maps to $d$. \LMHash{} A scope $S_0$ induces a namespace $NS_0$ that maps the simple name of each variable, type or function declaration $d$ declared in $S_0$ to $d$. Labels are not included in the induced namespace of a scope; instead they have their own dedicated namespace. \commentary{ It is therefore impossible, e.g., to define a class that declares a method and a getter with the same name in Dart. Similarly one cannot declare a top-level function with the same name as a library variable or a class. } \LMHash{} It is a compile-time error if there is more than one entity with the same name declared in the same scope. \commentary{ In some cases, the name of the declaration differs from the identifier used to declare it. Setters have names that are distinct from the corresponding getters because they always have an = automatically added at the end, and unary minus has the special name unary-. } \LMHash{} Dart is lexically scoped. Scopes may nest. A name or declaration $d$ is {\em available in scope} $S$ if $d$ is in the namespace induced by $S$ or if $d$ is available in the lexically enclosing scope of $S$. We say that a name or declaration $d$ is {\em in scope} if $d$ is available in the current scope. \LMHash{} If a declaration $d$ named $n$ is in the namespace induced by a scope $S$, then $d$ {\em hides} any declaration named $n$ that is available in the lexically enclosing scope of $S$. \commentary{ A consequence of these rules is that it is possible to hide a type with a method or variable. Naming conventions usually prevent such abuses. Nevertheless, the following program is legal: } \begin{dartCode} \CLASS{} HighlyStrung \{ String() => "?"; \} \end{dartCode} \LMHash{} Names may be introduced into a scope by declarations within the scope or by other mechanisms such as imports or inheritance. \rationale{ The interaction of lexical scoping and inheritance is a subtle one. Ultimately, the question is whether lexical scoping takes precedence over inheritance or vice versa. Dart chooses the former. Allowing inherited names to take precedence over locally declared names could create unexpected situations as code evolves. Specifically, the behavior of code in a subclass could silently change if a new name is introduced in a superclass. Consider: } \begin{dartCode} \LIBRARY{} L1; \CLASS{} S \{\} \LIBRARY{} L2; \IMPORT{} L1.dart'; foo() => 42; \CLASS{} C \EXTENDS{} S\{ bar() => foo();\} \end{dartCode} \rationale{ Now assume a method \code{foo()} is added to \code{S}. } \begin{dartCode} \LIBRARY{} L1; \CLASS{} S \{foo() => 91;\} \end{dartCode} \rationale{ If inheritance took precedence over the lexical scope, the behavior of \code{C} would change in an unexpected way. Neither the author of \code{S} nor the author of \code{C} are necessarily aware of this. In Dart, if there is a lexically visible method \code{foo()}, it will always be called. Now consider the opposite scenario. We start with a version of \code{S} that contains \code{foo()}, but do not declare \code{foo()} in library \code{L2}. Again, there is a change in behavior - but the author of \code{L2} is the one who introduced the discrepancy that effects their code, and the new code is lexically visible. Both these factors make it more likely that the problem will be detected. These considerations become even more important if one introduces constructs such as nested classes, which might be considered in future versions of the language. Good tooling should of course endeavor to inform programmers of such situations (discreetly). For example, an identifier that is both inherited and lexically visible could be highlighted (via underlining or colorization). Better yet, tight integration of source control with language aware tools would detect such changes when they occur. } \subsection{Privacy} \LMLabel{privacy} \LMHash{} Dart supports two levels of privacy: {\em public} and {\em private}. A declaration is {\em private} if{}f its name is private, otherwise it is {\em public}. A name $q$ is private if{}f any one of the identifiers that comprise $q$ is private, otherwise it is {\em public}. An identifier is private if{}f it begins with an underscore (the \_ character) otherwise it is {\em public}. \LMHash{} A declaration $m$ is {\em accessible to library $L$} if $m$ is declared in $L$ or if $m$ is public. \commentary{ This means private declarations may only be accessed within the library in which they are declared. } \LMHash{} Privacy applies only to declarations within a library, not to library declarations themselves. \rationale{ Libraries do not reference each other by name and so the idea of a private library is meaningless. Thus, if the name of a library begins with an underscore, it has no effect on the accessibility of the library or its members. } \rationale{ Privacy is, at this point, a static notion tied to a particular piece of code (a library). It is designed to support software engineering concerns rather than security concerns. Untrusted code should always run in an another isolate. It is possible that libraries will become first class objects and privacy will be a dynamic notion tied to a library instance. Privacy is indicated by the name of a declaration - hence privacy and naming are not orthogonal. This has the advantage that both humans and machines can recognize access to private declarations at the point of use without knowledge of the context from which the declaration is derived. } \subsection{Concurrency} \LMLabel{concurrency} \LMHash{} Dart code is always single threaded. There is no shared-state concurrency in Dart. Concurrency is supported via actor-like entities called {\em isolates}. \LMHash{} An isolate is a unit of concurrency. It has its own memory and its own thread of control. Isolates communicate by message passing (\ref{sendingMessages}). No state is ever shared between isolates. Isolates are created by spawning (\ref{spawningAnIsolate}). \section{Errors} \LMLabel{errors} \LMHash{} This specification distinguishes between several kinds of errors. \LMHash{} {\em Compile-time errors} are errors that preclude execution. A compile-time error must be reported by a Dart compiler before the erroneous code is executed. \rationale{ A Dart implementation has considerable freedom as to when compilation takes place. Modern programming language implementations often interleave compilation and execution, so that compilation of a method may be delayed, e.g., until it is first invoked. Consequently, compile-time errors in a method $m$ may be reported as late as the time of $m$'s first invocation. Dart is often loaded directly from source, with no intermediate binary representation. In the interests of rapid loading, Dart implementations may choose to avoid full parsing of method bodies, for example. This can be done by tokenizing the input and checking for balanced curly braces on method body entry. In such an implementation, even syntax errors will be detected only when the method needs to be executed, at which time it will be compiled (JITed). In a development environment a compiler should of course report compilation errors eagerly so as to best serve the programmer. A Dart development environment might choose to support error eliminating program transformations, e.g., replacing an erroneous expression by the invocation of a debugger. It is outside the scope of this document to specify how such transformations work, and where they may be applied. } \LMHash{} If an uncaught compile-time error occurs within the code of a running isolate $A$, $A$ is immediately suspended. The only circumstance where a compile-time error could be caught would be via code run reflectively, where the mirror system can catch it. \rationale{ Typically, once a compile-time error is thrown and $A$ is suspended, $A$ will then be terminated. However, this depends on the overall environment. A Dart engine runs in the context of an {\em embedder}, a program that interfaces between the engine and the surrounding computing environment. The embedder will often be a web browser, but need not be; it may be a C++ program on the server for example. When an isolate fails with a compile-time error as described above, control returns to the embedder, along with an exception describing the problem. This is necessary so that the embedder can clean up resources etc. It is then the embedder's decision whether to terminate the isolate or not. } \LMHash{} When this specification says that a {\em run-time error} occurs, it means that a corresponding error object is thrown. When it says that a {\em dynamic type error} occurs, it represents a failed run-time type check, and the object which is thrown implements \code{TypeError}. \LMHash{} Whenever we say that an exception $ex$ is {\em thrown}, it acts like an expression had {\em thrown} (\ref{completion}) with $ex$ as exception object and with a stack trace corresponding to the current system state. When we say that {\em a} $C$ {\em is thrown}, where $C$ is a class, we mean that an instance of class $C$ is thrown. \LMHash{} If an uncaught exception is thrown by a running isolate $A$, $A$ is immediately suspended. \section{Variables} \LMLabel{variables} \LMHash{} Variables are storage locations in memory. \begin{grammar} ::= (,' )* ::= ::= \FINAL{} ? \alt \CONST{} ? \alt ::= \VAR{} \alt ::= (=' )? (,' )* ::= (=' )? ::= (,' )* \end{grammar} \LMHash{} A variable declaration that contains one or more terms of the form \syntax{} (\commentary{i.e., a declaration that declares two or more variables}) is equivalent to multiple variable declarations declaring the same set of variable names in the same order, with the same type and modifiers. \LMHash{} An initialized variable declaration that contains one or more terms of the form \syntax{} (\commentary{a declaration that declares two or more initialized variables}) is equivalent to multiple variable declarations declaring the same set of variable names in the same order, with the same initialization, type, and modifiers. \commentary{ For example, \code{\VAR{} x, y;} is equivalent to \code{\VAR{} x; \VAR{} y;} and \code{\STATIC{} \FINAL{} String s1, s2 = "foo";} is equivalent to \code{\STATIC{} \FINAL{} String s1; \STATIC{} \FINAL{} String s2 = "foo";}. } \LMHash{} In a variable declaration of one of the forms \code{$N$ $v$;} \code{$N$ $v$ = $e$;} where $N$ is derived from \syntax{ }, we say that $v$ is the {\em declaring occurrence} of the identifier. For every identifier which is not a declaring occurrence, we say that it is an {\em referencing occurrence}. We also abbreviate that to say that an identifier is a {\em declaring identifier} respectively an {\em referencing identifier}. \commentary{ In an expression of the form \code{$e$.\id} it is possible that $e$ has static type \DYNAMIC{} and \id{} cannot be associated with any declaration named \id{} at compile-time, but in this situation \id{} is still a referencing identifier. } \LMHash{} An {\em initialized variable} is a variable whose declaring identifier is immediately followed by \code{=}' and an {\em initializing expression}. \LMHash{} A variable declared at the top-level of a library is referred to as either a {\em library variable} or 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{}. \LMHash{} A {\em constant variable} is a variable whose declaration includes the modifier \CONST{}. A constant variable must be initialized to a constant expression (\ref{constants}) or a compile-time error occurs. \LMHash{} A {\em final variable} is a variable whose binding is fixed upon initialization; a final variable $v$ will always refer to the same object after $v$ has been initialized. A variable is final if{}f its declaration includes the modifier \FINAL{} or the modifier \CONST{}. \LMHash{} A {\em mutable variable} is a variable which is not final. %% Note that the following relies on the assumption that inference has %% already taken place, including member signature inference. For instance, %% if var x; is an instance variable declaration that overrides T get x; %% then we treat var x; as if it had been T x;. \LMHash{} The following rules apply to all static and instance variables. \LMHash{} A variable declaration of one of the forms \code{$T$ $v$;} \code{$T$ $v$ = $e$;} \code{\CONST{} $T$ $v$ = $e$;} \code{\FINAL{} $T$ $v$;} or \code{\FINAL{} $T$ $v$ = $e$;} induces an implicit getter function (\ref{getters}) with signature \code{$T$ \GET{} $v$} whose invocation evaluates as described below (\ref{evaluationOfImplicitVariableGetters}). In these cases the static type of $v$ is $T$. \LMHash{} A variable declaration of one of the forms \code{\VAR{} $v$;} \code{\VAR{} $v$ = $e$;} \code{\CONST{} $v$ = $e$;} \code{\FINAL{} $v$;} or \code{\FINAL{} $v$ = $e$;} induces an implicit getter function with signature \code{\DYNAMIC{} \GET{} $v$} whose invocation evaluates as described below (\ref{evaluationOfImplicitVariableGetters}). %% TODO[inference]: We assume inference has taken place, i.e., inferred types %% are written explicitly. Does this mean that the initialized variants %% cannot exist (not even for $e$ of type dynamic?). We probably don't %% want to start talking about a grammar before inference and another one %% after inference. In these cases, the static type of $v$ is \DYNAMIC{} (\ref{typeDynamic}). \LMHash{} A mutable variable declaration of the form \code{{} $T$ $v$;} or \code{$T$ $v$ = $e$;} induces an implicit setter function (\ref{setters}) with signature \code{\VOID{} \SET{} $v$=($T$ $x$)} whose execution sets the value of $v$ to the incoming argument $x$. \LMHash{} A mutable variable declaration of the form \code{\VAR{} $v$;} or \code{\VAR{} $v$ = $e$;} induces an implicit setter function with signature \code{\VOID{} \SET{} $v$=(\DYNAMIC{} $x$)} whose execution sets the value of $v$ to the incoming argument $x$. \LMHash{} The scope into which the implicit getters and setters are introduced depends on the kind of variable declaration involved. \LMHash{} A library variable introduces a getter into the top level scope of the enclosing library. A static class variable introduces a static getter into the immediately enclosing class. An instance variable introduces an instance getter into the immediately enclosing class. \LMHash{} A mutable library variable introduces a setter into the top level scope of the enclosing library. A mutable static class variable introduces a static setter into the immediately enclosing class. A mutable instance variable introduces an instance setter into the immediately enclosing class. \LMHash{} Let $v$ be an initialized variable and let $e$ be the associated initializing expression. It is a compile-time error if the static type of $e$ is not assignable to the declared type of $v$. It is a compile-time error if a final instance variable whose declaration has an initializer expression is also initialized by a constructor, either by an initializing formal or an initializer list entry. \commentary{ It is a compile-time error if a final instance variable that has been initialized by means of an initializing formal of a constructor $k$ is also initialized in the initializer list of $k$ (\ref{initializerLists}). A static final variable $v$ does not induce a setter, so unless a setter named \code{$v$=} is in scope it is a compile-time error to assign to $v$. Similarly, assignment to a final instance variable $v$ is a compile-time error, unless a setter named \code{$v$=} is in scope, or the receiver has type \DYNAMIC{}. $v$ can be initialized in its declaration or in initializer lists, but initialization and assignment is not the same thing. When the receiver has type \DYNAMIC{} such an assignment is not a compile-time error, but if there is no setter it will cause a dynamic error. } \LMHash{} A variable that has no initializing expression has the null object (\ref{null}) as its initial value. Otherwise, variable initialization proceeds as follows: \LMHash{} Static variable declarations with an initializing expression are initialized lazily (\ref{evaluationOfImplicitVariableGetters}). \rationale{ The lazy semantics are given because we do not want a language where one tends to define expensive initialization computations, causing long application startup times. This is especially crucial for Dart, which must support the coding of client applications. } \commentary{ Initialization of an instance variable with no initializing expression takes place during constructor execution (\ref{initializerLists}). } \LMHash{} Initialization of an instance variable $v$ with an initializing expression $e$ proceeds as follows: $e$ is evaluated to an object $o$ and the variable $v$ is bound to $o$. \commentary{ It is specified elsewhere when this initialization occurs, and in which environment (p.\,\pageref{executionOfGenerativeConstructors}, \ref{localVariableDeclaration}, \ref{bindingActualsToFormals}). } \commentary{ If the initializing expression throws then access to the uninitialized variable is prevented, because the instance creation that caused this initialization to take place will throw. } \LMHash{} It is a dynamic type error if $o$ is not the null object (\ref{null}) and the dynamic type of $o$ is not a subtype of the actual type of the variable $v$ (\ref{actualTypeOfADeclaration}). \subsection{Evaluation of Implicit Variable Getters} \LMLabel{evaluationOfImplicitVariableGetters} \LMHash{} Let $d$ be the declaration of a static or instance variable $v$. If $d$ is an instance variable, then the invocation of the implicit getter of $v$ evaluates to the value stored in $v$. If $d$ is a static variable (\commentary{which can be a library variable}) then the implicit getter method of $v$ executes as follows: \begin{itemize} \item {\bf Non-constant variable declaration with initializer}. If $d$ is of one of the forms \code{\VAR{} $v$ = $e$;}, \code{$T$ $v$ = $e$;}, \code{\FINAL{} $v$ = $e$;}, \code{\FINAL{} $T$ $v$ = $e$;}, \code{\STATIC{} $v$ = $e$;}, \code{\STATIC{} $T$ $v$ = $e$; }, \code{\STATIC{} \FINAL{} $v$ = $e$; } or \code{\STATIC{} \FINAL{} $T$ $v$ = $e$;} and no value has yet been stored into $v$ then the initializing expression $e$ is evaluated. If, during the evaluation of $e$, the getter for $v$ is invoked, a \code{CyclicInitializationError} is thrown. If the evaluation of $e$ throws an exception $e$ and stack trace $s$, the null object (\ref{null}) is stored into $v$; the execution of the getter then throws $e$ and stack trace $s$. Otherwise, the evaluation of $e$ succeeded yielding an object $o$; then $o$ is stored into $v$ and the execution of the getter completes by returning $o$. Otherwise, (\commentary{when a value $o$ has been stored in $v$}) execution of the getter completes by returning $o$. \item {\bf Constant variable declaration}. If $d$ is of one of the forms \code{\CONST{} $v$ = $e$;}, \code{\CONST{} $T$ $v$ = $e$;}, \code{\STATIC{} \CONST{} $v$ = $e$;} or \code{\STATIC{} \CONST{} $T$ $v$ = $e$;} the result of the getter is the value of the constant expression $e$. \commentary{ Note that a constant expression cannot depend on itself, so no cyclic references can occur. } \item {\bf Variable declaration without initializer}. The result of executing the getter method is the value stored in $v$. \commentary{This may be the initial value, that is, the null object.} \end{itemize} \section{Functions} \LMLabel{functions} \LMHash{} Functions abstract over executable actions. \begin{grammar} ::= ? ::= ? ::= \VOID{} \alt ::= \ASYNC{}? =>' ;' \alt (\ASYNC{} | \ASYNC *' | \SYNC *')? ::= {' }' \end{grammar} \LMHash{} Functions can be introduced by function declarations (\ref{functionDeclarations}), method declarations (\ref{instanceMethods}, \ref{staticMethods}), getter declarations (\ref{getters}), setter declarations (\ref{setters}), and constructor declarations (\ref{constructors}); and they can be introduced by function literals (\ref{functionExpressions}). \LMHash{} Each declaration that introduces a function has a signature that specifies its return type, name, and formal parameter part, except that the return type may be omitted, and getters never have a formal parameter part. Function literals have a formal parameter part, but no return type and no name. The formal parameter part optionally specifies the formal type parameter list of the function, and it always specifies its formal parameter list. 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, \code{\ASYNC*} or \code{\SYNC*}. \commentary{ 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 function body that ends without doing a throw or return will cause the function to return the null object (\ref{null}), as will a \RETURN{} without an expression. For generator functions, the situation is more subtle. See further discussion in section \ref{return}. } OR \item of the form \code{=> $e$} or the form \code{\ASYNC{} => $e$}, which both return the value of the expression $e$ as if by a \code{return $e$}. \commentary{ The other modifiers do not apply here, because they apply only to generators, discussed below, and generators are not allowed to return a value, values are added to the generated stream or iterable using \YIELD{} instead. } Let $R$ be the static type of $e$ and let $T$ be the declared return type of the function that has this body. It is a compile-time error unless one of the following conditions hold: \begin{itemize} \item $T$ is \VOID{}. \item The function is synchronous and $R$ is assignable to $T$. \item The function is asynchronous and \code{Future<\flatten{R}>} is assignable to $T$. \end{itemize} \end{itemize} \LMHash{} A function is {\em asynchronous} if its body is marked with the \ASYNC{} or \code{\ASYNC*} modifier. Otherwise the function is {\em synchronous}. A function is a {\em generator} if its body is marked with the \code{\SYNC*} or \code{\ASYNC*} modifier. \commentary{ Whether a function is synchronous or asynchronous is orthogonal to whether it is a generator or not. Generator functions are a sugar for functions that produce collections in a systematic way, by lazily applying a function that {\em generates} individual elements of a collection. Dart provides such a sugar in both the synchronous case, where one returns an iterable, and in the asynchronous case, where one returns a stream. Dart also allows both synchronous and asynchronous functions that produce a single value. } \LMHash{} It is a compile-time error if an \ASYNC, \code{\ASYNC*} or \code{\SYNC*} modifier is attached to the body of a setter or constructor. \rationale{ An asynchronous setter would be of little use, since setters can only be used in the context of an assignment (\ref{assignment}), and an assignment expression always evaluates to the value of the assignment's right hand side. If the setter actually did its work asynchronously, one might imagine that one would return a future that resolved to the assignment's right hand side after the setter did its work. An asynchronous constructor would, by definition, never return an instance of the class it purports to construct, but instead return a future. Calling such a beast via \NEW{} would be very confusing. If you need to produce an object asynchronously, use a method. One could allow modifiers for factories. A factory for \code{Future} could be modified by \ASYNC{}, a factory for \code{Stream} could be modified by \code{\ASYNC*} and a factory for \code{Iterable} could be modified by \code{\SYNC*}. No other scenario makes sense because the object returned by the factory would be of the wrong type. This situation is very unusual so it is not worth making an exception to the general rule for constructors in order to allow it. } \LMHash{} It is a compile-time error if the declared return type of a function marked \ASYNC{} is not a supertype of \code{Future<$T$>} for some type $T$. It is a compile-time error if the declared return type of a function marked \code{\SYNC*} is not a supertype of \code{Iterable<$T$>} for some type $T$. It is a compile-time error if the declared return type of a function marked \code{\ASYNC*} is not a supertype of \code{Stream<$T$>} for some type $T$. \subsection{Function Declarations} \LMLabel{functionDeclarations} \LMHash{} A {\em function declaration} is a function that is neither a member of a class nor a function literal. Function declarations include {\em library functions}, which are function declarations %(including getters and setters) at the top level of a library, and {\em local functions}, which are function declarations declared inside other functions. Library functions are often referred to simply as top-level functions. \LMHash{} A function declaration consists of an identifier indicating the function's name, possibly prefaced by a return type. The function name is followed by a signature and body. For getters, the signature is empty. The body is empty for functions that are external. \LMHash{} The scope of a library function is the scope of the enclosing library. The scope of a local function is described in section \ref{localFunctionDeclaration}. In both cases, the name of the function is in scope in its formal parameter scope (\ref{formalParameters}). \LMHash{} It is a compile-time error to preface a function declaration with the built-in identifier \STATIC{}. \LMHash{} 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 non-getter function declaration 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{} Some function declarations 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. \LMHash{} The {\em formal parameter part} of a function declaration consists of the formal type parameter list, if any, and the formal parameter list. \commentary{ The following kinds of functions cannot be generic: Getters, setters, operators, and constructors. } \LMHash{} The formal type parameter list of a function declaration introduces a new scope known as the function's {\em type parameter scope}. The 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 type parameter scope. \LMHash{} If it exists, the type parameter scope of a function $f$ is the current scope for the signature of $f$, and for the formal type parameter list itself; otherwise the scope where $f$ is declared is the current scope for the signature of $f$. \commentary{ This means that formal type parameters are in scope in the bounds of parameter declarations, allowing for so-called F-bounded type parameters like \code{class C{}> \{ \ldots{} \}}, \noindent and the formal type parameters are in scope for each other, allowing dependencies like \code{class D \{ \ldots{} \}}. } \LMHash{} The formal parameter list of a function declaration 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 type parameter scope of $f$. 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. \commentary{ This means that in a generic function declaration, 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 declaration 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.} \LMHash{} It is a compile-time error if a formal parameter is declared as a constant variable (\ref{variables}). \begin{grammar} ::= (' )' \alt (' ,'? )' \alt (' ,' )' \alt (' )' ::= (,' )* ::= \alt ::= [' (,' )* ,'? ]' ::= {' (,' )* ,'? }' \end{grammar} Formal parameter lists allow an optional trailing comma after the last parameter (\syntax{,'?}). A parameter list with such a trailing comma is equivalent in all ways to the same parameter list without the trailing comma. All parameter lists in this specification are shown without a trailing comma, but the rules and semantics apply equally to the corresponding parameter list with a trailing comma. \subsubsection{Required Formals} \LMLabel{requiredFormals} \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} ::= \alt \alt ::= \COVARIANT{}? ? \gnewline{} ::= \COVARIANT{}? ? ::= ? \THIS{} .' \gnewline{} ? \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{Optional Formals} \LMLabel{optionalFormals} \LMHash{} Optional parameters may be specified and provided with default values. \begin{grammar} ::= (=' )? ::= (=' )? \alt ( :' )? \end{grammar} A \syntax{} of the form \syntax{ :' } is equivalent to one of the form: \syntax{ =' }. The colon-syntax is included only for backwards compatibility. It is deprecated and will be removed in a later version of the language specification. \LMHash{} It is a compile-time error if the default value of an optional parameter is not a constant expression (\ref{constants}). If no default is explicitly specified for an optional parameter an implicit default of \NULL{} is provided. \LMHash{} It is a compile-time error if the name of a named optional parameter begins with an _' character. \rationale{ The need for this restriction is a direct consequence of the fact that naming and privacy are not orthogonal. 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 declaration 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, or it is a setter or operator \code{[]=}, in which case its return type is \VOID{}. \LMHash{} A function declaration may declare formal type parameters. The type of the function includes the names of the type parameters and their upper bounds. When consistent renaming of type parameters can make two function types identical, they are considered to be the same type. \commentary{ It is convenient to include the type parameter names in function types because they are needed in order to express such things as relations among different type parameters, and F-bounds. However, we do not wish to distinguish two function types if they have the same structure and only differ in the choice of names. This treatment of names is also known as alpha-equivalence. } \LMHash{} In the following three paragraphs, if the number $m$ of formal type parameters is zero then the type parameter list in the function type should be omitted. \LMHash{} Let $F$ be a function with formal type parameters $X_1\ B_1, \ldots,\ X_m\ B_m$, 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 \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n$) $\rightarrow T_0$}. \LMHash{} Let $F$ be a function with formal type parameters $X_1\ B_1, \ldots,\ X_m\ B_m$, 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 \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($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 formal type parameters $X_1\ B_1, \ldots,\ X_m\ B_m$, 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 \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($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 \FUNCTION{}. \commentary{ One cannot assume, based on the above, that given a function \code{f}, \code{f.runtimeType} will actually be \FUNCTION{}, or that any two distinct function objects necessarily have the same run-time type. } \rationale{ It is up to the implementation to choose an appropriate representation for function objects. For example, consider that a function object produced via property extraction treats equality differently from other function objects, and is therefore likely a different class. Implementations may also use different classes for function objects based on arity and or type. Arity may be implicitly affected by whether a function is an instance method (with an implicit receiver parameter) or not. The variations are manifold, and so this specification only guarantees that function objects are instances of some class that implements \FUNCTION{}. } \subsection{External Functions} \LMLabel{externalFunctions} \LMHash{} An {\em external function} is a function whose body is provided separately from its declaration. An external function may be a top-level function (\ref{librariesAndScripts}), a method (\ref{instanceMethods}, \ref{staticMethods}), a getter (\ref{getters}), a setter (\ref{setters}) or a non-redirecting constructor (\ref{generativeConstructors}, \ref{factories}). External functions are introduced via the built-in identifier \EXTERNAL{} (\ref{identifierReference}) followed by the function signature. \rationale{ External functions allow us to introduce type information for code that is not statically known to the Dart compiler. } \commentary{ Examples of external functions might be foreign functions (defined in C, or Javascript etc.), primitives of the implementation (as defined by the Dart run-time system), or code that was dynamically generated but whose interface is statically known. However, an abstract method is different from an external function, as it has {\em no} body. } \LMHash{} An external function is connected to its body by an implementation specific mechanism. Attempting to invoke an external function that has not been connected to its body will throw a \code{NoSuchMethodError} or some subclass thereof. \LMHash{} The actual syntax is given in sections \ref{classes} and \ref{librariesAndScripts} below. \section{Classes} \LMLabel{classes} \LMHash{} A {\em class} defines the form and behavior of a set of objects which are its {\em instances}. Classes may be defined by class declarations as described below, or via mixin applications (\ref{mixinApplication}). \begin{grammar} ::= \ABSTRACT{}? \CLASS{} ? \gnewline{} ? ? ? \gnewline{} {' ( )* }' \alt \ABSTRACT{}? \CLASS{} ::= \WITH{} ::= ;' \alt ::= ? \alt % This doesn't work: static @override foo() => 42, but functionSignature starts with metadata. https://github.com/dart-lang/sdk/issues/29614 \alt \STATIC{}? \alt \STATIC{}? \alt \STATIC{}? \alt ::= ( | )? \alt ( | )? \alt \EXTERNAL{} \alt \EXTERNAL{} \alt ((\EXTERNAL{} \STATIC{}?))? \alt ((\EXTERNAL{} \STATIC{}?))? \alt \EXTERNAL{}? % This doesn't work: static @override foo() => 42, but functionSignature starts with metadata. https://github.com/dart-lang/sdk/issues/29614 \alt ((\EXTERNAL{} \STATIC{}?))? \alt \STATIC{} (\FINAL{} | \CONST{}) ? % \CONST{} type? staticFinalDeclarationList; \alt \FINAL{} ? \alt (\STATIC{} | \COVARIANT{})? (\VAR{} | ) ::= (,' )* ::= =' \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 class 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} \LMHash{} The enclosing scope of an instance member declaration is the instance scope of the class in which it is declared. \LMHash{} The enclosing scope of a static member declaration is the static scope of the class in which it is declared. \LMHash{} Every class has a single superclass except class \code{Object} which has no superclass. A class may implement a number of interfaces by declaring them in its implements clause (\ref{superinterfaces}). \LMHash{} An {\em abstract class} is a class that is explicitly declared with the \ABSTRACT{} modifier, either by means of a class declaration or via a type alias (\ref{typedef}) for a mixin application (\ref{mixinApplication}). A {\em concrete class} is a class that is not abstract. \rationale{ We want different behavior for concrete classes and abstract classes. If $A$ is intended to be abstract, we want the static checker to warn about any attempt to instantiate $A$, and we do not want the checker to complain about unimplemented methods in $A$. In contrast, if $A$ is intended to be concrete, the checker should warn about all unimplemented methods, but allow clients to instantiate it freely. } \LMHash{} The {\em interface of class $C$} is an implicit interface that declares instance members that correspond to the instance members declared by $C$, and whose direct superinterfaces are the direct superinterfaces of $C$ (\ref{superinterfaces}). When a class name appears as a type, that name denotes the interface of the class. % making an exception for the setters generated for final fields is tempting but problematic. % If a super type defines a setter, it will be overridden yet have no impact on the interface. % Maybe the final field hides the setter in scope? % I think the original rules were best. \commentary{ It is a compile-time error if a class declares two members of the same name, either because it declares the same name twice in the same scope (\ref{scoping}), or because it declares a static member and an instance member with the same name (\ref{classMemberConflicts}). } \commentary{ Here are simple examples, that illustrate the difference between has a member'' and declares a member''. For example, \code{B} {\em declares} one member named \code{f}, but {\em has} two such members. The rules of inheritance determine what members a class has. } \begin{dartCode} \CLASS{} A \{ \VAR{} i = 0; \VAR{} j; f(x) => 3; \} \\ \CLASS{} B \EXTENDS{} A \{ int i = 1; // \comment{getter i and setter i= override versions from A} \STATIC{} j; // \comment{compile-time error: static getter \& setter conflict with} // \comment{instance getter \& setter} \\ // \comment{compile-time error: static method conflicts with instance method} \STATIC{} f(x) => 3; \} \end{dartCode} \LMHash{} It is a compile-time error if a class named $C$ declares a member with basename (\ref{classMemberConflicts}) $C$. If a generic class named $G$ declares a type variable named $X$, it is a compile-time error if $X$ is equal to $G$, if $G$ has a member whose basename is $X$, and if $G$ has a constructor named \code{$G$.$X$}. \subsection{Instance Methods} \LMLabel{instanceMethods} \LMHash{} Instance methods are functions (\ref{functions}) whose declarations are immediately contained within a class declaration and that are not declared \STATIC{}. The instance methods of a class $C$ are those instance methods declared by $C$ and the instance methods inherited by $C$ from its superclass. \LMHash{} It is a compile-time error if an instance method $m_1$ overrides (\ref{inheritanceAndOverriding}) an instance member $m_2$ and $m_1$ has a greater number of required parameters than $m_2$. It is a compile-time error if an instance method $m_1$ overrides an instance member $m_2$ and $m_1$ has fewer positional parameters than $m_2$. It is a compile-time error if an instance method $m_1$ overrides an instance member $m_2$ and $m_1$ does not declare all the named parameters declared by $m_2$. \LMHash{} %% TODO(eernst): We need to use the concept of 'correctly overrides' rather than 'is a subtype of', e.g., to treat void correctly. It is a compile-time error if an instance method $m_1$ overrides an instance member $m_2$ and the type of $m_1$ is not a subtype of the type of $m_2$. It is a compile-time error if an instance method $m_1$ overrides an instance member $m_2$, the signature of $m_2$ explicitly specifies a default value for a formal parameter $p$, and the signature of $m_1$ implies a different default value for $p$. \commentary{ A method declaration may conflict with other declarations (\ref{classMemberConflicts}). } \subsubsection{Operators} \LMLabel{operators} \LMHash{} {\em Operators} are instance methods with special names. \begin{grammar} ::= ? \OPERATOR{} ::= ~' \alt \alt []' \alt []=' ::= \alt \alt \alt \alt ==' \alt \end{grammar} \LMHash{} An operator declaration is identified using the built-in identifier (\ref{identifierReference}) \OPERATOR{}. \LMHash{} The following names are allowed for user-defined operators: \syntax{<'}, \syntax{>'}, \syntax{<='}, \syntax{>='}, \syntax{=='}, \syntax{-'}, \syntax{+'}, \syntax{/'}, \syntax{~'}, \syntax{*'}, \syntax{\%'}, \syntax{|'}, \syntax{^'}, \syntax{\&'}, \syntax{\ltlt'}, \syntax{\gtgt'}, \syntax{\gtgtgt'}, \syntax{[]='}, \syntax{[]'}, \syntax{~'}. \LMHash{} It is a compile-time error if the arity of the user-declared operator \syntax{[]='} is not 2. It is a compile-time error if the arity of a user-declared operator with one of the names: \syntax{<'}, \syntax{>'}, \syntax{<='}, \syntax{>='}, \syntax{=='}, \syntax{-'}, \syntax{+'}, \syntax{~/'}, \syntax{/'}, \syntax{*'}, \syntax{\%'}, \syntax{|'}, \syntax{^'}, \syntax{\&'}, \syntax{\ltlt'}, \syntax{\gtgt'}, \syntax{\gtgtgt'}, \syntax{[]'} is not 1. It is a compile-time error if the arity of the user-declared operator \syntax{-'} is not 0 or 1. \commentary{ The \syntax{-'} operator is unique in that two overloaded versions are permitted. If the operator has no arguments, it denotes unary minus. If it has an argument, it denotes binary subtraction. } \LMHash{} The name of the unary operator \syntax{-'} is \code{unary-}. \rationale{ This device allows the two methods to be distinguished for purposes of method lookup, override and reflection. } \LMHash{} It is a compile-time error if the arity of the user-declared operator \syntax{~'} is not 0. \LMHash{} It is a compile-time error to declare an optional parameter in an operator. \LMHash{} It is a compile-time error if the return type of a user-declared operator \syntax{[]='} is explicitly declared and not \VOID{}. \commentary{ If no return type is specified for a user-declared operator \syntax{[]='}, its return type is \VOID{} (\ref{typeOfAFunction}). } \rationale{ The return type is \VOID{} because a return statement in an implementation of operator \syntax{[]='} does not return a value. Consider a non-throwing evaluation of an expression $e$ of the form \code{$e_1$[$e_2$] = $e_3$}, and assume that the evaluation of $e_3$ yields an instance $o$. $e$ will then evaluate to $o$, and even if the executed body of operator \syntax{[]='} completes with a value $o'$, that is, if $o'$ is returned, that value is simply ignored. The rationale for this behavior is that assignments should be guaranteed to evaluate to the assigned value. } \subsubsection{The Method \code{noSuchMethod}} \LMLabel{theMethodNoSuchMethod} \LMHash{} The method \code{noSuchMethod} is invoked implicitly during execution in situations where one or more member lookups fail (\ref{ordinaryInvocation}, \ref{getterAccessAndMethodExtraction}, \ref{assignment}). \commentary{ We may think of \code{noSuchMethod} as a backup which kicks in when an invocation of a member $m$ is attempted, but there is no member named $m$, or it exists, but the given invocation has an argument list shape that does not fit the declaration of $m$ (passing fewer positional arguments than required or more than supported, or passing named arguments with names not declared by $m$). % The next sentence covers both function objects and instances of % a class with a method named \code{call}, because we would have a % compile-time error invoking \code{call} with a wrongly shaped argument % list unless the type is \DYNAMIC{} or \FUNCTION. This can only occur for an ordinary method invocation when the receiver has static type \DYNAMIC, or for a function invocation when the invoked function has static type \FUNCTION{} or \DYNAMIC. % The method \code{noSuchMethod} can also be invoked in other ways, e.g., it can be called explicitly like any other method, and it can be invoked from a \code{noSuchMethod} forwarder, as explained below. } \LMHash{} We say that a class $C$ {\em has a non-trivial \code{noSuchMethod}} if $C$ has a concrete member named \code{noSuchMethod} which is distinct from the one declared in the built-in class \code{Object}. \commentary{ Note that it must be a method that accepts one positional argument, in order to correctly override \code{noSuchMethod} in \code{Object}. For instance, it can have signature \code{noSuchMethod(Invocation i)} or \code{noSuchMethod(Object i, [String s])}, but not \code{noSuchMethod(Invocation i, String s)}. This implies that the situation where \code{noSuchMethod} is invoked (explicitly or implicitly) with one actual argument cannot fail for the reason that there is no such method'', such that we would enter an infinite loop trying to invoke \code{noSuchMethod}. It \emph{is} possible, however, to encounter a dynamic error during an invocation of \code{noSuchMethod} because the actual argument fails to satisfy a type check, but that situation will give rise to a dynamic type error rather than a repeated attempt to invoke \code{noSuchMethod} (\ref{bindingActualsToFormals}). Here is an example where a dynamic type error occurs because an attempt is made to pass an \code{Invocation} where only the null object is accepted: } \begin{dartCode} \CLASS{} A \{ noSuchMethod(\COVARIANT{} Null n) => n; \} \\ \VOID{} main() \{ \DYNAMIC{} d = A(); d.foo(42); // Dynamic type error when invoking noSuchMethod. \} \end{dartCode} \LMHash{} Let $C$ be a concrete class and let $L$ be the library that contains the declaration of $C$. The member $m$ is {\em noSuchMethod forwarded in} $C$ if{}f one of the following is true: \begin{itemize} \item $C$ has a non-trivial \code{noSuchMethod}, the interface of $C$ contains $m$, and $C$ has no concrete declaration of $m$ (\commentary{that is, no member $m$ is declared or inherited by $C$}). \item % Inaccessible private methods are not present in the interface of a class, % so we need to find a class that can access $m$. There exists a direct or indirect superinterface $D$ of $C$ which is declared in the library $L_2$, the interface of $D$ contains $m$ (\commentary{which implies that $m$ is accessible to $L_2$}), $m$ is inaccessible to $L$, and no superclass of $C$ has a concrete declaration of $m$ accessible to $L_2$. \end{itemize} \LMHash{} For a concrete class $C$, a {\em \code{noSuchMethod} forwarder} is implicitly induced for each member $m$ which is \code{noSuchMethod} forwarded. This is a concrete member of $C$ with the signature taken from the interface of $C$ respectively $D$ above, and with the same default value for each optional parameter. It can be invoked in an ordinary invocation and in a superinvocation, and when $m$ is a method it can be closurized (\ref{ordinaryMemberClosurization}) using a property extraction (\ref{propertyExtraction}). \commentary{ This implies that a \code{noSuchMethod} forwarder has the same properties as an explicitly declared concrete member, except of course that a \code{noSuchMethod} forwarder does not prevent itself from being induced. We do not specify the body of a \code{noSuchMethod} forwarder, but it will invoke \code{noSuchMethod}, and we specify the dynamic semantics of executing it below. } \commentary{ At the beginning of this section we mentioned that implicit invocations of \code{noSuchMethod} can only occur with a receiver of static type \DYNAMIC{} or a function of static type \DYNAMIC{} or \FUNCTION{}. With a \code{noSuchMethod} forwarder, \code{noSuchMethod} can also be invoked on a receiver whose static type is not \DYNAMIC{}. No similar situation exists for functions, because it is impossible to induce a \code{noSuchMethod} forwarder into the class of a function object. } \commentary{ For a concrete class $C$, we may think of a non-trivial \code{noSuchMethod} (declared in or inherited by $C$) as a request for automatic implementation'' of all unimplemented members in the interface of $C$ as \code{noSuchMethod} forwarders. Similarly, there is an implicit request for automatic implementation of all unimplemented inaccessible members of any concrete class, whether or not there is a non-trivial \code{noSuchMethod}. Note that the latter cannot be written explicitly in Dart, because their names are inaccessible; but the language can still specify that they are induced implicitly, because compilers control the treatment of private names. } \LMHash{} It is a compile-time error if a concrete class $C$ has a \code{noSuchMethod} forwarded method signature $S$ for a method named $m$, and a superclass of $C$ has a concrete declaration of $m$ which is not a \code{noSuchMethod} forwarder. \commentary{ This can only happen if that concrete declaration does not correctly override $S$. Consider the following example: } \begin{dartCode} \CLASS{} A \{ foo(int i) => \NULL; \} \ABSTRACT{} \CLASS{} B \{ foo([int i]); \} \CLASS{} C \EXTENDS{} A \IMPLEMENTS{} B \{ noSuchMethod(Invocation i) => ...; // Error: Forwarder would override A.foo. \} \end{dartCode} \commentary{ In this example, an implementation with signature \code{foo(int i)} is inherited by \code{C}, and the superinterface \code{B} declares the signature \code{foo([int i])}. This is a compile-time error because \code{C} does not have a method implementation with signature \code{foo([int])}. We do not wish to implicitly induce a \code{noSuchMethod} forwarder with signature \code{foo([int])} because it would override \code{A.foo}, and that is likely to be highly confusing for developers. % In particular, it would cause an invocation like \code{C().foo(42)} to invoke \code{noSuchMethod}, even though that is an invocation which is correct for the declaration of \code{foo} in \code{A}. % Hence, we require developers to explicitly resolve the conflict whenever an implicitly induced \code{noSuchMethod} forwarder would override an explicitly declared inherited implementation. % It is no problem, however, to let a \code{noSuchMethod} forwarder override another \code{noSuchMethod} forwarder, and hence there is no error in that situation. } \LMHash{} For the dynamic semantics, assume that a class $C$ has an implicitly induced \code{noSuchMethod} forwarder named $m$, with formal type parameters \code{$X_1,\ \ldots,\ X_r$}, positional formal parameters \code{$a1,\ \ldots,\ a_k$} (\commentary{some of which may be optional when $m = 0$}), and named formal parameters with names \code{$x_1,\ \ldots,\ x_m$} (\commentary{with default values as mentioned above}). \commentary{ For this purpose we need not distinguish between a signature that has optional positional parameters and a signature that has named parameters, because the former is covered by $m = 0$. } \LMHash{} The execution of the body of $m$ creates an instance $im$ of the predefined class \code{Invocation} such that: \begin{itemize} \item \code{$im$.isMethod} evaluates to \code{\TRUE{}} if{}f $m$ is a method. \item \code{$im$.isGetter} evaluates to \code{\TRUE{}} if{}f $m$ is a getter. \item \code{$im$.isSetter} evaluates to \code{\TRUE{}} if{}f $m$ is a setter. \item \code{$im$.memberName} evaluates to the symbol \code{m}. \item \code{$im$.positionalArguments} evaluates to an unmodifiable list with the same values as the list resulting from evaluation of \code{