Change docs to given/using syntax

Author: odersky

docs/docs/reference/contextual/by-name-context-parameters.md

@@ -12,7 +12,7 @@ trait Codec[T] {
 
 given intCodec as Codec[Int] = ???
 
-given optionCodec[T] with (ev: => Codec[T]) as Codec[Option[T]] {
+given optionCodec[T](using ev: => Codec[T]) as Codec[Option[T]] {
   def write(xo: Option[T]) = xo match {
     case Some(x) => ev.write(x)
     case None =>
@@ -55,7 +55,7 @@ In the example above, the definition of `s` would be expanded as follows.
 
 ```scala
 val s = summon[Test.Codec[Option[Int]]](
-  optionCodec[Int].with(intCodec)
+  optionCodec[Int](using intCodec)
 )
 ```
 

docs/docs/reference/contextual/context-bounds-new.md

@@ -11,11 +11,11 @@ def maximum[T: Ord](xs: List[T]): T = xs.reduceLeft(max)
 ```
 A bound like `: Ord` on a type parameter `T` of a method or class indicates a context parameter `with Ord[T]`. The context parameter(s) generated from context bounds come last in the definition of the containing method or class. E.g.,
 ```scala
-def f[T: C1 : C2, U: C3](x: T) with (y: U, z: V) : R
+def f[T: C1 : C2, U: C3](x: T)(using y: U, z: V): R
 ```
 would expand to
 ```scala
-def f[T, U](x: T) with (y: U, z: V) with C1[T], C2[T], C3[U]) : R
+def f[T, U](x: T)(using y: U, z: V)(using C1[T], C2[T], C3[U]): R
 ```
 Context bounds can be combined with subtype bounds. If both are present, subtype bounds come first, e.g.
 ```scala
@@ -25,12 +25,11 @@ def g[T <: B : C](x: T): R = ...
 ### Migration
 
 To ease migration, context bounds in Dotty map in Scala 3.0 to old-style implicit parameters
-for which arguments can be passed either using `.with(...)` or using a normal application.
-From Scala 3.1 on, they will map to context parameters instead, as is described above.
+for which arguments can be passed either with a `(using ...)` clause or with a normal application. From Scala 3.1 on, they will map to context parameters instead, as is described above.
 
 If the source version is `3.1` and the `-migration` command-line option is set, any pairing of an evidence
 context parameter stemming from a context bound with a normal argument will give a migration
-warning. The warning indicates that a `.with(...)` clause should be used instead. The rewrite can be
+warning. The warning indicates that a `(using ...)` clause is needed instead. The rewrite can be
 done automatically under `-rewrite`.
 
 ### Syntax

docs/docs/reference/contextual/context-functions-spec.md

@@ -22,7 +22,7 @@ methods with context parameters. Specifically, the `N`-ary function type
 ```scala
 package scala
 trait ContextFunctionN[-T1 , ... , -TN, +R] {
-  def apply with (x1: T1 , ... , xN: TN) : R
+  def apply(using x1: T1 , ... , xN: TN): R
 }
 ```
 Context function types erase to normal function types, so these classes are
@@ -45,7 +45,7 @@ The context function literal is evaluated as the instance creation
 expression
 ```scala
 new scala.ContextFunctionN[T1, ..., Tn, T] {
-  def apply with (x1: T1, ..., xn: Tn) : T = e
+  def apply(using x1: T1, ..., xn: Tn): T = e
 }
 ```
 A context parameter may also be a wildcard represented by an underscore `_`. In that case, a fresh name for the parameter is chosen arbitrarily.

docs/docs/reference/contextual/context-functions.md

@@ -17,7 +17,7 @@ the same way methods with context parameters is applied. For instance:
 
   def f(x: Int): Executable[Int] = ...
 
-  f(2).with(ec)    // explicit argument
+  f(2)(using ec)   // explicit argument
   f(2)             // argument is inferred
 ```
 Conversely, if the expected type of an expression `E` is a context function type
@@ -38,9 +38,9 @@ For example, continuing with the previous definitions,
 
   g(22)      // is expanded to g((ev: ExecutionContext) ?=> 22)
 
-  g(f(2))    // is expanded to g((ev: ExecutionContext) ?=> f(2).with(ev))
+  g(f(2))    // is expanded to g((ev: ExecutionContext) ?=> f(2)(using ev))
 
-  g((ctx: ExecutionContext) ?=> f(22).with(ctx)) // is left as it is
+  g((ctx: ExecutionContext) ?=> f(22)(using ctx)) // is left as it is
 ```
 ### Example: Builder Pattern
 
@@ -86,28 +86,28 @@ that would otherwise be necessary.
     t
   }
 
-  def row(init: Row ?=> Unit) with (t: Table) = {
+  def row(init: Row ?=> Unit)(using t: Table) = {
     given r as Row
     init
     t.add(r)
   }
 
-  def cell(str: String) with (r: Row) =
+  def cell(str: String)(using r: Row) =
     r.add(new Cell(str))
 ```
 With that setup, the table construction code above compiles and expands to:
 ```scala
   table { ($t: Table) ?=>
 
     row { ($r: Row) ?=>
-      cell("top left").with($r)
-      cell("top right").with($r)
-    }.with($t)
+      cell("top left")(using $r)
+      cell("top right")(using $r)
+    }(using $t)
 
     row { ($r: Row) ?=>
-      cell("bottom left").with($r)
-      cell("bottom right").with($r)
-    }.with($t)
+      cell("bottom left")(using $r)
+      cell("bottom right")(using $r)
+    }(using $t)
   }
 ```
 ### Example: Postconditions
@@ -118,10 +118,10 @@ As a larger example, here is a way to define constructs for checking arbitrary p
 object PostConditions {
   opaque type WrappedResult[T] = T
 
-  def result[T] with (r: WrappedResult[T]) : T = r
+  def result[T](using r: WrappedResult[T]): T = r
 
-  def (x: T) ensuring[T](condition: WrappedResult[T] ?=> Boolean): T = {
-    assert(condition.with(x))
+  def (x: T).ensuring[T](condition: WrappedResult[T] ?=> Boolean): T = {
+    assert(condition(using x))
     x
   }
 }

docs/docs/reference/contextual/context-parameters.md

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: "Context Parameters"
+title: "Using Clauses"
 ---
 
 Functional programming tends to express most dependencies as simple function parameterization.
@@ -11,22 +11,19 @@ repetitive arguments instead of the programmer having to write them explicitly.
 For example, with the [given instances](./givens.md) defined previously,
 a maximum function that works for any arguments for which an ordering exists can be defined as follows:
 ```scala
-def max[T](x: T, y: T) with (ord: Ord[T]) : T =
+def max[T](x: T, y: T)(using ord: Ord[T]): T =
   if ord.compare(x, y) < 0 then y else x
 ```
-Here, `ord` is a _context parameter_ introduced with a `with` clause.
+Here, `ord` is a _context parameter_ introduced with a `using` clause.
 The `max` method can be applied as follows:
 ```scala
-max(2, 3).with(intOrd)
+max(2, 3)(using intOrd)
 ```
-The `.with(intOrd)` part passes `intOrd` as an argument for the `ord` parameter. But the point of
-context parameters is that this argument can also be left out (and it usually is). So the following
-applications are equally valid:
+The `(using intOrd)` part passes `intOrd` as an argument for the `ord` parameter. But the point of context parameters is that this argument can also be left out (and it usually is). So the following applications are equally valid:
 ```scala
 max(2, 3)
 max(List(1, 2, 3), Nil)
 ```
-Formatting hint: For legibility it is recommended to always leave one space after a `with` clause before following it with another lexeme.
 
 ## Anonymous Context Parameters
 
@@ -35,45 +32,41 @@ mentioned explicitly at all, since it is used only in synthesized arguments for
 other context parameters. In that case one can avoid defining a parameter name
 and just provide its type. Example:
 ```scala
-def maximum[T](xs: List[T]) with Ord[T] : T =
+def maximum[T](xs: List[T])(using Ord[T]): T =
   xs.reduceLeft(max)
 ```
 `maximum` takes a context parameter of type `Ord` only to pass it on as an
 inferred argument to `max`. The name of the parameter is left out.
 
-Generally, context parameters may be defined either as a full parameter list `(p_1: T_1, ..., p_n: T_n)` or just as a sequence of types `T_1, ..., T_n`. Vararg parameters are not supported in with clauses.
-
-**Note:** According to the rules above, a `with` clause like `(A, B)` consisting of types in parentheses defines a context parameter of tuple type. But by analogy with `(a: A, b: B)` one might assume that it defines two context parameters
-of type `A` and `B` instead. To avoid confusion, the compiler could issue a warning in this case that clarifies the meaning. If a context parameter of tuple type is in fact intended, the warning can be avoided by switching to a named context parameter,
-e.g. `(ab: (A, B))` or enclosing the tuple in an extra set of parentheses, e.g. `((A, B))`.
+Generally, context parameters may be defined either as a full parameter list `(p_1: T_1, ..., p_n: T_n)` or just as a sequence of types `T_1, ..., T_n`. Vararg parameters are not supported in using clauses.
 
 ## Inferring Complex Arguments
 
 Here are two other methods that have a context parameter of type `Ord[T]`:
 ```scala
-def descending[T] with (asc: Ord[T]) : Ord[T] = new Ord[T] {
+def descending[T](using asc: Ord[T]): Ord[T] = new Ord[T] {
   def compare(x: T, y: T) = asc.compare(y, x)
 }
 
-def minimum[T](xs: List[T]) with Ord[T] =
-  maximum(xs).with(descending)
+def minimum[T](xs: List[T])(using Ord[T]) =
+  maximum(xs)(using descending)
 ```
 The `minimum` method's right hand side passes `descending` as an explicit argument to `maximum(xs)`.
 With this setup, the following calls are all well-formed, and they all normalize to the last one:
 ```scala
 minimum(xs)
-maximum(xs).with(descending)
-maximum(xs).with(descending.with(listOrd))
-maximum(xs).with(descending.with(listOrd.with(intOrd)))
+maximum(xs)(using descending)
+maximum(xs)(using descending(using listOrd))
+maximum(xs)(using descending(using listOrd(using intOrd)))
 ```
 
 ## Multiple With Clauses
 
-There can be several `with` clauses in a definition. Example:
+There can be several using clauses in a definition and using clauses can be freely mixed with normal parameter clauses. Example:
 ```scala
-def f(u: Universe) with (ctx: u.Context) with (s: ctx.Symbol, k: ctx.Kind) = ...
+def f(u: Universe)(using ctx: u.Context)(using s: ctx.Symbol, k: ctx.Kind) = ...
 ```
-Multiple with clauses are matched left-to-right in applications. Example:
+Multiple using clauses are matched left-to-right in applications. Example:
 ```scala
 object global extends Universe { type Context = ... }
 given ctx  as global.Context { type Symbol = ...; type Kind = ... }
@@ -83,56 +76,31 @@ given kind as ctx.Kind
 Then the following calls are all valid (and normalize to the last one)
 ```scala
 f(global)
-f(global).with(ctx)
-f(global).with(ctx).with(sym, kind)
+f(global)(using ctx)
+f(global)(using ctx)(using sym, kind)
 ```
-But `f(global).with(sym, kind)` would give a type error.
+But `f(global)(using sym, kind)` would give a type error.
 
-`with` clauses can be freely interspersed with normal parameters, but a normal parameter clause cannot
-directly follow a `with` clause consisting only of types outside parentheses. So the following is illegal:
-```scala
-def f with A, B (x: C) = ...
-```
-But the following variants are valid:
-```scala
-def g with A, B with (x: C) = ...
-def h with (A, B) (x: C) = ...
-```
 
 ## Summoning Instances
 
 The method `summon` in `Predef` returns the given of a specific type. For example,
 the given instance for `Ord[List[Int]]` is produced by
 ```scala
-summon[Ord[List[Int]]]  // reduces to listOrd.with(intOrd)
+summon[Ord[List[Int]]]  // reduces to listOrd(using intOrd)
 ```
 The `summon` method is simply defined as the (non-widening) identity function over a context parameter.
 ```scala
-def summon[T] with (x: T): x.type = x
+def summon[T](using x: T): x.type = x
 ```
 
 ## Syntax
 
-Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](../../internals/syntax.md).
+Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](../../internals/syntax.md). `using` is a soft keyword, recognized only at the start of a parameter or argument list. It can be used as a normal identifier everywhere else.
 ```
-ClsParamClauses     ::=  ...
-                      |  ClsParamClause ClsParamClauses
-                      |  ClsParamClauses1
-ClsParamClauses1    ::=  WithClsParamClause ClsParamClauses
-                      |  AnnotTypes ClsParamClauses1
-DefParamClauses     ::=  ...
-                      |  DefParamClause DefParamClauses
-                      |  DefParamClauses1
-DefParamClauses1    ::=  WithParamClause DefParamClauses
-                      |  AnnotTypes DefParamClauses1
-WithClsParamClause  ::=  ‘with’ (‘(’ (ClsParams | Types) ‘)’ | AnnotTypes)
-WithParamClause     ::=  ‘with’ (‘(’ (DefParams | Types) ‘)’ | AnnotTypes)
-Types               ::=  Type {‘,’ Type}
-AnnotTypes          ::=  AnnotType {‘,’ AnnotType}
-
-SimpleExpr          ::=  ...
-                      |  SimpleExpr ContextArguments
-ParArgumentExprss   ::=  {ParArgumentExprs | ContextArguments}
-ContextArguments    ::=  ‘.’ ‘with’ ArgumentExprs
-
+ClsParamClause      ::=  ... | UsingClsParamClause
+DefParamClauses     ::=  ... | UsingParamClause
+UsingClsParamClause ::=  ‘(’ ‘using’ (ClsParams | Types) ‘)’
+UsingParamClause    ::=  ‘(’ ‘using’ (DefParams | Types) ‘)’
+ParArgumentExprs    ::=  ... | ‘(’ ‘using’ ExprsInParens ‘)’
 ```

docs/docs/reference/contextual/derivation-new.md

@@ -139,15 +139,15 @@ signature and implementation of a `derived` method for a type class `TC[_]` are
 following form,
 
 ```scala
-def derived[T] with Mirror.Of[T] : TC[T] = ...
+def derived[T](using Mirror.Of[T]): TC[T] = ...
 ```
 
 That is, the `derived` method takes a context parameter of (some subtype of) type `Mirror` which defines the shape of
 the deriving type `T`, and computes the type class implementation according to that shape. This is all that the
 provider of an ADT with a `derives` clause has to know about the derivation of a type class instance.
 
-Note that `derived` methods may have given `Mirror` arguments indirectly (e.g. by having a context argument which in turn
-has a context `Mirror`, or not at all (e.g. they might use some completely different user-provided mechanism, for
+Note that `derived` methods may have context `Mirror` parameters indirectly (e.g. by having a context argument which in turn
+has a context `Mirror` parameter, or not at all (e.g. they might use some completely different user-provided mechanism, for
 instance using Dotty macros or runtime reflection). We expect that (direct or indirect) `Mirror` based implementations
 will be the most common and that is what this document emphasises.
 
@@ -175,7 +175,7 @@ we need to implement a method `Eq.derived` on the companion object of `Eq` that
 a `Mirror[T]`. Here is a possible implementation,
 
 ```scala
-inline given derived[T] with (m: Mirror.Of[T]) as Eq[T] = {
+inline given derived[T](using m: Mirror.Of[T]) as Eq[T] = {
   val elemInstances = summonAll[m.MirroredElemTypes]           // (1)
   inline m match {                                             // (2)
     case s: Mirror.SumOf[T]     => eqSum(s, elemInstances)
@@ -281,7 +281,7 @@ object Eq {
         }
     }
 
-  inline given derived[T] with (m: Mirror.Of[T]) as Eq[T] = {
+  inline given derived[T](using m: Mirror.Of[T]) as Eq[T] = {
     val elemInstances = summonAll[m.MirroredElemTypes]
     inline m match {
       case s: Mirror.SumOf[T]     => eqSum(s, elemInstances)
@@ -312,7 +312,7 @@ In this case the code that is generated by the inline expansion for the derived
 following, after a little polishing,
 
 ```scala
-given derived$Eq[T] with (eqT: Eq[T]) as Eq[Opt[T]] =
+given derived$Eq[T](using eqT: Eq[T]) as Eq[Opt[T]] =
   eqSum(summon[Mirror[Opt[T]]],
     List(
       eqProduct(summon[Mirror[Sm[T]]], List(summon[Eq[T]]))
@@ -329,24 +329,27 @@ As a third example, using a higher level library such as shapeless the type clas
 `derived` method as,
 
 ```scala
-given eqSum[A] with (inst: => K0.CoproductInstances[Eq, A]) as Eq[A] {
+given eqSum[A](using inst: => K0.CoproductInstances[Eq, A]) as Eq[A] {
   def eqv(x: A, y: A): Boolean = inst.fold2(x, y)(false)(
     [t] => (eqt: Eq[t], t0: t, t1: t) => eqt.eqv(t0, t1)
   )
 }
 
-given eqProduct[A] with (inst: K0.ProductInstances[Eq, A]) as Eq[A] {
+given eqProduct[A](using inst: K0.ProductInstances[Eq, A]) as Eq[A] {
   def eqv(x: A, y: A): Boolean = inst.foldLeft2(x, y)(true: Boolean)(
     [t] => (acc: Boolean, eqt: Eq[t], t0: t, t1: t) => Complete(!eqt.eqv(t0, t1))(false)(true)
   )
 }
 
-
-inline def derived[A] with (gen: K0.Generic[A]) as Eq[A] = gen.derive(eqSum, eqProduct)
+inline def derived[A](using gen: K0.Generic[A]) as Eq[A] = gen.derive(eqSum, eqProduct)
 ```
 
 The framework described here enables all three of these approaches without mandating any of them.
 
+For a brief discussion on how to use macros to write a type class `derived`
+method please read more at [How to write a type class `derived` method using
+macros](./derivation-macro.md).
+
 ### Deriving instances elsewhere
 
 Sometimes one would like to derive a type class instance for an ADT after the ADT is defined, without being able to