Update docs to given ... with syntax

For given instances:

    given ...

For context parameters

    ... with ...

For context functions

    A ?=> B

Author: odersky

docs/docs/internals/syntax.md

@@ -299,19 +299,19 @@ HkTypeParam       ::=  {Annotation} [‘+’ | ‘-’] (Id[HkTypeParamClause] |
                        SubtypeBounds
 
 ClsParamClauses   ::=  {ClsParamClause} [[nl] ‘(’ [‘implicit’] ClsParams ‘)’]
-                    |  {ClsParamClause} {GivenClsParamClause}
+                    |  {ClsParamClause} {WithClsParamClause}
 ClsParamClause    ::=  [nl] ‘(’ ClsParams ‘)’
-GivenClsParamClause::= ‘with’ (‘(’ (ClsParams | Types) ‘)’ | AnnotTypes)
+WithClsParamClause::= ‘with’ (‘(’ (ClsParams | Types) ‘)’ | AnnotTypes)
 ClsParams         ::=  ClsParam {‘,’ ClsParam}
 ClsParam          ::=  {Annotation}                                             ValDef(mods, id, tpe, expr) -- point of mods on val/var
                        [{Modifier} (‘val’ | ‘var’) | ‘inline’] Param
 Param             ::=  id ‘:’ ParamType [‘=’ Expr]
                     |  INT
 
 DefParamClauses   ::=  {DefParamClause} [[nl] ‘(’ [‘implicit’] DefParams ‘)’]
-                    |  {DefParamClause} {GivenParamClause}
+                    |  {DefParamClause} {WithParamClause}
 DefParamClause    ::=  [nl] ‘(’ DefParams ‘)’
-GivenParamClause  ::=  ‘with’ (‘(’ (DefParams | Types) ‘)’ | AnnotTypes)
+WithParamClause   ::=  ‘with’ (‘(’ (DefParams | Types) ‘)’ | AnnotTypes)
 DefParams         ::=  DefParam {‘,’ DefParam}
 DefParam          ::=  {Annotation} [‘inline’] Param                            ValDef(mods, id, tpe, expr) -- point of mods at id.
 ClosureMods       ::=  { ‘implicit’ | ‘given’}
@@ -391,8 +391,8 @@ ObjectDef         ::=  id [Template]
 EnumDef           ::=  id ClassConstr InheritClauses EnumBody                   EnumDef(mods, name, tparams, template)
 GivenDef          ::=  [GivenSig] [‘_’ ‘<:’] Type ‘=’ Expr
                     |  [GivenSig] ConstrApps [TemplateBody]
-GivenSig          ::=  [id] [DefTypeParamClause] {GivenParamClause} ‘as’
-ExtensionDef      ::=  [id] ‘on’ ExtParamClause {GivenParamClause} ExtMethods
+GivenSig          ::=  [id] [DefTypeParamClause] {WithParamClause} ‘as’
+ExtensionDef      ::=  [id] ‘on’ ExtParamClause {WithParamClause} ExtMethods
 ExtMethods        ::=  [nl] ‘{’ ‘def’ DefDef {semi ‘def’ DefDef} ‘}’
 ExtParamClause    ::=  [DefTypeParamClause] ‘(’ DefParam ‘)’
 Template          ::=  InheritClauses [TemplateBody]                            Template(constr, parents, self, stats)

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

@@ -0,0 +1,67 @@
+---
+layout: doc-page
+title: "By-Name Context Parameters"
+---
+
+Context parameters can be declared by-name to avoid a divergent inferred expansion. Example:
+
+```scala
+trait Codec[T] {
+  def write(x: T): Unit
+}
+
+given intCodec as Codec[Int] = ???
+
+given optionCodec[T] with (ev: => Codec[T]) as Codec[Option[T]] {
+  def write(xo: Option[T]) = xo match {
+    case Some(x) => ev.write(x)
+    case None =>
+  }
+}
+
+val s = summon[Codec[Option[Int]]]
+
+s.write(Some(33))
+s.write(None)
+```
+As is the case for a normal by-name parameter, the argument for the context parameter `ev`
+is evaluated on demand. In the example above, if the option value `x` is `None`, it is
+not evaluated at all.
+
+The synthesized argument for a context parameter is backed by a local val
+if this is necessary to prevent an otherwise diverging expansion.
+
+The precise steps for synthesizing an argument for a by-name context parameter of type `=> T` are as follows.
+
+ 1. Create a new given of type `T`:
+
+    ```scala
+    given lv as T = ???
+    ```
+    where `lv` is an arbitrary fresh name.
+
+ 1. This given is not immediately available as candidate for argument inference (making it immediately available could result in a loop in the synthesized computation). But it becomes available in all nested contexts that look again for an argument to a by-name context parameter.
+
+ 1. If this search succeeds with expression `E`, and `E` contains references to `lv`, replace `E` by
+
+
+    ```scala
+    { given lv as T = E; lv }
+    ```
+
+    Otherwise, return `E` unchanged.
+
+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)
+)
+```
+
+No local given instance was generated because the synthesized argument is not recursive.
+
+### Reference
+
+For more info, see [Issue #1998](https://github.com/lampepfl/dotty/issues/1998)
+and the associated [Scala SIP](https://docs.scala-lang.org/sips/byname-implicits.html).

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

@@ -0,0 +1,30 @@
+---
+layout: doc-page
+title: "Context Bounds"
+---
+
+## Context Bounds
+
+A context bound is a shorthand for expressing the common pattern of a context parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:
+```scala
+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
+```
+would expand to
+```scala
+def f[T, U](x: T) with (y: U, z: V) with 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
+def g[T <: B : C](x: T): R = ...
+```
+
+## Syntax
+
+```
+TypeParamBounds   ::=  [SubtypeBounds] {ContextBound}
+ContextBound      ::=  ‘:’ Type
+```

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

@@ -3,6 +3,9 @@ layout: doc-page
 title: "Context Bounds"
 ---
 
+**Note** The syntax described in this section is currently under revision.
+[Here is the new version which will be implemented in Dotty 0.22](./context-bounds-new.html).
+
 ## Context Bounds
 
 A context bound is a shorthand for expressing the common pattern of an implicit parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:

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

@@ -0,0 +1,74 @@
+---
+layout: doc-page
+title: "Context Functions - More Details"
+---
+
+## Syntax
+
+    Type              ::=  ...
+                        |  FunArgTypes ‘?=>’ Type
+    Expr              ::=  ...
+                        |  FunParams ‘?=>’ Expr
+
+Context function types associate to the right, e.g.
+`S ?=> T ?=> U` is the same as `S ?=> (T ?=> U)`.
+
+## Implementation
+
+Context function types are shorthands for class types that define `apply`
+methods with context parameters. Specifically, the `N`-ary function type
+`T1, ..., TN => R` is a shorthand for the class type
+`ContextFunctionN[T1 , ... , TN, R]`. Such class types are assumed to have the following definitions, for any value of `N >= 1`:
+```scala
+package scala
+trait ContextFunctionN[-T1 , ... , -TN, +R] {
+  def apply with (x1: T1 , ... , xN: TN) : R
+}
+```
+Context function types erase to normal function types, so these classes are
+generated on the fly for typechecking, but not realized in actual code.
+
+Context function literals `(x1: T1, ..., xn: Tn) ?=> e` map
+context parameters `xi` of types `Ti` to the result of evaluating the expression `e`.
+The scope of each context parameter `xi` is `e`. The parameters must have pairwise distinct names.
+
+If the expected type of the context function literal is of the form
+`scala.ContextFunctionN[S1, ..., Sn, R]`, the expected type of `e` is `R` and
+the type `Ti` of any of the parameters `xi` can be omitted, in which case `Ti
+= Si` is assumed. If the expected type of the context function literal is
+some other type, all context parameter types must be explicitly given, and the expected type of `e` is undefined.
+The type of the context function literal is `scala.ContextFunctionN[S1, ...,Sn, T]`, where `T` is the widened
+type of `e`. `T` must be equivalent to a type which does not refer to any of
+the context parameters `xi`.
+
+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
+}
+```
+A context parameter may also be a wildcard represented by an underscore `_`. In that case, a fresh name for the parameter is chosen arbitrarily.
+
+Note: The closing paragraph of the
+[Anonymous Functions section](https://www.scala-lang.org/files/archive/spec/2.12/06-expressions.html#anonymous-functions)
+of Scala 2.12 is subsumed by context function types and should be removed.
+
+Context function literals `(x1: T1, ..., xn: Tn) ?=> e` are
+automatically created for any expression `e` whose expected type is
+`scala.ContextFunctionN[T1, ..., Tn, R]`, unless `e` is
+itself a context function literal. This is analogous to the automatic
+insertion of `scala.Function0` around expressions in by-name argument position.
+
+Context function types generalize to `N > 22` in the same way that function types do, see [the corresponding
+documentation](../dropped-features/limit22.md).
+
+## Examples
+
+See the section on Expressiveness from [Simplicitly: foundations and
+applications of implicit function
+types](https://dl.acm.org/citation.cfm?id=3158130).
+
+### Type Checking
+
+After desugaring no additional typing rules are required for context function types.

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

@@ -0,0 +1,153 @@
+---
+layout: doc-page
+title: "Context Functions"
+---
+
+_Context functions_ are functions with (only) context parameters.
+Their types are _context function types_. Here is an example of a context function type:
+
+```scala
+type Executable[T] = ExecutionContext ?=> T
+```
+Context function are written using `?=>` as the "arrow" sign.
+They are applied to synthesized arguments, in
+the same way methods with context parameters is applied. For instance:
+```scala
+  given ec as ExecutionContext = ...
+
+  def f(x: Int): Executable[Int] = ...
+
+  f(2).with(ec)    // explicit argument
+  f(2)             // argument is inferred
+```
+Conversely, if the expected type of an expression `E` is a context function type
+`(T_1, ..., T_n) ?=> U` and `E` is not already an
+context function literal, `E` is converted to an context function literal by rewriting to
+```scala
+  (x_1: T1, ..., x_n: Tn) ?=> E
+```
+where the names `x_1`, ..., `x_n` are arbitrary. This expansion is performed
+before the expression `E` is typechecked, which means that `x_1`, ..., `x_n`
+are available as givens in `E`.
+
+Like their types, context function literals are written using `?=>` as the arrow between parameters and results. They differ from normal function literals in that their types are context function types.
+
+For example, continuing with the previous definitions,
+```scala
+  def g(arg: Executable[Int]) = ...
+
+  g(22)      // is expanded to g((ev: ExecutionContext) ?=> 22)
+
+  g(f(2))    // is expanded to g((ev: ExecutionContext) ?=> f(2).with(ev))
+
+  g((ctx: ExecutionContext) ?=> f(22).with(ctx)) // is left as it is
+```
+### Example: Builder Pattern
+
+Context function types have considerable expressive power. For
+instance, here is how they can support the "builder pattern", where
+the aim is to construct tables like this:
+```scala
+  table {
+    row {
+      cell("top left")
+      cell("top right")
+    }
+    row {
+      cell("bottom left")
+      cell("bottom right")
+    }
+  }
+```
+The idea is to define classes for `Table` and `Row` that allow
+addition of elements via `add`:
+```scala
+  class Table {
+    val rows = new ArrayBuffer[Row]
+    def add(r: Row): Unit = rows += r
+    override def toString = rows.mkString("Table(", ", ", ")")
+  }
+
+  class Row {
+    val cells = new ArrayBuffer[Cell]
+    def add(c: Cell): Unit = cells += c
+    override def toString = cells.mkString("Row(", ", ", ")")
+  }
+
+  case class Cell(elem: String)
+```
+Then, the `table`, `row` and `cell` constructor methods can be defined
+with context function types as parameters to avoid the plumbing boilerplate
+that would otherwise be necessary.
+```scala
+  def table(init: Table ?=> Unit) = {
+    given t as Table
+    init
+    t
+  }
+
+  def row(init: Row ?=> Unit) with (t: Table) = {
+    given r as Row
+    init
+    t.add(r)
+  }
+
+  def cell(str: String) with (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)
+
+    row { ($r: Row) ?=>
+      cell("bottom left").with($r)
+      cell("bottom right").with($r)
+    }.with($t)
+  }
+```
+### Example: Postconditions
+
+As a larger example, here is a way to define constructs for checking arbitrary postconditions using an extension method `ensuring` so that the checked result can be referred to simply by `result`. The example combines opaque aliases, context function types, and extension methods to provide a zero-overhead abstraction.
+
+```scala
+object PostConditions {
+  opaque type WrappedResult[T] = T
+
+  def result[T] with (r: WrappedResult[T]) : T = r
+
+  def (x: T) ensuring[T](condition: WrappedResult[T] ?=> Boolean): T = {
+    assert(condition.with(x))
+    x
+  }
+}
+import PostConditions.{ensuring, result}
+
+val s = List(1, 2, 3).sum.ensuring(result == 6)
+```
+**Explanations**: We use a context function type `WrappedResult[T] ?=> Boolean`
+as the type of the condition of `ensuring`. An argument to `ensuring` such as
+`(result == 6)` will therefore have a given of type `WrappedResult[T]` in
+scope to pass along to the `result` method. `WrappedResult` is a fresh type, to make sure
+that we do not get unwanted givens in scope (this is good practice in all cases
+where context parameters are involved). Since `WrappedResult` is an opaque type alias, its
+values need not be boxed, and since `ensuring` is added as an extension method, its argument
+does not need boxing either. Hence, the implementation of `ensuring` is as about as efficient
+as the best possible code one could write by hand:
+
+```scala
+{ val result = List(1, 2, 3).sum
+  assert(result == 6)
+  result
+}
+```
+### Reference
+
+For more info, see the [blog article](https://www.scala-lang.org/blog/2016/12/07/implicit-function-types.html),
+(which uses a different syntax that has been superseded).
+
+[More details](./context-functions-spec.md)