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
+
39
+ {% endtab %}
40
+ {% endtabs %}
41
+
24
42
See example below. Assume first a class ` Fruit ` and three ` Fruit ` objects in a package
25
43
` gardening.fruits ` :
26
44
45
+
46
+ {% tabs pkg-obj-vs-top-lvl_2 %}
47
+ {% tab 'Scala 2 and 3' for=pkg-obj-vs-top-lvl_2 %}
27
48
```
28
49
// in file gardening/fruits/Fruit.scala
29
50
package gardening.fruits
@@ -33,10 +54,15 @@ object Apple extends Fruit("Apple", "green")
33
54
object Plum extends Fruit("Plum", "blue")
34
55
object Banana extends Fruit("Banana", "yellow")
35
56
```
57
+ {% endtab %}
58
+ {% endtabs %}
36
59
37
60
Now assume you want to place a variable ` planted ` and a method ` showFruit ` directly into package ` gardening.fruits ` .
38
61
Here's how this is done:
39
62
63
+ {% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %}
64
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %}
65
+
40
66
```
41
67
// in file gardening/fruits/package.scala
42
68
package gardening
@@ -47,13 +73,29 @@ package object fruits {
47
73
}
48
74
}
49
75
```
76
+ {% endtab %}
77
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %}
78
+
79
+ ```
80
+ // in file gardening/fruits/package.scala
81
+ package gardening.fruits
82
+
83
+ val planted = List(Apple, Plum, Banana)
84
+ def showFruit(fruit: Fruit): Unit =
85
+ println(s"${fruit.name}s are ${fruit.color}")
86
+ ```
87
+ {% endtab %}
88
+ {% endtabs %}
50
89
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:
90
+ As an example of how to use this, the following program imports ` planted ` and ` showFruit ` in exactly the same
91
+ way it imports class ` Fruit ` , using a wildcard import on package ` gardening.fruits ` :
53
92
93
+ {% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %}
94
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %}
54
95
```
55
96
// in file PrintPlanted.scala
56
97
import gardening.fruits._
98
+
57
99
object PrintPlanted {
58
100
def main(args: Array[String]): Unit = {
59
101
for (fruit <- planted) {
@@ -62,11 +104,53 @@ object PrintPlanted {
62
104
}
63
105
}
64
106
```
107
+ {% endtab %}
108
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %}
109
+ ```
110
+ // in file printPlanted.scala
111
+ import gardening.fruits.*
65
112
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:
113
+ @main def printPlanted(): Unit =
114
+ for fruit <- planted do
115
+ showFruit(fruit)
116
+ ```
117
+ {% endtab %}
118
+ {% endtabs %}
119
+
120
+ ### Aggregating Several Definitions at the Package Level
121
+
122
+ Often, your project may have several reusable definitions defined in various modules, that you
123
+ wish to aggregate at the top level of a package.
124
+
125
+ For example, some helper methods in the trait ` FruitHelpers ` and
126
+ some term/type aliases in trait ` FruitAliases ` . Here is how you can put all their definitions at the level of the ` fruit `
127
+ package:
128
+
129
+ {% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %}
130
+ {% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %}
131
+
132
+ Package objects are like other objects, which means you can use inheritance for building them.
133
+ So here we mix in the helper traits as parents of the package object.
67
134
68
135
```
69
- package object fruits extends FruitAliases with FruitHelpers {
70
- // helpers and variables follows here
71
- }
136
+ package gardening
137
+
138
+ // `fruits` instead inherits its members from its parents.
139
+ package object fruits extends FruitAliases with FruitHelpers
140
+ ```
141
+ {% endtab %}
142
+ {% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %}
143
+
144
+ In Scala 3, it is preferred to use ` export ` to compose members from several objects into a single scope.
145
+ Here we define private objects that mix in the helper traits, then export their members at the top level:
146
+
147
+ ```
148
+ package gardening.fruits
149
+
150
+ private object FruitAliases extends FruitAliases
151
+ private object FruitHelpers extends FruitHelpers
152
+
153
+ export FruitHelpers.*, FruitAliases.*
72
154
```
155
+ {% endtab %}
156
+ {% endtabs %}
0 commit comments