From d26c089c4fd42c652a1959357c49592d46ce3d1a Mon Sep 17 00:00:00 2001 From: Som Snytt Date: Sun, 19 Dec 2021 18:59:39 -0800 Subject: [PATCH 1/2] Example accessing enum companion --- docs/_docs/reference/enums/enums.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/_docs/reference/enums/enums.md b/docs/_docs/reference/enums/enums.md index fda03d2dee81..715cc9009316 100644 --- a/docs/_docs/reference/enums/enums.md +++ b/docs/_docs/reference/enums/enums.md @@ -89,6 +89,31 @@ object Planet: end Planet ``` +As explained [later](./desugarEnums.md), enum cases are expanded in the companion object of the enum. +Even though the enum cases are written within the lexical scope of the enum template, they may not +reference members of the enum class. Like secondary constructors, although written inside the template, +they are scoped outside it. + +Similarly, they may not directly reference members of the companion object in which they expand. +They are like default class arguments, which are also expanded in the class's companion. For example: + +```scala +import Planet.* +enum Planet(mass: Double, radius: Double): + private final val (MercuryMass @ _, MercuryRadius @ _) = (3.303e+23, 2.4397e6) + + case Mercury extends Planet(MercuryMass, MercuryRadius) // Not found + case Venus extends Planet(VenusMass, VenusRadius) // illegal reference + case Earth extends Planet(Planet.EarthMass, Planet.EarthRadius) // ok +object Planet: + private final val (VenusMass @ _, VenusRadius @ _) = (4.869e+24, 6.0518e6) + private final val (EarthMass @ _, EarthRadius @ _) = (5.976e+24, 6.37814e6) +end Planet +``` +The fields for Mercury are not visible, and the fields for Venus may not be referenced directly. +Since the direct reference after expansion shadows any import clause, the import statement does not make the fields available. +Direct references using a renaming import are also disallowed. + ### Deprecation of Enum Cases As a library author, you may want to signal that an enum case is no longer intended for use. However you could still want to gracefully handle the removal of a case from your public API, such as special casing deprecated cases. From f00102caeb544531293c8f57a2ec82ddb2c41330 Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Wed, 23 Feb 2022 17:25:44 +0100 Subject: [PATCH 2/2] reword to avoid low level details --- docs/_docs/reference/enums/enums.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/_docs/reference/enums/enums.md b/docs/_docs/reference/enums/enums.md index 715cc9009316..134df4cd0f15 100644 --- a/docs/_docs/reference/enums/enums.md +++ b/docs/_docs/reference/enums/enums.md @@ -77,6 +77,7 @@ enum Planet(mass: Double, radius: Double): end Planet ``` +### User-defined companion object of enums It is also possible to define an explicit companion object for an enum: ```scala @@ -89,13 +90,15 @@ object Planet: end Planet ``` -As explained [later](./desugarEnums.md), enum cases are expanded in the companion object of the enum. -Even though the enum cases are written within the lexical scope of the enum template, they may not -reference members of the enum class. Like secondary constructors, although written inside the template, -they are scoped outside it. +### Restrictions on Enum Cases -Similarly, they may not directly reference members of the companion object in which they expand. -They are like default class arguments, which are also expanded in the class's companion. For example: +Enum case declarations are similar to secondary constructors: +they are scoped outside of the enum template, despite being declared within it. +This means that enum case declarations cannot access inner members of the +enum class. + +Similarly, enum case declarations may not directly reference members of the enum's companion object, +even if they are imported (directly, or by renaming). For example: ```scala import Planet.* @@ -110,9 +113,9 @@ object Planet: private final val (EarthMass @ _, EarthRadius @ _) = (5.976e+24, 6.37814e6) end Planet ``` -The fields for Mercury are not visible, and the fields for Venus may not be referenced directly. -Since the direct reference after expansion shadows any import clause, the import statement does not make the fields available. -Direct references using a renaming import are also disallowed. +The fields referenced by `Mercury` are not visible, and the fields referenced by `Venus` may not +be referenced directly (using `import Planet.*`). You must use an indirect reference, +such as demonstrated with `Earth`. ### Deprecation of Enum Cases