Move Expr.underlyingArgument to UnsafeExpr.underlyingArgument

Make it explicit that this operation may change the call semantics.

Author: nicolasstucki

library/src/scala/quoted/Expr.scala

@@ -29,26 +29,6 @@ class Expr[+T] private[scala] {
   final def matches(that: Expr[Any])(given qctx: QuoteContext): Boolean =
     !scala.internal.quoted.Expr.unapply[Unit, Unit](this)(given that, false, qctx).isEmpty
 
-  /** Returns the undelying argument that was in the call before inlining.
-   *
-   *  ```
-   *  inline foo(x: Int): Int = baz(x, x)
-   *  foo(bar())
-   *  ```
-   *  is inlined as
-   *  ```
-   *  val x = bar()
-   *  baz(x, x)
-   *  ```
-   *  in this case the undelying argument of `x` will be `bar()`.
-   *
-   *  Warning: Using the undelying argument directly in the expansion of a macro may change the parameter
-   *           semantics from by-value to by-name.
-   */
-  def underlyingArgument(given qctx: QuoteContext): Expr[T] = {
-    import qctx.tasty.{given, _}
-    this.unseal.underlyingArgument.seal.asInstanceOf[Expr[T]]
-  }
 }
 
 object Expr {

library/src/scala/quoted/unsafe/UnsafeExpr.scala

@@ -0,0 +1,28 @@
+package scala.quoted
+package unsafe
+
+object UnsafeExpr {
+
+ /** Returns the undelying argument that was in the call before inlining.
+  *
+  *  ```
+  *  inline foo(x: Int): Int = baz(x, x)
+  *  foo(bar())
+  *  ```
+  *  is inlined as
+  *  ```
+  *  val x = bar()
+  *  baz(x, x)
+  *  ```
+  *  in this case the undelying argument of `x` will be `bar()`.
+  *
+  *  Warning: Using the undelying argument directly in the expansion of a macro may
+  *           change the parameter semantics as by-value parameter could be re-evaluated.
+  */
+  def underlyingArgument[T](expr: Expr[T])(given qctx: QuoteContext): Expr[T] = {
+    import qctx.tasty.{given, _}
+    expr.unseal.underlyingArgument.seal.asInstanceOf[Expr[T]]
+  }
+
+
+}

tests/run-macros/i7898/Macro_1.scala

@@ -1,9 +1,10 @@
 import quoted._
+import quoted.unsafe._
 object Main {
 
   def myMacroImpl(body: Expr[_])(given qctx: QuoteContext): Expr[_] = {
     import qctx.tasty.{_, given}
-    val bodyTerm = body.underlyingArgument.unseal
+    val bodyTerm = UnsafeExpr.underlyingArgument(body).unseal
     val showed = bodyTerm.show
     '{
       println(${Expr(showed)})

tests/run-macros/quoted-matching-docs/Macro_1.scala

@@ -1,5 +1,6 @@
 import scala.quoted._
 import scala.quoted.matching._
+import scala.quoted.unsafe._
 
 inline def sum(args: Int*): Int = ${ sumExpr('args) }
 
@@ -10,7 +11,7 @@ private def sumExprShow(argsExpr: Expr[Seq[Int]])(given QuoteContext): Expr[Stri
 
 private def sumExpr(argsExpr: Expr[Seq[Int]])(given qctx: QuoteContext): Expr[Int] = {
   import qctx.tasty.{given, _}
-  argsExpr.underlyingArgument match {
+  UnsafeExpr.underlyingArgument(argsExpr) match {
     case ConstSeq(args) => // args is of type Seq[Int]
       Expr(args.sum) // precompute result of sum
     case ExprSeq(argExprs) => // argExprs is of type Seq[Expr[Int]]