macros
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that defines shorthands for the most frequently used types and functions of the underlying compiler universe.
EXPERIMENTAL
EXPERIMENTAL
Attachments provide a way to associate custom metadata with symbols and trees.
Along with symbol and tpe, which represent core metadata of trees, each tree
carries the attachments field that can store other metadata: compiler-defined (e.g. positions) or user-defined.
Same story is true for symbols, which also have extensible metadata by the virtue
of the same attachments field.
Typically attachments just store a scala.reflect.api.Position, but they can be extended to
encompass arbitrary payloads. Payloads are stored in type-indexed slots, which can be read with get[T] and written
with update[T] and remove[T].
This API doesn't have much use in the runtime reflection API (the scala.reflect.api package), but it might be of help
for macro writers, providing a way to coordinate multiple macros operating on the same code. Therefore the attachments
field is only declared in trees and symbols belonging to scala.reflect.macros.Universe.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that exposes enclosing trees (method, class, compilation unit and currently compiled macro application), the enclosing position of the macro expansion, as well as macros and implicits that are currently in-flight.
Starting from Scala 2.11.0, the APIs to get the trees enclosing by the current macro application are deprecated,
and the reasons for that are two-fold. Firstly, we would like to move towards the philosophy of locally-expanded macros,
as it has proven to be important for understanding of code. Secondly, within the current architecture of scalac,
we are unable to have c.enclosingTree-style APIs working robustly. Required changes to the typechecker would greatly
exceed the effort that we would like to expend on this feature given the existence of more pressing concerns at the moment.
This is somewhat aligned with the overall evolution of macros during the 2.11 development cycle, where we played with
c.introduceTopLevel and c.introduceMember, but at the end of the day decided to reject them.
If you're relying on the now deprecated APIs, consider using the new c.internal.enclosingOwner method that can be used to obtain the names of enclosing definitions. Alternatively try reformulating your macros in terms of completely local expansion and/or joining a discussion of a somewhat related potential language feature at https://groups.google.com/forum/#!topic/scala-debate/f4CLmYShX6Q. We also welcome questions and suggestions on our mailing lists, where we would be happy to further discuss this matter.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that provides a facility to evaluate trees.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that defines shorthands for the
most common Expr-creating functions.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that provides facilities to communicate with the compiler's front end (emit warnings, errors and other sorts of messages).
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that provides facilities to communicate with the compiler's infrastructure.
EXPERIMENTAL
EXPERIMENTAL
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that provides functions that generate fresh names.
In the current implementation, fresh names are more or less unique in the sense that
within the same compilation run they are guaranteed not to clash with:
1) Results of past and future invocations of functions of freshName family
2) User-defined or macro-generated names that don't contain dollar symbols
3) Macro-generated names that are created by concatenating names from the first, second and third categories
Uniqueness of fresh names across compilation runs is not guaranteed, but that's something that we would like to improve upon in future releases. See https://issues.scala-lang.org/browse/SI-6879 for more information.
Indicates an error during scala.reflect.macros.Parsers#parse.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that exposes functions to parse strings with Scala code into trees.
Indicates an expected error during one of the reifyXXX methods in scala.reflect.macros.Reifiers.
Indicates an expected error during one of the reifyXXX methods in scala.reflect.macros.Reifiers.
Such errors represent one of the standard ways for reification to go wrong, e.g.
an attempt to create a TypeTag from a weak type.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that exposes functions to save reflection artifacts for runtime.
Indicates an error during one of the methods in scala.reflect.macros.Typers.
EXPERIMENTAL
EXPERIMENTAL
A slice of the Scala macros context that partially exposes the type checker to macro writers.
Indicates an unexpected expected error during one of the reifyXXX methods in scala.reflect.macros.Reifiers.
Indicates an unexpected expected error during one of the reifyXXX methods in scala.reflect.macros.Reifiers.
Such errors wrap random crashes in reification logic and are distinguished from expected scala.reflect.macros.ReificationExceptions
so that the latter can be reported as compilation errors, while the former manifest themselves as compiler crashes.
EXPERIMENTAL
EXPERIMENTAL
The refinement of scala.reflect.api.Universe for the use by macro writers.
This 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.
The Scala macros context.
The Scala macros context.
In Scala 2.11, macros that were once the one are split into blackbox and whitebox macros, with the former being better supported and the latter being more powerful. You can read about the details of the split and the associated trade-offs in the Macros Guide.
scala.reflect.macros.Context follows this tendency and turns into scala.reflect.macros.blackbox.Context
and scala.reflect.macros.whitebox.Context. The original Context is left in place for compatibility reasons,
but it is now deprecated, nudging the users to choose between blackbox and whitebox macros.
(Since version 2.11.0) Use blackbox.Context or whitebox.Context instead
EXPERIMENTAL
The base package for Scala macros.
Macros are functions that are called by the compiler during compilation. Within these functions the programmer has access to compiler APIs. For example, it is possible to generate, analyze and typecheck code.
See the Macros Guide on how to get started with Scala macros.