Merge pull request #11129 from dotty-staging/rename-staging-toolbox

Rename scala.quoted.staging.{Toolbox => Compiler}

Author: nicolasstucki

docs/docs/reference/metaprogramming/staging.md

@@ -60,15 +60,15 @@ The framework as discussed so far allows code to be staged, i.e. be prepared
 to be executed at a later stage. To run that code, there is another method
 in class `Expr` called `run`. Note that `$` and `run` both map from `Expr[T]`
 to `T` but only `$` is subject to the PCP, whereas `run` is just a normal method.
-`run` provides a `Quotes` that can be used to show the expression in its scope.
-On the other hand `withQuotes` provides a `Quotes` without evaluating the expression.
+`scala.quoted.staging.run` provides a `Quotes` that can be used to show the expression in its scope.
+On the other hand `scala.quoted.staging.withQuotes` provides a `Quotes` without evaluating the expression.
 
 ```scala
 package scala.quoted.staging
 
-def run[T](expr: Quotes ?=> Expr[T])(using toolbox: Toolbox): T = ...
+def run[T](expr: Quotes ?=> Expr[T])(using Compiler): T = ...
 
-def withQuotes[T](thunk: Quotes ?=> T)(using toolbox: Toolbox): T = ...
+def withQuotes[T](thunk: Quotes ?=> T)(using Compiler): T = ...
 ```
 
 ## Create a new Scala 3 project with staging enabled
@@ -99,17 +99,17 @@ scala -with-compiler -classpath out Test
 Now take exactly the same example as in [Macros](./macros.md). Assume that we
 do not want to pass an array statically but generate code at run-time and pass
 the value, also at run-time. Note, how we make a future-stage function of type
-`Expr[Array[Int] => Int]` in line 6 below. Using `run { ... }` we can evaluate an
-expression at runtime. Within the scope of `run` we can also invoke `show` on an expression
+`Expr[Array[Int] => Int]` in line 6 below. Using `staging.run { ... }` we can evaluate an
+expression at runtime. Within the scope of `staging.run` we can also invoke `show` on an expression
 to get a source-like representation of the expression.
 
 ```scala
-import scala.quoted.staging._
+import scala.quoted._
 
-// make available the necessary toolbox for runtime code generation
-given Toolbox = Toolbox.make(getClass.getClassLoader)
+// make available the necessary compiler for runtime code generation
+given staging.Compiler = staging.Compiler.make(getClass.getClassLoader)
 
-val f: Array[Int] => Int = run {
+val f: Array[Int] => Int = staging.run {
    val stagedSum: Expr[Array[Int] => Int] =
       '{ (arr: Array[Int]) => ${sum('arr)}}
    println(stagedSum.show) // Prints "(arr: Array[Int]) => { var sum = 0; ... }"

sbt-dotty/sbt-test/sbt-dotty/i7897/src/main/scala/hello/i7897.scala

@@ -1,6 +1,6 @@
 import scala.quoted._, staging._
 
-given Toolbox = Toolbox.make(getClass.getClassLoader)
+given Compiler = Compiler.make(getClass.getClassLoader)
 
 val f: Array[Int] => Int = run {
   val stagedSum: Expr[Array[Int] => Int] = '{ (arr: Array[Int]) => 6 }

sbt-dotty/sbt-test/sbt-dotty/quoted-example-project/src/main/scala/hello/Hello.scala

@@ -2,11 +2,11 @@ package hello
 
 // Import `Expr` and some extension methods
 import scala.quoted._
-import scala.quoted.staging.{run, Toolbox}
+import scala.quoted.staging.{run, Compiler}
 
 object Main {
 
-  given Toolbox = Toolbox.make(getClass.getClassLoader)
+  given Compiler = Compiler.make(getClass.getClassLoader)
 
   def main(args: Array[String]): Unit = {
 

sbt-dotty/sbt-test/sbt-dotty/quoted-example-project/src/test/scala/hello/Tests.scala

@@ -4,10 +4,11 @@ import org.junit.Test
 
 // Import Expr and some extension methods
 import scala.quoted._
+import scala.quoted.staging._
 
 class Tests {
 
-  implicit val toolbox: scala.quoted.staging.Toolbox = scala.quoted.staging.Toolbox.make(getClass.getClassLoader)
+  given Compiler = Compiler.make(getClass.getClassLoader)
 
   @Test def test(): Unit = {
     import hello.Main._

staging/src/scala/quoted/staging/Toolbox.scala renamed to staging/src/scala/quoted/staging/Compiler.scala

@@ -5,26 +5,26 @@ import scala.annotation.implicitNotFound
 
 import scala.quoted.runtime.impl.ScopeException
 
-@implicitNotFound("Could not find implicit scala.quoted.staging.Toolbox.\n\nDefault toolbox can be instantiated with:\n  `given scala.quoted.staging.Toolbox = scala.quoted.staging.Toolbox.make(getClass.getClassLoader)`\n\n")
-trait Toolbox:
+@implicitNotFound("Could not find implicit scala.quoted.staging.Compiler.\n\nDefault compiler can be instantiated with:\n  `import scala.quoted.staging.Compiler; given Compiler = Compiler.make(getClass.getClassLoader)`\n\n")
+trait Compiler:
   def run[T](expr: Quotes => Expr[T]): T
 
-object Toolbox:
+object Compiler:
 
-  /** Create a new instance of the toolbox using the the classloader of the application.
+  /** Create a new instance of the compiler using the the classloader of the application.
    *
    * Usuage:
    * ```
    * import scala.quoted.staging._
-   * given Toolbox = Toolbox.make(getClass.getClassLoader)
+   * given Compiler = Compiler.make(getClass.getClassLoader)
    * ```
    *
    * @param appClassloader classloader of the application that generated the quotes
-   * @param settings toolbox settings
-   * @return A new instance of the toolbox
+   * @param settings compiler settings
+   * @return A new instance of the compiler
    */
-  def make(appClassloader: ClassLoader)(implicit settings: Settings): Toolbox =
-    new Toolbox:
+  def make(appClassloader: ClassLoader)(implicit settings: Settings): Compiler =
+    new Compiler:
 
       private[this] val driver: QuoteDriver = new QuoteDriver(appClassloader)
 
@@ -43,14 +43,14 @@ object Toolbox:
 
     end new
 
-  /** Setting of the Toolbox instance. */
+  /** Setting of the Compiler instance. */
   case class Settings private (outDir: Option[String], compilerArgs: List[String])
 
   object Settings:
 
     implicit def default: Settings = make()
 
-    /** Make toolbox settings
+    /** Make compiler settings
      *  @param outDir Output directory for the compiled quote. If set to None the output will be in memory
      *  @param compilerArgs Compiler arguments. Use only if you know what you are doing.
      */
@@ -62,4 +62,4 @@ object Toolbox:
 
   end Settings
 
-end Toolbox
+end Compiler

staging/src/scala/quoted/staging/QuoteDriver.scala

@@ -9,7 +9,7 @@ import dotty.tools.repl.AbstractFileClassLoader
 import dotty.tools.dotc.reporting._
 import dotty.tools.dotc.util.ClasspathFromClassloader
 import scala.quoted._
-import scala.quoted.staging.Toolbox
+import scala.quoted.staging.Compiler
 import java.io.File
 import scala.annotation.tailrec
 
@@ -22,7 +22,7 @@ private class QuoteDriver(appClassloader: ClassLoader) extends Driver:
 
   private[this] val contextBase: ContextBase = new ContextBase
 
-  def run[T](exprBuilder: Quotes => Expr[T], settings: Toolbox.Settings): T =
+  def run[T](exprBuilder: Quotes => Expr[T], settings: Compiler.Settings): T =
     val outDir: AbstractFile =
       settings.outDir match
         case Some(out) =>
@@ -34,7 +34,7 @@ private class QuoteDriver(appClassloader: ClassLoader) extends Driver:
     end outDir
 
     val (_, ctx0: Context) = setup(settings.compilerArgs.toArray :+ "dummy.scala", initCtx.fresh)
-    val ctx = setToolboxSettings(ctx0.fresh.setSetting(ctx0.settings.outputDir, outDir), settings)
+    val ctx = setCompilerSettings(ctx0.fresh.setSetting(ctx0.settings.outputDir, outDir), settings)
 
     new QuoteCompiler().newRun(ctx).compileExpr(exprBuilder) match
       case Right(value) =>
@@ -59,7 +59,7 @@ private class QuoteDriver(appClassloader: ClassLoader) extends Driver:
     ictx.settings.classpath.update(ClasspathFromClassloader(appClassloader))(using ictx)
     ictx
 
-  private def setToolboxSettings(ctx: FreshContext, settings: Toolbox.Settings): ctx.type =
+  private def setCompilerSettings(ctx: FreshContext, settings: Compiler.Settings): ctx.type =
     // An error in the generated code is a bug in the compiler
     // Setting the throwing reporter however will report any exception
     ctx.setReporter(new ThrowingReporter(ctx.reporter))

staging/src/scala/quoted/staging/staging.scala

@@ -16,7 +16,7 @@ package object staging:
    *  This method should not be called in a context where there is already has a `Quotes`
    *  such as within a `run` or a `withQuotes`.
    */
-  def run[T](expr: Quotes ?=> Expr[T])(using toolbox: Toolbox): T = toolbox.run(expr(using _))
+  def run[T](expr: Quotes ?=> Expr[T])(using compiler: Compiler): T = compiler.run(expr(using _))
 
   /** Provide a new quote context within the scope of the argument that is only valid within the scope the argument.
    *  Return the result of the argument.
@@ -32,15 +32,15 @@ package object staging:
    *  This method should not be called in a context where there is already has a `Quotes`
    *  such as within a `run` or a `withQuotes`.
    */
-  def withQuotes[T](thunk: Quotes ?=> T)(using toolbox: Toolbox): T =
+  def withQuotes[T](thunk: Quotes ?=> T)(using compiler: Compiler): T =
     val noResult = new Object
     var result: T = noResult.asInstanceOf[T]
     def dummyRun(using Quotes): Expr[Unit] = {
       result = thunk
       '{}
     }
-    toolbox.run(dummyRun(using _))
-    assert(result != noResult) // toolbox.run should have thrown an exception
+    compiler.run(dummyRun(using _))
+    assert(result != noResult) // compiler.run should have thrown an exception
     result
   end withQuotes
 

staging/test-resources/repl-staging/i6007

@@ -1,7 +1,7 @@
 scala> import scala.quoted._
-scala> import scala.quoted.staging._
-scala> implicit def toolbox: Toolbox = Toolbox.make(getClass.getClassLoader)
-def toolbox: quoted.staging.Toolbox
+scala> import quoted.staging.{Compiler => StagingCompiler, _}
+scala> implicit def compiler: StagingCompiler = StagingCompiler.make(getClass.getClassLoader)
+def compiler: quoted.staging.Compiler
 scala> def v(using Quotes) = '{ (if true then Some(1) else None).map(v => v+1) }
 def v(using x$1: quoted.Quotes): quoted.Expr[Option[Int]]
 scala> scala.quoted.staging.withQuotes(v.show)

staging/test-resources/repl-staging/i6263

@@ -1,7 +1,7 @@
 scala> import quoted._
-scala> import quoted.staging._
-scala> implicit def toolbox: Toolbox = Toolbox.make(getClass.getClassLoader)
-def toolbox: quoted.staging.Toolbox
+scala> import quoted.staging.{Compiler => StagingCompiler, _}
+scala> implicit def compiler: StagingCompiler = StagingCompiler.make(getClass.getClassLoader)
+def compiler: quoted.staging.Compiler
 scala> def fn[T : Type](v : T) = println("ok")
 def fn[T](v: T)(implicit evidence$1: quoted.Type[T]): Unit
 scala> withQuotes { fn("foo") }

tests/disabled/neg-with-compiler/quote-run-in-macro-2/quoted_1.scala

@@ -4,7 +4,7 @@ object Macros {
 
   inline def foo(i: => Int): Int = ${ fooImpl('i) }
   def fooImpl(i: Expr[Int])(using Quotes): Expr[Int] = {
-    given Toolbox = Toolbox.make(getClass.getClassLoader)
+    given Compiler = Compiler.make(getClass.getClassLoader)
     val y: Int = run(i)
     y
   }