Use given for implicit parameters and arguments

Author: odersky

compiler/src/dotty/tools/dotc/core/Types.scala

@@ -3879,11 +3879,11 @@ object Types {
     def selfType(implicit ctx: Context): Type = {
       if (selfTypeCache == null)
         selfTypeCache = {
-          val given = cls.givenSelfType
-          if (!given.isValueType) appliedRef
-          else if (cls is Module) given
+          val givenSelf = cls.givenSelfType
+          if (!givenSelf.isValueType) appliedRef
+          else if (cls is Module) givenSelf
           else if (ctx.erasedTypes) appliedRef
-          else AndType(given, appliedRef)
+          else AndType(givenSelf, appliedRef)
         }
       selfTypeCache
     }

compiler/src/dotty/tools/dotc/parsing/Parsers.scala

@@ -535,7 +535,7 @@ object Parsers {
           }
           else recur(operand())
         }
-        else if (in.token == WITH) {
+        else if (in.token == GIVEN) {
           val top1 = reduceStack(base, top, minInfixPrec, leftAssoc = true, nme.WITHkw, isType)
           assert(opStack `eq` base)
           val app = atSpan(startOffset(top1), in.offset) {
@@ -2139,7 +2139,7 @@ object Parsers {
                      ofInstance: Boolean = false): List[List[ValDef]] = {
       def recur(firstClause: Boolean, nparams: Int): List[List[ValDef]] = {
         val initialMods =
-          if (in.token == WITH) {
+          if (in.token == GIVEN) {
             in.nextToken()
             Modifiers(Contextual | Implicit)
           }

compiler/src/dotty/tools/dotc/parsing/Tokens.scala

@@ -180,6 +180,7 @@ object Tokens extends TokensCommon {
   final val ENUM = 62;             enter(ENUM, "enum")
   final val ERASED = 63;           enter(ERASED, "erased")
   final val INSTANCE = 64;         enter(INSTANCE, "instance")
+  final val GIVEN = 65;            enter(GIVEN, "given")
 
   /** special symbols */
   final val NEWLINE = 78;          enter(NEWLINE, "end of statement", "new line")
@@ -201,7 +202,7 @@ object Tokens extends TokensCommon {
   /** XML mode */
   final val XMLSTART = 96;         enter(XMLSTART, "$XMLSTART$<") // TODO: deprecate
 
-  final val alphaKeywords: TokenSet = tokenRange(IF, INSTANCE)
+  final val alphaKeywords: TokenSet = tokenRange(IF, GIVEN)
   final val symbolicKeywords: TokenSet = tokenRange(USCORE, VIEWBOUND)
   final val symbolicTokens: TokenSet = tokenRange(COMMA, VIEWBOUND)
   final val keywords: TokenSet = alphaKeywords | symbolicKeywords

compiler/src/dotty/tools/dotc/typer/Namer.scala

@@ -118,9 +118,9 @@ trait NamerContextOps { this: Context =>
   /** The given type, unless `sym` is a constructor, in which case the
    *  type of the constructed instance is returned
    */
-  def effectiveResultType(sym: Symbol, typeParams: List[Symbol], given: Type): Type =
+  def effectiveResultType(sym: Symbol, typeParams: List[Symbol], givenTp: Type): Type =
     if (sym.name == nme.CONSTRUCTOR) sym.owner.typeRef.appliedTo(typeParams.map(_.typeRef))
-    else given
+    else givenTp
 
   /** if isConstructor, make sure it has one non-implicit parameter list */
   def normalizeIfConstructor(termParamss: List[List[Symbol]], isConstructor: Boolean): List[List[Symbol]] =

docs/docs/internals/syntax.md

@@ -92,10 +92,11 @@ semi             ::=  ‘;’ |  nl {nl}
 
 ```
 abstract  case      catch     class     def       do        else      enum
-erased    extends   false     final     finally   for       if        implicit
-import    lazy      match     new       null      object    package   private
-protected override  return    super     sealed    then      throw     trait
-true      try       type      val       var       while     with      yield
+erased    extends   false     final     finally   for       given     if
+implicit  import    instance  lazy      match     new       null      object
+package   private   protected override  return    super     sealed    then
+throw     trait     true      try       type      val       var       while
+with      yield
 :         =         <-        =>        <:        :>        #         @
 ```
 
@@ -205,7 +206,7 @@ Catches           ::=  ‘catch’ Expr
 PostfixExpr       ::=  InfixExpr [id]                                           PostfixOp(expr, op)
 InfixExpr         ::=  PrefixExpr
                     |  InfixExpr id [nl] InfixExpr                              InfixOp(expr, op, expr)
-                    |  InfixExpr ‘with’ (InfixExpr | ParArgumentExprs)
+                    |  InfixExpr ‘given’ (InfixExpr | ParArgumentExprs)
 PrefixExpr        ::=  [‘-’ | ‘+’ | ‘~’ | ‘!’] SimpleExpr                       PrefixOp(expr, op)
 SimpleExpr        ::=  ‘new’ (ConstrApp [TemplateBody] | TemplateBody)          New(constr | templ)
                     |  BlockExpr
@@ -290,7 +291,7 @@ HkTypeParam       ::=  {Annotation} [‘+’ | ‘-’] (Id[HkTypeParamClause] |
 
 ClsParamClauses   ::=  {ClsParamClause}
 ClsParamClause    ::=  [nl] ‘(’ [[FunArgMods] ClsParams] ‘)’
-                    |  ‘with’ (‘(’ ([[FunArgMods] ClsParams] ‘)’ | ContextTypes)
+                    |  ‘given’ (‘(’ ([[FunArgMods] ClsParams] ‘)’ | ContextTypes)
 ClsParams         ::=  ClsParam {‘,’ ClsParam}
 ClsParam          ::=  {Annotation}                                             ValDef(mods, id, tpe, expr) -- point of mods on val/var
                        [{Modifier} (‘val’ | ‘var’) | ‘inline’] Param
@@ -299,7 +300,7 @@ Param             ::=  id ‘:’ ParamType [‘=’ Expr]
 
 DefParamClauses   ::=  {DefParamClause} [[nl] ‘(’ [FunArgMods] DefParams ‘)’]
 DefParamClause    ::=  [nl] ‘(’ [DefParams] ‘)’ | InstParamClause
-InstParamClause   ::=  ‘with’ (‘(’ [DefParams] ‘)’ | ContextTypes)
+InstParamClause   ::=  ‘given’ (‘(’ [DefParams] ‘)’ | ContextTypes)
 DefParams         ::=  DefParam {‘,’ DefParam}
 DefParam          ::=  {Annotation} [‘inline’] Param                            ValDef(mods, id, tpe, expr) -- point of mods at id.
 ContextTypes      ::=  RefinedType {‘,’ RefinedType}

docs/docs/reference/instances/context-params.md

@@ -1,69 +1,68 @@
 ---
 layout: doc-page
-title: "Context Parameters and Arguments"
+title: "Implicit Parameters and Arguments"
 ---
 
-Context parameters are the name of a new syntax for implicit parameters that aligns definition and call syntax. Parameter definitions
-and method  arguments both follow a `with` connective. On the definition side, the old syntax
+A new syntax for implicit parameters aligns definition and call syntax. Parameter definitions and method arguments both follow a `given` keyword. On the definition side, the old syntax
 ```scala
 def f(a: A)(implicit b: B)
 ```
 is now expressed as
 ```scala
-def f(a: A) with (b: B)
+def f(a: A) given (b: B)
 ```
 or, leaving out the parameter name,
 ```scala
-def f(a: A) with B
+def f(a: A) given B
 ```
 Implicit parameters defined with the new syntax are also called _context parameters_.
-They come with a matching syntax for applications: explicit arguments for context parameters are also given after a `with`.
+They come with a matching syntax for applications: explicit arguments for context parameters are also written after a `given`.
 
 The following example shows shows three methods that each have a context parameter for `Ord[T]`.
 ```scala
-def maximum[T](xs: List[T]) with Ord[T]: T =
+def maximum[T](xs: List[T]) given Ord[T]: T =
   xs.reduceLeft((x, y) => if (x < y) y else x)
 
-def descending[T] with (asc: Ord[T]): Ord[T] = new Ord[T] {
+def descending[T] given (asc: Ord[T]): Ord[T] = new Ord[T] {
   def (x: T) compareTo (y: T) = asc.compareTo(y)(x)
 }
 
-def minimum[T](xs: List[T]) with Ord[T] =
-  maximum(xs) with descending
+def minimum[T](xs: List[T]) given Ord[T] =
+  maximum(xs) given descending
 ```
 The `minimum` method's right hand side passes `descending` as an explicit argument to `maximum(xs)`.
 But usually, explicit arguments for context parameters are be left out. For instance,
 given `xs: List[Int]`, the following calls are all possible (and they all normalize to the last one:)
 ```scala
 maximum(xs)
-maximum(xs) with descending
-maximum(xs) with (descending with IntOrd)
+maximum(xs) given descending
+maximum(xs) given (descending given IntOrd)
 ```
-Arguments for context parameters must be given using the `with` syntax. So the expression `maximum(xs)(descending)` would give a type error.
+Arguments for context parameters must use the `given` syntax. So the expression `maximum(xs)(descending)` would produce a type error.
 
-The `with` connective is treated like an infix operator with the same precedence as other operators that start with a letter. The expression following a `with` may also be an argument list consisting of several implicit arguments separated by commas. If a tuple should be passed as a single implicit argument (probably an uncommon case), it has to be put in a pair of extra parentheses:
+The `given` connective is treated like an infix operator with the same precedence as other operators that start with a letter. The expression following a `given` may also be an argument list consisting of several implicit arguments separated by commas. If a tuple should be passed as a single implicit argument (probably an uncommon case), it has to be put in a pair of extra parentheses:
 ```scala
-def f with (x: A, y: B)
-f with (a, b)
+def f given (x: A, y: B)
+f given (a, b)
 
-def g with (xy: (A, B))
-g with ((a, b))
+def g given (xy: (A, B))
+g given ((a, b))
 ```
 Unlike existing implicit parameters, context parameters can be freely mixed with normal parameter lists.
 A context parameter may be followed by a normal parameter and _vice versa_. There can be several context parameter
 lists in a definition. Example:
 ```scala
-def f with (u: Universe) (x: u.T) with Context = ...
+def f given (u: Universe) (x: u.T) given Context = ...
 
-instance global for Universe { type T = String ... }
-instance ctx for Context { ... }
+instance global of Universe { type T = String ... }
+instance ctx of Context { ... }
 ```
 Then the following calls are all valid (and normalize to the last one)
 ```scala
 f("abc")
-(f with global)("abc")
-f("abc") with ctx
-(f with global)("abc") with ctx
+(f given global)("abc")
+f("abc") given ctx
+(f given global)("abc") given ctx
 ```
 Context parameters may be given either as a normal parameter list `(...)`
 or as a sequence of types. To distinguish the two, a leading `(` always indicates a parameter list.
@@ -81,9 +80,9 @@ def summon[T] with (x: T) = x
 Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](http://dotty.epfl.ch/docs/internals/syntax.html).
 ```
 ClsParamClause    ::=  ...
-                    |  ‘with’ (‘(’ [ClsParams] ‘)’ | ContextTypes)
+                    |  ‘given’ (‘(’ [ClsParams] ‘)’ | ContextTypes)
 DefParamClause    ::=  ...
                     |  InstParamClause
 InfixExpr         ::=  ...
-                    |  InfixExpr ‘with’ (InfixExpr | ParArgumentExprs)
+                    |  InfixExpr ‘given’ (InfixExpr | ParArgumentExprs)
 ```

docs/docs/reference/instances/discussion/motivation.md

@@ -33,13 +33,16 @@ Can implicit function types help? Implicit function types allow to abstract over
 
 ### Alternative Design
 
-`implicit` is a modifier that gets attached to various constructs. I.e. we talk about implicit vals, defs, objects, parameters, or arguments. This conveys mechanism rather than intent. What _is_ the intent that we want to convey? Ultimately it's "trade types for terms". The programmer specifies a type and the compiler fills in the term matching that type automatically. So the concept we are after would serve to express definitions that provide the canonical _instances_ for certain types.
-
-The next sections elaborate such an alternative design. It consists of three proposals:
-
- - A proposal to replace implicit _definitions_ by [instance definitions](./instance-defs.html).
- - A proposal for a [new syntax](./context-params.html) of implicit _parameters_ and their _arguments_.
- - A proposal to [replace all remaining usages](./replacing-implicits.html) of `implicit` in the language.
-
-The first two proposals are independent of each other. The last one would work only if the first two are adopted.
-A [discussion page](./discussion.html) summarizes and evaluates the proposal.
+`implicit` is a modifier that gets attached to various constructs.
+I.e. we talk about implicit vals, defs, objects, parameters, or arguments.
+This conveys mechanism rather than intent. What _is_ the intent that we want to convey?
+Ultimately it's "trade types for terms". The programmer specifies a type and the compiler
+fills in the term matching that type automatically. So the concept we are after would
+serve to express definitions that provide the canonical _instances_ for certain types.
+
+The next sections elaborate this alternative design. It consists of the following pages:
+
+ - a proposal to replace implicit _definitions_ by [instance definitions](./instance-defs.md),
+ - a proposal for a [new syntax](./context-params.md) of implicit _parameters_ and their _arguments_,
+ - updates to the syntax for [implicit function types and closures](./implicit-function-types.md),
+ - a new way to express [implicit conversions](./implicit-conversions.md) as instances of a special trait,

docs/docs/reference/instances/implicit-conversions.md

@@ -0,0 +1,78 @@
+---
+layout: doc-page
+title: "Implicit Conversions"
+---
+
+Implicit conversions are defined by instances of the `scala.Conversion` class.
+This class is defined in package `scala` as follows:
+```scala
+abstract class Conversion[-T, +U] extends (T => U)
+```
+For example, here is an implicit conversion from `String` to `Token`:
+```scala
+instance of Conversion[String, Token] {
+  def apply(str: String): Token = new KeyWord(str)
+}
+```
+An implicit conversion is applied automatically by the compiler in three situations:
+
+1. If an expression `e` has type `T`, and `T` does not conform to the expression's expected type `S`.
+2. In a selection `e.m` with `e` of type `T`, but `T` defines no member `m`.
+3. In an application `e.m(args)` with `e` of type `T`, if ``T` does define
+   some member(s) named `m`, but none of these members can be applied to the arguments `args`.
+
+In the first case, the compiler looks in the implicit scope for a an instance of
+`scala.Conversion` that maps an argument of type `T` to type `S`. In the second and third
+case, it looks for an instance of `scala.Conversion` that maps an argument of type `T`
+to a type that defines a member `m` which can be applied to `args` if present.
+If such an instance `C` is found, the expression `e` is replaced by `C.apply(e)`.
+
+## Examples
+
+1. The `Predef` package contains "auto-boxing" conversions that map
+primitive number types to subclasses of `java.lang.Number`. For instance, the
+conversion from `Int` to `java.lang.Integer` can be defined as follows:
+```scala
+instance int2Integer of Conversion[Int, java.lang.Integer] {
+  def apply(x: Int) = new java.lang.Integer(x)
+}
+```
+
+2. The "magnet" pattern is sometimes used to express many variants of a method. Instead of defining overloaded versions of the method, one can also let the method take one or more arguments of specially defined "magnet" types, into which various argument types can be converted. E.g.
+```scala
+object Completions {
+
+  // The argument "magnet" type
+  enum CompletionArg {
+    case Error(s: String)
+    case Response(f: Future[HttpResponse])
+    case Status(code: Future[StatusCode])
+  }
+  object CompletionArg {
+
+    // conversions defining the possible arguments to pass to `complete`
+    // these always come with CompletionArg
+    // They can be invoked explicitly, e.g.
+    //
+    //   CompletionArg.from(statusCode)
+
+    instance from of Conversion[String, CompletionArg] {
+      def apply(s: String) = CompletionArg.Error(s)
+    }
+    instance from of Conversion[Future[HttpResponse], CompletionArg] {
+      def apply(f: Future[HttpResponse]) = CompletionArg.Response(f)
+    }
+    instance from of Conversion[Future[StatusCode], CompletionArg] {
+      def apply(code: Future[StatusCode]) = CompletionArg.Status(code)
+    }
+  }
+  import CompletionArg._
+
+  def complete[T](arg: CompletionArg) = arg match {
+    case Error(s) => ...
+    case Response(f) => ...
+    case Status(code) => ...
+  }
+}
+```
+This setup is more complicated than simple overloading of `complete`, but it can still be useful if normal overloading is not available (as in the case above, since we cannot have two overloaded methods that take `Future[...]` arguments), or if normal overloading would lead to a combinatorial explosion of variants.