You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Separation of macros into blackbox ones and whitebox ones is implemented in the recent milestone builds of Scala 2.11, starting from 2.11.0-M7 (however, in 2.11.0-M8, the syntax underwent some changes, so this documentation isn't applicable to earlier milestone builds of 2.11). The blackbox/whitebox separation is not implemented in Scala 2.10.x or in macro paradise. Follow the instructions at [http://www.scala-lang.org/download](http://www.scala-lang.org/download) to download and use the latest milestone of 2.11.
15
+
Separation of macros into blackbox ones and whitebox ones is a feature of Scala 2.11.x and Scala 2.12.x. The blackbox/whitebox separation is not supported in Scala 2.10.x. It is also not supported in macro paradise for Scala 2.10.x.
15
16
16
17
## Why macros work?
17
18
18
19
With macros becoming a part of the official Scala 2.10 release, programmers in research and industry have found creative ways of using macros to address all sorts of problems, far extending our original expectations.
19
20
20
21
In fact, macros became an important part of our ecosystem so quickly that just a couple months after the release of Scala 2.10, when macros were introduced in experimental capacity, we had a Scala language team meeting and decided to standardize macros and make them a full-fledged feature of Scala by 2.12.
21
22
23
+
<spanclass="label success">UPDATE</span> It turned out that it was not that simple to stabilize macros by Scala 2.12. Our research into that has resulted in establishing a new metaprogramming foundation for Scala, called [scala.meta](http://scalameta.org), whose first beta is expected to be released simultaneously with Scala 2.12 and might later be included in future versions of Scala. In the meanwhile, Scala 2.12 is not going to see any changes to reflection and macros - everything is going to stay experimental as it was in Scala 2.10 and Scala 2.11, and no features are going to be removed. However, even though circumstances under which this document has been written have changed, the information still remains relevant, so please continue reading.
24
+
22
25
Macro flavors are plentiful, so we decided to carefully examine them to figure out which ones should be put in the standard. This entails answering a few important questions. Why are macros working so well? Why do people use them?
23
26
24
27
Our hypothesis is that this happens because the hard to comprehend notion of metaprogramming expressed in def macros piggybacks on the familiar concept of a typed method call. Thanks to that, the code that users write can absorb more meaning without becoming bloated or losing
@@ -32,7 +35,7 @@ This curious feature provides additional flexibility, enabling [fake type provid
32
35
33
36
To concretize the crucial distinction between macros that behave just like normal methods and macros that refine their return types, we introduce the notions of blackbox macros and whitebox macros. Macros that faithfully follow their type signatures are called **blackbox macros** as their implementations are irrelevant to understanding their behaviour (could be treated as black boxes). Macros that can't have precise signatures in Scala's type system are called **whitebox macros** (whitebox def macros do have signatures, but these signatures are only approximations).
34
37
35
-
We recognize the importance of both blackbox and whitebox macros, however we feel more confidence in blackbox macros, because they are easier to explain, specify and support. Therefore our plans to standardize macros in Scala 2.12 only include blackbox macros. In future releases of Scala we might make whitebox macros non-experimental as well, but it is too early to tell.
38
+
We recognize the importance of both blackbox and whitebox macros, however we feel more confidence in blackbox macros, because they are easier to explain, specify and support. Therefore our plans to standardize macros only include blackbox macros. Later on, we might also include whitebox macros into our plans, but it's too early to tell.
36
39
37
40
## Codifying the distinction
38
41
@@ -47,4 +50,4 @@ Blackbox def macros are treated differently from def macros of Scala 2.10. The f
47
50
1. When an application of a blackbox macro is used as an implicit candidate, no expansion is performed until the macro is selected as the result of the implicit search. This makes it impossible to [dynamically calculate availability of implicit macros](/sips/pending/source-locations.html).
48
51
1. When an application of a blackbox macro is used as an extractor in a pattern match, it triggers an unconditional compiler error, preventing [customizations of pattern matching](https://github.com/paulp/scala/commit/84a335916556cb0fe939d1c51f27d80d9cf980dc) implemented with macros.
49
52
50
-
Whitebox def macros work exactly like def macros used to work in Scala 2.10. No restrictions of any kind get applied, so everything that could be done with macros in 2.10 should be possible in 2.11.
53
+
Whitebox def macros work exactly like def macros used to work in Scala 2.10. No restrictions of any kind get applied, so everything that could be done with macros in 2.10 should be possible in 2.11 and 2.12.
Macro bundles are shipped with the recent milestone builds of Scala 2.11, starting from 2.11.0-M4 (however, in 2.11.0-M8, the syntax underwent some changes, so this documentation isn't applicable to earlier milestone builds of 2.11). Macro bundles are not available in Scala 2.10.x or in macro paradise. Follow the instructions at [http://www.scala-lang.org/download/](http://www.scala-lang.org/download/) to download and use the latest milestone of 2.11.
16
+
Macro bundles are a feature of Scala 2.11.x and Scala 2.12.x. Macro bundles are not supported in Scala 2.10.x. They are also not supported in macro paradise for Scala 2.10.x.
16
17
17
18
## Macro bundles
18
19
19
-
Currently, in Scala 2.10.x, macro implementations are represented with functions. Once the compiler sees an application of a macro definition,
20
+
In Scala 2.10.x, macro implementations are represented with functions. Once the compiler sees an application of a macro definition,
20
21
it calls the macro implementation - as simple as that. However practice shows that just functions are often not enough due to the
2. Moreover, since macro parameters are path-dependent on the macro context, [special incantations](/overviews/macros/overview.html#writing_bigger_macros) are required to wire implementations and helpers together.
27
28
28
29
Macro bundles provide a solution to these problems by allowing macro implementations to be declared in classes that take
29
-
`c: BlackboxContext` or `c: WhiteboxContext` as their constructor parameters, relieving macro implementations from having
30
+
`c: scala.reflect.macros.blackbox.Context` or `c: scala.reflect.macros.whitebox.Context` as their constructor parameters, relieving macro implementations from having
30
31
to declare the context in their signatures, which simplifies modularization. Referencing macro implementations defined in bundles
31
32
works in the same way as with impls defined in objects. You specify a bundle name and then select a method from it,
32
33
providing type arguments if necessary.
@@ -42,3 +43,7 @@ providing type arguments if necessary.
42
43
def mono = macro Impl.mono
43
44
def poly[T] = macro Impl.poly[T]
44
45
}
46
+
47
+
## Blackbox vs whitebox
48
+
49
+
Macro bundles can be used to implement both [blackbox](/overviews/macros/blackbox-whitebox.html) and [whitebox](/overviews/macros/blackbox-whitebox.html) macros. Give the macro bundle constructor parameter the type of `scala.reflect.macros.blackbox.Context` to define a blackbox macro and the type of `scala.reflect.macros.whitebox.Context` to define a whitebox macro.
Extractor macros are shipped with the recent milestone builds of Scala 2.11, starting from 2.11.0-M5, enabled by name-based extractors introduced by Paul Phillips in Scala 2.11.0-M5. Extractor macros are not available in Scala 2.10.x or in macro paradise. Follow the instructions at [http://www.scala-lang.org/download/](http://www.scala-lang.org/download/) to download and use the latest milestone of 2.11.
15
+
Extractor macros are a feature of Scala 2.11.x and Scala 2.12.x, enabled by name-based extractors introduced by Paul Phillips in Scala 2.11.0-M5. Extractor macros are not supported in Scala 2.10.x. They are also not supported in macro paradise for Scala 2.10.x.
15
16
16
-
###The pattern
17
+
## The pattern
17
18
18
19
In a nutshell, given an unapply method (for simplicity, in this
19
20
example the scrutinee is of a concrete type, but it's also possible
@@ -61,7 +62,7 @@ because one can't declare value classes local. Nevertheless,
61
62
I'm leaving a canary in place ([neg/t5903e](https://github.com/scala/scala/blob/00624a39ed84c3fd245dd9df7454d4cec4399e13/test/files/neg/t5903e/Macros_1.scala#L1)) that will let us know
62
63
once this restriction is lifted.
63
64
64
-
###Use cases
65
+
## Use cases
65
66
66
67
In particular, the pattern can be used to implement shapeshifting
67
68
pattern matchers for string interpolators without resorting to dirty
@@ -87,4 +88,7 @@ Follow our test cases at [run/t5903a](https://github.com/scala/scala/tree/00624a
87
88
[run/t5903d](https://github.com/scala/scala/tree/00624a39ed84c3fd245dd9df7454d4cec4399e13/test/files/run/t5903d) to see implementations
88
89
of this and other use cases for extractor macros.
89
90
90
-
Please note that extractor macros must be [whitebox](/overviews/macros/blackbox-whitebox.html), otherwise they will not work.
91
+
## Blackbox vs whitebox
92
+
93
+
Extractor macros must be [whitebox](/overviews/macros/blackbox-whitebox.html).
94
+
If you declare an extractor macro as [blackbox](/overviews/macros/blackbox-whitebox.html), it will not work.
Note that in 2.10.x, expansion of fundep materializer macros requires macro paradise,
21
+
called fundep materialization, is unavailable in 2.10.0 through 2.10.4, but has been implemented in
22
+
[macro paradise](/overviews/macros/paradise.html), Scala 2.10.5 and Scala 2.11.x.
23
+
Note that in 2.10.0 through 2.10.4, expansion of fundep materializer macros requires macro paradise,
23
24
which means that your users will have to add macro paradise to their builds in order to use your fundep materializers.
24
25
However, after fundep materializers expand, the resulting code will no longer have any references to macro paradise
25
-
and won't require its presence at compile-time or at runtime.
26
+
and won't require its presence at compile-time or at runtime. Also note that in 2.10.5, expansion of
27
+
fundep materializer macros can happen without macro paradise, but then your users will have to enable
28
+
the <code>-Yfundep-materialization</code> compiler flag.
26
29
27
30
## Implicit macros
28
31
@@ -147,4 +150,12 @@ Note how simple everything is. The `materializeIso` implicit macro just takes it
147
150
We don't need to make sense of the second type argument (which isn't inferred yet), we don't need to interact with type inference -
148
151
everything happens automatically.
149
152
150
-
Please note that there is [a funny caveat](https://github.com/scala/scala/blob/7b890f71ecd0d28c1a1b81b7abfe8e0c11bfeb71/test/files/run/t5923a/Macros_1.scala) with Nothings that we plan to address later. Also note that fundep materializers must be [whitebox](/overviews/macros/blackbox-whitebox.html), otherwise they will not work.
153
+
Please note that there is [a funny caveat](https://github.com/scala/scala/blob/7b890f71ecd0d28c1a1b81b7abfe8e0c11bfeb71/test/files/run/t5923a/Macros_1.scala) with Nothings that we plan to address later.
154
+
155
+
## Blackbox vs whitebox
156
+
157
+
Vanilla materializers (covered in the first part of this document) can be both [blackbox](/overviews/macros/blackbox-whitebox.html) and [whitebox](/overviews/macros/blackbox-whitebox.html).
158
+
159
+
There is a noticeable distinction between blackbox and whitebox materializers. An error in an expansion of a blackbox implicit macro (e.g. an explicit <code>c.abort</code> call or an expansion typecheck error) will produce a compilation error. An error in an expansion of a whitebox implicit macro will just remove the macro from the list of implicit candidates in the current implicit search, without ever reporting an actual error to the user. This creates a trade-off: blackbox implicit macros feature better error reporting, while whitebox implicit macros are more flexible, being able to dynamically turn themselves off when necessary.
160
+
161
+
Fundep materializers must be whitebox. If you declare a fundep materializer as blackbox, it will not work.
0 commit comments