See the overview page for a description of how macros work. This documentation
entry provides information on the API available to macro writers.
A macro context wraps a compiler universe exposed in universe and having type scala.reflect.macros.Universe.
This type is a refinement over the generic reflection API provided in scala.reflect.api.Universe. The
extended Universe provides mutability for reflection artifacts (e.g. macros can change types of compiler trees,
add annotation to symbols representing definitions, etc) and exposes some internal compiler functionality
such as Symbol.deSkolemize or Tree.attachments.
Another fundamental part of a macro context is macroApplication, which provides access to the tree undergoing
macro expansion. Parts of this tree can be found in arguments of the corresponding macro implementations and
in prefix, but macroApplication gives the full picture.
Other than that, macro contexts provide facilities for typechecking, exploring the compiler's symbol table and
enclosing trees and compilation units, evaluating trees, logging warnings/errors and much more.
Refer to the documentation of top-level traits in this package to learn the details.
If a macro def refers to a macro impl that uses blackbox.Context, then this macro def becomes a blackbox macro,
which means that its expansion will be upcast to its return type, enforcing faithfullness of that macro to its
type signature. Whitebox macros, i.e. the ones defined with whitebox.Context, aren't bound by this restriction,
which enables a number of important use cases, but they are also going to enjoy less support than blackbox macros,
so choose wisely. See the Macros Guide for more information.
EXPERIMENTAL
The blackbox Scala macros context.
See the overview page for a description of how macros work. This documentation entry provides information on the API available to macro writers.
A macro context wraps a compiler universe exposed in
universeand having type scala.reflect.macros.Universe. This type is a refinement over the generic reflection API provided in scala.reflect.api.Universe. The extended Universe provides mutability for reflection artifacts (e.g. macros can change types of compiler trees, add annotation to symbols representing definitions, etc) and exposes some internal compiler functionality such asSymbol.deSkolemizeorTree.attachments.Another fundamental part of a macro context is
macroApplication, which provides access to the tree undergoing macro expansion. Parts of this tree can be found in arguments of the corresponding macro implementations and inprefix, butmacroApplicationgives the full picture.Other than that, macro contexts provide facilities for typechecking, exploring the compiler's symbol table and enclosing trees and compilation units, evaluating trees, logging warnings/errors and much more. Refer to the documentation of top-level traits in this package to learn the details.
If a macro def refers to a macro impl that uses
blackbox.Context, then this macro def becomes a blackbox macro, which means that its expansion will be upcast to its return type, enforcing faithfullness of that macro to its type signature. Whitebox macros, i.e. the ones defined withwhitebox.Context, aren't bound by this restriction, which enables a number of important use cases, but they are also going to enjoy less support than blackbox macros, so choose wisely. See the Macros Guide for more information.scala.reflect.macros.whitebox.Context