Packages

package macros

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.

Source
package.scala
Linear Supertypes

Package Members

  1. package blackbox
  2. package whitebox

Type Members

  1. trait Aliases extends AnyRef

    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.

  2. abstract class Attachments extends AnyRef

    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.

  3. trait Enclosures extends AnyRef

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

  4. trait Evals extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

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

  5. trait ExprUtils extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

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

  6. trait FrontEnds extends AnyRef

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

  7. trait Infrastructure extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

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

  8. trait Internals extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

    See also

    scala.reflect.api.Internals

  9. trait Names extends AnyRef

    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.

  10. case class ParseException(pos: Position, msg: String) extends Exception with Product with Serializable

    Indicates an error during scala.reflect.macros.Parsers#parse.

  11. trait Parsers extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

    A slice of the Scala macros context that exposes functions to parse strings with Scala code into trees.

  12. case class ReificationException(pos: Position, msg: String) extends Exception with Product with Serializable

    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.

  13. trait Reifiers extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

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

  14. case class TypecheckException(pos: Position, msg: String) extends Exception with Product with Serializable

    Indicates an error during one of the methods in scala.reflect.macros.Typers.

  15. trait Typers extends AnyRef

    EXPERIMENTAL

    EXPERIMENTAL

    A slice of the Scala macros context that partially exposes the type checker to macro writers.

  16. case class UnexpectedReificationException(pos: Position, msg: String, cause: Throwable = null) extends Exception with Product with Serializable

    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.

  17. abstract class Universe extends api.Universe

    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.

Deprecated Type Members

  1. type Context = macros.whitebox.Context

    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.

    Annotations
    @deprecated
    Deprecated

    (Since version 2.11.0) use blackbox.Context or whitebox.Context instead

Inherited from AnyRef

Inherited from Any

Ungrouped