Merge branch 'scala:main' into _overview/scala3-book/num24-code-tabs

Author: benluo

_overviews/scala3-macros/faq.md

@@ -13,7 +13,7 @@ All quotes containing a value of a primitive type is optimised to an `Expr.apply
 Choose one in your project and stick with a single notation to avoid confusion.
 
 ## How do I get a value out of an `Expr`?
-If the expression represents a value, you can use `.value`, `.valueOrError` or `Expr.unapply`
+If the expression represents a value, you can use `.value`, `.valueOrAbort` or `Expr.unapply`
 
 ## How can I get the precise type of an `Expr`?
 We can get the precise type (`Type`) of an `Expr` using the following pattern match:

_overviews/scala3-macros/tutorial/macros.md

@@ -14,13 +14,16 @@ Macros enable us to do exactly this: treat **programs as data** and manipulate t
 
 ## Macros Treat Programs as Values
 With a macro, we can treat programs as values, which allows us to analyze and generate them at compile time.
+
 A Scala expression with type `T` is represented by an instance of the type `scala.quoted.Expr[T]`.
 
 We will dig into the details of the type `Expr[T]`, as well as the different ways of analyzing and constructing instances, when talking about [Quoted Code][quotes] and [Reflection][tasty].
 For now, it suffices to know that macros are metaprograms that manipulate expressions of type `Expr[T]`.
 
-The following macro implementation simply prints the expression of the provided argument:
+The following macro implementation prints the expression of the provided argument:
 ```scala
+import scala.quoted.* // imports Quotes, Expr
+
 def inspectCode(x: Expr[Any])(using Quotes): Expr[Any] =
   println(x.show)
   x
@@ -113,7 +116,7 @@ def powerCode(
   x: Expr[Double],
   n: Expr[Int]
 )(using Quotes): Expr[Double] =
-  val value: Double = pow(x.valueOrError, n.valueOrError)
+  val value: Double = pow(x.valueOrAbort, n.valueOrAbort)
   Expr(value)
 ```
 Here, the `pow` operation is a simple Scala function that computes the value of `xⁿ`.
@@ -131,22 +134,36 @@ Other types can also work if a `ToExpr` is implemented for it, we will [see this
 
 ### Extracting Values from Expressions
 
-The second method we use in the implementation of `powerCode` is `Expr[T].valueOrError`, which has an effect opposite to `Expr.apply`.
+The second method we use in the implementation of `powerCode` is `Expr[T].valueOrAbort`, which has an effect opposite to `Expr.apply`.
 It attempts to extract a value of type `T` from an expression of type `Expr[T]`.
 This can only succeed, if the expression directly contains the code of a value, otherwise, it will throw an exception that stops the macro expansion and reports that the expression did not correspond to a value.
 
-Instead of `valueOrError`, we could also use the `value` operation, which will return an `Option`.
+Instead of `valueOrAbort`, we could also use the `value` operation, which will return an `Option`.
 This way we can report the error with a custom error message.
 
+#### Reporting Custom Error Messages
+
+The contextual `Quotes` parameter provides a `report` object that we can use to report a custom error message.
+Within a macro implementation method, you can access the contextual `Quotes` parameter with the `quotes` method
+(imported with `import scala.quoted.*`), then import the `report` object by `import quotes.reflect.report`.
+
+#### Providing the Custom Error
+
+We will provide the custom error message by calling `errorAndAbort` on the `report` object as follows:
 ```scala
-  ...
+def powerCode(
+  x: Expr[Double],
+  n: Expr[Int]
+)(using Quotes): Expr[Double] =
+  import quotes.reflect.report
   (x.value, n.value) match
     case (Some(base), Some(exponent)) =>
-      pow(base, exponent)
+      val value: Double = pow(base, exponent)
+      Expr(value)
     case (Some(_), _) =>
-      report.error("Expected a known value for the exponent, but was " + n.show, n)
+      report.errorAndAbort("Expected a known value for the exponent, but was " + n.show, n)
     case _ =>
-      report.error("Expected a known value for the base, but was " + x.show, x)
+      report.errorAndAbort("Expected a known value for the base, but was " + x.show, x)
 ```
 
 Alternatively, we can also use the `Expr.unapply` extractor
@@ -155,27 +172,30 @@ Alternatively, we can also use the `Expr.unapply` extractor
   ...
   (x, n) match
     case (Expr(base), Expr(exponent)) =>
-      pow(base, exponent)
+      val value: Double = pow(base, exponent)
+      Expr(value)
     case (Expr(_), _) => ...
     case _ => ...
 ```
-The operations `value`, `valueOrError`, and `Expr.unapply` will work for all _primitive types_, _tuples_ of any arity, `Option`, `Seq`, `Set`, `Map`, `Either` and `StringContext`.
+The operations `value`, `valueOrAbort`, and `Expr.unapply` will work for all _primitive types_, _tuples_ of any arity, `Option`, `Seq`, `Set`, `Map`, `Either` and `StringContext`.
 Other types can also work if an `FromExpr` is implemented for it, we will [see this later][quotes].
 
 
 ### Showing Expressions
 
 In the implementation of `inspectCode`, we have already seen how to convert expressions to the string representation of their _source code_ using the `.show` method.
 This can be useful to perform debugging on macro implementations:
+
+<!-- The below code example does not use multi-line string because it causes syntax highlighting to break -->
 ```scala
 def debugPowerCode(
   x: Expr[Double],
   n: Expr[Int]
 )(using Quotes): Expr[Double] =
   println(
-    s"""powerCode
-       |  x := ${x.show}
-       |  n := ${n.show}""".stripMargin)
+    s"powerCode \n" +
+    s"  x := ${x.show}\n" +
+    s"  n := ${n.show}")
   val code = powerCode(x, n)
   println(s"  code := ${code.show}")
   code
@@ -188,23 +208,24 @@ Varargs in Scala are represented with `Seq`, hence when we write a macro with a
 It is possible to recover each individual argument (of type `Expr[T]`) using the `scala.quoted.Varargs` extractor.
 
 ```scala
-import scala.quoted.Varargs
+import scala.quoted.* // imports `Varargs`, `Quotes`, etc.
 
 inline def sumNow(inline nums: Int*): Int =
   ${ sumCode('nums)  }
 
 def sumCode(nums: Expr[Seq[Int]])(using Quotes): Expr[Int] =
+  import quotes.reflect.report
   nums match
     case  Varargs(numberExprs) => // numberExprs: Seq[Expr[Int]]
-      val numbers: Seq[Int] = numberExprs.map(_.valueOrError)
+      val numbers: Seq[Int] = numberExprs.map(_.valueOrAbort)
       Expr(numbers.sum)
-    case _ => report.error(
-      "Expected explicit argument" +
-      "Notation `args: _*` is not supported.", numbersExpr)
+    case _ => report.errorAndAbort(
+      "Expected explicit varargs sequence. " +
+      "Notation `args*` is not supported.", nums)
 ```
 
 The extractor will match a call to `sumNow(1, 2, 3)` and extract a `Seq[Expr[Int]]` containing the code of each parameter.
-But, if we try to match the argument of the call `sumNow(nums: _*)`, the extractor will not match.
+But, if we try to match the argument of the call `sumNow(nums*)`, the extractor will not match.
 
 `Varargs` can also be used as a constructor. `Varargs(Expr(1), Expr(2), Expr(3))` will return an `Expr[Seq[Int]]`.
 We will see how this can be useful later.
@@ -244,7 +265,7 @@ inline def test(inline ignore: Boolean, computation: => Unit): Boolean =
   ${ testCode('ignore, 'computation) }
 
 def testCode(ignore: Expr[Boolean], computation: Expr[Unit])(using Quotes) =
-  if ignore.valueOrError then Expr(false)
+  if ignore.valueOrAbort then Expr(false)
   else Expr.block(List(computation), Expr(true))
 ```
 

_overviews/scala3-macros/tutorial/quotes.md

@@ -367,7 +367,7 @@ As with expression quote patterns, type variables are represented using lower ca
 
 ## FromExpr
 
-The `Expr.value`, `Expr.valueOrError`, and `Expr.unapply` methods uses intances of `FromExpr` to extract the value if possible.
+The `Expr.value`, `Expr.valueOrAbort`, and `Expr.unapply` methods uses intances of `FromExpr` to extract the value if possible.
 ```scala
 extension [T](expr: Expr[T]):
   def value(using Quotes)(using fromExpr: FromExpr[T]): Option[T] =

_tour/package-objects.md

@@ -1,29 +1,50 @@
 ---
 layout: tour
-title: Package Objects
+title: Top Level Definitions in Packages
 partof: scala-tour
 
 num: 36
 previous-page: packages-and-imports
 ---
 
-# Package objects
+Often, it is convenient to have definitions accessible accross an entire package, and not need to invent a
+name for a wrapper `object` to contain them.
 
-Scala provides package objects as a convenient container shared across an entire package.
+{% tabs pkg-obj-vs-top-lvl_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_1 %}
+Scala 2 provides _package objects_ as a convenient container shared across an entire package.
 
 Package objects
 can contain arbitrary definitions, not just variable and method definitions. For instance, they are frequently
 used to hold package-wide type aliases and implicit conversions. Package objects can even inherit
 Scala classes and traits.
 
+> In a future version of Scala 3, package objects will be removed in favor of top level definitions.
+
 By convention, the source code for a package object is usually put in a source file named `package.scala`.
 
 Each package is allowed to have one package object. Any definitions placed in a package object are considered
 members of the package itself.
 
+{% endtab %}
+{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_1 %}
+In Scala 3, any kind of definition can be declared at the top level of a package. For example, classes, enums,
+methods and variables.
+
+Any definitions placed at the top level of a package are considered members of the package itself.
+
+> In Scala 2 top-level method, type and variable definitions had to be wrapped in a **package object**.
+> These are still usable in Scala 3 for backwards compatibility. You can see how they work by switching tabs.
+
+{% endtab %}
+{% endtabs %}
+
 See example below. Assume first a class `Fruit` and three `Fruit` objects in a package
 `gardening.fruits`:
 
+
+{% tabs pkg-obj-vs-top-lvl_2 %}
+{% tab 'Scala 2 and 3' for=pkg-obj-vs-top-lvl_2 %}
 ```
 // in file gardening/fruits/Fruit.scala
 package gardening.fruits
@@ -33,10 +54,15 @@ object Apple extends Fruit("Apple", "green")
 object Plum extends Fruit("Plum", "blue")
 object Banana extends Fruit("Banana", "yellow")
 ```
+{% endtab %}
+{% endtabs %}
 
 Now assume you want to place a variable `planted` and a method `showFruit` directly into package `gardening.fruits`.
 Here's how this is done:
 
+{% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %}
+
 ```
 // in file gardening/fruits/package.scala
 package gardening
@@ -47,13 +73,29 @@ package object fruits {
   }
 }
 ```
+{% endtab %}
+{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %}
+
+```
+// in file gardening/fruits/package.scala
+package gardening.fruits
+
+val planted = List(Apple, Plum, Banana)
+def showFruit(fruit: Fruit): Unit =
+  println(s"${fruit.name}s are ${fruit.color}")
+```
+{% endtab %}
+{% endtabs %}
 
-As an example of how to use this, the following object `PrintPlanted` imports `planted` and `showFruit` in exactly the same
-way it imports class `Fruit`, using a wildcard import on package gardening.fruits:
+As an example of how to use this, the following program imports `planted` and `showFruit` in exactly the same
+way it imports class `Fruit`, using a wildcard import on package `gardening.fruits`:
 
+{% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %}
 ```
 // in file PrintPlanted.scala
 import gardening.fruits._
+
 object PrintPlanted {
   def main(args: Array[String]): Unit = {
     for (fruit <- planted) {
@@ -62,11 +104,53 @@ object PrintPlanted {
   }
 }
 ```
+{% endtab %}
+{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %}
+```
+// in file printPlanted.scala
+import gardening.fruits.*
 
-Package objects are like other objects, which means you can use inheritance for building them. For example, one might mix in a couple of traits:
+@main def printPlanted(): Unit =
+  for fruit <- planted do
+    showFruit(fruit)
+```
+{% endtab %}
+{% endtabs %}
+
+### Aggregating Several Definitions at the Package Level
+
+Often, your project may have several reusable definitions defined in various modules, that you
+wish to aggregate at the top level of a package.
+
+For example, some helper methods in the trait `FruitHelpers` and
+some term/type aliases in trait `FruitAliases`. Here is how you can put all their definitions at the level of the `fruit`
+package:
+
+{% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %}
+
+Package objects are like other objects, which means you can use inheritance for building them.
+So here we mix in the helper traits as parents of the package object.
 
 ```
-package object fruits extends FruitAliases with FruitHelpers {
-  // helpers and variables follows here
-}
+package gardening
+
+// `fruits` instead inherits its members from its parents.
+package object fruits extends FruitAliases with FruitHelpers
+```
+{% endtab %}
+{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %}
+
+In Scala 3, it is preferred to use `export` to compose members from several objects into a single scope.
+Here we define private objects that mix in the helper traits, then export their members at the top level:
+
+```
+package gardening.fruits
+
+private object FruitAliases extends FruitAliases
+private object FruitHelpers extends FruitHelpers
+
+export FruitHelpers.*, FruitAliases.*
 ```
+{% endtab %}
+{% endtabs %}

_tour/packages-and-imports.md

@@ -38,7 +38,7 @@ One convention is to name the package the same as the directory containing the S
           UserPreferences.scala
     - test
 ```
-Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by using braces:
+Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by nesting them inside each other:
 
 {% tabs packages-and-imports_2 class=tabs-scala-version %}
 {% tab 'Scala 2' for=packages-and-imports_2 %}
@@ -58,6 +58,7 @@ package users {
 package users:
   package administrators:
     class NormalUser
+
   package normalusers:
     class NormalUser
 ```