wip

Author: biboudis

docs/docs/reference/features-classification.md

@@ -170,9 +170,9 @@ It's worth noting that macros were never included in the Scala 2 language specif
 To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for meta programming is our first priority.
 
 - [Match Types](https://dotty.epfl.ch/docs/reference/new-types/match-types.html) allow computation on types.
-- [Inline](https://dotty.epfl.ch/docs/reference/other-new-features/inline.html) provides
+- [Inline](https://dotty.epfl.ch/docs/reference/metaprogramming/inline.html) provides
 by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
-- [Quotes and Splices](https://dotty.epfl.ch/docs/reference/other-new-features/principled-meta-programming.html) provide a principled way to express macros and staging with a unified set of abstractions.
+- [Quotes and Splices](https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html) provide a principled way to express macros and staging with a unified set of abstractions.
 - [Typeclass derivation](https://dotty.epfl.ch/docs/reference/contextual/derivation.html) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
 - [Implicit by-name parameters](https://dotty.epfl.ch/docs/reference/contextual/inferable-by-name-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
 - [Erased Terms](https://dotty.epfl.ch/docs/reference/other-new-features/erased-terms.html) provide a general mechanism for compile-time-only computations.

docs/docs/reference/metaprogramming/inline.md

@@ -30,11 +30,11 @@ object Logger {
 }
 ```
 
-The `Config` object contains a definition of the **inline value**
-`logging`. This means that `logging` is treated as a _constant value_,
-equivalent to its right-hand side `false`. The right-hand side of such
-an `inline val` must itself be a [constant expression](#the-definition-of-constant-expression).
-Used in this way, `inline` is equivalent to Java and Scala 2's `final`. `final` meaning
+The `Config` object contains a definition of the **inline value** `logging`.
+This means that `logging` is treated as a _constant value_, equivalent to its
+right-hand side `false`. The right-hand side of such an `inline val` must itself
+be a [constant expression](#the-definition-of-constant-expression). Used in this
+way, `inline` is equivalent to Java and Scala 2's `final`. `final` meaning
 "constant" is still supported in Dotty, but will be phased out.
 
 The `Logger` object contains a definition of the **inline method** `log`.
@@ -106,16 +106,16 @@ val msg = s"factorial($n)"
 ```
 
 instead. This behavior is designed so that calling an inline method is
-semantically the same as calling a normal method: By-value arguments
-are evaluated before the call whereas by-name arguments are evaluated
-each time they are referenced. As a consequence, it is often
-preferable to make arguments of inline methods by-name in order to
-avoid unnecessary evaluations. Additionally, in the code above, our
-goal is to print the result after the evaluation of `op`. Imagine, if we were
-printing the duration of the evaluation between the two prints.
-
-For instance, here is how we can define a zero-overhead `foreach` method
-that translates into a straightforward while loop without any indirection or
+semantically the same as calling a normal method: By-value arguments are
+evaluated before the call whereas by-name arguments are evaluated each time they
+are referenced. As a consequence, it is often preferable to make arguments of
+inline methods by-name in order to avoid unnecessary evaluations. Additionally,
+in the code above, our goal is to print the result after the evaluation of `op`.
+Imagine, if we were printing the duration of the evaluation between the two
+prints.
+
+For instance, here is how we can define a zero-overhead `foreach` method that
+translates into a straightforward while loop without any indirection or
 overhead:
 
 ```scala
@@ -128,7 +128,8 @@ inline def foreach(op: => Int => Unit): Unit = {
 }
 ```
 
-By contrast, if `op` is a call-by-value parameter, it would be evaluated separately as a closure.
+By contrast, if `op` is a call-by-value parameter, it would be evaluated
+separately as a closure.
 
 Inline methods can be recursive. For instance, when called with a constant
 exponent `n`, the following method for `power` will be implemented by
@@ -205,10 +206,6 @@ constant expressions in the sense defined by the [SLS §
 including "platform-specific" extensions such as constant folding of pure
 numeric computations.
 
-#### Implicit Match
-
-https://github.com/lampepfl/dotty/pull/5392/files
-
 ### Specializing Inline (Whitebox)
 
 Inline methods support the `<: T` return syntax. This means that the return type
@@ -353,7 +350,6 @@ can safely use it to scrutinize its return type (`S[S[Z]]` in this case).
 `constvalue` is a function that produces the constant value represented by a
 type.
 
-
 ```scala
 inline def toIntC[N] <: Int =
   inline scala.compiletime.constValue[N] match {
@@ -364,8 +360,89 @@ inline def toIntC[N] <: Int =
 final val ctwo = toIntC[2]
 ```
 
+#### Implicit Match
+
+It is foreseen that many areas of typelevel programming can be done with rewrite
+methods instead of implicits. But sometimes implicits are unavoidable. The
+problem so far was that the Prolog-like programming style of implicit search
+becomes viral: Once some construct depends on implicit search it has to be
+written as a logic program itself. Consider for instance the problem of creating
+a `TreeSet[T]` or a `HashSet[T]` depending on whether `T` has an `Ordering` or
+not. We can create a set of implicit definitions like this:
+
+```scala
+trait SetFor[T, S <: Set[T]]
+class LowPriority {
+  implicit def hashSetFor[T]: SetFor[T, HashSet[T]] = ...
+}
+object SetsFor extends LowPriority {
+  implicit def treeSetFor[T: Ordering]: SetFor[T, TreeSet[T]] = ...
+}
+```
+
+Clearly, this is not pretty. Besides all the usual indirection of implicit
+search, we face the problem of rule prioritization where we have to ensure that
+`treeSetFor` takes priority over `hashSetFor` if the element type has an
+ordering. This is solved (clumsily) by putting `hashSetFor` in a superclass
+`LowPriority` of the object `SetsFor` where `treeSetFor` is defined. Maybe the
+boilerplate would still be acceptable if the crufty code could be contained.
+However, this is not the case. Every user of the abstraction has to be
+parameterized itself with a `SetFor` implicit. Considering the simple task _"I
+want a `TreeSet[T]` if `T` has an ordering and a `HashSet[T]` otherwise"_, this
+seems like a lot of ceremony.
+
+There are some proposals to improve the situation in specific areas, for
+instance by allowing more elaborate schemes to specify priorities. But they all
+keep the viral nature of implicit search programs based on logic programming.
+
+By contrast, the new `implicit match` construct makes implicit search available
+in a functional context. To solve the problem of creating the right set, one
+would use it as follows:
+```scala
+inline def setFor[T]: Set[T] = implicit match {
+  case ord: Ordering[T] => new TreeSet[T]
+  case _                => new HashSet[T]
+}
+```
+An implicit match uses the `implicit` keyword in the place of the scrutinee. Its
+patterns are type ascriptions of the form `identifier : Type`.
+
+Patterns are tried in sequence. The first case with a pattern `x: T` such that
+an implicit value of type `T` can be summoned is chosen. The variable `x` is
+then bound to the implicit value for the remainder of the case. It can in turn
+be used as an implicit in the right hand side of the case. It is an error if one
+of the tested patterns gives rise to an ambiguous implicit search.
+
+An implicit matches is considered to be a special kind of a inline match. This
+means it can only occur in the body of an inline method, and it must be reduced
+at compile time.
+
+Consequently, if we summon an `Ordering[String]` the code above will return a
+new instance of `TreeSet[String]`.
+
+```scala
+the[Ordering[String]]
+
+println(setFor[String].getClass) // prints class scala.collection.immutable.TreeSet
+```
+
+**Note** implicit matches can raise ambiguity errors. Consider the following
+code with two implicit values in scope of type `A`. The single pattern match
+case of the implicit match with type ascription of an `A` raises the ambiguity
+error.
+
+```scala
+class A
+implicit val a1: A = new A
+implicit val a2: A = new A
+
+inline def f: Any = implicit match {
+  case _: A => ???  // error: ambiguous implicits
+}
+```
 
 ### Reference
 
-For more info, see [PR #4927](https://github.com/lampepfl/dotty/pull/4768), which explains how
-inline methods can be used for typelevel programming and code specialization.
+For more info, see [PR #4927](https://github.com/lampepfl/dotty/pull/4768),
+which explains how inline methods can be used for typelevel programming and code
+specialization.