syntax change: delegate for -> given as

Author: odersky

docs/docs/reference/contextual/conversions.md

@@ -3,20 +3,20 @@ layout: doc-page
 title: "Implicit Conversions"
 ---
 
-Implicit conversions are defined by delegates for the `scala.Conversion` class.
+Implicit conversions are defined by given 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
-delegate for Conversion[String, Token] {
+given as Conversion[String, Token] {
   def apply(str: String): Token = new KeyWord(str)
 }
 ```
-Using an alias delegate this can be expressed more concisely as:
+Using an alias given this can be expressed more concisely as:
 ```scala
-delegate for Conversion[String, Token] = new KeyWord(_)
+given as Conversion[String, Token] = new KeyWord(_)
 ```
 An implicit conversion is applied automatically by the compiler in three situations:
 
@@ -25,19 +25,19 @@ An implicit conversion is applied automatically by the compiler in three situati
 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 for a delegate for
-`scala.Conversion` that maps an argument of type `T` to type `S`. In the second and third
-case, it looks for a delegate for `scala.Conversion` that maps an argument of type `T`
+In the first case, the compiler looks for a given `scala.Conversion` that maps
+an argument of type `T` to type `S`. In the second and third
+case, it looks for a given `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 a delegate `C` is found, the expression `e` is replaced by `C.apply(e)`.
+If such an instance `C` is given, 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
-delegate int2Integer for Conversion[Int, java.lang.Integer] =
+given int2Integer as Conversion[Int, java.lang.Integer] =
  java.lang.Integer.valueOf(_)
 ```
 
@@ -59,9 +59,9 @@ object Completions {
     //
     //   CompletionArg.fromStatusCode(statusCode)
 
-    delegate fromString     for Conversion[String, CompletionArg]               = Error(_)
-    delegate fromFuture     for Conversion[Future[HttpResponse], CompletionArg] = Response(_)
-    delegate fromStatusCode for Conversion[Future[StatusCode], CompletionArg]   = Status(_)
+    given fromString     as Conversion[String, CompletionArg]               = Error(_)
+    given fromFuture     as Conversion[Future[HttpResponse], CompletionArg] = Response(_)
+    given fromStatusCode as Conversion[Future[StatusCode], CompletionArg]   = Status(_)
   }
   import CompletionArg._
 

docs/docs/reference/contextual/delegates.md

@@ -1,9 +1,9 @@
 ---
 layout: doc-page
-title: "Delegates"
+title: "Given Instances"
 ---
 
-Delegates define "canonical" values of certain types
+Given instances (or, simply, "givens") define "canonical" values of certain types
 that serve for synthesizing arguments to [given clauses](./given-clauses.html). Example:
 
 ```scala
@@ -13,12 +13,14 @@ trait Ord[T] {
   def (x: T) > (y: T) = compare(x, y) > 0
 }
 
-delegate IntOrd for Ord[Int] {
+given IntOrd as Ord[Int] {
   def compare(x: Int, y: Int) =
     if (x < y) -1 else if (x > y) +1 else 0
 }
 
-delegate ListOrd[T] for Ord[List[T]] given (ord: Ord[T]) {
+given ListOrd[T] as Ord[List[T]] given (ord: Ord[T]) {
+  where Ord[T], { x <= 0 }
+
   def compare(xs: List[T], ys: List[T]): Int = (xs, ys) match {
     case (Nil, Nil) => 0
     case (Nil, _) => -1
@@ -29,57 +31,56 @@ delegate ListOrd[T] for Ord[List[T]] given (ord: Ord[T]) {
   }
 }
 ```
-This code defines a trait `Ord` with two delegate definitions. `IntOrd` defines
-a delegate for the type `Ord[Int]` whereas `ListOrd[T]` defines delegates
-for `Ord[List[T]]` for all types `T` that come with a delegate for `Ord[T]` themselves.
-The `given` clause in `ListOrd` defines an implicit parameter.
+This code defines a trait `Ord` with two givens. `IntOrd` defines
+a given for the type `Ord[Int]` whereas `ListOrd[T]` defines givens
+for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]` themselves.
+The `given (ord: Ord[T])` clause in `ListOrd` defines an implicit parameter.
 Given clauses are further explained in the [next section](./given-clauses.html).
 
-## Anonymous Delegates
+## Anonymous Given Instances
 
-The name of a delegate can be left out. So the delegate definitions
+The name of a given instance can be left out. So the given definitions
 of the last section can also be expressed like this:
 ```scala
-delegate for Ord[Int] { ... }
-delegate [T] for Ord[List[T]] given (ord: Ord[T]) { ... }
+given as Ord[Int] { ... }
+given [T] as Ord[List[T]] given Ord[T] { ... }
 ```
-If the name of a delegate is missing, the compiler will synthesize a name from
-the type(s) in the `for` clause.
+If the name of a given is missing, the compiler will synthesize a name from
+the type(s) in the `as` clause.
 
-## Alias Delegates
+## Alias Givens
 
-An alias can be used to define a delegate that is equal to some expression. E.g.:
+An alias can be used to define a given instance that is equal to some expression. E.g.:
 ```scala
-delegate global for ExecutionContext = new ForkJoinPool()
+given global as ExecutionContext = new ForkJoinPool()
 ```
-This creates a delegate `global` of type `ExecutionContext` that resolves to the right hand side `new ForkJoinPool()`.
+This creates a given `global` of type `ExecutionContext` that resolves to the right
+hand side `new ForkJoinPool()`.
 The first time `global` is accessed, a new `ForkJoinPool` is created, which is then
 returned for this and all subsequent accesses to `global`.
 
-Alias delegates can be anonymous, e.g.
+Alias givens can be anonymous, e.g.
 ```scala
-delegate for Position = enclosingTree.position
-delegate for Context given (outer: Context) =
-  outer.withOwner(currentOwner)
+given as Position = enclosingTree.position
+given as Context given (outer: Context) = outer.withOwner(currentOwner)
 ```
-An alias delegate can have type parameters and given clauses just like any other delegate, but it can only implement a single type.
+An alias given can have type parameters and given clauses just like any other given instance, but it can only implement a single type.
 
-## Delegate Instantiation
+## Given Instance Initialization
 
-A delegate without type parameters or given clause is instantiated on-demand, the first
+A given instance without type parameters or given clause is initialized on-demand, the first
 time it is accessed. It is not required to ensure safe publication, which means that
-different threads might create different delegates for the same `delegate` clause.
-If a `delegate` clause has type parameters or a given clause, a fresh delegate is
-created for each reference.
+different threads might create different instances for the same `given` definition.
+If a `given` definition has type parameters or a given clause, a fresh instance is created for each reference.
 
 ## Syntax
 
-Here is the new syntax of delegate clauses, seen as a delta from the [standard context free syntax of Scala 3](http://dotty.epfl.ch/docs/internals/syntax.html).
+Here is the new syntax of given instances, seen as a delta from the [standard context free syntax of Scala 3](http://dotty.epfl.ch/docs/internals/syntax.html).
 ```
 TmplDef          ::=  ...
-                  |   ‘delegate’ DelegateDef
-DelegateDef      ::=  [id] [DefTypeParamClause] DelegateBody
-DelegateBody     ::=  [‘for’ ConstrApp {‘,’ ConstrApp }] {GivenParamClause} [TemplateBody]
+                  |   ‘given’ GivenDef
+GivenDef         ::=  [id] [DefTypeParamClause] GivenBody
+GivenBody        ::=  [‘for’ ConstrApp {‘,’ ConstrApp }] {GivenParamClause} [TemplateBody]
                    |  ‘for’ Type {GivenParamClause} ‘=’ Expr
 ConstrApp        ::=  SimpleConstrApp
                    |  ‘(’ SimpleConstrApp {‘given’ (PrefixExpr | ParArgumentExprs)} ‘)’

docs/docs/reference/contextual/derivation.md

@@ -3,18 +3,18 @@ layout: doc-page
 title: Typeclass Derivation
 ---
 
-Typeclass derivation is a way to generate delegates for certain type classes automatically or with minimal code hints. A type class in this sense is any trait or class with a type parameter that describes the type being operated on. Commonly used examples are `Eql`, `Ordering`, `Show`, or `Pickling`. Example:
+Typeclass derivation is a way to generate given instances for certain type classes automatically or with minimal code hints. A type class in this sense is any trait or class with a type parameter that describes the type being operated on. Commonly used examples are `Eql`, `Ordering`, `Show`, or `Pickling`. Example:
 ```scala
 enum Tree[T] derives Eql, Ordering, Pickling {
   case Branch(left: Tree[T], right: Tree[T])
   case Leaf(elem: T)
 }
 ```
-The `derives` clause generates delegates for the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`:
+The `derives` clause generates given instances for the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`:
 ```scala
-delegate [T: Eql]      for Eql[Tree[T]]      = Eql.derived
-delegate [T: Ordering] for Ordering[Tree[T]] = Ordering.derived
-delegate [T: Pickling] for Pickling[Tree[T]] = Pickling.derived
+given [T: Eql]      as Eql[Tree[T]]      = Eql.derived
+given [T: Ordering] as Ordering[Tree[T]] = Ordering.derived
+given [T: Pickling] as Pickling[Tree[T]] = Pickling.derived
 ```
 
 ### Deriving Types
@@ -40,7 +40,7 @@ The generated typeclass delegates are placed in the companion objects `Labelled`
 
 A trait or class can appear in a `derives` clause if its companion object defines a method named `derived`. The type and implementation of a `derived` method are arbitrary, but typically it has a definition like this:
 ```scala
-  def derived[T] given Mirror.Of[T] = ...
+  def derived[T] where Mirror.Of[T] = ...
 ```
 That is, the `derived` method takes an implicit parameter of (some subtype of) type `Mirror` that defines the shape of the deriving type `T` and it computes the typeclass implementation according
 to that shape. A `Mirror` delegate is generated automatically for
@@ -101,10 +101,10 @@ is represented as `T *: Unit` since there is no direct syntax for such tuples: `
 
 ### The Generic Typeclass
 
-For every class `C[T_1,...,T_n]` with a `derives` clause, the compiler generates in the companion object of `C` a delegate for `Generic[C[T_1,...,T_n]]` that follows
+For every class `C[T_1,...,T_n]` with a `derives` clause, the compiler generates in the companion object of `C` a given instance for `Generic[C[T_1,...,T_n]]` that follows
 the outline below:
 ```scala
-delegate [T_1, ..., T_n] for Generic[C[T_1,...,T_n]] {
+given [T_1, ..., T_n] as Generic[C[T_1,...,T_n]] {
   type Shape = ...
   ...
 }
@@ -122,7 +122,7 @@ would produce:
 object Result {
   import scala.compiletime.Shape._
 
-  delegate [T, E] for Generic[Result[T, E]] {
+  given [T, E] as Generic[Result[T, E]] {
     type Shape = Cases[(
       Case[Ok[T], T *: Unit],
       Case[Err[E], E *: Unit]
@@ -322,7 +322,7 @@ calling the `error` method defined in `scala.compiletime`.
 **Example:** Here is a slightly polished and compacted version of the code that's generated by inline expansion for the derived `Eql` delegate for class `Tree`.
 
 ```scala
-delegate [T] for Eql[Tree[T]] given (elemEq: Eql[T]) {
+given [T] as Eql[Tree[T]] where (elemEq: Eql[T]) {
   def eql(x: Tree[T], y: Tree[T]): Boolean = {
     val ev = the[Generic[Tree[T]]]
     val mx = ev.reflect(x)

docs/docs/reference/contextual/extension-methods.md

@@ -36,7 +36,7 @@ When is an extension method applicable? There are two possibilities.
 
  - An extension method is applicable if it is visible under a simple name, by being defined
    or inherited or imported in a scope enclosing the application.
- - An extension method is applicable if it is a member of some delegate that's eligible at the point of the application.
+ - An extension method is applicable if it is a member of some instance that is given at the point of the application.
 
 As an example, consider an extension method `longestStrings` on `String` defined in a trait `StringSeqOps`.
 
@@ -48,15 +48,15 @@ trait StringSeqOps {
   }
 }
 ```
-We can make the extension method available by defining a delegate for `StringSeqOps`, like this:
+We can make the extension method available by defining a given of class `StringSeqOps`, like this:
 ```scala
-delegate ops1 for StringSeqOps
+given ops1 as StringSeqOps
 ```
 Then
 ```scala
 List("here", "is", "a", "list").longestStrings
 ```
-is legal everywhere `ops1` is available as a delegate. Alternatively, we can define `longestStrings` as a member of a normal object. But then the method has to be brought into scope to be usable as an extension method.
+is legal everywhere `ops1` is available as a given instance. Alternatively, we can define `longestStrings` as a member of a normal object. But then the method has to be brought into scope to be usable as an extension method.
 
 ```scala
 object ops2 extends StringSeqOps
@@ -69,32 +69,32 @@ Assume a selection `e.m[Ts]` where `m` is not a member of `e`, where the type ar
 and where `T` is the expected type. The following two rewritings are tried in order:
 
  1. The selection is rewritten to `m[Ts](e)`.
- 2. If the first rewriting does not typecheck with expected type `T`, and there is a delegate `d`
-    in either the current scope or in the implicit scope of `T`, and `d` defines an extension
-    method named `m`, then selection is expanded to `d.m[Ts](e)`.
+ 2. If the first rewriting does not typecheck with expected type `T`, and there is a given instance `i`
+    in either the current scope or in the implicit scope of `T`, and `i` defines an extension
+    method named `m`, then selection is expanded to `i.m[Ts](e)`.
     This second rewriting is attempted at the time where the compiler also tries an implicit conversion
     from `T` to a type containing `m`. If there is more than one way of rewriting, an ambiguity error results.
 
 So `circle.circumference` translates to `CircleOps.circumference(circle)`, provided
-`circle` has type `Circle` and `CircleOps` is an eligible delegate (i.e. it is visible at the point of call or it is defined in the companion object of `Circle`).
+`circle` has type `Circle` and `CircleOps` is a given instance (i.e. it is visible at the point of call or it is defined in the companion object of `Circle`).
 
-### Delegates for Extension Methods
+### Given Instances for Extension Methods
 
-Delegates that define extension methods can also be defined without a `for` clause. E.g.,
+Given instances that define extension methods can also be defined without a `for` clause. E.g.,
 
 ```scala
-delegate StringOps {
+given StringOps {
   def (xs: Seq[String]) longestStrings: Seq[String] = {
     val maxLength = xs.map(_.length).max
     xs.filter(_.length == maxLength)
   }
 }
 
-delegate {
+given {
   def (xs: List[T]) second[T] = xs.tail.head
 }
 ```
-If such delegates are anonymous (as in the second clause), their name is synthesized from the name
+If such given instances are anonymous (as in the second clause), their name is synthesized from the name
 of the first defined extension method.
 
 ### Operators

docs/docs/reference/contextual/given-clauses.md

@@ -9,7 +9,7 @@ call trees where the same value is passed over and over again in long call chain
 functions. Given clauses can help here since they enable the compiler to synthesize
 repetitive arguments instead of the programmer having to write them explicitly.
 
-For example, given the [delegates](./delegates.md) defined previously,
+For example, with the [given instances](./delegates.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) given (ord: Ord[T]): T =
@@ -73,8 +73,8 @@ def f given (u: Universe) given (x: u.Context) = ...
 However, all `given` clauses in a definition must come after any normal parameter clauses.
 Multiple given clauses are matched left-to-right in applications. Example:
 ```scala
-delegate global for Universe { type Context = ... }
-delegate ctx for global.Context { ... }
+given global as Universe { type Context = ... }
+given ctx as global.Context { ... }
 ```
 Then the following calls are all valid (and normalize to the last one)
 ```scala
@@ -84,10 +84,10 @@ f
 ```
 But `f given ctx` would give a type error.
 
-## Summoning Delegates
+## Summoning Instances
 
-A method `the` in `Predef` returns the delegate for a given type. For example,
-the delegate for `Ord[List[Int]]` is produced by
+A method `the` in `Predef` returns the given instance of a specific type. For example,
+the given instance for `Ord[List[Int]]` is produced by
 ```scala
 the[Ord[List[Int]]]  // reduces to ListOrd given IntOrd
 ```

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

@@ -10,9 +10,9 @@ trait Codec[T] {
   def write(x: T): Unit
 }
 
-delegate intCodec for Codec[Int] = ???
+given intCodec as Codec[Int] = ???
 
-delegate optionCodec[T] for Codec[Option[T]] given (ev: => Codec[T]) {
+given optionCodec[T] as Codec[Option[T]] given (ev: => Codec[T]) {
   def write(xo: Option[T]) = xo match {
     case Some(x) => ev.write(x)
     case None =>
@@ -33,20 +33,20 @@ if this is necessary to prevent an otherwise diverging expansion.
 
 The precise steps for synthesizing an argument for an implicit by-name parameter of type `=> T` are as follows.
 
- 1. Create a new delegate for type `T`:
+ 1. Create a new given instance of type `T`:
 
     ```scala
-    delegate lv for T = ???
+    given lv as T = ???
     ```
     where `lv` is an arbitrary fresh name.
 
- 1. This delegate 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 an implicit by-name parameter.
+ 1. This given instance 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 an implicit by-name parameter.
 
- 1. If this search succeeds with expression `E`, and `E` contains references to the delegate `lv`, replace `E` by
+ 1. If this search succeeds with expression `E`, and `E` contains references to `lv`, replace `E` by
 
 
     ```scala
-    { delegate lv for T = E; lv }
+    { given lv as T = E; lv }
     ```
 
     Otherwise, return `E` unchanged.
@@ -58,7 +58,7 @@ val s = the[Test.Codec[Option[Int]]](
   optionCodec[Int](intCodec))
 ```
 
-No local delegate was generated because the synthesized argument is not recursive.
+No local given instance was generated because the synthesized argument is not recursive.
 
 ### Reference