Add Expr.valueOrAbort and reflect.report.errorAndAbort

Provides a homogeneous and unambiguous concept for stopping the expansion of a macro.

The advantages of this naming are

* Consistent name suffixes `xyzAbort`
* `report.e` will show auto-completion for all variants of `error` and `errorAndAbort`
* `Abort` cannot be confused with other kinds of error handling in this API

Author: nicolasstucki

compiler/src/dotty/tools/dotc/transform/Splicer.scala

@@ -63,8 +63,11 @@ object Splicer {
       catch {
         case ex: CompilationUnit.SuspendException =>
           throw ex
+        case ex: scala.quoted.runtime.AbortExpansion if ctx.reporter.hasErrors =>
+          // errors have been emitted
+          EmptyTree
         case ex: scala.quoted.runtime.StopMacroExpansion if ctx.reporter.hasErrors =>
-           // errors have been emitted
+          // errors have been emitted
           EmptyTree
         case ex: StopInterpretation =>
           report.error(ex.msg, ex.pos)
@@ -423,6 +426,8 @@ object Splicer {
           throw new StopInterpretation(sw.toString, pos)
         case ex: InvocationTargetException =>
           ex.getTargetException match {
+            case ex: scala.quoted.runtime.AbortExpansion =>
+              throw ex
             case ex: scala.quoted.runtime.StopMacroExpansion =>
               throw ex
             case MissingClassDefinedInCurrentRun(sym) if ctx.compilationUnit.isSuspendable =>

compiler/src/scala/quoted/runtime/impl/QuotesImpl.scala

@@ -45,6 +45,17 @@ class QuotesImpl private (using val ctx: Context) extends Quotes, QuoteUnpickler
     def matches(that: scala.quoted.Expr[Any]): Boolean =
       treeMatch(reflect.asTerm(self), reflect.asTerm(that)).nonEmpty
 
+    def value(using fromExpr: FromExpr[T]): Option[T] =
+      fromExpr.unapply(self)(using QuotesImpl.this)
+
+    def valueOrAbort(using fromExpr: FromExpr[T]): T =
+      def reportError =
+        val tree = reflect.asTerm(self)
+        val code = reflect.Printer.TreeCode.show(tree)
+        val msg = s"Expected a known value. \n\nThe value of: $code\ncould not be extracted using $fromExpr"
+        reflect.report.throwError(msg, self)
+      fromExpr.unapply(self)(using QuotesImpl.this).getOrElse(reportError)
+
   end extension
 
   extension (self: scala.quoted.Expr[Any])
@@ -2750,17 +2761,17 @@ class QuotesImpl private (using val ctx: Context) extends Quotes, QuoteUnpickler
       def error(msg: String, pos: Position): Unit =
         dotc.report.error(msg, pos)
 
-      def throwError(msg: String): Nothing =
+      def errorAndAbort(msg: String): Nothing =
         error(msg)
-        throw new scala.quoted.runtime.StopMacroExpansion
+        throw new scala.quoted.runtime.AbortExpansion
 
-      def throwError(msg: String, expr: Expr[Any]): Nothing =
+      def errorAndAbort(msg: String, expr: Expr[Any]): Nothing =
         error(msg, expr)
-        throw new scala.quoted.runtime.StopMacroExpansion
+        throw new scala.quoted.runtime.AbortExpansion
 
-      def throwError(msg: String, pos: Position): Nothing =
+      def errorAndAbort(msg: String, pos: Position): Nothing =
         error(msg, pos)
-        throw new scala.quoted.runtime.StopMacroExpansion
+        throw new scala.quoted.runtime.AbortExpansion
 
       def warning(msg: String): Unit =
         dotc.report.warning(msg, Position.ofMacroExpansion)

docs/docs/reference/metaprogramming/macros.md

@@ -454,8 +454,8 @@ either a constant or is a parameter that will be a constant when instantiated. T
 aspect is also important for macro expansion.
 
 To get values out of expressions containing constants `Expr` provides the method
-`value` (or `valueOrError`). This will convert the `Expr[T]` into a `Some[T]` (or `T`) when the
-expression contains value. Otherwise it will retrun `None` (or emit an error).
+`value` (or `valueOrAbort`). This will convert the `Expr[T]` into a `Some[T]` (or `T`) when the
+expression contains value. Otherwise it will return `None` (or emit an error).
 To avoid having incidental val bindings generated by the inlining of the `def`
 it is recommended to use an inline parameter. To illustrate this, consider an
 implementation of the `power` function that makes use of a statically known exponent:
@@ -628,7 +628,7 @@ transparent inline def defaultOf(inline str: String) =
    ${ defaultOfImpl('str) }
 
 def defaultOfImpl(strExpr: Expr[String])(using Quotes): Expr[Any] =
-   strExpr.valueOrError match
+   strExpr.valueOrAbort match
       case "int" => '{1}
       case "string" => '{"a"}
 

library/src/scala/quoted/Expr.scala

@@ -46,7 +46,7 @@ object Expr {
    *    // value: T
    *  ```
    *
-   *  To directly get the value of an expression `expr: Expr[T]` consider using `expr.value`/`expr.valueOrError` instead.
+   *  To directly get the value of an expression `expr: Expr[T]` consider using `expr.value`/`expr.valueOrAbort` instead.
    *  @syntax markdown
    */
   def unapply[T](x: Expr[T])(using FromExpr[T])(using Quotes): Option[T] =

library/src/scala/quoted/Exprs.scala

@@ -14,7 +14,7 @@ object Exprs:
    *      ...
    *  }
    *  ```
-   *  To directly get the value of all expressions in a sequence `exprs: Seq[Expr[T]]` consider using `exprs.map(_.value)`/`exprs.map(_.valueOrError)` instead.
+   *  To directly get the value of all expressions in a sequence `exprs: Seq[Expr[T]]` consider using `exprs.map(_.value)`/`exprs.map(_.valueOrAbort)` instead.
    */
   def unapply[T](exprs: Seq[Expr[T]])(using FromExpr[T])(using Quotes): Option[Seq[T]] =
     val builder = Seq.newBuilder[T]

library/src/scala/quoted/Quotes.scala

@@ -44,22 +44,22 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
      *  Returns `None` if the expression does not represent a value or possibly contains side effects.
      *  Otherwise returns the `Some` of the value.
      */
-    def value(using FromExpr[T]): Option[T] =
-      given Quotes = Quotes.this
-      summon[FromExpr[T]].unapply(self)
+    def value(using FromExpr[T]): Option[T]
 
     /** Return the value of this expression.
      *
      *  Emits an error and throws if the expression does not represent a value or possibly contains side effects.
      *  Otherwise returns the value.
      */
-    def valueOrError(using FromExpr[T]): T =
-      val fromExpr = summon[FromExpr[T]]
-      def reportError =
-        val msg = s"Expected a known value. \n\nThe value of: ${self.show}\ncould not be extracted using $fromExpr"
-        reflect.report.throwError(msg, self)
-      given Quotes = Quotes.this
-      fromExpr.unapply(self).getOrElse(reportError)
+    @deprecated("Use valueOrThrow", "3.0.0-RC3")
+    def valueOrError(using FromExpr[T]): T = valueOrAbort
+
+    /** Return the value of this expression.
+     *
+     *  Emits an error and aborts if the expression does not represent a value or possibly contains side effects.
+     *  Otherwise returns the value.
+     */
+    def valueOrAbort(using FromExpr[T]): T
 
   end extension
 
@@ -4112,14 +4112,23 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
       /** Report an error message at the given position */
       def error(msg: String, pos: Position): Unit
 
-      /** Report an error at the position of the macro expansion and throw a StopMacroExpansion */
-      def throwError(msg: String): Nothing
+      /** Report an error at the position of the macro expansion and throw a AbortExpansion */
+      def errorAndAbort(msg: String): Nothing
 
-      /** Report an error at the position of `expr` */
-      def throwError(msg: String, expr: Expr[Any]): Nothing
+      /** Report an error at the position of `expr` and throw a AbortExpansion */
+      def errorAndAbort(msg: String, expr: Expr[Any]): Nothing
+
+      /** Report an error message at the given position and throw a AbortExpansion */
+      def errorAndAbort(msg: String, pos: Position): Nothing
+
+      /** Report an error at the position of the macro expansion and throw a AbortExpansion */
+      def throwError(msg: String): Nothing = errorAndAbort(msg)
+
+      /** Report an error at the position of `expr` and throw a AbortExpansion */
+      def throwError(msg: String, expr: Expr[Any]): Nothing = errorAndAbort(msg, expr)
 
-      /** Report an error message at the given position and throw a StopMacroExpansion */
-      def throwError(msg: String, pos: Position): Nothing
+      /** Report an error message at the given position and throw a AbortExpansion */
+      def throwError(msg: String, pos: Position): Nothing = errorAndAbort(msg, pos)
 
       /** Report a warning at the position of the macro expansion */
       def warning(msg: String): Unit

library/src/scala/quoted/runtime/AbortExpansion.scala

@@ -0,0 +1,9 @@
+package scala.quoted.runtime
+
+/** Throwable used to stop the quote expansion after an error was reported. */
+class AbortExpansion extends Throwable:
+
+  // Do not fill the stacktrace for performance.
+  // We know that the stacktrace will be ignored
+  // and only the reported error message will be used.
+  override def fillInStackTrace(): Throwable = this

library/src/scala/quoted/runtime/StopMacroExpansion.scala

@@ -1,4 +1,5 @@
 package scala.quoted.runtime
 
 /** Throwable used to stop the expansion of a macro after an error was reported */
+@deprecated("Use AbortExpansion", "3.0.0-RC3")
 class StopMacroExpansion extends Throwable

tests/bench/power-macro/PowerMacro.scala

@@ -5,7 +5,7 @@ object PowerMacro {
   inline def power(inline n: Long, x: Double) = ${ powerCode('n, 'x) }
 
   def powerCode(n: Expr[Long], x: Expr[Double])(using Quotes): Expr[Double] =
-    powerCode(n.valueOrError, x)
+    powerCode(n.valueOrAbort, x)
 
   def powerCode(n: Long, x: Expr[Double])(using Quotes): Expr[Double] =
     if (n == 0) '{1.0}

tests/neg-macros/i9014/Macros_1.scala

@@ -1,4 +1,4 @@
 import scala.quoted.*
 trait Bar
 inline given Bar = ${ impl }
-def impl(using Quotes): Expr[Bar] = quotes.reflect.report.throwError("Failed to expand!")
+def impl(using Quotes): Expr[Bar] = quotes.reflect.report.errorAndAbort("Failed to expand!")