Enums.

docs/language/dartLangSpec.tex

 \documentclass{article}
 \usepackage{epsfig}
 \usepackage{dart}
 \usepackage{bnf}
 \usepackage{hyperref}
 \newcommand{\code}[1]{{\sf #1}}
 \title{Dart Programming Language  Specification \\
 {\large Version 1.6}}
 %\author{The Dart Team}
 \begin{document}
@@ skipping 1188 matching lines @@
 (respectively  \SUPER{}$.id(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$ 
 
 proceeds as follows:
 
 First, the argument list $(a_1, \ldots, a_n, x_{n+1}: a_{n+1}, \ldots, x_{n+k}: a_{n+k})$ is evaluated.
 
 Let $C$ be the class in which the superinitializer appears and let $S$ be the superclass of $C$.  If $S$ is generic (\ref{generics}), let $U_1, , \ldots, U_m$ be the actual type arguments passed to $S$ in the superclass clause of $C$.
 
 Then, the initializer list of the constructor $S$ (respectively $S.id$) is executed with respect to the bindings that resulted from the evaluation of the argument list,  with \THIS{} bound to the current binding of \THIS{}, and  the type parameters (if any) of class $S$ bound to the current bindings of $U_1, , \ldots, U_m$.
 
-It is a compile-time error if class $S$ does not declare a generative constructor named $S$ (respectively $S.id$)
+It is a compile-time error if class $S$ does not declare a generative constructor named $S$ (respectively $S.id$).
 
 \subsubsection{Factories}
 \label{factories}
 
 A {\em factory} is a constructor prefaced by the built-in identifier  (\ref{identifierReference})   \FACTORY{}. 
 
 \begin{grammar}
 {\bf factoryConstructorSignature:}
       \FACTORY{} identifier  (`{\escapegrammar .}' identifier)?  formalParameterList
     .
@@ skipping 283 matching lines @@
       \EXTENDS{} type
     .
 \end{grammar}
 
 %The superclass clause of a class C is processed within the enclosing scope of the static scope of C.
 %\commentary{
 %This means that in a generic class, the type parameters of the generic are available in the superclass clause.
 %} 
 
 %It is a compile-time error if  the \EXTENDS{} clause of a class $C$ includes a type expression that does not denote a class available in the lexical scope of $C$. 
-It is a compile-time error if  the \EXTENDS{} clause of a class $C$ specifies a malformed  type or a deferred type (\ref{staticTypes}) as a superclass.
+It is a compile-time error if  the \EXTENDS{} clause of a class $C$ specifies an enumerated type (\ref{enums}), a malformed  type or a deferred type (\ref{staticTypes}) as a superclass.
 % too strict? Do we e want extends List<Undeclared> to work as List<dynamic>? 
 
 \commentary{ The type parameters of a generic class are available in the lexical scope of the superclass clause, potentially shadowing classes in the surrounding scope. The following code is therefore illegal and should cause a compile-time error:
 }
 
 \begin{dartCode}
 class T \{\}
 
 /* Compilation error: Attempt to subclass a type parameter */
 class G$<$T$>$ extends T \{\} 
@@ skipping 102 matching lines @@
 
 A class has a set of direct superinterfaces. This set includes the interface of its superclass and the interfaces specified in the the \IMPLEMENTS{}  clause of the class.
 % and any superinterfaces specified by interface injection (\ref{interfaceInjection}).  \Q{The latter needs to be worded carefully - when do interface injection clauses execute and in what scope?}
 
 \begin{grammar}
 {\bf interfaces:}
       \IMPLEMENTS{} typeList
     .
 \end{grammar}
 
-It is a compile-time error if  the \IMPLEMENTS{}  clause of a class $C$ specifies a type variable as a superinterface. It is a compile-time error if  the  \IMPLEMENTS{} clause of a class $C$ specifies  a malformed type or deferred type (\ref{staticTypes}) as a superinterface  It is a compile-time error if the \IMPLEMENTS{} clause of a class $C$ specifies type \DYNAMIC{} as a superinterface. It is a compile-time error if  the  \IMPLEMENTS{} clause of a class $C$ specifies  a type $T$ as a superinterface more than once.
+It is a compile-time error if  the \IMPLEMENTS{}  clause of a class $C$ specifies a type variable as a superinterface. It is a compile-time error if  the  \IMPLEMENTS{} clause of a class $C$ specifies an enumerated type (\ref{enums}),  a malformed type or deferred type (\ref{staticTypes}) as a superinterface  It is a compile-time error if the \IMPLEMENTS{} clause of a class $C$ specifies type \DYNAMIC{} as a superinterface. It is a compile-time error if  the  \IMPLEMENTS{} clause of a class $C$ specifies  a type $T$ as a superinterface more than once.
 It is a compile-time error if the superclass of a class $C$ is specified as a superinterface of $C$.
 
 \rationale{
 One might argue that it is harmless to repeat a type in the superinterface list, so why make it an error? The issue is not so much that the situation described in program source is erroneous, but that it is pointless. 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.  Nevertheless, we could simply issue a warning; and perhaps we should and will. That said, problems like these are local and easily corrected on the spot, so we feel justified in taking a harder line. 
 }
 
 It is a compile-time error if the interface of a class $C$ is a superinterface of itself.
 
 Let $C$ be a concrete class that does not declare its own \code{noSuchMethod()} method.
 It is a static warning if the implicit interface of  $C$ includes an instance member $m$ of type $F$ and $C$ does not declare or inherit a corresponding non-abstract instance member $m$ of type $F'$ such that $F' <: F$. 
@@ skipping 170 matching lines @@
 
 In both cases above, $C$ declares the same instance members as $M$ (respectively, $M_k$). If any of the instance fields of $M$ (respectively, $M_k$) have initializers, they are executed in the scope of $M$ (respectively, $M_k$) to initialize the corresponding fields of $C$. 
 
 For each generative constructor named $q_i(T_{i1}$ $ a_{i1}, \ldots , T_{ik_i}$ $ a_{ik_i}), i \in 1..n$ of $S$, $C$ has an implicitly declared constructor named
 $q'_i = [C/S]q_i$ of the form 
 
 $q'_i(a_{i1}, \ldots , a_{ik_i}):\SUPER(a_{i1}, \ldots , a_{ik_i});$.
 
 If the mixin application declares support for interfaces, the resulting class implements those interfaces.
 
-It is a compile-time error if $S$ is a malformed type. It is a compile-time error if $M$ (respectively, any of $M_1, \ldots, M_k$) is 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$). 
+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$). 
 
 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 static warning if the declaration of $K$ would cause a static warning.  It is a compile-time error if the declaration of $K$ would cause a compile-time error.
 
 \commentary{
 If, for example, $M$ declares an instance member $im$ whose type is at odds with the type of a member of the same name in $S$, this will result in a static warning just as if we had defined $K$ by means of an ordinary class declaration extending $S$, with a body that included $im$.
 
 }
 
 The effect of a class definition of the form \code{\CLASS{} $C$ = $M$; } or the form 
  \code{\CLASS{} $C<T_1, \ldots, T_n>$ = $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$. The name of the class is also set to $C$. Iff the  class is prefixed by the built-in identifier \ABSTRACT{}, the class being defined is an abstract class.
@@ skipping 31 matching lines @@
 }
 
 Mixin composition is associative.
 
 
 \commentary{
 Note that any subset of $M_1$, $M_2$ and $S$ may or may not be generic. For any non-generic declaration, the corresponding type parameters may be elided, and if no type parameters remain in the derived declarations $Id_1$ and/or $Id_2$ then the those declarations need not be generic either.
 }
 
 
+\section{Enums}
+\label{enums}
+
+An {\em enumerated type}, or {\em enum}, is used to represent a fixed number of constant values.
+
+\begin{grammar}
+{\bf enumType:}
+metadata \ENUM{} id `\{' id [`,' id]* [`,'] `\}'
+    .
+\end{grammar}
+
+The declaration of an enum of the form \code{metadata \ENUM{} E \{ id$_1$, \ldots id$_n$\};}

[kasperl, 2014/08/19 05:04:35]

You could consider calling these id$_0$ to id$_{n-1}$ to avoid confusion with
the index.

[gbracha, 2014/08/19 17:54:40]

Done.

+has the same effect as a class declaration
+
+\begin{dartCode}
+metadata \CLASS{} E \{
+  \FINAL{} int index;
+  \FINAL{} String \_name;
+  \CONST{} E(\THIS{}.index,\THIS{}.\_name);
+  \STATIC{} \CONST{} E id$_1$ = \CONST{} E(0, `id$_1$');
+  $\ldots$
+  \STATIC{} \CONST{} E id$_n$ = const E(n - 1, `id$_{n-1}$');

[kasperl, 2014/08/19 05:04:35]

`id$_{n-1}$' should be `id$_n$'.

[gbracha, 2014/08/19 17:54:40]

Not anymore.

+
+  \STATIC{} \CONST{} List$<$E$>$ values = const $<$E$>$[id$_1 \ldots $ id$_n$];
+  String toString() =$>$ `E.\$\_name';
+\}
+\end{dartCode}
+
+
+
+It is compile-time error to access the private fields of an enumerated type anywhere outside its definition.

[kasperl, 2014/08/19 05:04:35]

How can we tell statically?

Is there any way we can specify it so that enums are conceptually in their own
library so the library privacy mechanism works for us? 

[gbracha, 2014/08/19 17:54:41]

The problem is that the surrounding library would have to have an import. Note
that nothing says you have to actually implement things using a _name field.
since the field is hidden everywhere including reflection. So  strictly
speaking, the spec is fine. It might be clearer to implementors if we did give
some suitable scheme in the spec - but it is all overspecification.

Anyway, the map idea works better, and eliminates the need for a special rule
etc. Much nicer.

+
+\commentary {
+It is also a compile-time error to subclass, mix-in or implement an enum or to explicitly instantiate an enum.  These restrictions are given in normative form in sections \ref{superclasses}, \ref{superinterfaces}, \ref{mixinApplication} and \ref{instanceCreation} as appropriate.
+
+All of these restrictions should be enforced by the implementation even in the case of reflection.
+}
+
+% should this be rephrased so that these rules go elsewhere (i.e., in the rules for new/const/extends/implements/with?)

[kasperl, 2014/08/19 05:04:35]

Haven't you already done so?

[gbracha, 2014/08/19 17:54:41]

Yes, I have. This is just an old comment. I'll get rid of it.

+
+
 \section{Generics}
 \label{generics}
 
 A class declaration (\ref{classes}) or type alias (\ref{typedef}) 
 $G$ may be {\em generic}, that is, $G$ may have formal type parameters declared. A generic declaration induces a family of declarations, one for each set of actual type parameters provided in the program. 
 
 \begin{grammar}
 {\bf typeParameter:}
      metadata identifier (\EXTENDS{} type)?
     .
@@ skipping 881 matching lines @@
 It is a static type warning if
 the type $T$ in an instance creation expression of one of  the forms 
 
 \NEW{} $T.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$,  
 
 \NEW{} $T(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$,
 
 \CONST{} $T.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$,  
 
 \CONST{} $T(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$ is malformed (\ref{dynamicTypeSystem}) or malbounded (\ref{parameterizedTypes}).
+
+It is a compile-time error if the type $T$ in an instance creation expression of one of  the forms 

[kasperl, 2014/08/19 05:04:35]

one of  the forms -> one of the forms (I know it will not be visible in the PDF
version, but anyway).

[gbracha, 2014/08/19 17:54:40]

Done.

+
+\NEW{} $T.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$,  
+
+\NEW{} $T(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$,
+
+\CONST{} $T.id(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$,  
+
+\CONST{} $T(a_1, \ldots , a_n, x_{n+1}: a_{n+1}, \ldots , x_{n+k}: a_{n+k})$ 
+
+is an enumerated type (\ref{enums}).
 %any of the type arguments to a constructor of a generic type $G$ invoked by a new expression or a constant object expression are not subtypes of the bounds of the corresponding formal type parameters of $G$.
 
 
 \subsubsection{ New}
 \label{new}
 
 The {\em new expression} invokes a constructor (\ref{constructors}).
 
 \begin{grammar}
 {\bf newExpression:}
@@ skipping 1862 matching lines @@
 \begin{dartCode}
 \SWITCH{} (x) \{
   \CASE{} 1: \TRY{} \{ $\ldots$ \RETURN{};\} \FINALLY{} \{ $\ldots$ \RETURN{};\}
 \}
 \end{dartCode}
 
 \rationale{
   Very elaborate code in a case clause is probably bad style in any case, and such code can always be refactored.
 }
  
+ It is a static warning if all of the following conditions hold:
+ \begin{itemize}
+\item  The switch statement does not have a default clause.
+ \item The static type of $e$ is an enumerated typed with elements $id_1, \ldots, id_n$.
+\item The sets $\{e_1, \ldots,  e_k\} $ and $\{id_1, \ldots, id_n\}$ are not the same.
+\end{itemize}
+
+\commentary{
+In other words, a warning will be issued if a switch statement over an enum is not exhaustive.
+}
+
  
 \subsection{ Rethrow}
 \label{rethrow}
 
 
 The {\em rethrow statement}  is used to re-raise an exception.
 
  \begin{grammar}
 {\bf rethrowStatement:}
      \RETHROW{}
@@ skipping 1387 matching lines @@
 \item The names of compile time constant variables never use lower case letters. If they consist of multiple words, those words are separated by underscores. Examples: PI,  I\_AM\_A\_CONSTANT.
 \item The names of functions (including getters, setters, methods and local or library functions) and non-constant variables begin with a lowercase letter. If the name consists of multiple words, each  word (except the first) begins with an uppercase letter.  No other uppercase letters are used. Examples: camlCase, dart4TheWorld
 \item The names of types (including classes and type aliases) begin with an upper case letter.  If the name consists of multiple words, each  word  begins with an uppercase letter.  No other uppercase letters are used. Examples: CamlCase, Dart4TheWorld.
 \item The names of type variables are short (preferably single letter). Examples: T, S, K, V , E.
 \item The names of libraries or library prefixes never use upper case letters. If they consist of multiple words, those words are separated by underscores. Example: my\_favorite\_library.
 \end{itemize}
 }
 
 
 \end{document}