Macros
Related Doc:
package typechecker
Expands a term macro used in apply role as M(2)(3) in val x = M(2)(3).
Calculate the arguments to pass to a macro implementation when expanding the provided tree.
Performs macro expansion:
Performs macro expansion:
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>)
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.
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
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.
Abstracts away resolution of macro runtimes.
Abstracts away resolution of macro runtimes.
Test two objects for inequality.
Test two objects for inequality.
true if !(this == that), false otherwise.
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.
a hash value consistent with ==
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).
true if the receiver object is equivalent to the argument; false otherwise.
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.
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.
the receiver object.
ClassCastException if the receiver object is not an instance of the erasure of type T0.
Create a copy of the receiver object.
Create a copy of the receiver object.
The default implementation of the clone method is platform dependent.
a copy of the receiver object.
not specified by SLS as a member of AnyRef
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
Metalevels.scala for more information and examples about metalevels
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.
Tests whether the argument (that) is a reference to the receiver object (this).
Tests whether the argument (that) 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:
x and y of type AnyRef, multiple invocations of
x.eq(y) consistently returns true or consistently returns false.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).
true if the argument is a reference to the receiver object; false otherwise.
The equality method for reference types.
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.
not specified by SLS as a member of AnyRef
Obtains a ClassLoader instance used for macro expansion.
Obtains a ClassLoader instance used for macro expansion.
By default a new ScalaClassLoader is created using the classpath
from global and the classloader of self as parent.
Mirrors with runtime definitions (e.g. Repl) need to adjust this method.
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.
a representation that corresponds to the dynamic class of the receiver object.
not specified by SLS as a member of AnyRef
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)
The hashCode method for reference types.
Increases metalevel of the type, i.e.
Increases metalevel of the type, i.e. transforms: * T to c.Expr[T]
Metalevels.scala for more information and examples about metalevels
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.
true if the receiver object is an instance of erasure of type T0; false otherwise.
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:
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).
DefMacroExpander
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.
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.
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.
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.
Requested runtime if macro implementation can be loaded successfully from either of the mirrors,
null otherwise.
Equivalent to !(this eq that).
Equivalent to !(this eq that).
true if the argument is not a reference to the receiver object; false otherwise.
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.
not specified by SLS as a member of AnyRef
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.
not specified by SLS as a member of AnyRef
Default implementation of isBlackbox.
Default implementation of isBlackbox.
Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsIsBlackbox for more details)
Default implementation of macroArgs.
Default implementation of macroArgs.
Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsMacroArgs for more details)
Default implementation of macroExpand.
Default implementation of macroExpand.
Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsMacroExpand for more details)
Default implementation of typedMacroBody.
Default implementation of typedMacroBody.
Can be overridden by analyzer plugins (see AnalyzerPlugins.pluginsTypedMacroBody for more details)
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.
a String representation of the object.
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.
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.
Macro impl reference for the given macro definition if everything is okay. EmptyTree if an error occurs.
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.
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))