Scala 3 Macros: Create Types with Arbitrary Values & Methods :: Jun 17, 2023

Sometimes you want to make types whose values & methods are determined programmatically, at compile time.

An example usecase is a `Builder` for arbitrary case classes:

case class User(firstName: String, age: Int)

val userBuilder = Builder[User]
  .withFirstName("Athena")
  .withAge(22)

println(userBuilder.age) // 22
println(userBuilder.build) // User("Athena", 22)

Note that autocomplete is somewhat working in Metals:

And that the type of `userBuilder` is

Builder[User] {
  val firstName: java.lang.String
  def withFirstName(value: java.lang.String): this
  val age: scala.Int
  def withAge(value: scala.Int): this
}

Tools of the Trade

One way to implement the `Builder` would be with Macro Annotations, which are an experimental feature introduced in Scala 3.3.

But this is not required. Programatic Structural Types already let us refine types with new vals and defs. Then we just need a macro to decide the names of the vals & defs. The macro must also be transparent in order to return the programmatic type.

Implementing the Builder class

As with other Structural Types, our Builder class must implement Selectable.

class Builder[T](
    mirror: Mirror.ProductOf[T],
    getters: IArray[String],
    setters: IArray[String]
) extends Selectable:
  private val values = Array.ofDim[Object](getters.length)

  def selectDynamic(name: String): Any =
    values(getters.indexOf(name))

  def applyDynamic(name: String)(args: Any*): this.type =
    values(setters.indexOf(name)) = args.head.asInstanceOf[Object]
    this

  def build: T = mirror.fromProduct(Tuple.fromArray(values))

When we call `Builder[User].age`, this is translated by the compiler into `Builder[User].selectDynamic("age")`. Likewise, `Builder[User].withAge(22)` becomes `Builder[User].applyDynamic("withAge")(22)`. Finally, `build` uses a Mirror to instantiate the class.

For `Builder[User]`, the `getters` array must be `IArray("firstName", "age")`, and `setters` must be `IArray("withFirstName", "withAge")`.

The Builder macro

Our macro is defined as the `apply` method in Builder's companion object:

import scala.deriving.*
import scala.compiletime.*
import scala.quoted.*

object Builder:
  transparent inline def apply[T <: Product] = ${ builderImpl[T] }

`builderImpl` summons the product mirror:

private def builderImpl[T: Type](using Quotes): Expr[Any] =
  Expr.summon[Mirror.ProductOf[T]].get match
    case '{
          $m: Mirror.ProductOf[T] {
            type MirroredElemLabels = mels
            type MirroredElemTypes = mets
          }
        } =>
      refineBuilder[T, mets, mels, Builder[T]](m)

`refineBuilder` is the meat and potatoes. It recursively loops over T's element types & labels, constructing the getter and setter arrays. Refinement is used to construct the structural refinement on Builder[T]. For the getter, this refinement is a simple val (`Refinement(TypeRepr.of[Res], getter, TypeRepr.of[met])`). But setters are harder, since they are Methods returning `this.type`.

private def refineBuilder[T: Type, Mets: Type, Mels: Type, Res: Type](
    m: Expr[Mirror.ProductOf[T]],
    getters: IArray[String] = IArray.empty,
    setters: IArray[String] = IArray.empty
)(using Quotes): Expr[Any] =
  import quotes.reflect.*
  (Type.of[Mets], Type.of[Mels]) match
    case ('[met *: metTail], '[mel *: melTail]) =>
      val getter: String = Type.valueOfConstant[mel].get.toString
      val setter = "with" + getter.head.toUpper + getter.substring(1)
      val getterRefinement =
        Refinement(TypeRepr.of[Res], getter, TypeRepr.of[met])
      val setterRefinement = RecursiveType: parent =>
        val mt =
          MethodType(List("value"))(
            _ => List(TypeRepr.of[met]),
            _ => parent.recThis
          )
        Refinement(getterRefinement, setter, mt)
      setterRefinement.asType match
        case '[tpe] =>
          refineBuilder[T, metTail, melTail, tpe](
            m,
            getters :+ getter,
            setters :+ setter
          )
    case ('[EmptyTuple], '[EmptyTuple]) =>
      '{
        new Builder[T](
          $m,
          ${ Expr(getters) },
          ${ Expr(setters) }
        ).asInstanceOf[Res]
      }

Error Messages

Because the setter methods return `this.type`, compiling `Builder[User].wrongMethodName(22)` makes scalac stack overflow. Hopefully there's a better way to encode the refinement with RecursiveType.

Conclusions

Scala 3 meta-programming is a pleasure to use. Macros + structural types allow many possibilities, but should only be used when all other methods are exhausted, since the IDE support and error messages are not as good as the alternatives.

Edit: It appears that returning `this` in a structural type is deprecated: https://github.com/lampepfl/dotty/discussions/14056#discussioncomment-6238099

Final Code

import scala.deriving.*
import scala.compiletime.*
import scala.quoted.*
import scala.collection.mutable as m
import scala.reflect.{ClassTag, classTag}

class Builder[T](
    mirror: Mirror.ProductOf[T],
    getters: IArray[String],
    setters: IArray[String]
) extends Selectable:
  private val values = Array.ofDim[Object](getters.length)

  def selectDynamic(name: String): Any =
    values(getters.indexOf(name))

  def applyDynamic(name: String)(args: Any*): this.type =
    values(setters.indexOf(name)) = args.head.asInstanceOf[Object]
    this

  def build: T = mirror.fromProduct(Tuple.fromArray(values))

object Builder:
  transparent inline def apply[T <: Product] = ${ builderImpl[T] }

  private def builderImpl[T: Type](using Quotes): Expr[Any] =
    Expr.summon[Mirror.ProductOf[T]].get match
      case '{
            $m: Mirror.ProductOf[T] {
              type MirroredElemLabels = mels
              type MirroredElemTypes = mets
            }
          } =>
        refineBuilder[T, mets, mels, Builder[T]](m)

  private def refineBuilder[T: Type, Mets: Type, Mels: Type, Res: Type](
      m: Expr[Mirror.ProductOf[T]],
      getters: IArray[String] = IArray.empty,
      setters: IArray[String] = IArray.empty
  )(using Quotes): Expr[Any] =
    import quotes.reflect.*
    (Type.of[Mets], Type.of[Mels]) match
      case ('[met *: metTail], '[mel *: melTail]) =>
        val getter: String = Type.valueOfConstant[mel].get.toString
        val setter = "with" + getter.head.toUpper + getter.substring(1)
        val getterRefinement =
          Refinement(TypeRepr.of[Res], getter, TypeRepr.of[met])
        val setterRefinement = RecursiveType: parent =>
          val mt =
            MethodType(List("value"))(
              _ => List(TypeRepr.of[met]),
              _ => parent.recThis
            )
          Refinement(getterRefinement, setter, mt)
        setterRefinement.asType match
          case '[tpe] =>
            refineBuilder[T, metTail, melTail, tpe](
              m,
              getters :+ getter,
              setters :+ setter
            )
      case ('[EmptyTuple], '[EmptyTuple]) =>
        '{
          new Builder[T](
            $m,
            ${ Expr(getters) },
            ${ Expr(setters) }
          ).asInstanceOf[Res]
        }

Tweet