Package scala.reflect.macros

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

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

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

A slice of the Scala macros context that provides a facility to evaluate trees.

EXPERIMENTAL

A slice of the Scala macros context that defines shorthands for the most common Expr-creating functions.

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

A slice of the Scala macros context that provides facilities to communicate with the compiler's infrastructure.

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://github.com/scala/bug/issues/6879 for more information.

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. 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

A slice of the Scala macros context that exposes functions to save reflection artifacts for runtime.

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. 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

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.