diff --git a/docs/language/.gitignore b/docs/language/.gitignore index 13c76142d02..8c6cc1f53b0 100644 --- a/docs/language/.gitignore +++ b/docs/language/.gitignore @@ -1,4 +1,7 @@ dartLangSpec*.aux +dartLangSpec*.idx +dartLangSpec*.ilg +dartLangSpec*.ind dartLangSpec*.log dartLangSpec*.out dartLangSpec*.pdf diff --git a/docs/language/Makefile b/docs/language/Makefile index 4819c234643..aecfd61f78b 100644 --- a/docs/language/Makefile +++ b/docs/language/Makefile @@ -6,21 +6,25 @@ HASHER=../../tools/addlatexhash.dart pdf: pdflatex $(SPEC) + makeindex $(NAME).idx pdflatex $(SPEC) pdflatex $(SPEC) pdfhash: hash_and_list pdflatex $(HASH) + makeindex $(NAME)-hash.idx pdflatex $(HASH) pdflatex $(HASH) dvi: latex $(SPEC) + makeindex $(NAME).idx latex $(SPEC) latex $(SPEC) dvihash: hash_and_list latex $(HASH) + makeindex $(NAME)-hash.idx latex $(HASH) latex $(HASH) @@ -35,8 +39,7 @@ help: @echo " clean: remove all generated files" cleanish: - rm -f *.aux *.log *.toc *.out + rm -f *.aux *.log *.toc *.out *.idx *.ilg clean: cleanish - rm -f *.dvi *.pdf $(HASH) $(LIST) - + rm -f *.dvi *.pdf *.ind $(HASH) $(LIST) diff --git a/docs/language/dart.sty b/docs/language/dart.sty index d6c265d2947..0aede6bd2a4 100644 --- a/docs/language/dart.sty +++ b/docs/language/dart.sty @@ -78,7 +78,7 @@ % Used as line break in the right hand side of a grammar % alternative, that is, when starting a "continuation line". -\newcommand{\gnewline}{\\\mbox{}\qquad{}} +\newcommand{\gnewline}{\leavevmode\\} % Metavariables for argument lists. \newcommand{\argumentList}[1]{\metavar{{#1}s}} @@ -110,6 +110,17 @@ % A commonly used name for an identifier \newcommand{\id}{\metavar{id}} +% Used for defining occurrence of phrase, with customized index entry. +\newcommand{\IndexCustom}[2]{% + \leavevmode\marginpar{\ensuremath{\diamond}}\emph{#1}\index{#2}} + +% Used for a defining occurrence of a phrase, adding it to the index. +\newcommand{\Index}[1]{\IndexCustom{#1}{#1}} + +% Same appearance, but not adding an entry to the index. +\newcommand{\NoIndex}[1]{ + \leavevmode\marginpar{\ensuremath{\diamond}}\emph{#1}} + % ---------------------------------------------------------------------- % Support for hash valued Location Markers @@ -128,14 +139,14 @@ \definecolor{LMdim}{gray}{1.0} % insert location marker showing hash value of following paragraph -\newcommand{\LMHash}[1]{% - \hspace{0pt}\marginpar{\raisebox{0.5ex}{\miniscule{\color{LMdim}#1}}}} +\newcommand{\LMHash}[1]{\leavevmode\marginpar{\quad% + \raisebox{0.5ex}{\miniscule{\color{LMdim}#1}}\vspace{-2\baselineskip}}} % support convenient renewcommand \let\OriginalLMHash\LMHash % define a label, and show the associated logical location marker \newcommand{\LMLabel}[1]{% - \vspace{-\baselineskip}\hspace{0pt}\OriginalLMHash{\raisebox{10ex}{#1}}% + \vspace{-\baselineskip}\leavevmode\OriginalLMHash{\raisebox{10ex}{#1}}% \label{#1}} % ---------------------------------------------------------------------- diff --git a/docs/language/dartLangSpec.tex b/docs/language/dartLangSpec.tex index 51fd94cff01..f7134a10d6a 100644 --- a/docs/language/dartLangSpec.tex +++ b/docs/language/dartLangSpec.tex @@ -1,4 +1,4 @@ -\documentclass{article} +\documentclass[makeidx]{article} \usepackage{xspace} \usepackage{epsfig} \usepackage{color} @@ -7,6 +7,8 @@ \usepackage{hyperref} \usepackage{lmodern} \usepackage[T1]{fontenc} +\usepackage{makeidx} +\makeindex \title{Dart Programming Language Specification\\ {5th edition draft}\\ {\large Version 2.1.0-dev}} @@ -190,7 +192,7 @@ \section{Scope} \LMLabel{ecmaScope} -\LMHash{} +\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}). @@ -198,17 +200,17 @@ It does not specify the APIs of the Dart libraries except where those library el \section{Conformance} \LMLabel{ecmaConformance} -\LMHash{} +\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{} +\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{} +\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. @@ -224,16 +226,17 @@ For undated references, the latest edition of the referenced document (including \section{Terms and Definitions} \LMLabel{ecmaTermsAndDefinitions} -\LMHash{} +\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'. +Such terms are highlighted in italics when they are introduced, e.g., `we use the term \NoIndex{verbosity} to refer to the property of excess verbiage', +and add a marker in the margin. % End Ecma Boilerplate \section{Notation} \LMLabel{notation} -\LMHash{} +\LMHash{}% We distinguish between normative and non-normative text. Normative text defines the rules of Dart. It is given in this font. @@ -257,14 +260,14 @@ Open questions are points that are unsettled in the mind of the author(s) of the \Q{Should the text at the end of the previous bullet be rationale or commentary?} \end{itemize} -\LMHash{} +\LMHash{}% Reserved words and built-in identifiers (\ref{identifierReference}) appear in {\bf bold}. \commentary{ Examples would be \SWITCH{} or \CLASS{}. } -\LMHash{} +\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. @@ -294,32 +297,32 @@ An example would be: \alt \end{grammar} -\LMHash{} +\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{} +\LMHash{}% Productions are embedded, as much as possible, in the discussion of the constructs they represent. -\LMHash{} -A {\em term} is a syntactic construct. +\LMHash{}% +A \Index{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 +An \Index{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$, +A \Index{subterm} of a given term $t$ is $t$, or an immediate subterm of $t$, or a subterm of an immediate subterm of $t$. -\LMHash{} +\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{} +\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), @@ -327,7 +330,7 @@ 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{} +\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. @@ -338,11 +341,11 @@ the relevant declarations in $E$ are systematically renamed to fresh names. In short, capture freedom ensures that the ``meaning'' of each identifier is preserved during substitution. } -\LMHash{} +\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{} +\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} @@ -355,22 +358,28 @@ This circumlocution is required because x.op(y), where op is an operator, is not 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{} +\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. +\LMHash{}% +When the specification refers to a +\IndexCustom{fresh variable}{variable!fresh}, +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{} +\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. +\LMHash{}% +When the specification says that one piece of syntax \Index{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. } @@ -380,12 +389,12 @@ If execution or evaluation of a construct is said to be equivalent to execution \section{Overview} \LMLabel{overview} -\LMHash{} +\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{} +\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 @@ -405,7 +414,7 @@ dynamic semantics of Dart as specified here, but, as mentioned, this specification makes no attempt to specify exactly what that means. } -\LMHash{} +\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. @@ -449,8 +458,9 @@ 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}). +\LMHash{}% +Dart programs are organized in a modular fashion into +units called \NoIndex{libraries} (\ref{librariesAndScripts}). Libraries are units of encapsulation and may be mutually recursive. \commentary{ @@ -458,7 +468,7 @@ However they are not first class. To get multiple copies of a library running simultaneously, one needs to spawn an isolate. } -\LMHash{} +\LMHash{}% A dart program execution may occur with assertions enabled or disabled. The method used to enable or disable assertions is implementation specific. @@ -466,13 +476,13 @@ 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. +\LMHash{}% +A \Index{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$. +We say that a name $n$ \Index{is in} $NS$ if $n$ is a key of $NS$. +We say a declaration $d$ \NoIndex{is in} $NS$ if a key of $NS$ maps to $d$. -\LMHash{} +\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. @@ -481,7 +491,7 @@ It is therefore impossible, e.g., to define a class that declares a method and a Similarly one cannot declare a top-level function with the same name as a library variable or a class. } -\LMHash{} +\LMHash{}% It is a compile-time error if there is more than one entity with the same name declared in the same scope. \commentary{ @@ -489,14 +499,14 @@ In some cases, the name of the declaration differs from the identifier used to d 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{} +\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. +A name or declaration $d$ is \Index{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 \Index{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$. +\LMHash{}% +If a declaration $d$ named $n$ is in the namespace induced by a scope $S$, then $d$ \Index{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. @@ -510,7 +520,7 @@ Nevertheless, the following program is legal: \} \end{dartCode} -\LMHash{} +\LMHash{}% Names may be introduced into a scope by declarations within the scope or by other mechanisms such as imports or inheritance. \rationale{ @@ -563,20 +573,27 @@ Better yet, tight integration of source control with language aware tools would \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{}% +Dart supports two levels of \Index{privacy}: public and private. +A declaration is \IndexCustom{private}{private!declaration} +if{}f its name is private, +otherwise it is \IndexCustom{public}{public!declaration}. +A name $q$ is \IndexCustom{private}{private!name} +if{}f any one of the identifiers that comprise $q$ is private, +otherwise it is \IndexCustom{public}{public!name}. +An identifier is \IndexCustom{private}{private!identifier} +if{}f it begins with an underscore (the \_ character) +otherwise it is \IndexCustom{public}{public!identifier}. -\LMHash{} -A declaration $m$ is {\em accessible to library $L$} if $m$ is declared in $L$ or if $m$ is public. +\LMHash{}% +A declaration $m$ is \Index{accessible to a 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{} +\LMHash{}% Privacy applies only to declarations within a library, not to library declarations themselves. \rationale{ @@ -598,12 +615,12 @@ This has the advantage that both humans and machines can recognize access to pri \subsection{Concurrency} \LMLabel{concurrency} -\LMHash{} +\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}. +Concurrency is supported via actor-like entities called \Index{isolates}. -\LMHash{} +\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}). @@ -614,11 +631,12 @@ Isolates are created by spawning (\ref{spawningAnIsolate}). \section{Errors and Warnings} \LMLabel{errorsAndWarnings} -\LMHash{} +\LMHash{}% This specification distinguishes between several kinds of errors. -\LMHash{} -{\em Compile-time errors} are errors that preclude execution. +\LMHash{}% +\IndexCustom{Compile-time errors}{compile-time error} +are errors that preclude execution. A compile-time error must be reported by a Dart compiler before the erroneous code is executed. \rationale{ @@ -638,14 +656,14 @@ 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{} +\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 Dart engine runs in the context of an \Index{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. @@ -653,32 +671,37 @@ 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{} -{\em Compile-time warnings} are situations that do not preclude execution, +\LMHash{}% +\IndexCustom{Static warnings}{static warning} +are situations that do not preclude execution, but which are unlikely to be intended, and likely to cause bugs or inconveniences. -A compile-time warning must be reported by a Dart compiler before the associated code is executed. +A static warning must be reported by a Dart compiler before the associated code is executed. -\LMHash{} -When this specification says that a {\em run-time error} occurs, +\LMHash{}% +When this specification says that a \Index{run-time error} occurs, it means that a corresponding error object is thrown. -When it says that a {\em dynamic type error} occurs, +When it says that a \Index{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{}% +Whenever we say that an exception $ex$ is +\IndexCustom{thrown}{throwing an exception}, +it acts like an expression had thrown (\ref{completion}) +with $ex$ as exception object and with a stack trace +corresponding to the current system state. +When we say that a $C$ \IndexCustom{is thrown}{throwing a class}, +where $C$ is a class, we mean that an instance of class $C$ is thrown. -\LMHash{} +\LMHash{}% If an uncaught exception is thrown by a running isolate $A$, $A$ is immediately suspended. \section{Variables} \LMLabel{variables} -\LMHash{} +\LMHash{}% Variables are storage locations in memory. \begin{grammar} @@ -693,7 +716,7 @@ Variables are storage locations in memory. ::= \VAR{} \alt - ::= + ::= \gnewline{} (`=' )? (`,' )* ::= (`=' )? @@ -701,7 +724,7 @@ Variables are storage locations in memory. ::= (`,' )* \end{grammar} -\LMHash{} +\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}) @@ -709,7 +732,7 @@ is equivalent to multiple variable declarations declaring the same set of variable names in the same order, with the same type and modifiers. -\LMHash{} +\LMHash{}% An \syntax{} that contains one or more terms of the form \syntax{} (\commentary{that is, a declaration that declares two or more initialized variables}) @@ -728,17 +751,17 @@ is equivalent to \code{\STATIC{} \FINAL{} String s1; \STATIC{} \FINAL{} String s2 = "foo";}. } -\LMHash{} +\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. +we say that $v$ is the \Index{declaring occurrence} of the identifier. For every identifier which is not a declaring occurrence, -we say that it is an {\em referencing occurrence}. +we say that it is an \Index{referencing occurrence}. We also abbreviate that to say that an identifier is -a {\em declaring identifier} respectively an {\em referencing identifier}. +a \Index{declaring identifier} respectively an \Index{referencing identifier}. \commentary{ In an expression of the form \code{$e$.\id} it is possible that @@ -747,42 +770,49 @@ any declaration named \id{} at compile-time, but in this situation \id{} is still a referencing identifier. } -\LMHash{} -An {\em initializing variable declaration} +\LMHash{}% +An \Index{initializing variable declaration} is a variable declaration whose declaring identifier is -immediately followed by `\code{=}' and an {\em initializing expression}. +immediately followed by `\code{=}' and an \Index{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 variable declared at the top-level of a library is referred to as either a +\IndexCustom{library variable}{variable!library} or a +\IndexCustom{top-level variable}{variable!top-level}. -\LMHash{} -A {\em static variable} is a variable that is not associated with a particular instance, but rather with an entire library or class. +\LMHash{}% +A \IndexCustom{static variable}{variable!static} +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{}. +\LMHash{}% +A \IndexCustom{constant variable}{variable!constant} +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; +\LMHash{}% +A \IndexCustom{final variable}{variable!final} +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. +\LMHash{}% +A \IndexCustom{mutable variable}{variable!mutable} +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{} +\LMHash{}% The following rules apply to all static and instance variables. -\LMHash{} +\LMHash{}% A variable declaration of one of the forms \code{$T$ $v$;} \code{$T$ $v$ = $e$;} @@ -795,7 +825,7 @@ whose invocation evaluates as described below (\ref{evaluationOfImplicitVariableGetters}). In these cases the static type of $v$ is $T$. -\LMHash{} +\LMHash{}% A variable declaration of one of the forms \code{\VAR{} $v$;} \code{\VAR{} $v$ = $e$;} @@ -814,7 +844,7 @@ whose invocation evaluates as described below In these cases, the static type of $v$ is \DYNAMIC{} (\ref{typeDynamic}). -\LMHash{} +\LMHash{}% A mutable variable declaration of the form \code{{} $T$ $v$;} or \code{$T$ $v$ = $e$;} @@ -822,7 +852,7 @@ 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{} +\LMHash{}% A mutable variable declaration of the form \code{\VAR{} $v$;} or \code{\VAR{} $v$ = $e$;} @@ -830,20 +860,20 @@ 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{} +\LMHash{}% The scope into which the implicit getters and setters are introduced depends on the kind of variable declaration involved. -\LMHash{} +\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{} +\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{} +\LMHash{}% Let $v$ be variable declared in an initializing variable declaration, 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$. @@ -870,11 +900,11 @@ such an assignment is not a compile-time error, but if there is no setter it will cause a dynamic error. } -\LMHash{} +\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{} +\LMHash{}% Static variable declarations with an initializing expression are initialized lazily (\ref{evaluationOfImplicitVariableGetters}). @@ -889,7 +919,7 @@ takes place during constructor execution (\ref{initializerLists}). } -\LMHash{} +\LMHash{}% Initialization of an instance variable $v$ with an initializing expression $e$ proceeds as follows: @@ -912,7 +942,7 @@ that caused this initialization to take place will throw. } -\LMHash{} +\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$ @@ -922,7 +952,7 @@ a subtype of the actual type of the variable $v$ \subsection{Evaluation of Implicit Variable Getters} \LMLabel{evaluationOfImplicitVariableGetters} -\LMHash{} +\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 @@ -974,11 +1004,12 @@ The result of executing the getter method is the value stored in $v$. \section{Functions} \LMLabel{functions} -\LMHash{} +\LMHash{}% Functions abstract over executable actions. \begin{grammar} - ::= ? + ::= \gnewline{} + ? ::= ? @@ -991,7 +1022,7 @@ Functions abstract over executable actions. ::= `{' `}' \end{grammar} -\LMHash{} +\LMHash{}% Functions can be introduced by function declarations (\ref{functionDeclarations}), method declarations (\ref{instanceMethods}, \ref{staticMethods}), getter declarations (\ref{getters}), @@ -999,7 +1030,7 @@ setter declarations (\ref{setters}), and constructor declarations (\ref{constructors}); and they can be introduced by function literals (\ref{functionExpressions}). -\LMHash{} +\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. @@ -1034,20 +1065,22 @@ OR \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. +\LMHash{}% +A function is \IndexCustom{asynchronous}{function!asynchronous} +if its body is marked with the \ASYNC{} or \code{\ASYNC*} modifier. +Otherwise the function is \IndexCustom{synchronous}{function!synchronous}. +A function is a \IndexCustom{generator}{function!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. +by lazily applying a function that \emph{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{} +\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{ @@ -1066,7 +1099,7 @@ No other scenario makes sense because the object returned by the factory would b 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{} +\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$. @@ -1075,60 +1108,69 @@ It is a compile-time error if the declared return type of a function marked \cod \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 +\LMHash{}% +A \Index{function declaration} is a function that is neither a member of a class nor a function literal. +Function declarations include exactly the following: +\IndexCustom{library functions}{function!library}, +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. +at the top level of a library, and +\IndexCustom{local functions}{function!local}, +which are function declarations declared inside other functions. Library functions are often referred to simply as top-level functions. -\LMHash{} +\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{} +\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{} +\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. +\LMHash{}% +When we say that a function $f_1$ \Index{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}, +\LMHash{}% +Every non-getter function declaration includes a \Index{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{}% +Some function declarations include a +\Index{formal type parameter list} (\ref{functions}), +in which case we say that it is a +\IndexCustom{generic function}{function!generic}. +A \IndexCustom{non-generic function}{function!non-generic} +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. +\LMHash{}% +The \Index{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}. +\LMHash{}% +The formal type parameter list of a function declaration introduces +a new scope known as the function's +\IndexCustom{type parameter scope}{scope!type parameter}. 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{} +\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$. @@ -1143,8 +1185,9 @@ and the formal type parameters are in scope for each other, allowing dependencie \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}. +\LMHash{}% +The formal parameter list of a function declaration introduces a new scope known as the function's +\IndexCustom{formal parameter scope}{scope!formal parameter}. 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. @@ -1156,8 +1199,9 @@ the return type and parameter type annotations can use the formal type parameter 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}. +\LMHash{}% +The body of a function declaration introduces a new scope known as the function's +\IndexCustom{body scope}{scope!function body}. 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. @@ -1165,7 +1209,7 @@ The body scope of a function $f$ is enclosed in the scope introduced by the form % 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{} +\LMHash{}% It is a compile-time error if a formal parameter is declared as a constant variable (\ref{variables}). \begin{grammar} @@ -1174,14 +1218,17 @@ It is a compile-time error if a formal parameter is declared as a constant varia \alt `(' `,' `)' \alt `(' `)' - ::= (`,' )* + ::= \gnewline{} + (`,' )* ::= \alt - ::= `[' (`,' )* `,'? `]' + ::= \gnewline{} + `[' (`,' )* `,'? `]' - ::= `{' (`,' )* `,'? `}' + ::= \gnewline{} + `{' (`,' )* `,'? `}' \end{grammar} Formal parameter lists allow an optional trailing comma after the last parameter (\syntax{`,'?}). @@ -1192,8 +1239,8 @@ All parameter lists in this specification are shown without a trailing comma, bu \subsubsection{Required Formals} \LMLabel{requiredFormals} -\LMHash{} -A {\em required formal parameter} may be specified in one of three ways: +\LMHash{}% +A \Index{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? @@ -1206,16 +1253,18 @@ It is a compile-time error if any default values are specified in the signature \alt \alt - ::= \COVARIANT{}? ? - \gnewline{} + ::= \gnewline{} + \COVARIANT{}? ? - ::= \COVARIANT{}? ? + ::= \gnewline{} + \COVARIANT{}? ? - ::= ? \THIS{} `.' - \gnewline{} ? + ::= \gnewline{} + ? \THIS{} `.' \gnewline{} + ? \end{grammar} -\LMHash{} +\LMHash{}% It is possible to include the modifier \COVARIANT{} in some forms of parameter declarations. This modifier has no effect. @@ -1224,14 +1273,14 @@ 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{} +\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{} +\LMHash{}% Optional parameters may be specified and provided with default values. \begin{grammar} @@ -1241,18 +1290,17 @@ Optional parameters may be specified and provided with default values. \alt ( `:' )? \end{grammar} -A \syntax{} of the form -\syntax{ `:' } -is equivalent to one of the form: +The form \syntax{ `:' } +is equivalent to 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{} +\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{} +\LMHash{}% It is a compile-time error if the name of a named optional parameter begins with an `_' character. \rationale{ @@ -1266,12 +1314,12 @@ The static checker would of course flag such situations, but the consequence wou \subsection{Type of a Function} \LMLabel{typeOfAFunction} -\LMHash{} +\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{} +\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, @@ -1283,11 +1331,11 @@ However, we do not wish to distinguish two function types if they have the same This treatment of names is also known as alpha-equivalence. } -\LMHash{} +\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{} +\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$, @@ -1296,7 +1344,7 @@ 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{} +\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$, @@ -1306,7 +1354,7 @@ 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{} +\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$, @@ -1316,7 +1364,7 @@ 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{} +\LMHash{}% The run-time type of a function object always implements the class \FUNCTION{}. \commentary{ @@ -1335,8 +1383,9 @@ The variations are manifold, and so this specification only guarantees that func \subsection{External Functions} \LMLabel{externalFunctions} -\LMHash{} -An {\em external function} is a function whose body is provided separately from its declaration. +\LMHash{}% +An \IndexCustom{external function}{function!external} +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. @@ -1346,22 +1395,24 @@ External functions allow us to introduce type information for code that is not s \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. +However, an abstract method is different from an external function, +as it has \emph{no} body. } -\LMHash{} +\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{} +\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}. +\LMHash{}% +A \Index{class} defines the form and behavior of a set of objects which are its +\IndexCustom{instances}{instance}. Classes may be defined by class declarations as described below, or via mixin applications (\ref{mixinApplication}). \begin{grammar} @@ -1397,12 +1448,13 @@ Classes may be defined by class declarations as described below, or via mixin ap \alt \FINAL{} ? \alt (\STATIC{} | \COVARIANT{})? (\VAR{} | ) - ::= (`,' )* + ::= \gnewline{} + (`,' )* ::= `=' \end{grammar} -\LMHash{} +\LMHash{}% It is possible to include the modifier \COVARIANT{} in some forms of declarations. This modifier has no effect. @@ -1411,36 +1463,47 @@ 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{} +\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. +The \IndexCustom{instance members}{members!instance} of a class +are its instance methods, getters, setters and instance variables. +The \IndexCustom{static members}{members!static} of a class +are its static methods, getters, setters and class variables. +The \IndexCustom{members}{members} of a class +are its static and instance members. -\LMHash{} +\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}). +\item A \IndexCustom{type-parameter scope}{scope!type parameter}, + 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}. +\item A \IndexCustom{static scope}{scope!static}. 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}. +\item An \IndexCustom{instance scope}{scope!instance}. The enclosing scope of a class' instance scope is the class' static scope. \end{itemize} -\LMHash{} +\LMHash{}% The enclosing scope of an instance member declaration is the instance scope of the class in which it is declared. -\LMHash{} +\LMHash{}% The enclosing scope of a static member declaration is the static scope of the class in which it is declared. -\LMHash{} +\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. +\LMHash{}% +An \IndexCustom{abstract class declaration}{class declaration!abstract} +is a class declaration that is explicitly declared +with the \ABSTRACT{} modifier. +A \IndexCustom{concrete class declaration}{class declaration!concrete} +is a class declaration that is not abstract. +An \IndexCustom{abstract class}{class!abstract} is a class +whose declaration is abstract, and +a \IndexCustom{concrete class}{class!concrete} is a class +whose declaration is concrete. \rationale{ We want different behavior for concrete classes and abstract classes. @@ -1448,8 +1511,8 @@ If $A$ is intended to be abstract, we want the static checker to warn about any 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}). +\LMHash{}% +The \Index{interface of a 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. @@ -1466,7 +1529,9 @@ or because it declares a static member and an instance member with the same name \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. +For example, \code{B} \IndexCustom{declares}{declares member} + one member named \code{f}, +but \IndexCustom{has}{has member} two such members. The rules of inheritance determine what members a class has. } @@ -1487,7 +1552,7 @@ The rules of inheritance determine what members a class has. \} \end{dartCode} -\LMHash{} +\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$, @@ -1500,19 +1565,23 @@ and if $G$ has a constructor named \code{$G$.$X$}. \subsection{Instance Methods} \LMLabel{instanceMethods} -\LMHash{} +\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{} +\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{} +\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 warning 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$. +It is a static warning 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 @@ -1523,11 +1592,12 @@ A method declaration may conflict with other declarations \subsubsection{Operators} \LMLabel{operators} -\LMHash{} -{\em Operators} are instance methods with special names. +\LMHash{}% +\IndexCustom{Operators}{operators} are instance methods with special names. \begin{grammar} - ::= ? \OPERATOR{} + ::= \gnewline{} + ? \OPERATOR{} ::= `~' \alt @@ -1542,10 +1612,10 @@ A method declaration may conflict with other declarations \alt \end{grammar} -\LMHash{} +\LMHash{}% An operator declaration is identified using the built-in identifier (\ref{identifierReference}) \OPERATOR{}. -\LMHash{} +\LMHash{}% The following names are allowed for user-defined operators: \syntax{`<'}, \syntax{`>'}, @@ -1568,7 +1638,7 @@ The following names are allowed for user-defined operators: \syntax{`[]'}, \syntax{`~'}. -\LMHash{} +\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: @@ -1602,23 +1672,23 @@ If the operator has no arguments, it denotes unary minus. If it has an argument, it denotes binary subtraction. } -\LMHash{} +\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{} +\LMHash{}% It is a compile-time error if the arity of the user-declared operator \syntax{`~'} is not 0. -\LMHash{} +\LMHash{}% It is a compile-time error to declare an optional parameter in an operator. -\LMHash{} -It is a compile-time warning if the return type of a user-declared operator +\LMHash{}% +It is a static warning if the return type of a user-declared operator \syntax{`[]='} is explicitly declared and not \VOID{}. @@ -1647,7 +1717,7 @@ The rationale for this behavior is that assignments should be guaranteed to eval \subsubsection{The Method \code{noSuchMethod}} \LMLabel{theMethodNoSuchMethod} -\LMHash{} +\LMHash{}% The method \code{noSuchMethod} is invoked implicitly during execution in situations where one or more member lookups fail (\ref{ordinaryInvocation}, @@ -1678,8 +1748,8 @@ 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}} +\LMHash{}% +We say that a class $C$ \Index{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}. @@ -1718,10 +1788,10 @@ where only the null object is accepted: \} \end{dartCode} -\LMHash{} +\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 +The member $m$ is \Index{noSuchMethod forwarded} in $C$ if{}f one of the following is true: \begin{itemize} @@ -1741,10 +1811,11 @@ one of the following is true: a concrete declaration of $m$ accessible to $L_2$. \end{itemize} -\LMHash{} -For a concrete class $C$, a {\em \code{noSuchMethod} forwarder} +\LMHash{}% +For a concrete class $C$, a +\IndexCustom{\code{noSuchMethod} forwarder}{noSuchMethod forwarder} is implicitly induced for each member $m$ -which is \code{noSuchMethod} forwarded. +which is 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. @@ -1793,7 +1864,7 @@ but the language can still specify that they are induced implicitly, because compilers control the treatment of private names. } -\LMHash{} +\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$, @@ -1847,7 +1918,7 @@ another \code{noSuchMethod} forwarder, and hence there is no error in that situation. } -\LMHash{} +\LMHash{}% For the dynamic semantics, assume that a class $C$ has an implicitly induced \code{noSuchMethod} forwarder named $m$, @@ -1867,7 +1938,7 @@ a signature that has named parameters, because the former is covered by $m = 0$. } -\LMHash{} +\LMHash{}% The execution of the body of $m$ creates an instance $im$ of the predefined class \code{Invocation} such that: @@ -1889,7 +1960,7 @@ such that: \code{[$X_1, \ldots,\ X_r$]}. \end{itemize} -\LMHash{} +\LMHash{}% Next, \code{noSuchMethod} is invoked with $i$ as the actual argument, and the result obtained from there is returned by the execution of $m$. @@ -1939,23 +2010,23 @@ because this is an invocation of a function object \subsection{Getters} \LMLabel{getters} -\LMHash{} +\LMHash{}% Getters are functions (\ref{functions}) that are used to retrieve the values of object properties. \begin{grammar} ::= ? \GET{} \end{grammar} -\LMHash{} +\LMHash{}% If no return type is specified, the return type of the getter is \DYNAMIC{}. -\LMHash{} +\LMHash{}% A getter definition that is prefixed with the \STATIC{} modifier defines a static getter. Otherwise, it defines an instance getter. The name of the getter is given by the identifier in the definition. The effect of a static getter declaration in class $C$ is to add an instance getter with the same name and signature to the \code{Type} object for class $C$ that forwards (\ref{functionDeclarations}) to the static getter. -\LMHash{} +\LMHash{}% The instance getters of a class $C$ are those instance getters declared by $C$, either implicitly or explicitly, and the instance getters inherited by $C$ from its superclass. The static getters of a class $C$ are those static getters declared by $C$. @@ -1966,7 +2037,7 @@ In particular, a getter can never override a method, and a method can never override a getter or an instance variable. } -\LMHash{} +\LMHash{}% It is a compile-time error if a getter $m_1$ overrides (\ref{inheritanceAndOverriding}) a getter $m_2$ and the return type of $m_1$ is not a subtype of the return type of $m_2$. @@ -1974,7 +2045,7 @@ and the return type of $m_1$ is not a subtype of the return type of $m_2$. \subsection{Setters} \LMLabel{setters} -\LMHash{} +\LMHash{}% Setters are functions (\ref{functions}) that are used to set the values of object properties. \begin{grammar} @@ -1985,7 +2056,7 @@ Setters are functions (\ref{functions}) that are used to set the values of objec If no return type is specified, the return type of the setter is \VOID{} (\ref{typeOfAFunction}). } -\LMHash{} +\LMHash{}% A setter definition that is prefixed with the \STATIC{} modifier defines a static setter. Otherwise, it defines an instance setter. The name of a setter is obtained by appending the string `=' to the identifier given in its signature. @@ -1995,21 +2066,21 @@ The effect of a static setter declaration in class $C$ is to add an instance set Hence, a setter name can never conflict with, override or be overridden by a getter or method. } -\LMHash{} +\LMHash{}% The instance setters of a class $C$ are those instance setters declared by $C$ either implicitly or explicitly, and the instance setters inherited by $C$ from its superclass. The static setters of a class $C$ are those static setters declared by $C$. -\LMHash{} +\LMHash{}% It is a compile-time error if a setter's formal parameter list does not consist of exactly one required formal parameter $p$. \rationale{ We could enforce this via the grammar, but we'd have to specify the evaluation rules in that case. } -\LMHash{} -It is a compile-time warning if a setter declares a return type other than \VOID{}. +\LMHash{}% +It is a static warning if a setter declares a return type other than \VOID{}. It is a compile-time error if a setter $m_1$ overrides (\ref{inheritanceAndOverriding}) a setter $m_2$ and the parameter type of $m_1$ is not a supertype of the parameter type of $m_2$. -It is a compile-time warning if a class has +It is a static warning if a class has a setter named $v=$ with argument type $T$ and a getter named $v$ with return type $S$, and $S$ may not be assigned to $T$. @@ -2023,9 +2094,17 @@ A setter declaration may conflict with other declarations \subsection{Abstract Instance Members} \LMLabel{abstractInstanceMembers} -\LMHash{} -An {\em abstract method} (respectively, {\em abstract getter} or {\em abstract setter)} is an instance method, getter or setter that is not declared \EXTERNAL{} and does not provide an implementation. -A {\em concrete method} (respectively, {\em concrete getter} or {\em concrete setter)} is an instance method, getter or setter that is not abstract. +\LMHash{}% +An \IndexCustom{abstract method}{method!abstract} +(respectively, +\IndexCustom{abstract getter}{getter!abstract} or +\IndexCustom{abstract setter}{setter!abstract}) +is an instance method, getter or setter that is not declared \EXTERNAL{} and does not provide an implementation. +A \IndexCustom{concrete method}{method!concrete} +(respectively, +\IndexCustom{concrete getter}{getter!concrete} or +\IndexCustom{concrete setter}{setter!concrete}) +is an instance method, getter or setter that is not abstract. \rationale{ Earlier versions of Dart required that abstract members be identified by prefixing them with the modifier \ABSTRACT{}. @@ -2055,7 +2134,7 @@ The purpose of an abstract method is to provide a declaration for purposes such In classes used as mixins, it is often useful to introduce such declarations for methods that the mixin expects will be provided by the superclass the mixin is applied to. } -\LMHash{} +\LMHash{}% %% TODO(eernst): This is semi-redundant: We should define what it means for %% a class to be 'fully implemented' and require once and for all that it is %% a compile-time error if a concrete class is not fully implemented. That @@ -2094,11 +2173,11 @@ Therefore no error should be raised if a corresponding concrete member exists in \subsection{Instance Variables} \LMLabel{instanceVariables} -\LMHash{} +\LMHash{}% Instance variables are variables whose declarations are immediately contained within a class declaration and that are not declared \STATIC{}. The instance variables of a class $C$ are those instance variables declared by $C$ and the instance variables inherited by $C$ from its superclass. -\LMHash{} +\LMHash{}% It is a compile-time error if an instance variable is declared to be constant. \rationale{ @@ -2117,16 +2196,16 @@ An instance getter for it can always be defined manually if desired. \subsection{Constructors} \LMLabel{constructors} -\LMHash{} -A {\em constructor} is a special function that is used in instance creation expressions (\ref{instanceCreation}) to obtain objects, typically by creating or initializing them. +\LMHash{}% +A \Index{constructor} is a special function that is used in instance creation expressions (\ref{instanceCreation}) to obtain objects, typically by creating or initializing them. Constructors may be generative (\ref{generativeConstructors}) or they may be factories (\ref{factories}). -\LMHash{} -A {\em constructor name} always begins with the name of its immediately enclosing class, and may optionally be followed by a dot and an identifier \id. +\LMHash{}% +A \Index{constructor name} always begins with the name of its immediately enclosing class, and may optionally be followed by a dot and an identifier \id. It is a compile-time error if the name of a constructor is not a constructor name. -\LMHash{} -The {\em function type of a constructor} $k$ is the function type whose +\LMHash{}% +The \Index{function type of a constructor} $k$ is the function type whose return type is the class that contains the declaration of $k$, and whose formal parameter types, optionality, and names of named parameters correspond to the declaration of $k$. @@ -2151,35 +2230,44 @@ A constructor declaration may conflict with static member declarations % The enclosing scope of a generative constructor is the instance scope of the class in which it is declared (but what about redirecting?) -\LMHash{} +\LMHash{}% If{}f no constructor is specified for a class $C$, it implicitly has a default constructor \code{C() : \SUPER{}() \{\}}, unless $C$ is class \code{Object}. \subsubsection{Generative Constructors} \LMLabel{generativeConstructors} -\LMHash{} -A {\em generative constructor} consists of a constructor name, a constructor parameter list, and either a redirect clause or an initializer list and an optional body. +\LMHash{}% +A \IndexCustom{generative constructor}{constructor!generative} +declaration consists of a constructor name, a constructor parameter list, +and either a redirect clause or an initializer list and an optional body. \begin{grammar} - ::= (`.' )? + ::= \gnewline{} + (`.' )? \end{grammar} -\LMHash{} -A {\em constructor parameter list} is a parenthesized, comma-separated list of formal constructor parameters. -A {\em formal constructor parameter} is either a formal parameter (\ref{formalParameters}) or an initializing formal. -An {\em initializing formal} has the form \code{\THIS{}.\id}, where \id{} is the name of an instance variable of the immediately enclosing class. +\LMHash{}% +A \Index{constructor parameter list} is a parenthesized, comma-separated list of formal constructor parameters. +A \Index{formal constructor parameter} is either a formal parameter (\ref{formalParameters}) or an initializing formal. +An \Index{initializing formal} has the form \code{\THIS{}.\id}, where \id{} is the name of an instance variable of the immediately enclosing class. It is a compile-time error if \id{} is not an instance variable of the immediately enclosing class. It is a compile-time error if an initializing formal is used by a function other than a non-redirecting generative constructor. -\LMHash{} +\LMHash{}% If an explicit type is attached to the initializing formal, that is its static type. Otherwise, the type of an initializing formal named \id{} is $T_{id}$, where $T_{id}$ is the type of the instance variable named \id{} in the immediately enclosing class. It is a compile-time error if the static type of \id{} is not a subtype of $T_{id}$. -\LMHash{} -Initializing formals constitute an exception to the rule that every formal parameter introduces a local variable into the formal parameter scope (\ref{formalParameters}). -When the formal parameter list of a non-redirecting generative constructor contains any initializing formals, a new scope is introduced, the {\em formal parameter initializer scope}, which is the current scope of the initializer list of the constructor, and which is enclosed in the scope where the constructor is declared. +\LMHash{}% +Initializing formals constitute an exception to the rule that +every formal parameter introduces a local variable into +the formal parameter scope (\ref{formalParameters}). +When the formal parameter list of a non-redirecting generative constructor +contains any initializing formals, a new scope is introduced, the +\IndexCustom{formal parameter initializer scope}{scope!formal parameter initializer}, +which is the current scope of the initializer list of the constructor, +and which is enclosed in the scope where the constructor is declared. Each initializing formal in the formal parameter list introduces a final local variable into the formal parameter initializer scope, but not into the formal parameter scope; every other formal parameter introduces a local variable into both the formal parameter scope and the formal parameter initializer scope. \commentary{ @@ -2188,7 +2276,7 @@ When a formal parameter introduces a local variable into two scopes, it is still The type of the constructor is defined in terms of its formal parameters, including the initializing formals. } -\LMHash{} +\LMHash{}% Initializing formals are executed during the execution of generative constructors detailed below. Executing an initializing formal \code{\THIS{}.\id} causes the instance variable \id{} of the immediately surrounding class to be assigned the value of the corresponding actual parameter, unless \id{} is a final variable that has already been initialized, in which case a run-time error occurs. @@ -2215,8 +2303,8 @@ class A \{ \} \end{dartCode} -\LMHash{} -A {\em fresh instance} is an instance whose identity is distinct from any previously allocated instance of its class. +\LMHash{}% +A \Index{fresh instance} is an instance whose identity is distinct from any previously allocated instance of its class. A generative constructor always operates on a fresh instance of its immediately enclosing class. \commentary{ @@ -2225,15 +2313,17 @@ If a constructor $c$ is referenced by \CONST{}, $c$ may not be run; instead, a c See the section on instance creation (\ref{instanceCreation}). } -\LMHash{} +\LMHash{}% If a generative constructor $c$ is not a redirecting constructor and no body is provided, then $c$ implicitly has an empty body \code{\{\}}. \paragraph{Redirecting Generative Constructors} \LMLabel{redirectingGenerativeConstructors} -\LMHash{} -A generative constructor may be {\em redirecting}, in which case its only action is to invoke another generative constructor. +\LMHash{}% +A generative constructor may be +\IndexCustom{redirecting}{constructor!redirecting}, +in which case its only action is to invoke another generative constructor. A redirecting constructor has no body; instead, it has a redirect clause that specifies which constructor the invocation is redirected to, and with which arguments. @@ -2243,7 +2333,7 @@ instead, it has a redirect clause that specifies which constructor the invocatio \def\ConstMetavar{\mbox{\CONST{}?}} -\LMHash{} +\LMHash{}% Assume that \code{$C$<$X_1\ \EXTENDS\ B_1 \ldots,\ X_m\ \EXTENDS\ B_m$>} is the name and formal type parameters of the enclosing class, @@ -2263,8 +2353,10 @@ where $R$ is of one of the forms \code{$\THIS{}.\id$($e_1 \ldots,\ e_p,\ x_1$: $e_{p+1}, \ldots,\ x_q$: $e_{p+q}$)} -\LMHash{} -The {\em redirectee constructor} for this declaration is then the constructor denoted by +\LMHash{}% +The +\IndexCustom{redirectee constructor}{constructor!redirectee} +for this declaration is then the constructor denoted by \code{$C$<$X_1 \ldots,\ X_m$>} respectively \code{$C$<$X_1 \ldots,\ X_m$>.\id}. It is a compile-time error if the static argument list type (\ref{actualArgumentLists}) of \code{($e_1 \ldots,\ e_p,\ x_1$: $e_{p+1}, \ldots,\ x_q$: $e_{p+q}$)} @@ -2287,14 +2379,14 @@ if $e_j$ were subject to more strict constraints than the ones applied to actual arguments to function invocations in general. } -\LMHash{} +\LMHash{}% When $\ConstMetavar$ is \CONST{}, it is a compile-time error if the redirectee is not a constant constructor. Moreover, when $\ConstMetavar$ is \CONST{}, each $e_i,\ i \in 1 .. p+q$, must be a potentially constant expression (\ref{constantConstructors}). -\LMHash{} +\LMHash{}% It is a dynamic type error if an actual argument passed in an invocation of a redirecting generative constructor $k$ is not a subtype of the actual type (\ref{actualTypeOfADeclaration}) of the corresponding formal parameter in the declaration of $k$. @@ -2307,15 +2399,19 @@ of the corresponding formal parameter in the declaration of the redirectee. \paragraph{Initializer Lists} \LMLabel{initializerLists} -\LMHash{} -An initializer list begins with a colon, and consists of a comma-separated list of individual {\em initializers}. +\LMHash{}% +An initializer list begins with a colon, and consists of a comma-separated list of individual \Index{initializers}. \commentary{ There are three kinds of initializers. \begin{itemize} -\item[$\bullet$] A {\em superinitializer} identifies a {\em superconstructor}\,---\,that is, a specific constructor of the superclass. -Execution of the superinitializer causes the initializer list of the superconstructor to be executed. -\item[$\bullet$] An {\em instance variable initializer} assigns a value to an individual instance variable. +\item[$\bullet$] A \emph{superinitializer} identifies a + \emph{superconstructor}\,---\,that is, + a specific constructor of the superclass. + Execution of the superinitializer causes + the initializer list of the superconstructor to be executed. +\item[$\bullet$] An \emph{instance variable initializer} + assigns a value to an individual instance variable. \item[$\bullet$] An assertion. \end{itemize} } @@ -2328,19 +2424,20 @@ Execution of the superinitializer causes the initializer list of the superconstr \alt \alt - ::= (\THIS{} `.')? `=' * + ::= \gnewline{} + (\THIS{} `.')? `=' * \end{grammar} -\LMHash{} +\LMHash{}% An initializer of the form \code{$v$ = $e$} is equivalent to an initializer of the form \code{\THIS{}.$v$ = $e$}, -both forms are called {\em instance variable initializers}. +both forms are called \Index{instance variable initializers}. It is a compile-time error if the enclosing class does not declare an instance variable named $v$. Otherwise, let $T$ be the static type of $v$. It is a compile-time error unless the static type of $e$ is assignable to $T$. -\LMHash{} -Consider a {\em superinitializer} $s$ of the form +\LMHash{}% +Consider a \Index{superinitializer} $s$ of the form \code{\SUPER{}($a_1, \ldots,\ a_n,\ x_{n+1}: a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} respectively @@ -2361,7 +2458,7 @@ and substituting the formal type variables of the superclass for the corresponding actual type arguments passed to the superclass in the header of the current class. -\LMHash{} +\LMHash{}% Let $k$ be a generative constructor. Then $k$ may include at most one superinitializer in its initializer list or a compile-time error occurs. If no superinitializer is provided, an implicit superinitializer of the form \SUPER{}() is added at the end of $k$'s initializer list, @@ -2372,7 +2469,7 @@ It is a compile-time error if $k$'s initializer list contains an initializer for It is a compile-time error if $k$'s initializer list contains an initializer for a final variable $f$ whose declaration includes an initialization expression. It is a compile-time error if $k$ includes an initializing formal for a final variable $f$ whose declaration includes an initialization expression. -\LMHash{} +\LMHash{}% Let $f$ be a final instance variable declared in the immediately enclosing class. A compile-time error occurs unless $f$ is initialized @@ -2383,21 +2480,21 @@ by one of the following means: \item $f$ has an initializer in $k$'s initializer list. \end{itemize} -\LMHash{} +\LMHash{}% It is a compile-time error if $k$'s initializer list contains an initializer for a variable that is not an instance variable declared in the immediately surrounding class. \commentary{ The initializer list may of course contain an initializer for any instance variable declared by the immediately surrounding class, even if it is not final. } -\LMHash{} +\LMHash{}% It is a compile-time error if a generative constructor of class \code{Object} includes a superinitializer. \paragraph{Execution of Generative Constructors} \LMLabel{executionOfGenerativeConstructors} -\LMHash{} +\LMHash{}% Execution of a generative constructor $k$ of type $T$ to initialize a fresh instance $i$ is always done with respect to a set of bindings for its formal parameters and the type parameters of the immediately enclosing class bound to @@ -2408,7 +2505,7 @@ These bindings are usually determined by the instance creation expression that i However, they may also be determined by a reflective call. } -\LMHash{} +\LMHash{}% If $k$ is redirecting then its redirect clause has the form \code{\THIS{}.$g$($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} @@ -2421,24 +2518,24 @@ to an actual argument list $a$ of the form in an environment where the type parameters of the enclosing class are bound to $t_1, \ldots, t_m$. -\LMHash{} +\LMHash{}% Next, the body of $g$ is executed to initialize $i$ with respect to the bindings that map the formal parameters of $g$ to the corresponding objects in the actual argument list $a$, with \THIS{} bound to $i$, and the type parameters of the immediately enclosing class bound to $t_1, \ldots, t_m$. -\LMHash{} +\LMHash{}% Otherwise, $k$ is not redirecting. Execution then proceeds as follows: -\LMHash{} +\LMHash{}% The instance variable declarations of the immediately enclosing class are visited in the order they appear in the program text. For each such declaration $d$, if $d$ has the form \code{\syntax{finalConstVarOrType} $v$ = $e$; } then $e$ is evaluated to an object $o$ and the instance variable $v$ of $i$ is bound to $o$. -\LMHash{} +\LMHash{}% Any initializing formals declared in $k$'s parameter list are executed in the order they appear in the program text. % In fact, this order is unobservable; this could be done any time prior to running the body, since % these only effect \THIS{}. @@ -2451,17 +2548,17 @@ We could observe the order by side effecting external routines called. So we need to specify the order. } -\LMHash{} +\LMHash{}% Then if any instance variable of $i$ declared by the immediately enclosing class is not yet bound to a value, all such variables are initialized with the null object (\ref{null}). -\LMHash{} +\LMHash{}% Then, unless the enclosing class is \code{Object}, the explicitly specified or implicitly added superinitializer (\ref{initializerLists}) is executed to further initialize $i$. -\LMHash{} +\LMHash{}% After the superinitializer has completed, the body of $k$ is executed in a scope where \THIS{} is bound to $i$. \rationale{ @@ -2475,12 +2572,12 @@ nor can \THIS{} be passed into any other code being invoked in the initializer. \paragraph{Execution of Initializer Lists} \LMLabel{executionOfInitializerLists} -\LMHash{} +\LMHash{}% During the execution of a generative constructor to initialize an instance $i$, execution of an initializer of the form \code{\THIS{}.$v$ = $e$} proceeds as follows: -\LMHash{} +\LMHash{}% First, the expression $e$ is evaluated to an object $o$. Then, the instance variable $v$ of $i$ is bound to $o$. It is a dynamic type error if $o$ is not the null object @@ -2489,10 +2586,10 @@ and the dynamic type of $o$ is not a subtype of the actual type (\ref{actualTypeOfADeclaration}) of the instance variable $v$. -\LMHash{} +\LMHash{}% Execution of an initializer that is an assertion proceeds by executing the assertion (\ref{assert}). -\LMHash{} +\LMHash{}% Consider a superinitializer $s$ of the form \code{\SUPER{}($a_1, \ldots,\ a_n,\ x_{n+1}: a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} @@ -2500,7 +2597,7 @@ respectively \code{\SUPER{}.\id($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)}. -\LMHash{} +\LMHash{}% Let $C$ be the class in which $s$ appears and let $S$ be the superclass of $C$. If $S$ is generic (\ref{generics}), let $u_1, \ldots, u_p$ be the actual type arguments passed to $S$, @@ -2512,7 +2609,7 @@ are the actual bindings of the type variables of $C$. Let $k$ be the constructor declared in $S$ and named $S$ respectively \code{$S$.\id}. -\LMHash{} +\LMHash{}% Execution of $s$ proceeds as follows: The argument list \code{($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} @@ -2527,23 +2624,27 @@ and the formal type parameters of $S$ are bound to $u_1, \ldots, u_p$. \subsubsection{Factories} \LMLabel{factories} -\LMHash{} -A {\em factory} is a constructor prefaced by the built-in identifier (\ref{identifierReference}) \FACTORY{}. +\LMHash{}% +A \IndexCustom{factory}{constructor!factory} +is a constructor prefaced by the built-in identifier +(\ref{identifierReference}) +\FACTORY{}. \begin{grammar} - ::= \FACTORY{} (`.' )? + ::= \gnewline{} + \FACTORY{} (`.' )? \end{grammar} %The enclosing scope of a factory constructor is the static scope \ref{} of the class in which it is declared. -\LMHash{} -The {\em return type} of a factory whose signature is of the form \FACTORY{} $M$ or the form \FACTORY{} \code{$M$.\id} is $M$ if $M$ is not a generic type; +\LMHash{}% +The return type of a factory whose signature is of the form \FACTORY{} $M$ or the form \FACTORY{} \code{$M$.\id} is $M$ if $M$ is not a generic type; otherwise the return type is \code{$M$<$T_1, \ldots,\ T_n$>} where $T_1, \ldots, T_n$ are the type parameters of the enclosing class. -\LMHash{} +\LMHash{}% It is a compile-time error if $M$ is not the name of the immediately enclosing class. -\LMHash{} +\LMHash{}% It is a dynamic type error if a factory returns a non-null object whose type is not a subtype of its actual (\ref{actualTypeOfADeclaration}) @@ -2564,12 +2665,15 @@ Likewise, factories can return instances of different classes. \paragraph{Redirecting Factory Constructors} \LMLabel{redirectingFactoryConstructors} -\LMHash{} -A {\em redirecting factory constructor} specifies a call to a constructor of another class that is to be used whenever the redirecting constructor is called. +\LMHash{}% +A \IndexCustom{redirecting factory constructor}{constructor!redirecting factory} +specifies a call to a constructor of another class that is to be used +whenever the redirecting constructor is called. \begin{grammar} - ::= \CONST{}? \FACTORY{} (`.' )? - \gnewline{} `=' (`.' )? + ::= \gnewline{} + \CONST{}? \FACTORY{} (`.' )? `=' + \gnewline{} (`.' )? \end{grammar} Assume that @@ -2593,7 +2697,7 @@ where $R$ is of one of the forms \code{$T$<$S_1 \ldots,\ S_p$>} or \code{$T$<$S_1 \ldots,\ S_p$>.\id}. -\LMHash{} +\LMHash{}% It is a compile-time error if $T$ does not denote a class accessible in the current scope. If $T$ does denote such a class $D$, @@ -2603,11 +2707,12 @@ it is a compile-time error if $R$ does not denote a constructor. % redirections: Otherwise, it is a compile-time error if $R$ denotes a generative constructor and $D$ is abstract. -Otherwise, the {\em redirectee constructor} for this declaration is -the constructor denoted by $R$. +Otherwise, the +\IndexCustom{redirectee constructor}{constructor!redirectee} +for this declaration is the constructor denoted by $R$. -\LMHash{} -A redirecting factory constructor $q'$ is {\em redirection-reachable} +\LMHash{}% +A redirecting factory constructor $q'$ is \Index{redirection-reachable} from a redirecting factory constructor $q$ if{}f $q'$ is the redirectee constructor of $q$, or $q''$ is the redirectee constructor of $q$ @@ -2615,7 +2720,7 @@ and $q'$ is redirection-reachable from $q''$. It is a compile-time error if a redirecting factory constructor is redirection-reachable from itself. -\LMHash{} +\LMHash{}% Let $\argumentList{T}$ be the static argument list type (\ref{actualArgumentLists}) \code{($T_1 \ldots,\ T_{n+k}$)} when $k$ takes no named arguments, and @@ -2641,15 +2746,16 @@ in which case the formal type parameter list of the class $C$ and/or the actual type argument list of the redirectee constructor is omitted (\ref{generics}). } -\LMHash{} +\LMHash{}% It is a compile-time error if $k$ explicitly specifies a default value for an optional parameter. \commentary{ -Default values specified in $k$ would be ignored, since it is the {\em actual} parameters that are passed to $k'$. +Default values specified in $k$ would be ignored, +since it is the \emph{actual} parameters that are passed to $k'$. Hence, default values are disallowed. } -\LMHash{} +\LMHash{}% It is a compile-time error if a formal parameter of $k'$ has a default value whose type is not a subtype of the type annotation on the corresponding formal parameter in $k$. @@ -2667,10 +2773,10 @@ However, redirecting factories have several advantages: \end{itemize} } -\LMHash{} +\LMHash{}% It is a compile-time error if $k$ is prefixed with the \CONST{} modifier but $k'$ is not a constant constructor (\ref{constantConstructors}). -\LMHash{} +\LMHash{}% Let $T_1, \ldots, T_m$ be the actual type arguments passed to $k'$ in the declaration of $k$. Let $X_1, \ldots, X_m$ be the formal type arguments declared by @@ -2686,22 +2792,22 @@ In general, this implies that the resulting object conforms to the interface of the immediately enclosing class of $k$. } -\LMHash{} +\LMHash{}% For the dynamic semantics, assume that $k$ is a redirecting factory constructor and $k'$ is the redirectee of $k$. -\LMHash{} +\LMHash{}% It is a dynamic type error if an actual argument passed in an invocation of $k$ is not a subtype of the actual type (\ref{actualTypeOfADeclaration}) of the corresponding formal parameter in the declaration of $k$. -\LMHash{} +\LMHash{}% When the redirectee $k'$ is a factory constructor, execution of $k$ amounts to execution of $k'$ with the actual arguments passed to $k$. The result of the execution of $k'$ is the result of $k$. -\LMHash{} +\LMHash{}% When the redirectee $k'$ is a generative constructor, let $o$ be a fresh instance (\ref{generativeConstructors}) of the class that contains $k'$. @@ -2714,8 +2820,9 @@ otherwise $k'$ completes by throwing the exception and stack trace thrown by $k$ \subsubsection{Constant Constructors} \LMLabel{constantConstructors} -\LMHash{} -A {\em constant constructor} may be used to create compile-time constant (\ref{constants}) objects. +\LMHash{}% +A \IndexCustom{constant constructor}{constructor!constant} +may be used to create compile-time constant (\ref{constants}) objects. A constant constructor is prefixed by the reserved word \CONST{}. \begin{grammar} @@ -2728,28 +2835,28 @@ A constant constructor is prefixed by the reserved word \CONST{}. All the work of a constant constructor must be handled via its initializers. } -\LMHash{} +\LMHash{}% It is a compile-time error if a constant constructor is declared by a class that has a mutable instance variable. \commentary{ The above refers to both locally declared and inherited instance variables. } -\LMHash{} +\LMHash{}% It is a compile-time error if a constant constructor is declared by a class $C$ if any instance variable declared in $C$ is initialized with an expression that is not a constant expression. \commentary{ A superclass of $C$ cannot declare such an initializer either, because it must necessarily declare constant constructor as well (unless it is \code{Object}, which declares no instance variables). } -\LMHash{} +\LMHash{}% The superinitializer that appears, explicitly or implicitly, in the initializer list of a constant constructor must specify a constant constructor of the superclass of the immediately enclosing class or a compile-time error occurs. -\LMHash{} +\LMHash{}% Any expression that appears within the initializer list of a constant constructor must be a potentially constant expression, or a compile-time error occurs. -\LMHash{} -A {\em potentially constant expression} is an expression $e$ that could be a valid constant expression if all formal parameters of $e$'s immediately enclosing constant constructor were treated as compile-time constants of appropriate types, and where $e$ is also a valid expression if all the formal parameters are treated as non-constant variables. +\LMHash{}% +A \Index{potentially constant expression} is an expression $e$ that could be a valid constant expression if all formal parameters of $e$'s immediately enclosing constant constructor were treated as compile-time constants of appropriate types, and where $e$ is also a valid expression if all the formal parameters are treated as non-constant variables. \commentary{ The difference between a potentially constant expression and a constant expression (\ref{const}) deserves some explanation. @@ -2806,7 +2913,7 @@ Careful readers will of course worry about cases where the actual arguments to \ This is precluded by the following rule, combined with the rules for evaluating constant objects (\ref{const}). } -\LMHash{} +\LMHash{}% When a constant constructor $k$ is invoked from a constant object expression, it is a compile-time error if the invocation of $k$ at run time would throw an exception, @@ -2831,11 +2938,12 @@ and that same expression would evaluate without errors at run time. \subsection{Static Methods} \LMLabel{staticMethods} -\LMHash{} -{\em Static methods} are functions, other than getters or setters, whose declarations are immediately contained within a class declaration and that are declared \STATIC{}. +\LMHash{}% +\IndexCustom{Static methods}{method!static} +are functions, other than getters or setters, whose declarations are immediately contained within a class declaration and that are declared \STATIC{}. The static methods of a class $C$ are those static methods declared by $C$. -\LMHash{} +\LMHash{}% The effect of a static method declaration in class $C$ is to add an instance method with the same name and signature to the \code{Type} object for class $C$ that forwards (\ref{functionDeclarations}) to the static method. \rationale{ @@ -2866,7 +2974,7 @@ Static method declarations may conflict with other declarations %% class (unless we start defining nested classes, such that the %% superclass can be declared in that scope). -\LMHash{} +\LMHash{}% The superclass $S'$ of a class $C$ whose declaration has a with clause \code{\WITH{} $M_1, \ldots,\ M_k$} and an extends clause @@ -2883,7 +2991,7 @@ If no \EXTENDS{} clause is specified, then either: \code{\EXTENDS{} Object}, and the rules above apply. \end{itemize} -\LMHash{} +\LMHash{}% It is a compile-time error to specify an \EXTENDS{} clause for class \code{Object}. @@ -2896,10 +3004,10 @@ for class \code{Object}. %This means that in a generic class, the type parameters of the generic are available in the superclass clause. %} -\LMHash{} +\LMHash{}% The scope of the \EXTENDS{} and \WITH{} clauses of a class $C$ is the type-parameter scope of $C$. -\LMHash{} +\LMHash{}% It is a compile-time error if the type in the \EXTENDS{} clause of a class $C$ is a type variable (\ref{generics}), a type alias (\ref{typedef}), an enumerated type (\ref{enums}), a malformed type (\ref{staticTypes}), @@ -2918,27 +3026,27 @@ class T \{\} class G extends T \{\} \end{dartCode} -\LMHash{} +\LMHash{}% %% TODO(eernst): Consider replacing all occurrences of `a superclass` %% by `a direct or indirect superclass`, because it's too confusing. -A class $S$ is {\em a superclass} of a class $C$ if{}f either: +A class $S$ is a \Index{superclass} of a class $C$ if{}f either: \begin{itemize} \item $S$ is the superclass of $C$, or \item $S$ is a superclass of a class $S'$, and $S'$ is the superclass of $C$. \end{itemize} -\LMHash{} +\LMHash{}% It is a compile-time error if a class $C$ is a superclass of itself. \subsubsection{Inheritance and Overriding} \LMLabel{inheritanceAndOverriding} -\LMHash{} +\LMHash{}% Let $C$ be a class, let $A$ be a superclass of $C$, and let $S_1, \ldots, S_k$ be superclasses of $C$ that are also subclasses of $A$. -$C$ {\em inherits} all concrete, accessible instance members of $A$ +$C$ \Index{inherits} all concrete, accessible instance members of $A$ that have not been overridden by a concrete declaration in $C$ or in at least one of $S_1, \ldots, S_k$. \rationale{ @@ -2949,10 +3057,10 @@ whereas $S$ comes from a different library $L_2$, but the superclass chain of $S$ includes a class declared in $L_1$. } -\LMHash{} +\LMHash{}% A class may override instance members that would otherwise have been inherited from its superclass. -\LMHash{} +\LMHash{}% Let $C = S_0$ be a class declared in library $L$, and let $\{S_1, \ldots, S_k\}$ be the set of all superclasses of $C$, where $S_i$ is the superclass of $S_{i-1}$ for $i \in 1 .. k$. @@ -2973,7 +3081,7 @@ The getters and setters induced by instance variables do. Again, a local definition of overriding would be preferable, but fails to account for library privacy. } -\LMHash{} +\LMHash{}% Whether an override is legal or not is described elsewhere in this specification (see \ref{instanceMethods}, \ref{getters} and \ref{setters}). \commentary{ @@ -2991,7 +3099,7 @@ Also, getters don't override setters and vice versa. Finally, static members never override anything. } -\LMHash{} +\LMHash{}% Let $C$ be a concrete class whose interface has an accessible member $m$ named \id{}. It is a compile-time error if $C$ does not have @@ -3119,7 +3227,7 @@ The controlling language is in the relevant sections of the specification. \LMLabel{superinterfaces} % what about rules about classes that fail to implement their interfaces? -\LMHash{} +\LMHash{}% A class has a set of direct superinterfaces. This set includes the interface of its superclass and the interfaces specified in the \IMPLEMENTS{} clause of the class. @@ -3127,10 +3235,10 @@ This set includes the interface of its superclass and the interfaces specified i ::= \IMPLEMENTS{} \end{grammar} -\LMHash{} +\LMHash{}% The scope of the \IMPLEMENTS{} clause of a class $C$ is the type-parameter scope of $C$. -\LMHash{} +\LMHash{}% It is a compile-time error if an element in the type list of the \IMPLEMENTS{} clause of a class $C$ is a type variable (\ref{generics}), a type alias (\ref{typedef}), an enumerated type (\ref{enums}), a malformed type (\ref{staticTypes}), @@ -3149,10 +3257,10 @@ One might argue that it is harmless to repeat a type in the superinterface list, As such, it is an indication that the programmer may very well have meant to say something else - and that is a mistake that should be called to her or his attention. } -\LMHash{} +\LMHash{}% It is a compile-time error if the interface of a class $C$ is a superinterface of itself. -\LMHash{} +\LMHash{}% Let $C$ be a concrete class that does not have a concrete \code{noSuchMethod()} method distinct from the one declared in class \code{Object}. %% TODO(eernst): Adjust to use 'correctly overrides' terminology. It is a compile-time error if the implicit interface of $C$ has an accessible instance member $m$ of type $F$, @@ -3176,7 +3284,7 @@ and no actual declarations of the implemented interface's members are needed. This allows proxy classes for specific types to be implemented without provoking errors. } -\LMHash{} +\LMHash{}% %% TODO(eernst): Switch to use 'correctly overrides' terminology. It is a compile-time error if the implicit interface of a class $C$ has an instance member $m$ of type $F$ and $C$ declares or inherits a corresponding instance member $m$ of type $F'$ if $F'$ is not a subtype of $F$. @@ -3188,16 +3296,16 @@ However, if a class does explicitly declare a member that conflicts with its sup \subsection{Class Member Conflicts} \LMLabel{classMemberConflicts} -\LMHash{} +\LMHash{}% Some pairs of class member declarations cannot coexist, even though they do not both introduce the same name into the same scope. This section specifies these errors. -\LMHash{} -The {\em basename} of a getter or method named $n$ is $n$; +\LMHash{}% +The \Index{basename} of a getter or method named $n$ is $n$; the basename of a setter named \code{$n$=} is $n$. -\LMHash{} +\LMHash{}% Let $C$ be a class. It is a compile-time error if $C$ declares a \begin{itemize} @@ -3213,25 +3321,25 @@ as well as when they are induced by variable declarations. \section{Interfaces} \LMLabel{interfaces} -\LMHash{} -An {\em interface} defines how one may interact with an object. +\LMHash{}% +An \Index{interface} defines how one may interact with an object. An interface has methods, getters and setters and a set of superinterfaces. \subsection{Superinterfaces} \LMLabel{interfaceSuperinterfaces} -\LMHash{} +\LMHash{}% An interface has a set of direct superinterfaces. -\LMHash{} +\LMHash{}% An interface $J$ is a superinterface of an interface $I$ if{}f either $J$ is a direct superinterface of $I$ or $J$ is a superinterface of a direct superinterface of $I$. \subsubsection{Inheritance and Overriding} \LMLabel{interfaceInheritanceAndOverriding} -\LMHash{} +\LMHash{}% Let $J$ be an interface and $K$ be a library. We define $inherited(J, K)$ to be the set of members $m$ such that all of the following hold: \begin{itemize} @@ -3244,7 +3352,7 @@ We define $inherited(J, K)$ to be the set of members $m$ such that all of the fo \item $m$ is not overridden by $J$. \end{itemize} -\LMHash{} +\LMHash{}% Furthermore, we define $overrides(J, K)$ to be the set of members $m'$ such that all of the following hold: \begin{itemize} \item $J$ is the implicit interface of a class $C$. @@ -3258,14 +3366,14 @@ Furthermore, we define $overrides(J, K)$ to be the set of members $m'$ such that \end{itemize} \end{itemize} -\LMHash{} +\LMHash{}% Let $I$ be the implicit interface of a class $C$ declared in library $L$. -$I$ {\em inherits} all members of $inherited(I, L)$ and $I$ {\em overrides} $m'$ if $m' \in overrides(I, L)$. +$I$ \Index{inherits} all members of $inherited(I, L)$ and $I$ \Index{overrides} $m'$ if $m' \in overrides(I, L)$. -\LMHash{} +\LMHash{}% All the compile-time errors pertaining to the overriding of instance members given in section \ref{classes} above hold for overriding between interfaces as well. -\LMHash{} +\LMHash{}% It is a compile-time error if $m$ is a method and $m'$ is a getter, or if $m$ is a getter and $m'$ is a method. %Let $I = S_0$ be the implicit interface of a class $C$ declared in library $L$, and let $\{S_1, \ldots, S_k\}$ be the set of all superinterfaces of $I$. @@ -3274,13 +3382,13 @@ It is a compile-time error if $m$ is a method and $m'$ is a getter, or if $m$ is % tighten definition? do we need chain as for classes? Definition for interface override? -\LMHash{} +\LMHash{}% However, if the above rules would cause multiple members $m_1, \ldots, m_k$ with the same name $n$ to be inherited (because identically named members existed in several superinterfaces) then at most one member is inherited. -\LMHash{} +\LMHash{}% If some but not all of the $m_i, 1 \le i \le k$ are getters, a compile-time error occurs. -\LMHash{} +\LMHash{}% %% TODO(eernst): Adjust to use 'correctly overrides' terminology. Otherwise, if the static types $T_1, \ldots, T_k$ of the members $m_1, \ldots, m_k$ are not identical then there must be an $x \in 1 .. k$ such that $T_x <: T_i$ for all $i \in 1 .. k$, or a compile-time error occurs. @@ -3290,11 +3398,11 @@ The member that is inherited is $m_x$, if it exists. \section{Mixins} \LMLabel{mixins} -\LMHash{} +\LMHash{}% A mixin describes the difference between a class and its superclass. A mixin is always derived from an existing class declaration. -\LMHash{} +\LMHash{}% It is a compile-time error to derive a mixin from a class which explicitly declares a generative constructor. It is a compile-time error to derive a mixin from a class which has a superclass other than \code{Object}. @@ -3309,7 +3417,7 @@ The restriction on constructors simplifies the construction of mixin application \subsection{Mixin Application} \LMLabel{mixinApplication} -\LMHash{} +\LMHash{}% A mixin may be applied to a superclass, yielding a new class. Mixin application occurs when one or more mixins are mixed into a class declaration via its \WITH{} clause. The mixin application may be used to extend a class per section \ref{classes}; @@ -3321,26 +3429,27 @@ a deferred type (\ref{staticTypes}), type \DYNAMIC{} (\ref{typeDynamic}), or type \code{FutureOr<$T$>} for any $T$ (\ref{typeFutureOr}). \begin{grammar} - ::= ? `=' `;' + ::= \gnewline{} + ? `=' `;' ::= ? \end{grammar} -\LMHash{} +\LMHash{}% A mixin application of the form \code{$S$ \WITH{} $M$;} for the name $N$ defines a class $C$ with superclass $S$ and name $N$. -\LMHash{} +\LMHash{}% A mixin application of the form \code{$S$ \WITH{} $M_1,\ \ldots,\ M_k$;} for the name $N$ defines a class $C$ whose superclass is the application of the mixin composition (\ref{mixinComposition}) $M_{k-1} * \ldots * M_1$ to $S$ of a name that is a fresh identifer, and whose name is $N$. \rationale{The name of the resulting class is necessary because it is part of the names of the introduced constructors.} -\LMHash{} +\LMHash{}% In both cases above, $C$ declares the same instance members as $M$ (respectively, $M_k$), and it does not declare any static members. If any of the instance variables of $M$ (respectively, $M_k$) have initializers, they are executed in the instance scope of $M$ (respectively, $M_k$) to initialize the corresponding instance variables of $C$. -\LMHash{} +\LMHash{}% Let $L_C$ be the library containing the mixin application. \commentary{That is, the library containing the clause \code{$S$ \WITH{} $M$} or the clause \code{$S_0$ \WITH{} $M_1$, \ldots,\ $M_k$, $M$}.} @@ -3361,7 +3470,7 @@ replacing occurrences of $S_N$ which denote the superclass by \SUPER{}. If $S_q$ is a generative const constructor, and $M$ does not declare any fields, $C_q$ is also a const constructor. -\LMHash{} +\LMHash{}% For each generative constructor of the form \code{$S_q$($T_{1}$ $a_{1}$, \ldots , $T_{k}$ $a_{k}$, [$T_{k+1}$ $a_{k+1}$ = $d_1$, \ldots , $T_{k+p}$ $a_{k+p}$ = $d_p$])} of $S$ that is accessible to $L_C$, $C$ has an implicitly declared constructor of the form \begin{dartCode} @@ -3379,7 +3488,7 @@ to the same value as $d_i$. If $S_q$ is a generative const constructor, and $M$ does not declare any fields, $C_q$ is also a const constructor. -\LMHash{} +\LMHash{}% For each generative constructor of the form \code{$S_q$($T_{1}$ $a_{1}$, \ldots , $T_{k}$ $a_{k}$, \{$T_{k+1}$ $a_{k+1}$ = $d_1$, \ldots , $T_{k+n}$ $a_{k+n}$ = $d_n$\})} of $S$ that is accessible to $L_C$, $C$ has an implicitly declared constructor of the form \begin{dartCode} @@ -3396,15 +3505,15 @@ and $d'_i$, $i \in 1..n$, is a constant expression evaluating to the same value If $S_q$ is a generative const constructor, and $M$ does not declare any fields, $C_q$ is also a const constructor. -\LMHash{} +\LMHash{}% If the mixin application class declares interfaces, the resulting class also implements those interfaces. -\LMHash{} +\LMHash{}% It is a compile-time error if $S$ is an enumerated type (\ref{enums}) or a malformed type. It is a compile-time error if $M$ (respectively, any of $M_1, \ldots, M_k$) is an enumerated type (\ref{enums}) or a malformed type. It is a compile-time error if a well formed mixin cannot be derived from $M$ (respectively, from each of $M_1, \ldots, M_k$). -\LMHash{} +\LMHash{}% Let $K$ be a class declaration with the same constructors, superclass and interfaces as $C$, and the instance members declared by $M$ (respectively $M_1, \ldots, M_k$). It is a compile-time error if the declaration of $K$ would cause a compile-time error. @@ -3414,19 +3523,19 @@ $M$ declares an instance member $im$ whose type is at odds with the type of a me this will result in a compile-time error just as if we had defined $K$ by means of an ordinary class declaration extending $S$, with a body that included $im$. } -\LMHash{} +\LMHash{}% The effect of a class definition of the form \code{\CLASS{} $C$ = $M$; } or the form \code{\CLASS{} $C$ = $M$; } in library $L$ is to introduce the name $C$ into the scope of $L$, bound to the class (\ref{classes}) defined by the mixin application $M$ for the name $C$. The name of the class is also set to $C$. If{}f the class is prefixed by the built-in identifier \ABSTRACT{}, the class being defined is an abstract class. -\LMHash{} +\LMHash{}% Let $M_A$ be a mixin derived from a class $M$ with direct superclass $S_{static}$, e.g., as defined by the class declaration \code{class M extends S$_{static}$ \{ \ldots \}}. -\LMHash{} +\LMHash{}% Let $A$ be an application of $M_A$. It is a compile-time error if the superclass of $A$ is not a subtype of $S_{static}$. -\LMHash{} +\LMHash{}% Let $C$ be a class declaration that includes $M_A$ in a with clause. It is a compile-time error if $C$ does not implement, directly or indirectly, all the direct superinterfaces of $M$. @@ -3438,12 +3547,18 @@ It is a compile-time error if $C$ does not implement, directly or indirectly, al Dart does not directly support mixin composition, but the concept is useful when defining how the superclass of a class with a mixin clause is created. } -\LMHash{} -The {\em composition of two mixins}, $M_1$ and $M_2$, written $M_1 * M_2$ defines an anonymous mixin such that for any class $S$, the application of +\LMHash{}% +The \Index{composition of two mixins}, +\code{$M_1$<$T_1, \ldots, T_{k_{M_1}}$>} and +\code{$M_2$<$U_1, \ldots, U_{k_{M_2}}$>}, written +\code{$M_1$<$T_1, \ldots, T_{k_{M_1}}$>$ * M_2$<$U_1, \ldots, U_{k_{M_2}}$>} +defines an anonymous mixin such that for any class +\code{$S$<$V_1, \ldots, V_{k_S}$>}, +the application of -$M_1 * M_2$ +\code{$M_1$<$T_1, \ldots, T_{k_{M_1}}$> $*$ $M_2$<$U_1, \ldots, U_{k_{M_2}}$>} -to $S$ for the name $C$ is equivalent to +to \code{$S$<$V_1, \ldots, V_{k_S}$>} for the name $C$ is equivalent to \begin{dartCode} \ABSTRACT{} \CLASS{} $C = $ @@ -3465,7 +3580,7 @@ They are only introduced as anonymous superclasses of ordinary class declaration Consequently, no errors are raised if a mixin composition includes abstract members, or incompletely implements an interface. } -\LMHash{} +\LMHash{}% Mixin composition is associative. \commentary{ @@ -3477,8 +3592,8 @@ For any non-generic declaration, the corresponding type parameters may be elided \section{Enums} \LMLabel{enums} -\LMHash{} -An {\em enumerated type}, or {\em enum}, is used to represent a fixed number of constant values. +\LMHash{}% +An \Index{enumerated type}, or \Index{enum}, is used to represent a fixed number of constant values. \begin{grammar} ::= \ENUM{} @@ -3487,7 +3602,7 @@ An {\em enumerated type}, or {\em enum}, is used to represent a fixed number of ::= \end{grammar} -\LMHash{} +\LMHash{}% The declaration of an enum of the form \code{$m$ \ENUM{} $E$ \{$m_0\,\,\id_0, \ldots,\ m_{n-1}\,\,\id_{n-1}$\}} has the same effect as a class declaration @@ -3513,10 +3628,10 @@ These restrictions are given in normative form in sections \ref{superclasses}, \ \section{Generics} \LMLabel{generics} -\LMHash{} -A class declaration (\ref{classes}), type alias (\ref{typedef}), or function (\ref{functions}) $G$ may be {\em generic}, that is, $G$ may have formal type parameters declared. +\LMHash{}% +A class declaration (\ref{classes}), type alias (\ref{typedef}), or function (\ref{functions}) $G$ may be \Index{generic}, that is, $G$ may have formal type parameters declared. -\LMHash{} +\LMHash{}% When an entity in this specification is described as generic, and the special case is considered where the number of type arguments is zero, the type argument list should be omitted. @@ -3531,19 +3646,21 @@ In this situation some operations are also omitted (have no effect), e.g., operations where formal type parameters are replaced by actual type arguments. } -\LMHash{} -A {\em generic class declaration} introduces a generic class into the enclosing library scope. -A {\em generic class} is a mapping that accepts a list of actual type arguments and maps them to a class. +\LMHash{}% +A \IndexCustom{generic class declaration}{class declaration!generic} +introduces a generic class into the enclosing library scope. +A \IndexCustom{generic class}{class!generic} +is a mapping that accepts a list of actual type arguments and maps them to a class. Consider a generic class declaration $G$ named \code{C} with formal type parameter declarations $X_1\ \EXTENDS\ B_1, \ldots,\ X_m\ \EXTENDS\ B_m$, and a parameterized type $T$ of the form \code{C<$T_1, \ldots,\ T_l$>}. -\LMHash{} +\LMHash{}% It is a compile-time error if $m \not= l$. It is a compile-time error if $T$ is not well-bounded (\ref{superBoundedTypes}). -\LMHash{} +\LMHash{}% Otherwise, said parameterized type \code{C<$T_1, \ldots,\ T_m$>} denotes an application of the generic class declared by $G$ to the type arguments $T_1, \ldots, T_m$. This yields a class $C'$ whose members are equivalent to those of a class declaration which is obtained from the declaration of $G$ by replacing each occurrence of $X_j$ by $T_j$. \commentary{ @@ -3552,8 +3669,8 @@ This yields a class $C'$ whose members are equivalent to those of a class declar Other properties of $C'$ such as the subtype relationships are specified elsewhere (\ref{interfaceTypes}). } -\LMHash{} -A {\em generic type alias} +\LMHash{}% +A \IndexCustom{generic type alias}{type alias!generic} introduces a mapping from actual type argument lists to types. Consider a generic type alias declaration $G$ named \code{F} with formal type parameter declarations @@ -3562,7 +3679,7 @@ $X_1\ \EXTENDS\ B_1, \ldots,\ X_m\ \EXTENDS\ B_m$, %% Explain what "the right hand side" means for an old-style declaration. and right hand side $T$. -\LMHash{} +\LMHash{}% Under the assumption that $X_1,\ \ldots,\ X_m$ are types such that $X_j <: B_j$, for all $j \in 1 .. m$, it is a compile-time error if any type in $T$ is not regular-bounded. @@ -3574,7 +3691,7 @@ must be such that when they are satisfied, the bounds that pertain to any type in the body must also be satisfied. } -\LMHash{} +\LMHash{}% Let $G$, \code{F}, and $X_1,\ \ldots,\ X_m$ be as defined above, let $T_1,\ \ldots,\ T_l$ be types, and let $S$ be the parameterized type \code{F<$T_1, \ldots,\ T_l$>}. @@ -3582,7 +3699,7 @@ It is a compile-time error if $m \not= l$. It is a compile-time error if $S$ is not well-bounded (\ref{superBoundedTypes}). -\LMHash{} +\LMHash{}% Otherwise, said parameterized type \code{F<$T_1, \ldots,\ T_m$>} denotes an application of the mapping denoted by $G$ to the type arguments @@ -3624,19 +3741,20 @@ So the types can be expressed, they just cannot be abbreviated using a generic type alias. } -\LMHash{} -A {\em generic type} is a type which is introduced by +\LMHash{}% +A \IndexCustom{generic type}{type!generic} is a type which is introduced by a generic class declaration or a generic type alias, or it is the type \code{FutureOr}. -\LMHash{} -A {\em generic function declaration} introduces a generic function (\ref{formalParameters}) into the enclosing scope. +\LMHash{}% +A \IndexCustom{generic function declaration}{function declaration!generic} +introduces a generic function (\ref{formalParameters}) into the enclosing scope. Consider a function invocation expression of the form \code{f<$T_1, \ldots,\ T_l$>(\ldots)}, where the static type of \code{f} is a generic function type with formal type parameters $X_1\ \EXTENDS\ B_1, \ldots,\ X_m\ \EXTENDS\ B_m$. -\LMHash{} +\LMHash{}% It is a compile-time error if $m \not= l$. It is a compile-time error if there exists a $j$ such that $T_j$ is not a subtype of $[T_1/X_1, \ldots, T_m/X_m]B_j$. @@ -3653,8 +3771,8 @@ where each formal type parameter has been replaced by the corresponding actual t ::= `<' (`,' )* `>' \end{grammar} -\LMHash{} -A type parameter $T$ may be suffixed with an \EXTENDS{} clause that specifies the {\em upper bound} for $T$. +\LMHash{}% +A type parameter $T$ may be suffixed with an \EXTENDS{} clause that specifies the \Index{upper bound} for $T$. If no \EXTENDS{} clause is present, the upper bound is \code{Object}. It is a compile-time error if a type parameter is a supertype of its upper bound when that upper bound is itself a type variable. @@ -3666,7 +3784,7 @@ and \code{X \EXTENDS{} Y, Y \EXTENDS{} X}. } -\LMHash{} +\LMHash{}% Type parameters are declared in the type parameter scope of a class or function. The type parameters of a generic $G$ are in scope in the bounds of all of the type parameters of $G$. The type parameters of a generic class declaration $G$ are also in scope in the \EXTENDS{} and \IMPLEMENTS{} clauses of $G$ (if these exist) and in the body of $G$. @@ -3755,25 +3873,25 @@ Some of these restrictions may be lifted in the future. \subsection{Variance} \LMLabel{variance} -\LMHash{} -We say that a type $S$ {\em occurs covariantly} in a type $T$ if{}f +\LMHash{}% +We say that a type $S$ \Index{occurs covariantly} in a type $T$ if{}f $S$ occurs in a covariant position in $T$, but not in a contravariant position, and not in an invariant position. -\LMHash{} -We say that a type $S$ {\em occurs contravariantly} in a type $T$ if{}f +\LMHash{}% +We say that a type $S$ \Index{occurs contravariantly} in a type $T$ if{}f $S$ occurs in a contravariant position in $T$, but not in a covariant position, and not in an invariant position. -\LMHash{} -We say that a type $S$ {\em occurs invariantly} in a type $T$ if{}f +\LMHash{}% +We say that a type $S$ \Index{occurs invariantly} in a type $T$ if{}f $S$ occurs in an invariant position in $T$, or $S$ occurs in a covariant position as well as a contravariant position. -\LMHash{} -We say that a type $S$ occurs {\em in a covariant position} in a type $T$ +\LMHash{}% +We say that a type $S$ occurs in a \Index{covariant position} in a type $T$ if{}f one of the following conditions is true: \begin{itemize} @@ -3821,8 +3939,8 @@ if{}f one of the following conditions is true: and $S$ occurs in a contravariant position in $S_j$. \end{itemize} -\LMHash{} -We say that a type $S$ occurs {\em in a contravariant position} in a type $T$ +\LMHash{}% +We say that a type $S$ occurs in a \Index{contravariant position} in a type $T$ if{}f one of the following conditions is true: \begin{itemize} @@ -3869,8 +3987,8 @@ if{}f one of the following conditions is true: and $S$ occurs in a covariant position in $S_j$. \end{itemize} -\LMHash{} -We say that a type $S$ occurs {\em in an invariant position} in a type $T$ +\LMHash{}% +We say that a type $S$ occurs in an \Index{invariant position} in a type $T$ if{}f one of the following conditions is true: \begin{itemize} @@ -3907,17 +4025,21 @@ if{}f one of the following conditions is true: and $S$ occurs in $S_j$. \end{itemize} -\LMHash{} +\LMHash{}% Consider a generic type alias declaration $G$ with formal type parameter declarations $X_1\ \EXTENDS\ B_1, \ldots,\ X_m\ \EXTENDS\ B_m$, and right hand side $T$. Let $j \in 1 .. m$. % -We say that {\em the formal type parameter} $X_j$ {\em is invariant} -if{}f $X_j$ occurs invariantly in $T$, -$X_j$ {\em is covariant} if{}f $X_j$ occurs covariantly in $T$, -and $X_j$ {\em is contravariant} if{}f $X_j$ occurs contravariantly in $T$. +We say that +\IndexCustom{the formal type parameter $X_j$ is invariant}{% + type parameter!invariant} +if{}f $X_j$ occurs invariantly in $T$, $X_j$ +\IndexCustom{is covariant}{type parameter!covariant} +if{}f $X_j$ occurs covariantly in $T$, and $X_j$ +\IndexCustom{is contravariant}{type parameter!contravariant} +if{}f $X_j$ occurs contravariantly in $T$. \rationale{ Variance gives a characterization of the way a type varies @@ -3939,13 +4061,13 @@ with invariance, all bets are off. \subsection{Super-Bounded Types} \LMLabel{superBoundedTypes} -\LMHash{} +\LMHash{}% This section describes how the declared upper bounds of formal type parameters are enforced, including some cases where a limited form of violation is allowed. -\LMHash{} -A {\em top type} is a type $T$ such that \code{Object} is a subtype of $T$. +\LMHash{}% +A \Index{top type} is a type $T$ such that \code{Object} is a subtype of $T$. \commentary{ For instance, \code{Object}, \DYNAMIC, and \VOID{} are top types, and so are \code{FutureOr<\VOID>} and \code{FutureOr{}>}. @@ -3958,22 +4080,22 @@ and so are \code{FutureOr<\VOID>} and \code{FutureOr{}>}. % require that types must be regular-bounded when used in certain % situations. -\LMHash{} -Every type which is not a parameterized type is {\em regular-bounded}. +\LMHash{}% +Every type which is not a parameterized type is \Index{regular-bounded}. \commentary{ In particular, every non-generic class and every function type is a regular-bounded type. } -\LMHash{} +\LMHash{}% Let $T$ be a parameterized type of the form \code{$G$<$S_1, \ldots,\ S_n$>} where $G$ denotes a generic class or a generic type alias. Let \code{$X_1\ \EXTENDS\ B_1, \ldots,\ X_n\ \EXTENDS\ B_n$} be the formal type parameter declarations of $G$. -$T$ is {\em regular-bounded} if{}f +$T$ is \Index{regular-bounded} if{}f $S_j$ is a subtype of $[S_1/X_1, \ldots,\ S_n/X_n]B_j$, for all $j \in 1 .. n$. @@ -3983,11 +4105,11 @@ This means that regular-bounded types are those types that do not violate their type parameter bounds. } -\LMHash{} +\LMHash{}% Let $T$ be a parameterized type of the form \code{$G$<$S_1, \ldots,\ S_n$>} where $G$ denotes a generic class or a generic type alias. -$T$ is {\em super-bounded} if{}f the following conditions are both true: +$T$ is \Index{super-bounded} if{}f the following conditions are both true: \begin{itemize} \item @@ -4014,14 +4136,14 @@ regular-bounded after replacing all occurrences of an extreme type by an opposite extreme type, depending on their variance. } -\LMHash{} -A type $T$ is {\em well-bounded} if{}f +\LMHash{}% +A type $T$ is \Index{well-bounded} if{}f it is either regular-bounded or super-bounded. -\LMHash{} +\LMHash{}% Any use of a type $T$ which is not well-bounded is a compile-time error. -\LMHash{} +\LMHash{}% It is a compile-time error if a parameterized type $T$ is super-bounded when it is used in any of the following ways: \begin{itemize} @@ -4131,14 +4253,14 @@ of expressions whose type proceeds beyond the given finite unfolding. \section{Metadata} \LMLabel{metadata} -\LMHash{} +\LMHash{}% Dart supports metadata which is used to attach user defined annotations to program structures. \begin{grammar} ::= (`@' (`.' )? ()?)* \end{grammar} -\LMHash{} +\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} @@ -4146,7 +4268,7 @@ It is a compile-time error if the expression is not one of the following: \item A call to a constant constructor. \end{itemize} -\LMHash{} +\LMHash{}% Metadata is associated with the abstract syntax tree of the program construct $p$ that immediately follows the metadata, assuming $p$ is not itself metadata or a comment. Metadata can be retrieved at run time via a reflective call, provided the annotated program construct $p$ is accessible via reflection. @@ -4166,24 +4288,29 @@ This is not as useless as it might seem. As noted above, the data can be retrieved statically if source code is available. } -\LMHash{} +\LMHash{}% Metadata can appear before a library, part header, class, typedef, type parameter, constructor, factory, function, parameter, or variable declaration and before an import, export or part directive. -\LMHash{} +\LMHash{}% The constant expression given in an annotation is type checked and evaluated in the scope surrounding the declaration being annotated. \section{Expressions} \LMLabel{expressions} -\LMHash{} +\LMHash{}% \label{evaluation} -An {\em expression} is a fragment of Dart code that can be evaluated at run time. -Evaluating an expression either {\em produces a value} (an object), -or it {\em throws} an exception object and an associated stack trace. -In the former case, we also say that the expression {\em evaluates to a value}. +An \Index{expression} is a fragment of Dart code that can be evaluated at run time. +Evaluating an expression either +\IndexCustom{produces a value}{expression!produces a value} +(an object), +or it +\IndexCustom{throws}{expression!throws} +an exception object and an associated stack trace. +In the former case, we also say that the expression +\NoIndex{evaluates to a value}. -\LMHash{} +\LMHash{}% Every expression has an associated static type (\ref{staticTypes}) and may have an associated static context type. \commentary{The static context type represents @@ -4194,7 +4321,7 @@ The static context type may affect the static type and evaluation of the expression. Every value has an associated dynamic type (\ref{dynamicTypeSystem}). -\LMHash{} +\LMHash{}% If evaluation of one expression, $e$, is defined in terms of evaluation of another expression, typically a subexpression of $e$, and the evaluation of the other expression throws an exception and a stack trace, the evaluation of $e$ stops at that point and throws the same exception object and stack trace. @@ -4221,7 +4348,7 @@ the evaluation of $e$ stops at that point and throws the same exception object a \alt `(' `)' \end{grammar} -\LMHash{} +\LMHash{}% An expression $e$ may always be enclosed in parentheses, but this never has any semantic effect on $e$. \commentary{ @@ -4233,7 +4360,7 @@ Given a class $C$ with static method $m => 42$, $C.m()$ returns 42, but $(C).m() \subsection{Object Identity} \LMLabel{objectIdentity} -\LMHash{} +\LMHash{}% The predefined Dart function \code{identical()} is defined such that \code{identical($c_1$, $c_2$)} if{}f: \begin{itemize} \item $c_1$ evaluates to either the null object (\ref{null}) or an instance of \code{bool} and \code{$c_1$ == $c_2$}, OR @@ -4275,7 +4402,7 @@ The rules for identity make it impossible for a Dart programmer to observe wheth All usages of the word 'constant' in Dart are associated with compile time. A potentially constant expression is an expression that will generally yield a constant value when the value of certain parameters is given. -The constant expressions is a subset of the potentially constant expressions that {\em can} be evaluated entirely at compile time. +The constant expressions is a subset of the potentially constant expressions that \emph{can} be evaluated entirely at compile time. } \rationale{ @@ -4285,8 +4412,11 @@ No user written function body is executed during constant expression evaluation, only members of the system classes \code{int}, \code{double}, \code{bool}, \code{String} or \code{Null}. } -\LMHash{} -The {\em potentially constant expressions} and {\em constant expressions} are the following: +\LMHash{}% +The \IndexCustom{potentially constant expressions}{% + potentially constant expression} +and \IndexCustom{constant expressions}{constant expression} +are the following: \begin{itemize} \item A literal boolean, \TRUE{} or \FALSE{} (\ref{booleans}), is a potentially constant and constant expression. @@ -4420,7 +4550,7 @@ including whether it's potentially constant or constant. \end{itemize} -\LMHash{} +\LMHash{}% % New in 2.1. A constant type expression is one of: \begin{itemize} @@ -4449,7 +4579,7 @@ and where $R$, \metavar{typeParameters} and \metavar{argumentTypes} (if present) % A validly typed potentially constant expression can still fail when evaluated. % If that happens in a const invociation, it's a compile-time error. -\LMHash{} +\LMHash{}% It is a compile-time error if an expression is required to be a constant expression but its evaluation would throw an exception. It is a compile-time error if an assertion is evaluated as part of a constant object expression evaluation, and the assertion would throw an exception. @@ -4516,7 +4646,7 @@ In particular, constant constructor initializers such as \code{\CONST{} C(foo): \THIS.foo = foo ?? someDefaultValue;} } -\LMHash{} +\LMHash{}% It is a compile-time error if the value of a constant expression depends on itself. \commentary{ @@ -4545,14 +4675,14 @@ As an example, consider: \subsection{Null} \LMLabel{null} -\LMHash{} -The reserved word \NULL{} evaluates to the {\em null object}. +\LMHash{}% +The reserved word \NULL{} evaluates to the \Index{null object}. \begin{grammar} ::= \NULL{} \end{grammar} -\LMHash{} +\LMHash{}% The null object is the sole instance of the built-in class \code{Null}. Attempting to instantiate \code{Null} causes a run-time error. It is a compile-time error for a class to extend, mix in or implement \code{Null}. @@ -4560,15 +4690,16 @@ The \code{Null} class extends the \code{Object} class and declares no methods ex \commentary{As such, it does not override the \code{==} operator inherited from the \code{Object} class.} -\LMHash{} +\LMHash{}% The static type of \NULL{} is the \code{Null} type. \subsection{Numbers} \LMLabel{numbers} -\LMHash{} -A {\em numeric literal} is either a decimal or hexadecimal numeral representing an integer value, or a decimal double representation. +\LMHash{}% +A \IndexCustom{numeric literal}{literal!numeric} +is either a decimal or hexadecimal numeral representing an integer value, or a decimal double representation. \begin{grammar} ::= @@ -4587,20 +4718,22 @@ A {\em numeric literal} is either a decimal or hexadecimal numeral representing \alt \end{grammar} -\LMHash{} +\LMHash{}% A numeric literal starting with `0x' or `0X' -is a {\em hexadecimal integer literal}. +is a \IndexCustom{hexadecimal integer literal}{literal!hexadecimal integer}. It has the numeric integer value of the hexadecimal numeral following `0x' (respectively `0X'). -\LMHash{} -A numeric literal that contains only decimal digits is a {\em decimal integer literal}. +\LMHash{}% +A numeric literal that contains only decimal digits is a +\IndexCustom{decimal integer literal}{literal!decimal integer}. It has the numeric integer value of the decimal numeral. -\LMHash{} -An {\em integer literal} is either a hexadecimal integer literal or a decimal integer literal. +\LMHash{}% +An \IndexCustom{integer literal}{literal!integer} +is either a hexadecimal integer literal or a decimal integer literal. -\LMHash{} +\LMHash{}% Let $l$ be an integer literal that is not the operand of by a unary minus operator, and let $T$ be the static context type of $l$. @@ -4612,12 +4745,13 @@ otherwise the static type of $l$ is \code{int}. when it would satisfy the type requirement, and an \code{int} would not. Otherwise it is an \code{int}, even in situations where that is an error. } -\LMHash{} -A numeric literal that is not an integer literal is a {\em double literal}. +\LMHash{}% +A numeric literal that is not an integer literal is a +\IndexCustom{double literal}{literal!double}. \commentary{A double literal always contains either a decimal point or an exponent part.} The static type of a double literal is \code{double}. -\LMHash{} +\LMHash{}% If $l$ is an integer literal with numeric value $i$ and static type \code{int}, and $l$ is not the operand of a unary minus operator, then evaluation of $l$ proceeds as follows: @@ -4643,16 +4777,16 @@ integer literals with more than 53 bits of precision cannot be represented exactly. } -\LMHash{} +\LMHash{}% A double literal evaluates to a an instance of the \code{double} class representing a 64 bit double precision floating point number as specified by the IEEE 754 standard. -\LMHash{} +\LMHash{}% An integer literal with static type \code{double} and numeric value $i$ evaluates to an instance of the \code{double} class representing the value $i$. It is a compile-time error if the value $i$ cannot be -represented {\em precisely} by the an instance of \code{double}. +represented \emph{precisely} by the an instance of \code{double}. \commentary{ A 64 bit double precision floating point number is usually taken to represent a range of real numbers @@ -4663,36 +4797,40 @@ values we insist that the integer literal's numeric value is the precise value of the \code{double} instance. } -\LMHash{} +\LMHash{}% It is a compile-time error for a class to extend, mix in or implement \code{int}. It is a compile-time error for a class to extend, mix in or implement \code{double}. It is a compile-time error for any class other than \code{int} and \code{double} to extend, mix in or implement \code{num}. -\LMHash{} +\LMHash{}% The instances of \code{int} and \code{double} all override the \code{==} operator inherited from the \code{Object} class. \subsection{Booleans} \LMLabel{booleans} -\LMHash{} -The reserved words \TRUE{} and \FALSE{} evaluate to objects {\em true} and {\em false} that represent the boolean values true and false respectively. -They are the {\em boolean literals}. +\LMHash{}% +The reserved words \TRUE{} and \FALSE{} evaluate to objects +\IndexCustom{true}{true, the object} and +\IndexCustom{false}{false, the object} +that represent the boolean values true and false respectively. +They are the \IndexCustom{boolean literals}{literal!boolean}. \begin{grammar} ::= \TRUE{} \alt \FALSE{} \end{grammar} -\LMHash{} -Both {\em true} and {\em false} are instances of the built-in class \code{bool}, +\LMHash{}% +Both \NoIndex{true} and \NoIndex{false} are instances of +the built-in class \code{bool}, and there are no other objects that implement \code{bool}. It is a compile-time error for a class to extend, mix in or implement \code{bool}. -\LMHash{} +\LMHash{}% The \code{bool} class does not override the \code{==} operator inherited from the \code{Object} class. -\LMHash{} +\LMHash{}% Invoking the getter \code{runtimeType} on a boolean value returns the \code{Type} object that is the value of the expression \code{bool}. The static type of a boolean literal is \code{bool}. @@ -4700,8 +4838,8 @@ The static type of a boolean literal is \code{bool}. \subsection{Strings} \LMLabel{strings} -\LMHash{} -A {\em string} is a sequence of UTF-16 code units. +\LMHash{}% +A \Index{string} is a sequence of UTF-16 code units. \rationale{ This decision was made for compatibility with web browsers and Javascript. @@ -4713,7 +4851,7 @@ Programmers should not depend on this distinction. ::= ( | )+ \end{grammar} -\LMHash{} +\LMHash{}% A string can be a sequence of single line strings and multiline strings. \begin{grammar} @@ -4723,7 +4861,7 @@ A string can be a sequence of single line strings and multiline strings. \alt `r"' (\~{}( `"' | ))* `"' \end{grammar} -\LMHash{} +\LMHash{}% A single line string is delimited by either matching single quotes or matching double quotes. \commentary{ @@ -4735,7 +4873,7 @@ However ``This ` is not a valid string, nor is `this''. The grammar ensures that a single line string cannot span more than one line of source code, unless it includes an interpolated expression that spans multiple lines. } -\LMHash{} +\LMHash{}% Adjacent strings are implicitly concatenated to form a single string literal. \commentary{ @@ -4799,13 +4937,14 @@ This can be expressed by writing smaller strings separated by whitespace, as sho \alt `\\u' \alt `\\u{' `}' - ::= ? ? + ::= \gnewline{} + ? ? \gnewline{} ? ? ? \end{grammar} -\LMHash{} +\LMHash{}% Multiline strings are delimited by either matching triples of single quotes or matching triples of double quotes. -If the first line of a multiline string consists solely of the whitespace characters defined by the production {\em WHITESPACE} (\ref{lexicalRules}), possibly prefixed by \syntax{`\\'}, then that line is ignored, including the line break at its end. +If the first line of a multiline string consists solely of the whitespace characters defined by the production \synt{WHITESPACE} (\ref{lexicalRules}), possibly prefixed by \syntax{`\\'}, then that line is ignored, including the line break at its end. \rationale{ The idea is to ignore a whitespace-only first line of a multiline string, where whitespace is defined as tabs, spaces and the final line break. @@ -4816,7 +4955,7 @@ These can be represented directly, but since for most characters prefixing by ba % """ ignored not. It depends if we mean whitespace before escapes are interpreted, % or after, or both. See https://code.google.com/p/dart/issues/detail?id=23020 -\LMHash{} +\LMHash{}% Strings support escape sequences for special characters. The escapes are: \begin{itemize} @@ -4831,6 +4970,8 @@ The escapes are: \syntax{`\\u{' $_1$ $_2$ `}'}. \item \syntax{`\\u' $_1$ $_2$ $_3$ $_4$}, equivalent to + +\noindent \syntax{`\\u{' $_1$ $_2$ $_3$ $_4$ `}'}. \item \syntax{`\\u{' `}'} is the Unicode code point represented by the \syntax{}. @@ -4842,16 +4983,16 @@ is not a valid Unicode code point. \syntax{$\{$`n', `r', `f', `b', `t', `v', `x', `u'$\}$}. \end{itemize} -\LMHash{} +\LMHash{}% Any string may be prefixed with the character \syntax{`r'}, -indicating that it is a {\em raw string}, +indicating that it is a \Index{raw string}, in which case no escapes or interpolations are recognized. -\LMHash{} +\LMHash{}% Line breaks in a multiline string are represented by the \syntax{} production. A line break introduces a single newline character into the string value. -\LMHash{} +\LMHash{}% It is a compile-time error if a non-raw string literal contains a character sequence of the form \syntax{`\\x'} that is not followed by a sequence of two hexadecimal digits. It is a compile-time error if a non-raw string literal contains a character sequence of the form \syntax{`\\u'} that is not followed by either a sequence of four hexadecimal digits, or by curly brace delimited sequence of hexadecimal digits. @@ -4877,7 +5018,7 @@ It is a compile-time error if a non-raw string literal contains a character sequ \alt `\\r\\n' \end{grammar} -\LMHash{} +\LMHash{}% All string literals evaluate to instances of the built-in class \code{String}. It is a compile-time error for a class to extend, mix in or implement \code{String}. The \code{String} class overrides the \code{==} operator inherited from @@ -4888,9 +5029,9 @@ The static type of a string literal is \code{String}. \subsubsection{String Interpolation} \LMLabel{stringInterpolation} -\LMHash{} +\LMHash{}% It is possible to embed expressions within non-raw string literals, such that these expressions are evaluated, and the resulting values are converted into strings and concatenated with the enclosing string. -This process is known as {\em string interpolation}. +This process is known as \Index{string interpolation}. \begin{grammar} ::= `$' @@ -4901,7 +5042,7 @@ This process is known as {\em string interpolation}. The reader will note that the expression inside the interpolation could itself include strings, which could again be interpolated recursively. } -\LMHash{} +\LMHash{}% An unescaped \syntax{`$'} character in a string signifies the beginning of an interpolated expression. The \syntax{`$'} sign may be followed by either: \begin{itemize} @@ -4909,7 +5050,7 @@ The \syntax{`$'} sign may be followed by either: \item An expression $e$ delimited by curly braces. \end{itemize} -\LMHash{} +\LMHash{}% The form \code{\$\id} is equivalent to the form \code{\$\{\id\}}. An interpolated string, $s$, with content `\code{$s_0$\$\{$e_1$\}$s_1\ldots{}s_{n-1}$\$\{$e_n$\}$s_{n}$}' (where any of $s_0, \ldots, s_n$ can be empty) @@ -4926,15 +5067,16 @@ Finally, the result of the evaluation of $s$ is the concatenation of the strings \subsection{Symbols} \LMLabel{symbols} -\LMHash{} -A {\em symbol literal} denotes a name that would be either +\LMHash{}% +A \IndexCustom{symbol literal}{literal!symbol} +denotes a name that would be either a valid declaration name or a valid library name in a Dart program. \begin{grammar} ::= `#' ( | ( (`.' )*)) \end{grammar} -\LMHash{} +\LMHash{}% A symbol literal \code{\#\id} where \id{} is an identifier that does not begin with an underscore ('\code{\_}'), evaluates to an instance of \code{Symbol} representing the identifier \id. @@ -4944,7 +5086,7 @@ and no other symbol literals evaluate to that \code{Symbol} instance or to a \code{Symbol} instance that is equal (according to the \code{==} operator \ref{equality}) to that instance. -\LMHash{} +\LMHash{}% A symbol literal \code{\#$\id.\id_2\ldots\id_n$} where $\id{} \ldots \id_n$ are identifiers, evaluates to an instance of \code{Symbol} representing that particular sequence of identifiers. @@ -4955,21 +5097,21 @@ or to a \code{Symbol} instance that is \code{==} to that instance. \commentary{This kind of symbol literal denotes the name of a library declaration. Library names are not subject to library privacy, even if some of its identifiers begin with an underscore.} -\LMHash{} +\LMHash{}% A symbol literal \code{\#\metavar{operator}} evaluates to an instance of \code{Symbol} representing that particular operator name. All occurrences of \code{\#\metavar{operator}} evaluate to the same instance, and no other symbol literals evaluate to that \code{Symbol} instance or to a \code{Symbol} instance that is \code{==} to that instance. -\LMHash{} +\LMHash{}% A symbol literal \code{\#\_\id}, evaluates to an instance of \code{Symbol} representing the private identifier \code{\_\id} of the containing library. -All occurrences of \code{\#\_\id} {\em in the same library} evaluate to the same instance, +All occurrences of \code{\#\_\id} \emph{in the same library} evaluate to the same instance, and no other symbol literals evaluate to that \code{Symbol} instance or to a \code{Symbol} instance that is \code{==} to that instance. -\LMHash{} +\LMHash{}% The objects created by symbol literals all override the \code{==} operator inherited from the \code{Object} class. @@ -4988,20 +5130,21 @@ Providing a literal form for symbols makes reflective code easier to read and wr The fact that symbols are easy to type and can often act as convenient substitutes for enums are secondary benefits. } -\LMHash{} +\LMHash{}% The static type of a symbol literal is \code{Symbol}. \subsection{Lists} \LMLabel{lists} -\LMHash{} -A {\em list literal} denotes a list, which is an integer indexed collection of objects. +\LMHash{}% +A \IndexCustom{list literal}{literal!list} +denotes a list, which is an integer indexed collection of objects. \begin{grammar} ::= \CONST{}? ? `[' ( `,'?)? `]' \end{grammar} -\LMHash{} +\LMHash{}% A list may contain zero or more objects. The number of elements in a list is its size. A list has an associated set of indices. @@ -5009,14 +5152,18 @@ An empty list has an empty set of indices. A non-empty list has the index set $\{0, \ldots, n - 1\}$ where $n$ is the size of the list. It is a run-time error to attempt to access a list using an index that is not a member of its set of indices. -\LMHash{} -If a list literal begins with the reserved word \CONST{}, it is a {\em constant list literal} which is a constant expression (\ref{constants}) and therefore evaluated at compile time. -Otherwise, it is a {\em run-time list literal} and it is evaluated at run time. +\LMHash{}% +If a list literal begins with the reserved word \CONST{}, it is a +\IndexCustom{constant list literal}{literal!list!constant} +which is a constant expression (\ref{constants}) and therefore evaluated at compile time. +Otherwise, it is a +\IndexCustom{run-time list literal}{literal!list!run-time} +and it is evaluated at run time. Only run-time list literals can be mutated after they are created. Attempting to mutate a constant list literal will result in a dynamic error. -\LMHash{} +\LMHash{}% It is a compile-time error if an element of a constant list literal is not a constant expression. % Need 'free': `const (X))>[]` is OK, but `X` is not free. It is a compile-time error if the type argument of a constant list literal is or contains a free type variable. @@ -5024,7 +5171,7 @@ It is a compile-time error if the type argument of a constant list literal is or The binding of a type parameter is not known at compile time, so we cannot use type parameters inside constant expressions. } -\LMHash{} +\LMHash{}% The value of a constant list literal \code{\CONST{} <$E$>[$e_1, \ldots, e_n$]} is an object $a$ whose class implements the built-in class @@ -5035,7 +5182,7 @@ The value of a constant list literal is defined as the value of the constant list literal \code{\CONST{} <\DYNAMIC{}>[$e_1, \ldots, e_n$]}. -\LMHash{} +\LMHash{}% Let $list_1 =$ \code{\CONST{} <$V$>[$e_{11}, \ldots, e_{1n}$]} and @@ -5047,7 +5194,7 @@ If{}f \code{identical($o_{1i}$, $o_{2i}$)} for $i \in 1 .. n$ and $V = U$ then \ In other words, constant list literals are canonicalized. } -\LMHash{} +\LMHash{}% A run-time list literal \code{<$E$>[$e_1, \ldots, e_n$]} is evaluated as follows: @@ -5065,7 +5212,7 @@ $o_{i+1}, 0 \le i < n$. The result of the evaluation is $a$. \end{itemize} -\LMHash{} +\LMHash{}% The objects created by list literals do not override the \code{==} operator inherited from the \code{Object} class. @@ -5077,7 +5224,7 @@ if element $i$ is not a subtype of the element type of the list, a dynamic type error will occur when $a[i]$ is assigned $o_{i-1}$. } -\LMHash{} +\LMHash{}% A run-time list literal \code{[$e_1, \ldots, e_n$]} is evaluated as @@ -5091,13 +5238,13 @@ is a list with type parameter \code{List}, containing two lists with type parameter \code{int}. } -\LMHash{} +\LMHash{}% The static type of a list literal of the form \code{\CONST{} <$E$>[$e_1, \ldots, e_n$]} or the form \code{<$E$>[$e_1, \ldots, e_n$]} is \code{List<$E$>}. -The static type a list literal of the form +The static type of a list literal of the form \code{\CONST{} [$e_1, \ldots, e_n$]} or the form \code{[$e_1, \ldots, e_n$]} @@ -5107,8 +5254,8 @@ is \code{List<\DYNAMIC{}>}. \subsection{Maps} \LMLabel{maps} -\LMHash{} -A {\em map literal} denotes a map object. +\LMHash{}% +A \IndexCustom{map literal}{literal!map} denotes a map object. \begin{grammar} ::= \CONST{}? ? @@ -5117,18 +5264,22 @@ A {\em map literal} denotes a map object. ::= `:' \end{grammar} -\LMHash{} -A {\em map literal} consists of zero or more entries. -Each entry has a {\em key} and a {\em value}. +\LMHash{}% +A map literal consists of zero or more entries. +Each entry has a \Index{key} and a \Index{value}. Each key and each value is denoted by an expression. -\LMHash{} -If a map literal begins with the reserved word \CONST{}, it is a {\em constant map literal} which is a constant expression (\ref{constants}) and therefore evaluated at compile time. -Otherwise, it is a {\em run-time map literal} and it is evaluated at run time. +\LMHash{}% +If a map literal begins with the reserved word \CONST{}, it is a +\IndexCustom{constant map literal}{literal!map!constant} +which is a constant expression (\ref{constants}) and therefore evaluated at compile time. +Otherwise, it is a +\IndexCustom{run-time map literal}{literal!map!run-time} +and it is evaluated at run time. Only run-time map literals can be mutated after they are created. Attempting to mutate a constant map literal will result in a dynamic error. -\LMHash{} +\LMHash{}% It is a compile-time error if either a key or a value of an entry in a constant map literal is not a constant expression. It is a compile-time error if the key of an entry in a constant map literal is an instance of a class that has a concrete operator \syntax{`=='} declaration different from the one in \code{Object}, @@ -5142,7 +5293,7 @@ a constant invocation of a constructor of the \code{Symbol} class. It is a compile-time error if a type argument of a constant map literal is or contains a free type variable. -\LMHash{} +\LMHash{}% The value of a constant map literal \code{\CONST{} <$K, V$>\{$k_1:e_1, \ldots, k_n:e_n$\}} is an object $m$ whose class implements the built-in class @@ -5153,7 +5304,7 @@ The value of a constant map literal is defined as the value of a constant map literal \code{\CONST{} <\DYNAMIC{}, \DYNAMIC{}>\{$k_1:e_1, \ldots, k_n:e_n$\}}. -\LMHash{} +\LMHash{}% Let $map_1 =$ \code{\CONST{} <$K, V$>\{$k_{11}:e_{11}, \ldots, k_{1n}:e_{1n}$\}} and @@ -5166,7 +5317,7 @@ If{}f \code{identical($o_{1i}$, $o_{2i}$)} and \code{identical($s_{1i}$, $s_{2i} In other words, constant map literals are canonicalized. } -\LMHash{} +\LMHash{}% A run-time map literal \code{<$K, V$>\{$k_1:e_1, \ldots, k_n:e_n$\}} is evaluated as follows: @@ -5184,21 +5335,21 @@ The operator \syntax{`[]='} is invoked on $m$ with first argument $u_i$ and seco The result of the evaluation is $m$. \end{itemize} -\LMHash{} +\LMHash{}% The objects created by map literals do not override the \code{==} operator inherited from the \code{Object} class. -\LMHash{} +\LMHash{}% A run-time map literal \code{\{$k_1:e_1, \ldots, k_n:e_n$\}} is evaluated as \code{<\DYNAMIC{}, \DYNAMIC{}>\{$k_1:e_1, \ldots, k_n:e_n$\}}. -\LMHash{} +\LMHash{}% It is a compile-time error if two keys of a constant map literal are equal. -\LMHash{} +\LMHash{}% A map literal is ordered: iterating over the keys and/or values of the maps always happens in the order the keys appeared in the source code. @@ -5206,7 +5357,7 @@ A map literal is ordered: iterating over the keys and/or values of the maps alwa Of course, if a key repeats, the order is defined by first occurrence, but the value is defined by the last. } -\LMHash{} +\LMHash{}% The static type of a map literal of the form \code{\CONST{} <$K, V$>\{$k_1:e_1, \ldots, k_n:e_n$\}} or the form @@ -5223,8 +5374,8 @@ or the form \subsection{Throw} \LMLabel{throw} -\LMHash{} -The {\em throw expression} is used to throw an exception. +\LMHash{}% +The \Index{throw expression} is used to throw an exception. \begin{grammar} ::= \THROW{} @@ -5232,43 +5383,44 @@ The {\em throw expression} is used to throw an exception. ::= \THROW{} \end{grammar} -\LMHash{} +\LMHash{}% Evaluation of a throw expression of the form \code{\THROW{} $e$;} proceeds as follows: -\LMHash{} +\LMHash{}% The expression $e$ is evaluated to a value $v$ (\ref{evaluation}). \commentary{ There is no requirement that the expression $e$ must evaluate to any special kind of object. } -\LMHash{} +\LMHash{}% If $v$ is the null object (\ref{null}), then a \code{NullThrownError} is thrown. Otherwise let $t$ be a stack trace corresponding to the current execution state, and the \THROW{} statement throws with $v$ as exception object and $t$ as stack trace (\ref{evaluation}). -\LMHash{} +\LMHash{}% If $v$ is an instance of class \code{Error} or a subclass thereof, and it is the first time that \code{Error} object is thrown, the stack trace $t$ is stored on $v$ so that it will be returned by the $v$'s \code{stackTrace} getter \commentary{ -If the same \code{Error} object is thrown more than once, its \code{stackTrace} getter will return the stack trace from the {\em first} time it was thrown. +If the same \code{Error} object is thrown more than once, its \code{stackTrace} getter will return the stack trace from the \emph{first} time it was thrown. } -\LMHash{} +\LMHash{}% The static type of a throw expression is $\bot$. \subsection{Function Expressions} \LMLabel{functionExpressions} -\LMHash{} +\LMHash{}% %% TODO(eernst): A function literal is a syntactic construct, and we may use %% function closurization to obtain a corresponding function object. -A {\em function literal} is an object that encapsulates an executable unit of code. +A \IndexCustom{function literal}{literal!function} +is an object that encapsulates an executable unit of code. \begin{grammar} ::= @@ -5285,10 +5437,10 @@ A {\em function literal} is an object that encapsulates an executable unit of co %% actually used to select the function literal signature must be described %% specifically for each relevant type of situation. -\LMHash{} +\LMHash{}% The class of a function literal implements the built-in class \FUNCTION{}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5304,7 +5456,7 @@ is %% TODO[inference]: The static type of the function literal may come from context. where $T_0$ is the static type of $e$. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5321,7 +5473,7 @@ is \noindent where $T_0$ is the static type of $e$. -\LMHash{} +\LMHash{}% In the previous two paragraphs, the type argument lists are omitted in the case where $m = 0$, and \flatten{T} is defined as follows: \begin{itemize} @@ -5350,7 +5502,7 @@ Then $\flatten{T} = S$. \item In any other circumstance, $\flatten{T} = T$. \end{itemize} -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5365,7 +5517,7 @@ is \noindent where $T_0$ is the static type of $e$. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1 B_1, \ldots,\ X_m B_m$>} @@ -5382,7 +5534,7 @@ is \noindent where $T_0$ is the static type of $e$. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5394,7 +5546,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ [$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$]) $ \rightarrow$ \DYNAMIC{}}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5406,7 +5558,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ [$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$]) $ \rightarrow$ Future}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5418,7 +5570,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ [$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$]) $ \rightarrow$ Stream}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5430,7 +5582,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ [$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$]) $ \rightarrow$ Iterable}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5442,7 +5594,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ [$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$]) $ \rightarrow$ \DYNAMIC{}}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5454,7 +5606,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ \{$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$\}) $ \rightarrow$ Future}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5466,7 +5618,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ \{$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$\}) $ \rightarrow$ Stream}. -\LMHash{} +\LMHash{}% The static type of a function literal of the form \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>} @@ -5478,7 +5630,7 @@ is \code{<$X_1\ B_1, \ldots,\ X_m\ B_m$>($T_1, \ldots,\ T_n, $ \{$T_{n+1}\ x_{n+1}, \ldots,\ T_{n+k}\ x_{n+k}$\}) $ \rightarrow$ Iterable}. -\LMHash{} +\LMHash{}% In all of the above cases, the type argument lists are omitted when $m=0$, and whenever $T_i, 1 \le i \le n+k$, is not specified, @@ -5488,28 +5640,28 @@ it is considered to have been specified as \DYNAMIC{}. \subsection{This} \LMLabel{this} -\LMHash{} +\LMHash{}% The reserved word \THIS{} denotes the target of the current instance member invocation. \begin{grammar} ::= \THIS{} \end{grammar} -\LMHash{} +\LMHash{}% The static type of \THIS{} is the interface of the immediately enclosing class. \commentary{ We do not support self-types at this point. } -\LMHash{} +\LMHash{}% It is a compile-time error if \THIS{} appears, implicitly or explicitly, in a top-level function or variable initializer, in a factory constructor, or in a static method or variable initializer, or in the initializer of an instance variable. \subsection{Instance Creation} \LMLabel{instanceCreation} -\LMHash{} +\LMHash{}% Instance creation expressions generally produce instances and invoke constructors to initialize them. @@ -5526,7 +5678,7 @@ the factory constructor invocation. %It is a compile-time error if a constructor of a non-generic type invoked by a new expression or a constant object expression is passed any type arguments. It is a compile-time error if a constructor of a generic type with $n$ type parameters invoked by a new expression or a constant object expression is passed $m$ type arguments where $m \ne n$, or if any of its type arguments is misconstructed (\ref{parameterizedTypes}). -\LMHash{} +\LMHash{}% It is a compile-time error if the type $T$ in an instance creation expression of one of the forms @@ -5547,14 +5699,14 @@ or is an enumerated type (\ref{enums}). \subsubsection{New} \LMLabel{new} -\LMHash{} -The {\em new expression} invokes a constructor (\ref{constructors}). +\LMHash{}% +The \Index{new expression} invokes a constructor (\ref{constructors}). \begin{grammar} ::= \NEW{} (`.' )? \end{grammar} -\LMHash{} +\LMHash{}% Let $e$ be a new expression of the form \code{\NEW{} $T$.\id($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} @@ -5562,7 +5714,7 @@ or the form \code{\NEW{} $T$($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)}. -\LMHash{} +\LMHash{}% It is a compile-time error if $T$ is not a class or a parameterized type accessible in the current scope, or if $T$ is a parameterized type which is not a class. @@ -5570,7 +5722,7 @@ or if $T$ is a parameterized type which is not a class. For instance, \code{\NEW{} F()} is an error if \code{F} is a type alias. } -\LMHash{} +\LMHash{}% If $T$ is a parameterized type (\ref{parameterizedTypes}) \code{$S$<$U_1, \ldots,\ U_m$>}, let $R$ be the generic class $S$, @@ -5592,10 +5744,10 @@ If $T$ is not a parameterized type, let $R$ be $T$. a constructor declared by $R$. \end{itemize} -\LMHash{} +\LMHash{}% Let $q$ be the above-mentioned constructor named \code{$R$.\id} or $R$. -\LMHash{} +\LMHash{}% It is a compile-time error if $R$ is abstract and $q$ is not a factory constructor. It is a compile-time error if $R$ is a non-generic class @@ -5612,7 +5764,7 @@ $T$ is a parameterized type, and $T$ is not regular-bounded (\ref{superBoundedTypes}). -\LMHash{} +\LMHash{}% If $q$ is a redirecting factory constructor, it is a compile-time error if $q$ in some number of redirecting factory redirections redirects to itself. @@ -5625,7 +5777,7 @@ Only loops that consist exclusively of redirecting factory redirections are detected at compile time. } -\LMHash{} +\LMHash{}% Let $S_i$ be the static type of the formal parameter of the constructor \code{$R$.\id} (respectively $R$) corresponding to the actual argument $a_i$, $i \in 1 .. n+k$. @@ -5636,13 +5788,13 @@ is not assignable to $[U_1/X_1, \ldots, U_m/X_m]S_i$. The non-generic case is covered with $m = 0$. } -\LMHash{} +\LMHash{}% The static type of $e$ is $T$. -\LMHash{} +\LMHash{}% Evaluation of $e$ proceeds as follows: -\LMHash{} +\LMHash{}% First, the argument part \code{<$U_1, \ldots,\ U_m$>($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} @@ -5660,11 +5812,11 @@ the run-time type of $o_j$ is not a subtype of $[u_1/X_1, \ldots, u_m/X_m]S_j$, a dynamic type error occurs. -\LMHash{} +\LMHash{}% \Case{Non-loaded deferred constructors} If $T$ is a deferred type with prefix $p$, then if $p$ has not been successfully loaded, a dynamic error occurs. -\LMHash{} +\LMHash{}% \Case{Generative constructors} When $q$ is a generative constructor (\ref{generativeConstructors}) @@ -5680,13 +5832,13 @@ the bindings that resulted from the evaluation of the argument list, and, if $R$ is a generic class, with its type parameters bound to $u_1, \ldots, u_m$. -\LMHash{} +\LMHash{}% If execution of $q$ completes normally (\ref{completion}), $e$ evaluates to $i$. Otherwise execution of $q$ throws an exception object $x$ and stack trace $t$, and then evaluation of $e$ also throws exception object $x$ and stack trace $t$ (\ref{evaluation}). -\LMHash{} +\LMHash{}% \Case{Redirecting factory constructors} When $q$ is a redirecting factory constructor (\ref{factories}) @@ -5703,7 +5855,7 @@ $X_j$ is bound to $u_j$ for $j \in 1 .. m$. We need access to the type variables because $c$ may contain them. } -\LMHash{} +\LMHash{}% \Case{Non-redirecting factory constructors} When $q$ is a non-redirecting factory constructor, the body of $q$ is executed with respect to @@ -5726,15 +5878,15 @@ as it will either produce a valid instance or throw. \subsubsection{Const} \LMLabel{const} -\LMHash{} -A {\em constant object expression} invokes a constant constructor +\LMHash{}% +A \Index{constant object expression} invokes a constant constructor (\ref{constantConstructors}). \begin{grammar} ::= \CONST{} (`.' )? \end{grammar} -\LMHash{} +\LMHash{}% Let $e$ be a constant object expression of the form \code{\CONST{} $T$.\id($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} @@ -5742,7 +5894,7 @@ or the form \code{\CONST{} $T$($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)}. -\LMHash{} +\LMHash{}% It is a compile-time error if $T$ is not a class or a parameterized type accessible in the current scope, or if $T$ is a parameterized type which is not a class. @@ -5752,11 +5904,11 @@ It is a compile-time error if $T$ is a deferred type In particular, $T$ must not be a type variable. } -\LMHash{} +\LMHash{}% It is a compile-time error if $a_i$ is not a constant expression for some $i \in 1 .. n + k$. -\LMHash{} +\LMHash{}% If $T$ is a parameterized type (\ref{parameterizedTypes}) \code{$S$<$U_1, \ldots,\ U_m$>}, let $R$ be the generic class $S$, @@ -5765,7 +5917,7 @@ and let be the formal type parameters of $S$. If $T$ is not a parameterized type, let $R$ be $T$. -\LMHash{} +\LMHash{}% If $T$ is a parameterized type, it is a compile-time error if $U_j$ contains a type variable for any $j \in 1 .. m$. @@ -5783,14 +5935,14 @@ $j \in 1 .. m$. a constant constructor declared by $R$. \end{itemize} -\LMHash{} +\LMHash{}% Let $q$ be the above-mentioned constant constructor named \code{$R$.\id} or $R$. %% TODO(eernst): These errors are the same as with `new`. Can we avoid %% stating them twice? We'd need to refer to an awkwardly shaped portion %% of text in the previous subsection, or just loosely say "exactly the %% same errors".. -\LMHash{} +\LMHash{}% It is a compile-time error if $R$ is abstract and $q$ is not a factory constructor. It is a compile-time error if $R$ is a non-generic class @@ -5807,7 +5959,7 @@ $T$ is a parameterized type, and $T$ is not regular-bounded (\ref{superBoundedTypes}). -\LMHash{} +\LMHash{}% Let $S_i$ be the static type of the formal parameter of the constructor \code{$R$.\id} (respectively $R$) corresponding to the actual argument $a_i$, $i \in 1 .. n+k$. @@ -5818,13 +5970,13 @@ is not assignable to $[U_1/X_1, \ldots, U_m/X_m]S_i$. The non-generic case is covered with $m = 0$. } -\LMHash{} +\LMHash{}% The static type of $e$ is $T$. -\LMHash{} +\LMHash{}% Evaluation of $e$ proceeds as follows: -\LMHash{} +\LMHash{}% If $e$ is of the form \code{\CONST{} $T$.\id($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)} let $i$ be the value of the expression $e'$: @@ -5840,7 +5992,7 @@ by canonicalization as described below. This means that the value is well-defined. } -\LMHash{} +\LMHash{}% If $e$ is of the form \code{\CONST{} $T$($a_1, \ldots,\ a_n,\ x_{n+1}$: $a_{n+1}, \ldots,\ x_{n+k}$: $a_{n+k}$)}, let $i$ be the value of @@ -5849,7 +6001,7 @@ let $i$ be the value of Which is well-defined for the same reason. } -\LMHash{} +\LMHash{}% \begin{itemize} \item If during execution of the program, a constant object expression has already evaluated to @@ -5877,7 +6029,7 @@ the execution of the constructor is unobservable. The constructor need only be executed once per call site, at compile time. } -\LMHash{} +\LMHash{}% It is a compile-time error if evaluation of a constant object results in an uncaught exception being thrown. @@ -5919,11 +6071,11 @@ the evaluation of constant expressions. \subsection{Spawning an Isolate} \LMLabel{spawningAnIsolate} -\LMHash{} +\LMHash{}% Spawning an isolate is accomplished via what is syntactically an ordinary library call, invoking one of the functions \code{spawnUri()} or \code{spawn()} defined in the \code{dart:isolate} library. However, such calls have the semantic effect of creating a new isolate with its own memory and thread of control. -\LMHash{} +\LMHash{}% An isolate's memory is finite, as is the space available to its thread's call stack. It is possible for a running isolate to exhaust its memory or stack, resulting in a run-time error that cannot be effectively caught, which will force the isolate to be suspended. @@ -5935,7 +6087,7 @@ As discussed in section \ref{errorsAndWarnings}, the handling of a suspended iso \subsection{Function Invocation} \LMLabel{functionInvocation} -\LMHash{} +\LMHash{}% Function invocation occurs in the following cases: when a function expression (\ref{functionExpressions}) is invoked (\ref{functionExpressionInvocation}), when a method (\ref{methodInvocation}), getter (\ref{topLevelGetterInvocation}, \ref{propertyExtraction}) or setter (\ref{assignment}) is invoked, @@ -5947,11 +6099,11 @@ formal type parameters of $f$ are bound to the corresponding actual type argumen and the formal parameters of $f$ are bound to corresponding actual arguments. When the body of $f$ is executed it will be executed with the aforementioned bindings. -\LMHash{} +\LMHash{}% Executing a body of the form \code{=> $e$} is equivalent to executing a body of the form \code{\{ return $e$; \}}. Execution a body of the form \code{\ASYNC{} => $e$} is equivalent to executing a body of the form \code{\ASYNC{} \{ return $e$; \}}. -\LMHash{} +\LMHash{}% If $f$ is synchronous and is not a generator (\ref{functions}) then execution of the body of $f$ begins immediately. If the execution of the body of $f$ returns a value, $v$, (\ref{completion}), the invocation evaluates to $v$. If the execution completes normally or it returns without a value, the invocation evaluates to the null object (\ref{null}). @@ -5964,7 +6116,7 @@ This means that a function body can only either complete normally, throw, or ret Completing normally or returning without a value is treated the same as returning the null object (\ref{null}), so the result of executing a function body can always be used as the result of evaluating an expression, either by evaluating to a value or by the evaluation throwing. } -\LMHash{} +\LMHash{}% If $f$ is marked \code{\SYNC*} (\ref{functions}), then a fresh instance (\ref{generativeConstructors}) $i$ implementing \code{Iterable<$U$>} is immediately returned, @@ -5979,7 +6131,7 @@ A typical strategy would be to produce an instance of a subclass of class \code{ The only method that needs to be added by the Dart implementation in that case is \code{iterator}. } -\LMHash{} +\LMHash{}% The iterable implementation must comply with the contract of \code{Iterable} and should not take any steps identified as exceptionally efficient in that contract. \commentary{ @@ -5990,7 +6142,7 @@ This is certainly true in the case of a synchronous generator, where each elemen It would not be acceptable to pre-compute the results of the generator and cache them, for example. } -\LMHash{} +\LMHash{}% When iteration over the iterable is started, by getting an iterator $j$ from the iterable and calling \code{moveNext()}, execution of the body of $f$ will begin. When execution of the body of $f$ completes (\ref{completion}), \begin{itemize} @@ -6013,14 +6165,14 @@ In particular, it should handle multiple simultaneous iterators gracefully. If the iterator depends on external state that might change, it should check that the state is still valid after every yield (and maybe throw a \code{ConcurrentModificationError} if it isn't). } -\LMHash{} +\LMHash{}% Each iterator runs with its own shallow copies of all local variables; in particular, each iterator has the same initial arguments, even if their bindings are modified by the function. \commentary{ Two executions of an iterator interact only via state outside the function. } % The alternative would be to cache the results of an iterator in the iterable, and check the cache at each \YIELD{}. This would have strange issues as well. The yielded value might differ from the expression in the yield. And it is a potential memory leak as the cache is kept alive by any iterator. -\LMHash{} +\LMHash{}% If $f$ is marked \ASYNC{} (\ref{functions}), then a fresh instance (\ref{generativeConstructors}) $o$ is associated with the invocation, where the dynamic type of $o$ implements \code{Future<$flatten(T)$>}, @@ -6039,10 +6191,10 @@ If execution of the body throws before the body suspends the first time, completion of $o$ happens at some future time after the invocation has returned. \rationale{ The caller needs time to set up error handling for the returned future, -so the future is not completed with an error {\em before} it has been returned. +so the future is not completed with an error \emph{before} it has been returned. } -\LMHash{} +\LMHash{}% If $f$ is marked \code{\ASYNC*} (\ref{functions}), then a fresh instance (\ref{generativeConstructors}) $s$ implementing \code{Stream<$U$>} is immediately returned, @@ -6071,14 +6223,14 @@ When an asynchronous generator's stream has been canceled, cleanup will occur in We choose to direct any exceptions that occur at this time to the cancellation future rather than have them be lost. } -%\LMHash{} +%\LMHash{}% %When a stream is canceled, the implementation must wait for the cancelation future returned by \code{cancell()} to complete before proceeding. \subsubsection{Actual Argument Lists} \LMLabel{actualArgumentLists} -\LMHash{} +\LMHash{}% Actual argument lists have the following syntax: \begin{grammar} @@ -6090,20 +6242,20 @@ Actual argument lists have the following syntax: ::=