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,10 @@ object Splicer {
       catch {
         case ex: CompilationUnit.SuspendException =>
           throw ex
-        case ex: scala.quoted.runtime.StopMacroExpansion if ctx.reporter.hasErrors =>
-           // errors have been emitted
+        case ex: scala.quoted.runtime.StopMacroExpansion =>
+          if !ctx.reporter.hasErrors then
+            report.error("Macro expansion was aborted by the macro without any errors reported. Macros should issue errors to end-users to facilitate debugging when aborting a macro expansion.", splicePos)
+          // errors have been emitted
           EmptyTree
         case ex: StopInterpretation =>
           report.error(ex.msg, ex.pos)
@@ -546,4 +548,3 @@ object Splicer {
     }
   }
 }
-

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

@@ -45,6 +45,19 @@ 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
 
+    override def value(using fromExpr: FromExpr[T]): Option[T] =
+      fromExpr.unapply(self)(using QuotesImpl.this)
+
+    override def valueOrError(using FromExpr[T]): T = self.valueOrAbort
+
+    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])
@@ -2744,14 +2757,23 @@ class QuotesImpl private (using val ctx: Context) extends Quotes, QuoteUnpickler
         dotc.report.error(msg, pos)
 
       def throwError(msg: String): Nothing =
+        errorAndAbort(msg)
+
+      def throwError(msg: String, expr: Expr[Any]): Nothing =
+        errorAndAbort(msg, expr)
+
+      def throwError(msg: String, pos: Position): Nothing =
+        errorAndAbort(msg, pos)
+
+      def errorAndAbort(msg: String): Nothing =
         error(msg)
         throw new scala.quoted.runtime.StopMacroExpansion
 
-      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
 
-      def throwError(msg: String, pos: Position): Nothing =
+      def errorAndAbort(msg: String, pos: Position): Nothing =
         error(msg, pos)
         throw new scala.quoted.runtime.StopMacroExpansion
 

docs/docs/reference/metaprogramming/macros.md

@@ -460,7 +460,7 @@ 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).
+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:

library/src/scala/quoted/Quotes.scala

@@ -45,22 +45,24 @@ 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)
+    // TODO: deprecate in 3.1.0 and remove @experimental from valueOrAbort
+    // @deprecated("Use valueOrThrow", "3.1.0")
+    def valueOrError(using FromExpr[T]): T
+
+    /** 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.
+     */
+    @experimental
+    def valueOrAbort(using FromExpr[T]): T
 
   end extension
 
@@ -4133,12 +4135,30 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
       def error(msg: String, pos: Position): Unit
 
       /** Report an error at the position of the macro expansion and throw a StopMacroExpansion */
+      @experimental
+      def errorAndAbort(msg: String): Nothing
+
+      /** Report an error at the position of `expr` and throw a StopMacroExpansion */
+      @experimental
+      def errorAndAbort(msg: String, expr: Expr[Any]): Nothing
+
+      /** Report an error message at the given position and throw a StopMacroExpansion */
+      @experimental
+      def errorAndAbort(msg: String, pos: Position): Nothing
+
+      /** Report an error at the position of the macro expansion and throw a StopMacroExpansion */
+      // TODO: deprecate in 3.1.0 and remove @experimental from errorAndAbort
+      // @deprecated("Use errorAndAbort", "3.1.0")
       def throwError(msg: String): Nothing
 
-      /** Report an error at the position of `expr` */
+      /** Report an error at the position of `expr` and throw a StopMacroExpansion */
+      // TODO: deprecate in 3.1.0 and remove @experimental from errorAndAbort
+      // @deprecated("Use errorAndAbort", "3.1.0")
       def throwError(msg: String, expr: Expr[Any]): Nothing
 
       /** Report an error message at the given position and throw a StopMacroExpansion */
+      // TODO: deprecate in 3.1.0 and remove @experimental from errorAndAbort
+      // @deprecated("Use errorAndAbort", "3.1.0")
       def throwError(msg: String, pos: Position): Nothing
 
       /** Report a warning at the position of the macro expansion */

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

@@ -1,4 +1,9 @@
 package scala.quoted.runtime
 
-/** Throwable used to stop the expansion of a macro after an error was reported */
-class StopMacroExpansion extends Throwable
+/** Throwable used to abort the expansion of a macro after an error was reported */
+class StopMacroExpansion 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

project/MiMaFilters.scala

@@ -5,9 +5,20 @@ import com.typesafe.tools.mima.core.ProblemFilters._
 object MiMaFilters {
   val Library: Seq[ProblemFilter] = Seq(
     // New APIs marked @experimental in 3.0.1
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes.value"),
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes.valueOrAbort"),
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes.valueOrError"),
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
+    exclude[DirectMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
     exclude[DirectMissingMethodProblem]("scala.quoted.Quotes#reflectModule#TermParamClauseMethods.isErased"),
-    exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#TermParamClauseMethods.isErased"),
-    exclude[MissingClassProblem]("scala.annotation.internal.ErasedParam"),
     exclude[MissingClassProblem]("scala.annotation.experimental"),
+    exclude[MissingClassProblem]("scala.annotation.internal.ErasedParam"),
+    exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes.valueOrAbort"),
+    exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
+    exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
+    exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#reportModule.errorAndAbort"),
+    exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#TermParamClauseMethods.isErased"),
   )
 }

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!")

tests/neg-macros/i9014b/Macros_1.scala

@@ -1,4 +1,4 @@
 import scala.quoted._
 trait Bar
 transparent 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!")

tests/neg-macros/ill-abort.check

@@ -0,0 +1,6 @@
+
+-- Error: tests/neg-macros/ill-abort/quoted_2.scala:1:15 ---------------------------------------------------------------
+1 |def test = fail() // error
+  |           ^^^^^^
+  |Macro expansion was aborted by the macro without any errors reported. Macros should issue errors to end-users to facilitate debugging when aborting a macro expansion.
+  | This location contains code that was inlined from quoted_1.scala:3