Reflection with quotes.reflect

The API is a member of the Quotes instance of the current scope. The usual way to reach all of it is an import inside the macro implementation:

quotes is a method that returns the Quotes in scope, so the import brings in every type and every companion-like module with its extension methods. Only import it where you need it. The code in the rest of the macro keeps the nicer Expr and Type view.

Source: Scala 3 Macros guide: Reflection

The two views convert into each other.

Source: Scala 3 Macros guide: Expr and Term

TypeRepr.of[A].typeSymbol is the shortcut for the symbol that defines A. flags.is(Flags.Case) tests a flag, and caseFields lists the case class parameters. The macro turns the compile-time list into a List[String] literal with Expr. For a class that is not a case class the macro reports a normal compile error:

The type Term and its subtypes are described as the tree hierarchy of the API page of scala.quoted.Quotes.reflectModule. For each type Foo, FooMethods holds the methods available on Foo and FooModule holds the constructors (apply, copy) and the unapply that makes the type usable in patterns. A subtype inherits the methods of its supertypes, so a TypeBounds value has the methods of TypeRepr.

Source: Scala 3 Macros guide: Expr and Term

A Term is a case-class-like tree. Pattern matching on it with the module extractors (Apply, Select, Ident, Literal, Inlined, Block, ValDef, …​) is the main way to navigate the API. The macro below prints what kind of tree it received, its widened type and its position.

Source: Scala 3 Reference: Reflection, tree extractors and constructors

Source: Scala 3 Reference: Reflection, tree extractors and constructors

Two lessons are in this output. First, an argument to an inline parameter arrives wrapped in Inlined, so a match that expects Apply directly would miss. The first case unwraps it. Second, positions are 0-based in the API (startLine, startColumn), so the macro adds 1 to get the numbers that the editor shows. term.pos is a Position that also has sourceFile, start, end, endLine and sourceCode.

For anything the pattern cases do not cover, print the tree structure:

That was structure(km + 1). The line is the actual extractor tree: the + is a Select on km applied to an Int literal. Printer.TreeStructure shows the constructor form, Printer.TreeCode shows source-like text (what .show does), and there are matching Printer.TypeReprStructure and Printer.TypeReprCode for types. When a pattern that you wrote does not match, this is the first thing to print.

Source: Scala 3 Macros guide: Reflection

A TypeRepr is the compiler’s representation of a type. The common operations are:

Source: Scala 3 Macros guide: Type and TypeRepr

Source: Scala 3 Macros guide: Type and TypeRepr

dealias only removes the top-level alias. Routes became the Map, but the alias Km inside the type arguments is still there. A macro that must compare types structurally should use <:< and =:= and not compare TypeRepr values with ==. The guide makes the same point for members: the two ways of getting the type of Leaf below are the same type but they are not ==.

Here Box is an object that holds sealed trait Base and case class Leaf(x: Int) extends Base. leafSym == baseSym.children.head is true: symbols can be compared with ==. Types cannot.

Source: Scala 3 Macros guide: Best practices and Scala 3 Reference: TypeReprs and TypeTrees

A Symbol identifies a definition: a class, method, val or type. Terms and types both have an associated symbol, and the symbol is how you compare definitions (==) and how you reach their members. The most used members are:

The case class Trail(name: String, lengthKm: Double, open: Boolean) reports 3 case fields and 15 declared methods (including the synthetic ones that the compiler adds), and the plain class class Hut(val beds: Int) declares no methods, because beds is a field.

Do not rely on Symbol.tree. The tree of a symbol is available only when the symbol was compiled in the same run, or the compiler was started with -Yretain-trees, and symbols that come from Java never have one. To get the type of a symbol use tpe.memberType(symbol) as shown above.

Source: Scala 3 Macros guide: Symbols

Reflection can also construct definitions, which quotes cannot do when the names or shapes are only known at compile time. Every new definition needs a symbol with an owner, a type and flags. The owner of code that appears inside the macro’s splice is Symbol.spliceOwner.

Source: Scala 3 Reference: Reflection, constructing and analysing trees

Source: Scala 3 Reference: Reflection, constructing and analysing trees

The macro creates a symbol for a val doubled: Int, builds its ValDef with a right-hand side x * 2, and returns a block { val doubled = x * 2; doubled }. Select.overloaded picks the right overload of * for the argument list.

A second example looks up a method by name at compile time and calls it:

Source: Scala 3 Macros guide: Symbols

With class Hut(val beds: Int) that has def capacity: Int = beds and def book(n: Int): Boolean:

The first call ran and printed 8. The two other calls were compiled separately as bad input to show the errors; they cannot appear in the same program as the first, because an error stops the compile. A first version of the macro applied the method to an empty argument list too, and failed on the parameterless capacity with method capacity in class Hut does not take parameters. A def without a parameter list is selected, not applied. Applying is only needed for a method with parameters, with Apply or appliedToArgs.

Source: Scala 3 Macros guide: Reflection

report is part of quotes.reflect. Its operations take an optional Position or an Expr/Tree that supplies one, so the message points at the code you choose: report.error(msg, expr), report.errorAndAbort(msg, expr), report.warning(msg, expr) and report.info(msg).

Source: Scala API: Quotes.reflectModule.reportModule and Scala 3 Reference: Reflection, positions

The caret is under the argument 1 because the macro passed x as the position. Without it the message points at the whole macro call.

A macro often has to ask: is there an instance of a type class in the caller’s scope? From the Expr API, Expr.summon[T] answers it (see Macros: Quotes & Splices). From reflection, Implicits.search(tpe) returns an ImplicitSearchSuccess with the tree, or an ImplicitSearchFailure with an explanation:

Source: Scala API: Quotes.reflectModule.ImplicitsModule

The result is the tree of the instance that the compiler would pick, here scala.math.Ordering.Int. Use Expr.summon when you already hold a Type, and Implicits.search when you start from a TypeRepr, as the guide recommends.

Source: Scala 3 Macros guide: Best practices

The guide’s best-practice page lists these rules for reflection code.

Should I write Expr(...) or '{ ... }? When the value is known at compile time, Expr(value) evaluates more of the work in the compiler. Quote only code that must run later, because it depends on runtime values. A quote of a primitive constant is optimised to the same result as Expr.apply.

How do I get the value out of an Expr? x.value returns an Option, x.valueOrAbort aborts with an error, and Expr.unapply works in patterns.

How do I get the precise type of an Expr? Match with a type variable, x match { case '{ $x: t } => ... }, which binds t to the precise type of x (see Quoted Pattern Matching).

How do I summon an instance for every element of a tuple type? Match the type with '[head *: tail] and '[EmptyTuple], summoning each head with Expr.summon. The FAQ page has two skeletons, one that returns List[Expr[Any]] and one that returns Option[Expr[Tuple]].

How do I summon an instance for a type I only know as a Type[?]? Name it with a pattern, case '[a] => Expr.summon[a], which also brings a given Type[a] into scope.

Source: Scala 3 Macros guide: FAQ

Scala 2 macros worked on the compiler’s scala.reflect.api trees through c.universe, which was a different API from the runtime reflection scala.reflect.runtime.universe but of a similar shape. In Scala 3 quotes.reflect is the compiler-time API. Runtime reflection also exists in Scala 3, through the JVM, as java.lang.reflect and scala.reflect.ClassTag/TypeTest. It sees classes after erasure, so it cannot tell List[Int] from List[String]. Java’s java.lang.reflect and annotation processing (javax.annotation.processing) are the Java counterparts; neither has access to typed trees. Kotlin offers KSP and compiler plugins, also outside the language.