scala.tools.nsc.typechecker

# Macros

###
Related Doc: package typechecker

#### trait Macros extends MacroRuntimes with Traces with Helpers

Code to deal with macros, namely with: * Compilation of macro definitions * Expansion of macro applications

Say we have in a class C:

def foo[T](xs: List[T]): T = macro fooBar

Then fooBar needs to point to a static method of the following form:

def fooBar[T: c.WeakTypeTag] // type tag annotation is optional (c: scala.reflect.macros.blackbox.Context) (xs: c.Expr[List[T]]) : c.Expr[T] = { ... }

Then, if foo is called in qual.foo[Int](elems), where qual: D, the macro application is expanded to a reflective invocation of fooBar with parameters:

(simpleMacroContext{ type PrefixType = D; val prefix = qual }) (Expr(elems)) (TypeTag(Int))

Self Type
  Analyzer
Source
  Macros.scala

Linear Supertypes
Helpers, Traces, MacroRuntimes, JavaReflectionRuntimes, AnyRef, Any
Known Subclasses
Analyzer, Duplicator, Duplicators, Erasure, SpecializationDuplicator, TreeCheckers, erasure, treeChecker
Type Hierarchy Learn more about scaladoc diagrams
Ordering

1. Alphabetic
2. By inheritance

Inherited

1. Macros
2. Helpers
3. Traces
4. MacroRuntimes
5. JavaReflectionRuntimes
6. AnyRef
7. Any

Implicitly

1. by any2stringadd
2. by StringFormat
3. by Ensuring
4. by ArrowAssoc

1. Hide All
2. Show all

Learn more about member selection
Visibility

1. Public
2. All

### Type Members

1. #### class DefMacroExpander extends Analyzer.MacroExpander

   Expands a term macro used in apply role as `M(2)(3)` in `val x = M(2)(3)`.

2. #### case class Delayed(delayed: Global.Tree) extends Analyzer.MacroStatus with Product with Serializable

3. #### case class Failure(failure: Global.Tree) extends Analyzer.MacroStatus with Product with Serializable

4. #### case class Fallback(fallback: Global.Tree) extends Analyzer.MacroStatus with Product with Serializable

5. #### trait JavaReflectionResolvers extends AnyRef

   Definition Classes
     JavaReflectionRuntimes

6. #### case class MacroArgs(c: Analyzer.MacroContext, others: List[Any]) extends Product with Serializable

   Calculate the arguments to pass to a macro implementation when expanding the provided tree.

7. #### abstract class MacroExpander extends AnyRef

   Performs macro expansion:

   Performs macro expansion:

   ###### Expandable trees

   A term of one of the following shapes:

   Ident(<term macro>) Select(<any qualifier>, <term macro>) TypeApply(<any of the above>, <targs>) Apply(...Apply(<any of the above>, <args1>)...<argsN>)

   ###### Macro expansion

   First of all `macroExpandXXX`: 1) If necessary desugars the `expandee` to fit into the default expansion scheme that is understood by `macroExpandWithRuntime` / `macroExpandWithoutRuntime`

   Then `macroExpandWithRuntime`: 2) Checks whether the expansion needs to be delayed 3) Loads macro implementation using `macroMirror` 4) Synthesizes invocation arguments for the macro implementation 5) Checks that the result is a tree or an expr bound to this universe

   Finally `macroExpandXXX`: 6) Validates the expansion against the white list of supported tree shapes 7) Typechecks the result as required by the circumstances of the macro application

   If -Ymacro-debug-lite is enabled, you will get basic notifications about macro expansion along with macro expansions logged in the form that can be copy/pasted verbatim into REPL.

   If -Ymacro-debug-verbose is enabled, you will get detailed log of how exactly this function performs class loading and method resolution in order to load the macro implementation. The log will also include other non-trivial steps of macro expansion.

   returns

     the expansion result if the expansion has been successful, the fallback tree if the expansion has been unsuccessful, but there is a fallback, the expandee unchanged if the expansion has been delayed, the expandee fully expanded if the expansion has been delayed before and has been expanded now, the expandee with an error marker set if the expansion has been cancelled due malformed arguments or implementation the expandee with an error marker set if there has been an error

8. #### case class MacroImplBinding(isBundle: Boolean, isBlackbox: Boolean, className: String, methName: String, signature: List[List[Fingerprint]], targs: List[Global.Tree]) extends Product with Serializable

   Represents all the information that a macro definition needs to know about its implementation.

   Represents all the information that a macro definition needs to know about its implementation. Includes a path to load the implementation via Java reflection, and various accounting information necessary when composing an argument list for the reflective invocation.

9. #### type MacroRuntime = (Analyzer.MacroArgs) ⇒ Any

   Abstracts away resolution of macro runtimes.

   Abstracts away resolution of macro runtimes.

   Definition Classes
     MacroRuntimes

10. #### class MacroRuntimeResolver extends tools.nsc.typechecker.Analyzer.JavaReflectionResolvers

    Definition Classes
      MacroRuntimes

11. #### sealed abstract class MacroStatus extends AnyRef

12. #### case class Skipped(skipped: Global.Tree) extends Analyzer.MacroStatus with Product with Serializable

13. #### case class Success(expanded: Global.Tree) extends Analyzer.MacroStatus with Product with Serializable

### Value Members

1. #### final def !=(arg0: Any): Boolean

   Test two objects for inequality.

   Test two objects for inequality.

   returns

     `true` if !(this == that), false otherwise.

   Definition Classes
     AnyRef → Any

2. #### final def ##(): Int

   Equivalent to `x.hashCode` except for boxed numeric types and `null`.

   Equivalent to `x.hashCode` except for boxed numeric types and `null`. For numerics, it returns a hash value which is consistent with value equality: if two value type instances compare as true, then ## will produce the same hash value for each of them. For `null` returns a hashcode where `null.hashCode` throws a `NullPointerException`.

   returns

     a hash value consistent with ==

   Definition Classes
     AnyRef → Any

3. #### def +(other: String): String

   Implicit information
     This member is added by an implicit conversion from Macros to any2stringadd[Macros] performed by method any2stringadd in scala.Predef.
   Definition Classes
     any2stringadd

4. #### def ->[B](y: B): (Macros, B)

   Implicit information
     This member is added by an implicit conversion from Macros to ArrowAssoc[Macros] performed by method ArrowAssoc in scala.Predef.
   Definition Classes
     ArrowAssoc
   Annotations
     @inline()

5. #### final def ==(arg0: Any): Boolean

   The expression `x == that` is equivalent to `if (x eq null) that eq null else x.equals(that)`.

   The expression `x == that` is equivalent to `if (x eq null) that eq null else x.equals(that)`.

   arg0

     the object to compare against this object for equality.

   returns

     `true` if the receiver object is equivalent to the argument; `false` otherwise.

   Definition Classes
     AnyRef → Any

6. #### def Delay(expanded: Global.Tree): Analyzer.Delayed

7. #### object MacroImplBinding extends Serializable

8. #### def Skip(expanded: Global.Tree): Analyzer.Skipped

9. #### var _openMacros: collection.immutable.List[Context { val universe: Macros.this.global.type }]

   Keeps track of macros in-flight.

   Keeps track of macros in-flight. See more informations in comments to `openMacros` in `scala.reflect.macros.whitebox.Context`.

10. #### final def asInstanceOf[T0]: T0

    Cast the receiver object to be of type `T0`.

    Cast the receiver object to be of type `T0`.

    Note that the success of a cast at runtime is modulo Scala's erasure semantics. Therefore the expression `1.asInstanceOf[String]` will throw a `ClassCastException` at runtime, while the expression `List(1).asInstanceOf[List[String]]` will not. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the requested type.

    returns

      the receiver object.

    Definition Classes
      Any
    Exceptions thrown

      `ClassCastException` if the receiver object is not an instance of the erasure of type `T0`.

11. #### def bindMacroImpl(macroDef: Global.Symbol, macroImplRef: Global.Tree): Unit

12. #### def clone(): AnyRef

    Create a copy of the receiver object.

    Create a copy of the receiver object.

    The default implementation of the `clone` method is platform dependent.

    returns

      a copy of the receiver object.

    Attributes
      protected[java.lang]
    Definition Classes
      AnyRef
    Annotations
      @throws( ... )
    Note

      not specified by SLS as a member of AnyRef

13. #### def computeMacroDefTypeFromMacroImplRef(macroDdef: Global.DefDef, macroImplRef: Global.Tree): Global.Type

14. #### def decreaseMetalevel(tp: Global.Type): Global.Type

    Decreases metalevel of the type, i.e.

    Decreases metalevel of the type, i.e. transforms: * c.Expr[T] to T * Nothing to Nothing * Anything else to NoType

    Definition Classes
      Helpers
    See also

      Metalevels.scala for more information and examples about metalevels

15. #### lazy val defaultMacroClassloader: ClassLoader

    Macro classloader that is used to resolve and run macro implementations.

    Macro classloader that is used to resolve and run macro implementations. Loads classes from from -cp (aka the library classpath). Is also capable of detecting REPL and reusing its classloader.

    When -Xmacro-jit is enabled, we sometimes fallback to on-the-fly compilation of macro implementations, which compiles implementations into a virtual directory (very much like REPL does) and then conjures a classloader mapped to that virtual directory.

    Definition Classes
      MacroRuntimes

16. #### def enclosingMacroPosition: Position

17. #### def ensuring(cond: (Macros) ⇒ Boolean, msg: ⇒ Any): Macros

    Implicit information
      This member is added by an implicit conversion from Macros to Ensuring[Macros] performed by method Ensuring in scala.Predef.
    Definition Classes
      Ensuring

18. #### def ensuring(cond: (Macros) ⇒ Boolean): Macros

    Implicit information
      This member is added by an implicit conversion from Macros to Ensuring[Macros] performed by method Ensuring in scala.Predef.
    Definition Classes
      Ensuring

19. #### def ensuring(cond: Boolean, msg: ⇒ Any): Macros

    Implicit information
      This member is added by an implicit conversion from Macros to Ensuring[Macros] performed by method Ensuring in scala.Predef.
    Definition Classes
      Ensuring

20. #### def ensuring(cond: Boolean): Macros

    Implicit information
      This member is added by an implicit conversion from Macros to Ensuring[Macros] performed by method Ensuring in scala.Predef.
    Definition Classes
      Ensuring

21. #### final def eq(arg0: AnyRef): Boolean

    Tests whether the argument (`arg0`) is a reference to the receiver object (`this`).

    Tests whether the argument (`arg0`) is a reference to the receiver object (`this`).

    The `eq` method implements an equivalence relation on non-null instances of `AnyRef`, and has three additional properties:

    - It is consistent: for any non-null instances `x` and `y` of type `AnyRef`, multiple invocations of `x.eq(y)` consistently returns `true` or consistently returns `false`.
    - For any non-null instance `x` of type `AnyRef`, `x.eq(null)` and `null.eq(x)` returns `false`.
    - `null.eq(null)` returns `true`.

    When overriding the `equals` or `hashCode` methods, it is important to ensure that their behavior is consistent with reference equality. Therefore, if two objects are references to each other (`o1 eq o2`), they should be equal to each other (`o1 == o2`) and they should hash to the same value (`o1.hashCode == o2.hashCode`).

    returns

      `true` if the argument is a reference to the receiver object; `false` otherwise.

    Definition Classes
      AnyRef

22. #### def equals(arg0: Any): Boolean

    The equality method for reference types.

    The equality method for reference types. Default implementation delegates to `eq`.

    See also `equals` in scala.Any.

    returns

      `true` if the receiver object is equivalent to the argument; `false` otherwise.

    Definition Classes
      AnyRef → Any

23. #### lazy val fastTrack: FastTrack[Macros.this.type]

24. #### def finalize(): Unit

    Called by the garbage collector on the receiver object when there are no more references to the object.

    Called by the garbage collector on the receiver object when there are no more references to the object.

    The details of when and if the `finalize` method is invoked, as well as the interaction between `finalize` and non-local returns and exceptions, are all platform dependent.

    Attributes
      protected[java.lang]
    Definition Classes
      AnyRef
    Annotations
      @throws( classOf[java.lang.Throwable] )
    Note

      not specified by SLS as a member of AnyRef

25. #### def findMacroClassLoader(): ClassLoader

    Attributes
      protected

26. #### def formatted(fmtstr: String): String

    Implicit information
      This member is added by an implicit conversion from Macros to StringFormat[Macros] performed by method StringFormat in scala.Predef.
    Definition Classes
      StringFormat
    Annotations
      @inline()

27. #### final def getClass(): Class[_]

    A representation that corresponds to the dynamic class of the receiver object.

    A representation that corresponds to the dynamic class of the receiver object.

    The nature of the representation is platform dependent.

    returns

      a representation that corresponds to the dynamic class of the receiver object.

    Definition Classes
      AnyRef → Any
    Note

      not specified by SLS as a member of AnyRef

28. #### def globalSettings: Settings

    Definition Classes
      Macros → Traces

29. #### var hasPendingMacroExpansions: Boolean

    Without any restrictions on macro expansion, macro applications will expand at will, and when type inference is involved, expansions will end up using yet uninferred type params.

    Without any restrictions on macro expansion, macro applications will expand at will, and when type inference is involved, expansions will end up using yet uninferred type params.

    For some macros this might be ok (thanks to TreeTypeSubstituter that replaces the occurrences of undetparams with their inferred values), but in general case this won't work. E.g. for reification simple substitution is not enough - we actually need to re-reify inferred types.

    Luckily, there exists a very simple way to fix the problem: delay macro expansion until everything is inferred. Here are the exact rules. Macro application gets delayed if any of its subtrees contain: 1) type vars (tpe.isInstanceOf[TypeVar]) // [Eugene] this check is disabled right now, because TypeVars seem to be created from undetparams anyways 2) undetparams (sym.isTypeParameter && !sym.isSkolem)

30. #### def hashCode(): Int

    The hashCode method for reference types.

    The hashCode method for reference types. See hashCode in scala.Any.

    returns

      the hash code value for this object.

    Definition Classes
      AnyRef → Any

31. #### def increaseMetalevel(pre: Global.Type, tp: Global.Type): Global.Type

    Increases metalevel of the type, i.e.

    Increases metalevel of the type, i.e. transforms: * T to c.Expr[T]

    Definition Classes
      Helpers
    See also

      Metalevels.scala for more information and examples about metalevels

32. #### def isBlackbox(macroDef: Global.Symbol): Boolean

33. #### def isBlackbox(expandee: Global.Tree): Boolean

34. #### final def isInstanceOf[T0]: Boolean

    Test whether the dynamic type of the receiver object is `T0`.

    Test whether the dynamic type of the receiver object is `T0`.

    Note that the result of the test is modulo Scala's erasure semantics. Therefore the expression `1.isInstanceOf[String]` will return `false`, while the expression `List(1).isInstanceOf[List[String]]` will return `true`. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the specified type.

    returns

      `true` if the receiver object is an instance of erasure of type `T0`; `false` otherwise.

    Definition Classes
      Any

35. #### def loadMacroImplBinding(macroDef: Global.Symbol): Option[Analyzer.MacroImplBinding]

36. #### def macroArgs(typer: Analyzer.Typer, expandee: Global.Tree): Analyzer.MacroArgs

37. #### def macroContext(typer: Analyzer.Typer, prefixTree: Global.Tree, expandeeTree: Global.Tree): Analyzer.MacroContext

38. #### val macroDebugLite: Boolean

    Definition Classes
      Traces

39. #### val macroDebugVerbose: Boolean

    Definition Classes
      Traces

40. #### def macroEngine: String

    Macro def -> macro impl bindings are serialized into a `macroImpl` annotation with synthetic content that carries the payload described in `MacroImplBinding`.

    Macro def -> macro impl bindings are serialized into a `macroImpl` annotation with synthetic content that carries the payload described in `MacroImplBinding`.

    For example, for a pair of macro definition and macro implementation: def impl(c: scala.reflect.macros.blackbox.Context): c.Expr[Unit] = ??? def foo: Unit = macro impl

    We will have the following annotation added on the macro definition `foo`:

41. #### def macroExpand(typer: Analyzer.Typer, expandee: Global.Tree, mode: Mode, pt: Global.Type): Global.Tree

    Expands a term macro used in apply role as `M(2)(3)` in `val x = M(2)(3)`.

    Expands a term macro used in apply role as `M(2)(3)` in `val x = M(2)(3)`.

    See also

      DefMacroExpander

42. #### def macroExpandAll(typer: Analyzer.Typer, expandee: Global.Tree): Global.Tree

    Performs macro expansion on all subtrees of a given tree.

    Performs macro expansion on all subtrees of a given tree. Innermost macros are expanded first, outermost macros are expanded last. See the documentation for `macroExpand` for more information.

43. #### def macroExpandWithRuntime(typer: Analyzer.Typer, expandee: Global.Tree, runtime: Analyzer.MacroRuntime): Analyzer.MacroStatus

    Expands a macro when a runtime (i.e.

    Expands a macro when a runtime (i.e. the macro implementation) can be successfully loaded Meant for internal use within the macro infrastructure, don't use it elsewhere.

44. #### def macroExpandWithoutRuntime(typer: Analyzer.Typer, expandee: Global.Tree): Analyzer.MacroStatus

    Expands a macro when a runtime (i.e.

    Expands a macro when a runtime (i.e. the macro implementation) cannot be loaded Meant for internal use within the macro infrastructure, don't use it elsewhere.

45. #### final def macroLogLite(msg: ⇒ Any): Unit

    Definition Classes
      Traces
    Annotations
      @inline()

46. #### final def macroLogVerbose(msg: ⇒ Any): Unit

    Definition Classes
      Traces
    Annotations
      @inline()

47. #### def macroRuntime(expandee: Global.Tree): Analyzer.MacroRuntime

    Produces a function that can be used to invoke macro implementation for a given macro definition: 1) Looks up macro implementation symbol in this universe.

    Produces a function that can be used to invoke macro implementation for a given macro definition: 1) Looks up macro implementation symbol in this universe. 2) Loads its enclosing class from the macro classloader. 3) Loads the companion of that enclosing class from the macro classloader. 4) Resolves macro implementation within the loaded companion.

    returns

      Requested runtime if macro implementation can be loaded successfully from either of the mirrors, `null` otherwise.

    Definition Classes
      MacroRuntimes

48. #### final def ne(arg0: AnyRef): Boolean

    Equivalent to `!(this eq that)`.

    Equivalent to `!(this eq that)`.

    returns

      `true` if the argument is not a reference to the receiver object; `false` otherwise.

    Definition Classes
      AnyRef

49. #### final def notify(): Unit

    Wakes up a single thread that is waiting on the receiver object's monitor.

    Wakes up a single thread that is waiting on the receiver object's monitor.

    Definition Classes
      AnyRef
    Note

      not specified by SLS as a member of AnyRef

50. #### final def notifyAll(): Unit

    Wakes up all threads that are waiting on the receiver object's monitor.

    Wakes up all threads that are waiting on the receiver object's monitor.

    Definition Classes
      AnyRef
    Note

      not specified by SLS as a member of AnyRef

51. #### def notifyUndetparamsAdded(newUndets: List[Global.Symbol]): Unit

52. #### def notifyUndetparamsInferred(undetNoMore: List[Global.Symbol], inferreds: List[Global.Type]): Unit

53. #### def openMacros: collection.immutable.List[Context { val universe: Macros.this.global.type }]

54. #### def popMacroContext(): Unit

55. #### def pushMacroContext(c: Analyzer.MacroContext): Unit

56. #### def standardIsBlackbox(macroDef: Global.Symbol): Boolean

    Default implementation of `isBlackbox`.

    Default implementation of `isBlackbox`. Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsIsBlackbox for more details)

57. #### def standardMacroArgs(typer: Analyzer.Typer, expandee: Global.Tree): Analyzer.MacroArgs

    Default implementation of `macroArgs`.

    Default implementation of `macroArgs`. Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsMacroArgs for more details)

58. #### def standardMacroExpand(typer: Analyzer.Typer, expandee: Global.Tree, mode: Mode, pt: Global.Type): Global.Tree

    Default implementation of `macroExpand`.

    Default implementation of `macroExpand`. Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsMacroExpand for more details)

59. #### def standardMacroRuntime(expandee: Global.Tree): Analyzer.MacroRuntime

    Definition Classes
      MacroRuntimes

60. #### def standardTypedMacroBody(typer: Analyzer.Typer, macroDdef: Global.DefDef): Global.Tree

    Default implementation of `typedMacroBody`.

    Default implementation of `typedMacroBody`. Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsTypedMacroBody for more details)

61. #### final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
      AnyRef

62. #### def toString(): String

    Creates a String representation of this object.

    Creates a String representation of this object. The default representation is platform dependent. On the java platform it is the concatenation of the class name, "@", and the object's hashcode in hexadecimal.

    returns

      a String representation of the object.

    Definition Classes
      AnyRef → Any

63. #### def transformTypeTagEvidenceParams(macroImplRef: Global.Tree, transform: (Global.Symbol, Global.Symbol) ⇒ Global.Symbol): List[List[Global.Symbol]]

    Transforms parameters lists of a macro impl.

    Transforms parameters lists of a macro impl. The `transform` function is invoked only for WeakTypeTag evidence parameters.

    The transformer takes two arguments: a value parameter from the parameter list and a type parameter that is witnesses by the value parameter.

    If the transformer returns a NoSymbol, the value parameter is not included from the result. If the transformer returns something else, this something else is included in the result instead of the value parameter.

    Despite of being highly esoteric, this function significantly simplifies signature analysis. For example, it can be used to strip macroImpl.paramss from the evidences (necessary when checking def <-> impl correspondence) or to streamline creation of the list of macro arguments.

    Definition Classes
      Helpers

64. #### def typedMacroBody(typer: Analyzer.Typer, macroDdef: Global.DefDef): Global.Tree

    Verifies that the body of a macro def typechecks to a reference to a static public non-overloaded method or a top-level macro bundle, and that that method is signature-wise compatible with the given macro definition.

    Verifies that the body of a macro def typechecks to a reference to a static public non-overloaded method or a top-level macro bundle, and that that method is signature-wise compatible with the given macro definition.

    returns

      Macro impl reference for the given macro definition if everything is okay. EmptyTree if an error occurs.

65. #### def untypeMetalevel(tp: Global.Type): Global.Type

    Transforms c.Expr[T] types into c.Tree and leaves the rest unchanged.

    Transforms c.Expr[T] types into c.Tree and leaves the rest unchanged.

    Definition Classes
      Helpers

66. #### final def wait(): Unit

    Definition Classes
      AnyRef
    Annotations
      @throws( ... )

67. #### final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
      AnyRef
    Annotations
      @throws( ... )

68. #### final def wait(arg0: Long): Unit

    Definition Classes
      AnyRef
    Annotations
      @throws( ... )

69. #### def →[B](y: B): (Macros, B)

    Implicit information
      This member is added by an implicit conversion from Macros to ArrowAssoc[Macros] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
      ArrowAssoc

### Inherited from Helpers

### Inherited from Traces

### Inherited from MacroRuntimes

### Inherited from JavaReflectionRuntimes

### Inherited from AnyRef

### Inherited from Any

### Inherited by implicit conversion any2stringadd from Macros to any2stringadd[Macros]

### Inherited by implicit conversion StringFormat from Macros to StringFormat[Macros]

### Inherited by implicit conversion Ensuring from Macros to Ensuring[Macros]

### Inherited by implicit conversion ArrowAssoc from Macros to ArrowAssoc[Macros]

### Ungrouped