1
1
---
2
2
layout : tour
3
- title : Package Objects
3
+ title : Top Level Definitions in Packages
4
4
partof : scala-tour
5
5
6
6
num : 36
7
7
previous-page : packages-and-imports
8
8
---
9
9
10
- # Package objects
10
+ Often, it is convenient to have definitions accessible accross an entire package, and not need to invent a
11
+ name for a wrapper ` object ` to contain them.
11
12
12
- Scala provides package objects as a convenient container shared across an entire package.
13
+ {% tabs pkg-obj-vs-top-lvl_1 class=tabs-scala-version %}
14
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_1 %}
15
+ Scala 2 provides _ package objects_ as a convenient container shared across an entire package.
13
16
14
17
Package objects
15
18
can contain arbitrary definitions, not just variable and method definitions. For instance, they are frequently
16
19
used to hold package-wide type aliases and implicit conversions. Package objects can even inherit
17
20
Scala classes and traits.
18
21
22
+ > In a future version of Scala 3, package objects will be removed in favor of top level definitions.
23
+
19
24
By convention, the source code for a package object is usually put in a source file named ` package.scala ` .
20
25
21
26
Each package is allowed to have one package object. Any definitions placed in a package object are considered
22
27
members of the package itself.
23
28
29
+ {% endtab %}
30
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_1 %}
31
+ In Scala 3, any kind of definition can be declared at the top level of a package. For example, classes, enums,
32
+ methods and variables.
33
+
34
+ Any definitions placed at the top level of a package are considered members of the package itself.
35
+
36
+ > In Scala 2 top-level method, type and variable definitions had to be wrapped in a ** package object** .
37
+ > These are still usable in Scala 3 for backwards compatibility. You can see how they work by switching tabs.
38
+ {% endtab %}
39
+ {% endtabs %}
40
+
24
41
See example below. Assume first a class ` Fruit ` and three ` Fruit ` objects in a package
25
42
` gardening.fruits ` :
26
43
44
+
45
+ {% tabs pkg-obj-vs-top-lvl_2 %}
46
+ {% tab 'Scala 2 and 3' for=pkg-obj-vs-top-lvl_2 %}
27
47
```
28
48
// in file gardening/fruits/Fruit.scala
29
49
package gardening.fruits
@@ -33,10 +53,15 @@ object Apple extends Fruit("Apple", "green")
33
53
object Plum extends Fruit("Plum", "blue")
34
54
object Banana extends Fruit("Banana", "yellow")
35
55
```
56
+ {% endtab %}
57
+ {% endtabs %}
36
58
37
59
Now assume you want to place a variable ` planted ` and a method ` showFruit ` directly into package ` gardening.fruits ` .
38
60
Here's how this is done:
39
61
62
+ {% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %}
63
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %}
64
+
40
65
```
41
66
// in file gardening/fruits/package.scala
42
67
package gardening
@@ -47,13 +72,29 @@ package object fruits {
47
72
}
48
73
}
49
74
```
75
+ {% endtab %}
76
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %}
77
+
78
+ ```
79
+ // in file gardening/fruits/package.scala
80
+ package gardening.fruits
81
+
82
+ val planted = List(Apple, Plum, Banana)
83
+ def showFruit(fruit: Fruit): Unit =
84
+ println(s"${fruit.name}s are ${fruit.color}")
85
+ ```
86
+ {% endtab %}
87
+ {% endtabs %}
50
88
51
- As an example of how to use this, the following object ` PrintPlanted ` imports ` planted ` and ` showFruit ` in exactly the same
52
- way it imports class ` Fruit ` , using a wildcard import on package gardening.fruits:
89
+ As an example of how to use this, the following program ` PrintPlanted ` imports ` planted ` and ` showFruit ` in exactly the same
90
+ way it imports class ` Fruit ` , using a wildcard import on package ` gardening.fruits ` :
53
91
92
+ {% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %}
93
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %}
54
94
```
55
95
// in file PrintPlanted.scala
56
96
import gardening.fruits._
97
+
57
98
object PrintPlanted {
58
99
def main(args: Array[String]): Unit = {
59
100
for (fruit <- planted) {
@@ -62,11 +103,53 @@ object PrintPlanted {
62
103
}
63
104
}
64
105
```
106
+ {% endtab %}
107
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %}
108
+ ```
109
+ // in file PrintPlanted.scala
110
+ import gardening.fruits.*
65
111
66
- Package objects are like other objects, which means you can use inheritance for building them. For example, one might mix in a couple of traits:
112
+ @main def PrintPlanted: Unit =
113
+ for fruit <- planted do
114
+ showFruit(fruit)
115
+ ```
116
+ {% endtab %}
117
+ {% endtabs %}
118
+
119
+ ### Aggregating Several Definitions at the Package Level
120
+
121
+ Often, your project may have several reusable definitions defined in various modules, that you
122
+ wish to aggregate at the top level of a package.
123
+
124
+ For example, some helper methods in the trait ` FruitHelpers ` and
125
+ some term/type aliases in trait ` FruitAliases ` . Here is how you can put all their definitions at the level of the ` fruit `
126
+ package:
127
+
128
+ {% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %}
129
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %}
130
+
131
+ Package objects are like other objects, which means you can use inheritance for building them.
132
+ So here we mix in the helper traits as parents of the package object.
67
133
68
134
```
69
- package object fruits extends FruitAliases with FruitHelpers {
70
- // helpers and variables follows here
71
- }
135
+ package gardening
136
+
137
+ // `fruits` instead inherits its members from its parents.
138
+ package object fruits extends FruitAliases with FruitHelpers
139
+ ```
140
+ {% endtab %}
141
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %}
142
+
143
+ In Scala 3, it is preferred to use ` export ` to compose members from several objects into a single scope.
144
+ Here we define private objects that mix in the helper traits, then export their members at the top level:
145
+
146
+ ```
147
+ package gardening.fruits
148
+
149
+ private object FruitAliases extends FruitAliases
150
+ private object FruitHelpers extends FruitHelpers
151
+
152
+ export FruitHelpers.*, FruitAliases.*
72
153
```
154
+ {% endtab %}
155
+ {% endtabs %}
0 commit comments