More docs for augmentations

Author: odersky

docs/docs/reference/augments/method-augments.md

@@ -78,7 +78,7 @@ augment List[type T] {
 ```
 
 The `type T` argument indicates that the augment applies to `List[T]`s for any type `T`.
-We also say that `type T` introduces `T` as a variable in the type pattern `List[type T]`.
+We also say that `type T` introduces `T` as a _variable_ in the type pattern `List[type T]`.
 Type variables may appear anywhere in a type pattern. Example:
 
 ```scala

docs/docs/reference/augments/trait-augments.md

@@ -0,0 +1,76 @@
+---
+layout: doc-page
+title: "Trait Augmentations"
+---
+
+In addition to adding methods, an augmentation can also implement traits and classes. For instance,
+
+```scala
+trait HasArea {
+  def area: Double
+}
+
+augment circleOps @ Circle extends HasArea {
+  def area = this.radius * this.radius * math.Pi
+}
+```
+
+This augemntation makes `Circle` implement the `HasArea` trait. Specifically, it defines an implicit subclass of `HasArea`
+which takes a `Circle` as argument and provides the given implementation. Hence, the implementation of the augmentation above would be like this
+
+```scala
+implicit class circleOps($this: Circle) extends HasArea {
+  def area = $this.radius * $this.radius * math.Pi
+}
+```
+
+A trait augmentation can thus provide a kind of "extends" relationship that can be defined independently of the types it connects.
+
+### Generic Trait Augmentations
+
+Just like method augmentations, trait augmentations can be generic with and their type parameters can have bounds.
+
+For example, assume we have the following two traits, which define binary and unary (infix) equality tests:
+
+```scala
+trait Eql[T] {
+  def eql (x: T, y: T): Boolean
+}
+
+trait HasEql[T] {
+  def === (that: T)
+}
+```
+
+The following augment makes any type `T` with an implicit `Eql[T]` instance implement `HasEql`:
+
+```scala
+augment (type T: Eql) extends HasEql[T] {
+  def === (that: T): Boolean = implicitly[Eql[T]].eql(this, that)
+}
+```
+
+### Syntax of Augmentations
+
+The syntax of augmentations iss pecified below as a delta with respect to the Scala syntax given [here](http://dotty.epfl.ch/docs/internals/syntax.html)
+
+    Augmentation        ::=  ‘augment’ [id ‘@’] BindingTypePattern
+                             [[nl] ImplicitParamClause] AugmentClause
+    AugmentClause       ::=  ‘extends’ Template
+                          |  [nl] ‘{’ ‘def’ DefDef {semi ‘def’ DefDef} ‘}’
+
+    ImplicitParamClause ::=  [nl] ‘(’ ImplicitMods ClsParams ‘)’
+    ImplicitMods        ::=  `implicit` [`ghost`] | `ghost` `implicit`
+
+    BindingTypePattern: :=  AnnotType
+    Type              ::=  ...
+                        |  ‘type’ TypeParamCore                (if inside a BindingTypePattern)
+    TypeParamCore     ::=  id [HkTypeParamClause] TypeParamBounds
+
+In this definition, type patterns and types share the same productions. However, the production
+
+    Type              ::=  ‘type’ TypeParamCore
+
+is applicable only inside a `BindingTypePattern`.
+
+

docs/docs/reference/augments/translation.md

@@ -0,0 +1,93 @@
+---
+layout: doc-page
+title: "Translation of Augmentations"
+---
+
+Augmentations are closely related to implicit classes and can be translated into them. In short,
+a method augmentation translates into an implicit value class and a trait implementation translates
+into a regular implicit class. The following sections sketch this translation.
+
+Conversely, it is conceivable (and desirable) to replace most usages of implicit classes and value classes by augmentations and [opaque types](../opaques.html). We plan to [drop](../dropped/implicit-value-classes.html)
+these constructs in future versions of the language. Once that is achieved, the translations described
+below can be simply composed with the existing translations of implicit and value classes into the core language. It is
+not necessary to retain implicit and value classes as an intermediate step.
+
+
+### Decomposing Type Patterns
+
+First, define a function `decompose` to decompose a type pattern `TP` into a list of type binders `tparams` and a type `T`. Going from left to right, every type binder `type U <bounds>` in `TP` is added to `tparams` and is replaced by the reference `U` in `T`. For instance, the type pattern
+
+```scala
+Map[type K <: AnyRef, List[type T]]
+```
+would be decomposed into the binders `type K <: AnyRef` and `type T` and the type `Map[K, List[T]]`.
+
+### Translation of Method Augmentations
+
+Now, a assume a method augmentation
+
+    augment <id> @ <TP> <params> { <defs> }
+
+where `<id> @` or `<params>` can be absent. For simplicity assume that there are no context bounds in
+type definitions of `<TP>`. This is no essential restriction as any such context bounds can be rewritten in a prior step to be evidence paramseters in `<params>`. Let `(<tparams>, <T>)` be the decomposition of `<TP>`.
+The augment clause can be translated to the following implicit value class:
+
+    implicit class <id> <tparams> ($this: <T>) extends AnyVal { <defs'> }
+
+Here `<defs'>` results from `<defs>` by augmenting any definition in <defs> with the parameters <params> and
+replacing any occurrence of `this` with `$this`. If the label `<id> @` is missing, a fresh compiler-generated name is chosen instead as the name of the implicit class.
+
+For example, the augmentation
+
+```scala
+augment seqOps @ Seq[type T: math.Ordering] {
+  def indexOfLargest  = this.zipWithIndex.maxBy(_._1)._2
+  def indexOfSmallest = this.zipWithIndex.minBy(_._1)._2
+}
+```
+
+would be translated to:
+
+```scala
+implicit class seqOps[T]($this: List[T]) extends AnyVal {
+  def indexOfLargest (implicit $ev: math.Ordering[T]) = $this.zipWithIndex.maxBy(_._1)._2
+  def indexOfSmallest(implicit $ev: math.Ordering[T]) = $this.zipWithIndex.minBy(_._1)._2
+}
+```
+
+### Translation of Trait Augmentations
+
+Now, assume a trait augmentation
+
+    augment <id> @ <TP> <params> extends <parents> { <body> }
+
+Let again `(<tparams>, <T>)` be the decomposition of `<TP>`. This augmentation is translated to
+
+    implicit class <id> <tparams> ($this: <T>) <params> extends <parents> { <body'> }
+
+As before, `<body'>` results from `<body>` by replacing any occurrence of `this` with `$this`. However, all
+parameters in <params> now stay on the class definition, instead of beging distributed to all members in `<body>`. This is necessary in general, since `<body>` might contain value definitions or other statements that cannot be
+parameterized.
+
+For example, the trait augmentation
+
+```scala
+class Test {
+  augment (type T: Eql) extends HasEql[T] {
+    def === (that: T): Boolean = implicitly[Eql[T]].eql(this, that)
+  }
+}
+```
+
+would be translated to
+
+```scala
+class Test {
+  implicit class Test$$_augment_T_to_HasEql_1 [T]
+                  ($this: T)(implicit $ev: Eql[T]) extends HasEql[T] {
+    def === (that: T): Boolean = implicitly[Eql[T]].eql($this, that)
+  }
+}
+```
+
+where the name `Test$$_augment_T_to_HasEql_1` is compiler generated and implementation dependent.

docs/docs/reference/dropped/implicit-value-classes.md

@@ -0,0 +1,35 @@
+---
+layout: doc-page
+title: Dropped: Implicit Classes and Value Classes
+---
+
+Scala uses implicit classes to define extension methods and conversions. E.g., from `Predef.scala`:
+
+```scala
+implicit final class ArrowAssoc[A](private val self: A) extends AnyVal {
+  def -> [B](y: B): (A, B) = (self, y)
+}
+```
+
+Implicit classes and value classes are still supported in Dotty, in order to support cross compilation with Scala 2. But they will be phased out in the future. The `ArrowAssoc` class can be written as an [augmentation](../augments/method-augments.html) as follows:
+
+```scala
+augment (type A) {
+  def -> [B](that: B): (A, B) = (this, that)
+}
+```
+
+Most other uses of value classes can be expressed by [opaque type aliases](../opaque.html).
+There are only two aspects of value classes that are not covered:
+
+ - A user-definable `toString` method. E.g. if `Meter` is a value class implemented in terms of `Double`, it is possible to define `toString` to that `new Meter(10).toString` prints `10m` instead of `10`.
+
+ - Type tests and checked type casts for value classes. E.g. if `x: Any` once can have a pattern match like this:
+
+      x match { case m: Meter => ... }
+
+   The match succeeds if `x` is a `Meter` but not if it is `Double`. By contrast, an implementation in terms of
+   opaque type aliases would flag the match with an unchecked warning and succeed for both. This is a consequence of using the same runtime representation for `Meter` and `Double`.
+
+Given the quite high complexity of value classes, in terms of rules what is legal and what is not, and in terms of their boxing model, it is attractive to drop them. The combinaton of opaque types and augmentations is both simpler and generally more pleasant to use.
+

docs/sidebar.yml

@@ -35,8 +35,6 @@ sidebar:
           subsection:
             - title: Method Augmentations
               url: docs/reference/augments/method-augments.html
-            - title: Type Patterns
-              url: docs/reference/augments/type-patterns.html
             - title: Trait Augmentations
               url: docs/reference/augments/trait-augments.html
             - title: Translation of Augmentations
@@ -113,6 +111,8 @@ sidebar:
               url: docs/reference/dropped/auto-apply.html
             - title: Weak Conformance
               url: docs/reference/dropped/weak-conformance.html
+            - title: Implicit and Value Classes
+              url: docs/reference/dropped/implicit-value-classes.html
     - title: Contributing
       subsection:
         - title: Getting Started

tests/run/augment.scala

@@ -19,13 +19,13 @@ object augments {
     def area = this.radius * this.radius * math.Pi
   }
 
-// Generic trait implementations
+// Generic augmentations
 
   augment List[type T] {
     def second = this.tail.head
   }
 
-// Specific trait implementations
+// Specific augmentations
 
   augment List[Int] {
     def maxx = (0 /: this)(_ `max` _)