hidden:true

Macros stub.

Since the 2.10.0 Scala includes macros that can be enabled

with`import language.experimental.macros` on per-file basis

or with`-language:experimental.macros` on per-compilation basis.

Macros significantly simplify code analysis and code generation, which makes them a tool of choice for

a multitude of[[http://scalamacros.org/usecases/index.html real-world use cases]].

Scenarios that traditionally involve writing and maintaining boilerplate can be addressed

with macros in concise and maintainable way.

This documentation page explains a type-safe`printf` macro through an end-to-end example.

To follow the example, create a file named <code>Macros.scala</code> and paste the following

code (be sure to follow the comments in the code, they reveal important things to know about

the macro system, accompanying APIs and infrastructure):

To summarize the code provided above, macros are mini-compiler plugins that get executed whenever a compiler

comes across an invocation of a method declared as a macro. Such methods, dubbed ''macro definitions'', use

the`macro` keyword to reference ''macro implementations''.

Macro implementations use[[scala.reflect.api.package reflection API]] to communicate

with the compiler. The gateway to that API is`c`, a ubiquitous parameter of type[[scala.reflect.macros.Context]]

that must be present in all macro implementations. Compiler universe is available through`c.universe`.

Input arguments to a macro implementation are[[scala.reflect.api.Trees abstract syntax trees]], which

correspond to the arguments of the method invocation that triggered a macro expansion. These trees

are wrapped in[[scala.reflect.api.Exprs exprs]], typed wrappers over trees.

The end result produced by a macro implementation is an abstract syntax tree

wrapped in an expr. This tree represents the code that the compiler will use

to replace the original method invocation.

To learn more about how to create trees that correspond to given Scala code and how to perform

tree manipulations, visit[[scala.reflect.api.Trees the documentation page on trees]].

=== Compiling macros ===

In 2.10.0 macros are an experimental feature, so they need to be enabled before use.

Normal compilation of the snippet written above (using`scalac Macros.scala`) fails as follows:

def printf(format: String, params: Any*): Unit = macro printf_impl

^

one error found

To enable macros one should use either`import language.experimental.macros` on per-file basis

or`-language:experimental.macros` (providing a compiler switch) on per-compilation basis.

=== Using macros ===

Create a file named <code>Test.scala</code> and paste the following code (just as simple as that,

to use a macro, it's only necessary to import it and call it as it were a regular function).

import Macros._

printf("hello %s!", "world")

}

An important rule about using macros is separate compilation. To perform macro expansion, compiler

needs a macro implementation in executable form. Thus macro implementations need to be compiled before

the main compilation, otherwise compiler will produce`macro implementation not found` errors.

In the REPL, however, macros and their usages can be written in the same session. That's because

the REPL compiles every line of input in a separate compilation run.

The test snippet seems to work! To see what happens under the covers, enable the`-Ymacro-debug-lite` compiler flag.

With`-Ymacro-debug-lite` one can see both pseudo-Scala representation of the code generated by macro expansion

and raw AST representation of the expansion. Both have their merits: the former is useful for surface analysis,

while the latter is invaluable for fine-grained debugging.

=== Writing bigger macros ===

When the code of a macro implementation grows big enough to warrant modularization beyond the body

of the implementation method, it becomes apparent that one needs to carry around the context parameter,

because most things of interest are path-dependent on the context.

One of the approaches is to write a class that takes a parameter of type`Context` and then split the

macro implementation into a series of methods of that class. This is natural and simple, except that

it's hard to get it right. Here's a typical compilation error.

The problem in this snippet is in a path-dependent type mismatch. The Scala compiler

does not understand that`c` in`impl` is the same object as`c` in`Helper`, even though the helper

is constructed using the original`c`.

Luckily just a small nudge is all that is needed for the compiler to figure out what's going on.

One of the possible ways of doing that is using refinement types (the example below is the simplest

application of the idea; for example, one could also write an implicit conversion from`Context`

to`Helper` to avoid explicit instantiations and simplify the calls).

An alternative approach is to use the[[scala.Singleton]] upper bound to express the fact

that`Helper`'s`C` has the same identity as`impl`'s`C` (note that it is mandatory to

explicitly spell out the type argument when instantiating`Helper`).