Skip to content

Commit 94a0fcd

Browse files
bishaboshasjrd
bishabosha
authored and
sjrd
committed
apply enums/desugarEnums.md
1 parent 4717553 commit 94a0fcd

File tree

2 files changed

+255
-230
lines changed

2 files changed

+255
-230
lines changed

‎docs/_spec/05-classes-and-objects.md

Lines changed: 255 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ The list of parents of a template must be well-formed.
4141
This means that the class denoted by the superclass constructor ´sc´ must be a subclass of the superclasses of all the traits ´mt_1, ..., mt_n´.
4242
In other words, the non-trait classes inherited by a template form a chain in the inheritance hierarchy which starts with the template's superclass.
4343

44+
It is forbidden for a template's superclass constructor ´sc´ to be an [enum class](#enum-definitions), unless the template is the implementation of an [enum case](#enum-definitions) of ´sc´.
45+
4446
The _least proper supertype_ of a template is the class type or [compound type](03-types.html#compound-types) consisting of all its parent class types.
4547

4648
The statement sequence ´\mathit{stats}´ contains member definitions that define new members or overwrite members in the parent classes.
@@ -811,32 +813,207 @@ EnumDef ::= id ClassConstr [‘extends’ [ConstrApps]] EnumBody
811813
EnumBody ::= [nl] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
812814
EnumStat ::= TemplateStat
813815
| {Annotation [nl]} {Modifier} EnumCase
816+
EnumCase ::= ‘case’ (id ClassConstr [‘extends’ ConstrApps] | ids)
814817
```
815818

816-
### Enum Cases
817-
<!-- TODO: Agree with NTs of rest of spec -->
818-
```ebnf
819-
EnumCase ::= ‘case’ (id ClassConstr [‘extends’ ConstrApps] | ids)
819+
An _enum definition_ implies the definition of an _enum class_, a companion object, and one or more _enum cases_.
820+
821+
Enum definitions are useful to encode both Generalised Algebraic Data Types and Enumerated Types.
822+
823+
The compiler expands enum definitions to code that only uses Scala's other language features.
824+
As such, enum definitions in Scala are convenient _syntactic sugar_, but they are not essential to understand Scala's core.
825+
826+
We now explain the expansion of enum definitions in detail.
827+
First, some terminology and notational conventions:
828+
829+
- We use ´E´ as a name of an enum definition, and ´C´ as a name of an enum case that appears in ´E´.
830+
- We use `<...>` for syntactic constructs that in some circumstances might be empty.
831+
For instance, `<value-params>` represents one or more parameter lists `(´\mathit{ps}_1\,´)...(´\mathit{ps}_n´)` or nothing at all.
832+
- Enum classes fall into two categories:
833+
- _parameterized_ enum classes have at least one of the following:
834+
- a type parameter section, denoted as `[´\mathit{tps}\,´]`;
835+
- one or more (possibly empty) parameter sections, denoted as `(´\mathit{ps}_1\,´)...(´\mathit{ps}_n´)`.
836+
- _unparameterized_ enum classes have no type parameter sections and no parameter sections.
837+
- Enum cases fall into three categories:
838+
839+
- _Class cases_ are those cases that are parameterized, either with a type parameter section `[´\mathit{tps}\,´]` or with one or more (possibly empty) parameter sections `(´\mathit{ps}_1\,´)...(´\mathit{ps}_n´)`.
840+
- _Simple cases_ are cases of an unparameterized enum that have neither parameters nor an extends clause or body.
841+
That is, they consist of a name only.
842+
- _Value cases_ are all cases that do not have a parameter section but that do have a (possibly generated) `extends` clause and/or a body.
843+
844+
- Simple cases and value cases are collectively called _singleton cases_.
845+
846+
###### Example
847+
848+
An example enum for a `Planet` enumeration can be given as
849+
```scala
850+
enum Planet(mass: Double, radius: Double):
851+
case Mercury extends Planet(3.303e+23, 2.4397e6)
852+
case Venus extends Planet(4.869e+24, 6.0518e6)
853+
case Earth extends Planet(5.976e+24, 6.37814e6)
854+
case Mars extends Planet(6.421e+23, 3.3972e6)
855+
case Jupiter extends Planet(1.9e+27, 7.1492e7)
856+
case Saturn extends Planet(5.688e+26, 6.0268e7)
857+
case Uranus extends Planet(8.686e+25, 2.5559e7)
858+
case Neptune extends Planet(1.024e+26, 2.4746e7)
859+
860+
private inline val G = 6.67300E-11
861+
def surfaceGravity = G * mass / (radius * radius)
862+
def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity
863+
end Planet
820864
```
821865

822-
<!-- TODO: an enum case is defined in terms of other scala constructs... -->
866+
###### Example
867+
868+
An example enum for the Option ADT can be given as
869+
```scala
870+
enum Option[+T]:
871+
case Some(x: T)
872+
case None
873+
```
823874

824875
### Lowering of Enum Definitions
825876

826-
Enums are represented as `sealed` classes that extend the `scala.reflect.Enum` trait.
827-
This trait defines a single public method, `ordinal`:
877+
###### Summary
878+
An enum class is represented as a `sealed` class that extends the `scala.reflect.Enum` trait.
879+
880+
Enum cases are represented as follows:
881+
- a class case is mapped to a `case class`,
882+
- a singleton case is mapped to a `val` definition, where
883+
- Simple cases all share a single implementation class.
884+
- Value cases will each be implemented by a unique class.
828885

886+
###### Precise rules
887+
The `scala.reflect.Enum` trait defines a single public method, `ordinal`:
829888
```scala
830889
package scala.reflect
831890

832891
transparent trait Enum extends Any, Product, Serializable:
833892

834893
def ordinal: Int
835894
```
895+
There are nine desugaring rules.
896+
Rule (1) desugars enum definitions.
897+
Rules (2) and (3) desugar simple cases.
898+
Rules (4) to (6) define `extends` clauses for cases that are missing them.
899+
Rules (7) to (9) define how such cases with `extends` clauses map into `case class`es or `val`s.
836900

837-
Simple enum cases all share a single implementation class.
901+
1. An `enum` definition
902+
```scala
903+
enum ´E´ ... { <defs> <cases> }
904+
```
905+
expands to a `sealed abstract` class that extends the `scala.reflect.Enum` trait and an associated companion object that contains the defined cases, expanded according to rules (2 - 8).
906+
The enum class starts with a compiler-generated import that imports the names `<caseIds>` of all cases so that they can be used without prefix in the class.
907+
```scala
908+
sealed abstract class ´E´ ... extends <parents> with scala.reflect.Enum {
909+
import ´E´.{ <caseIds> }
910+
<defs>
911+
}
912+
object ´E´ { <cases> }
913+
```
914+
915+
2. A singleton case consisting of a comma-separated list of enum names
916+
```scala
917+
case ´C_1´, ..., ´C_n´
918+
```
919+
expands to
920+
```scala
921+
case ´C_1´; ...; case ´C_n´
922+
```
923+
Any modifiers or annotations on the original case extend to all expanded cases.
924+
This result is then further rewritten by either (3 or 4).
925+
926+
3. A singleton case without an extends clause
927+
```scala
928+
case ´C´
929+
```
930+
of an unparameterized enum `´E´` expands to the following simple enum case in `´E´`'s companion object:
931+
```scala
932+
val ´C´ = $new(n, "C")
933+
```
934+
Here, `$new` is a private method that creates an instance of ´E´ (see below).
935+
936+
4. A singleton case without an extends clause
937+
```scala
938+
case ´C´
939+
```
940+
of an enum `´E´` with type parameters
941+
```scala
942+
´\mathit{v}_1´ ´T_1´ >: ´L_1´ <: ´U_1´ , ... , ´\mathit{v}_n´ ´T_n´ >: ´L_n´ <: ´U_n´ (n > 0)
943+
```
944+
where each of the variances `´\mathit{v}_i´` is either `'+'` or `'-'`, expands to the following value enum case:
945+
```scala
946+
case ´C´ extends ´E´[´B_1´, ..., ´B_n´]
947+
```
948+
where `´B_i´` is `´L_i´` if `´\mathit{v}_i´ = '+'` and `´U_i´` if `´\mathit{v}_i´ = '-'`.
949+
This result is then further rewritten with rule (8).
950+
**NOTE:** It is not permitted for enums with non-variant type parameters to have singleton cases without an extends clause.
951+
952+
5. A class case without an extends clause
953+
```scala
954+
case ´C´ <type-params> <value-params>
955+
```
956+
of an enum `´E´` that does not take type parameters expands to
957+
```scala
958+
case ´C´ <type-params> <value-params> extends ´E´
959+
```
960+
This result is then further rewritten with rule (9).
961+
962+
6. If `´E´` is an enum with type parameters `´\mathit{tps}´`, a class case with neither type parameters nor an extends clause
963+
```scala
964+
case ´C´ <value-params>
965+
```
966+
expands to
967+
```scala
968+
case ´C´[´\mathit{tps}´] <value-params> extends ´E´[´\mathit{tps}´]
969+
```
970+
This result is then further rewritten with rule (9).
971+
For class cases that have type parameters themselves, an extends clause needs to be given explicitly.
972+
973+
974+
7. If `´E´` is an enum with type parameters `´\mathit{tps}´`, a class case without type parameters but with an extends clause
975+
```scala
976+
case ´C´ <value-params> extends <parents>
977+
```
978+
expands to
979+
```scala
980+
case ´C´[´\mathit{tps}´] <value-params> extends <parents>
981+
```
982+
provided at least one of the parameters `´\mathit{tps}´` is mentioned in a parameter type in `<value-params>` or in a type argument in `<parents>`.
983+
984+
8. A value case
985+
```scala
986+
case ´C´ extends <parents>
987+
```
988+
expands to the following `val` definition in `´E´`'s companion object:
989+
```scala
990+
val ´C´ = new <parents> { <body>; def ordinal = ´\mathit{n}´ }
991+
```
992+
where `´\mathit{n}´` is the ordinal number of the case in the companion object, starting from 0.
993+
The anonymous class also implements the abstract `Product` methods that it inherits from `Enum`.
994+
**NOTE:** It is an error if a value case refers to a type parameter of `´E´` in a type argument within `<parents>`.
995+
996+
9. A class case
997+
```scala
998+
case ´C´ <type-params> <value-params> extends <parents>
999+
```
1000+
expands analogous to a final case class in `´E´`'s companion object:
1001+
```scala
1002+
final case class ´C´ <type-params> <value-params> extends <parents> {
1003+
def ordinal = ´\mathit{n}´
1004+
}
1005+
```
1006+
where `´\mathit{n}´` is the ordinal number of the case in the companion object, starting from 0.
1007+
**NOTE:** It is an error if a class case refers to a type parameter of `´E´` in a parameter type in `<type-params>` or `<value-params>` or in a type argument of `<parents>`, unless that parameter is already a type parameter of the case, i.e. the parameter name is defined in `<type-params>`.
1008+
1009+
###### Superclass of an enum case
1010+
1011+
an enum case (singleton or class) with explicit extends clause
1012+
```scala
1013+
case ´C´ <type-params> <value-params> extends <parents>
1014+
```
8381015

839-
Value enum cases will each be implemented by a unique class.
1016+
must extend the parent enum `´E´` as the first parent of `<parents>`.
8401017

8411018
###### Example
8421019
Consider the enumeration `RGB`, consisting of simple enum cases:
@@ -845,12 +1022,18 @@ enum RGB:
8451022
case Red, Green, Blue
8461023
```
8471024

848-
Each simple case `Red`, `Green`, and `Blue` will be instantiated using a private method that takes a tag and a name as arguments.
849-
850-
For instance, the first definition of value `Color.Red` above would expand to:
1025+
The three simple cases will expand as follows in the companion of `RGB`:
8511026

8521027
```scala
853-
val Red: Color = $new(0, "Red")
1028+
val Red = $new(0, "Red")
1029+
val Green = $new(1, "Green")
1030+
val Blue = $new(2, "Blue")
1031+
1032+
private def $new(_$ordinal: Int, $name: String) =
1033+
new RGB with scala.runtime.EnumValue:
1034+
def ordinal = _$ordinal
1035+
override def productPrefix = $name
1036+
override def toString = $name
8541037
```
8551038

8561039

@@ -864,15 +1047,72 @@ enum Color(val rgb: Int):
8641047
case Blue extends Color(0x0000FF)
8651048
```
8661049

867-
Each value case will expand as follows, for instance `Green` expands to
1050+
The three value cases will expand as follows in the companion of `Color`:
8681051

8691052
```scala
870-
val Green: Color = new Color(0x00FF00):
1053+
val Red = new Color(0xFF0000):
1054+
def ordinal: Int = 0
1055+
override def productPrefix: String = "Red"
1056+
override def toString: String = "Red"
1057+
val Green = new Color(0x00FF00):
8711058
def ordinal: Int = 1
8721059
override def productPrefix: String = "Green"
8731060
override def toString: String = "Green"
1061+
val Blue = new Color(0x0000FF):
1062+
def ordinal: Int = 2
1063+
override def productPrefix: String = "Blue"
1064+
override def toString: String = "Blue"
8741065
```
8751066

1067+
### Widening of enum cases post-construction
1068+
The compiler-generated `apply` and `copy` methods of an class enum case
1069+
```scala
1070+
case ´C´[´\mathit{tps}\,´](´\mathit{ps}_1\,´)...(´\mathit{ps}_n´) extends ´P_1´, ..., ´P_n´
1071+
```
1072+
are treated specially.
1073+
A call `´C´[´\mathit{tps}\,´](´\mathit{ps}_1\,´)...(´\mathit{ps}_n´)` of the `apply` method is ascribed the underlying type `´P_1´ & ... & ´P_n´` (dropping any [transparent traits](../other-new-features/transparent-traits.md)) as long as that type is still compatible with the expected type at the point of application.
1074+
A call `t.copy[´\mathit{tps}\,´](´\mathit{ps}_1\,´)...(´\mathit{ps}_n´)` of `´C´`'s `copy` method is treated in the same way.
1075+
1076+
### Translation of enums with only singleton cases
1077+
1078+
An enum `´E´` (possibly generic) that defines one or more singleton cases, and no class cases will define the following additional synthetic members in its companion object (where `´E'´` denotes `´E´` with any type parameters replaced by wildcards):
1079+
1080+
- A method `valueOf(name: String): ´E'´`.
1081+
It returns the singleton case value whose identifier is `name`.
1082+
- A method `values` which returns an `Array[´E'´]` of all singleton case values defined by `E`, in the order of their definitions.
1083+
1084+
### Factory method for simple enum cases
1085+
1086+
If an enum `´E´` contains at least one simple case, its companion object will define in addition:
1087+
1088+
- A private method `$new` which defines a new simple case value with given ordinal number and name.
1089+
This method can be thought as being defined as follows.
1090+
1091+
```scala
1092+
private def $new(_$ordinal: Int, $name: String): ´E´ with runtime.EnumValue
1093+
```
1094+
- `$new` returns a new instance of an anonymous class which implements the abstract `Product` methods that it inherits from `Enum`.
1095+
- if `´E´` inherits from `java.lang.Enum` the anonymous class does not override the `ordinal` or `toString` methods, as these are final in `java.lang.Enum`.
1096+
Additionally `productPrefix` will delegate to `this.name`.
1097+
1098+
### Translation of Java-compatible enums
1099+
1100+
A Java-compatible enum is an enum that extends `java.lang.Enum`.
1101+
The translation rules are the same as above, with the reservations defined in this section.
1102+
1103+
- It is a compile-time error for a Java-compatible enum to have class cases.
1104+
1105+
- Cases such as `case C` expand to a `@static val` as opposed to a `val`.
1106+
This allows them to be generated as static fields of the enum type, thus ensuring they are represented the same way as Java enums.
1107+
1108+
### Scopes for Enum Cases
1109+
1110+
A case in an `enum` is treated similarly to a secondary constructor.
1111+
It can access neither the enclosing `enum` using `this`, nor its value parameters or instance members using simple identifiers.
1112+
1113+
Even though translated enum cases are located in the enum's companion object, referencing this object or its members via `this` or a simple identifier is also illegal.
1114+
The compiler typechecks enum cases in the scope of the enclosing companion object but flags any such illegal accesses as errors.
1115+
8761116
### Variance for Type Parameters
8771117

8781118
A parameterized enum case ´C´ of enum ´E´ with _inferred_ type parameters will copy variance annotations.

0 commit comments

Comments
 (0)