diff --git a/docs/docs/reference/contextual-implicit/inferable-by-name-parameters.md b/docs/docs/reference/contextual-implicit/inferable-by-name-parameters.md index ee4b822d6d9f..d1230978e771 100644 --- a/docs/docs/reference/contextual-implicit/inferable-by-name-parameters.md +++ b/docs/docs/reference/contextual-implicit/inferable-by-name-parameters.md @@ -40,7 +40,7 @@ The precise steps for synthesizing an argument for a by-name parameter of type ` ``` where `lv` is an arbitrary fresh name. - 1. This implicit 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 implicit argument to a by-name parameter. + 1. This implicit is not immediately available as a 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 implicit argument to a by-name parameter. 1. If this search succeeds with expression `E`, and `E` contains references to the implicit `lv`, replace `E` by diff --git a/docs/docs/reference/contextual-implicit/inferable-params.md b/docs/docs/reference/contextual-implicit/inferable-params.md index a42344480c61..235e21645af5 100644 --- a/docs/docs/reference/contextual-implicit/inferable-params.md +++ b/docs/docs/reference/contextual-implicit/inferable-params.md @@ -30,7 +30,7 @@ max(List(1, 2, 3), Nil) ## Anonymous Implicit Parameters -In many situations, the name of an implicit parameter of a method need not be mentioned explicitly at all, since it is only used as synthesized implicit for other constraints. In that case one can avoid defining a parameter name and just provide its type. Example: +In many situations, the name of an implicit parameter of a method need not be mentioned explicitly at all, since it is only used as a synthesized argument for other implicit parameters. In that case one can avoid defining a parameter name and just provide its type. Example: ```scala def maximum[T](xs: List[T]) given Ord[T]: T = xs.reduceLeft(max) diff --git a/docs/docs/reference/contextual-implicit/instance-defs.md b/docs/docs/reference/contextual-implicit/instance-defs.md index 56ae214f924b..690f0b9b30a4 100644 --- a/docs/docs/reference/contextual-implicit/instance-defs.md +++ b/docs/docs/reference/contextual-implicit/instance-defs.md @@ -41,14 +41,14 @@ The name of an implicit instance can be left out. So the implicit instance defin of the last section can also be expressed like this: ```scala implicit for Ord[Int] { ... } -implicit [T] or Ord[List[T]] given (ord: Ord[T]) { ... } +implicit [T] for Ord[List[T]] given (ord: Ord[T]) { ... } ``` If the name of an implicit is missing, the compiler will synthesize a name from the type(s) in the `for` clause. ## Alias Implicits -An alias implicit defines an implicit value that is equal to some expression. E.g.: +An alias can be used to define an implicit value that is equal to some expression. E.g.: ```scala implicit global for ExecutionContext = new ForkJoinPool() ``` diff --git a/docs/docs/reference/contextual-implicit/multiversal-equality.md b/docs/docs/reference/contextual-implicit/multiversal-equality.md index bf15684ec3e2..0aefc971b437 100644 --- a/docs/docs/reference/contextual-implicit/multiversal-equality.md +++ b/docs/docs/reference/contextual-implicit/multiversal-equality.md @@ -31,7 +31,7 @@ that derives `Eql`, e.g. ```scala class T derives Eql ``` -Alternatively, one can also provide an `Eql` implicit directly, like this: +Alternatively, one can also define an `Eql` implicit directly, like this: ```scala implicit for Eql[T, T] = Eql.derived ``` @@ -141,7 +141,7 @@ The `Eql` object defines implicits for comparing - `java.lang.Number`, `java.lang.Boolean`, and `java.lang.Character`, - `scala.collection.Seq`, and `scala.collection.Set`. -Implicits are defined so that every one of these types is has a reflexive `Eql` implicit, and the following holds: +Implicits are defined so that every one of these types has a reflexive `Eql` implicit, and the following holds: - Primitive numeric types can be compared with each other. - Primitive numeric types can be compared with subtypes of `java.lang.Number` (and _vice versa_). diff --git a/docs/docs/reference/contextual-implicit/query-types-spec.md b/docs/docs/reference/contextual-implicit/query-types-spec.md index d7b67fd1e825..0e4dae6cb66a 100644 --- a/docs/docs/reference/contextual-implicit/query-types-spec.md +++ b/docs/docs/reference/contextual-implicit/query-types-spec.md @@ -76,4 +76,4 @@ Gist](https://gist.github.com/OlivierBlanvillain/234d3927fe9e9c6fba074b53a7bd9 ### Type Checking -After desugaring no additional typing rules are required for context query types. +After desugaring no additional typing rules are required for implicit function types. diff --git a/docs/docs/reference/contextual-implicit/relationship-implicits.md b/docs/docs/reference/contextual-implicit/relationship-implicits.md index ad6dd72e1d82..7c1e6faa7a0b 100644 --- a/docs/docs/reference/contextual-implicit/relationship-implicits.md +++ b/docs/docs/reference/contextual-implicit/relationship-implicits.md @@ -140,11 +140,11 @@ one can write ### Implicit Classes -Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Dotty. Other uses of implicit classes can be simulated by a pair of a regular class and a conversion delegate. +Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Dotty. Other uses of implicit classes can be simulated by a pair of a regular class and a conversion instance. ### Abstract Implicits -An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an implicit alias. E.g., Scala 2's +An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an alias implicit. E.g., Scala 2's ```scala implicit def symDeco: SymDeco ``` diff --git a/docs/docs/reference/contextual-repr/derivation.md b/docs/docs/reference/contextual-repr/derivation.md index 953cb9d79c35..2fc0ae078353 100644 --- a/docs/docs/reference/contextual-repr/derivation.md +++ b/docs/docs/reference/contextual-repr/derivation.md @@ -10,7 +10,7 @@ enum Tree[T] derives Eql, Ordering, Pickling { case Leaf(elem: T) } ``` -The `derives` clause generates repr representatives of the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`: +The `derives` clause generates representatives of the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`: ```scala repr [T: Eql] of Eql[Tree[T]] = Eql.derived repr [T: Ordering] of Ordering[Tree[T]] = Ordering.derived @@ -19,7 +19,7 @@ repr [T: Pickling] of Pickling[Tree[T]] = Pickling.derived ### Deriving Types -Besides for `enums`, typeclasses can also be derived for other sets of classes and objects that form an algebraic data type. These are: +Besides for enums, typeclasses can also be derived for other sets of classes and objects that form an algebraic data type. These are: - individual case classes or case objects - sealed classes or traits that have only case classes and case objects as children. @@ -93,8 +93,7 @@ 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` an representative of `Generic[C[T_1,...,T_n]]` that follows -the outline below: +For every class `C[T_1,...,T_n]` with a `derives` clause, the compiler generates in the companion object of `C` a representative of `Generic[C[T_1,...,T_n]]` that follows the outline below: ```scala repr [T_1, ..., T_n] of Generic[C[T_1,...,T_n]] { type Shape = ... @@ -215,7 +214,7 @@ trait Eql[T] { } ``` We need to implement a method `Eql.derived` that produces a representative of `Eql[T]` provided -there exists evidence of type `Generic[T]`. Here's a possible solution: +there exists a representative of type `Generic[T]`. Here's a possible solution: ```scala inline def derived[T] given (ev: Generic[T]): Eql[T] = new Eql[T] { def eql(x: T, y: T): Boolean = { @@ -234,7 +233,7 @@ there exists evidence of type `Generic[T]`. Here's a possible solution: The implementation of the inline method `derived` creates a representative of `Eql[T]` and implements its `eql` method. The right-hand side of `eql` mixes compile-time and runtime elements. In the code above, runtime elements are marked with a number in parentheses, i.e `(1)`, `(2)`, `(3)`. Compile-time calls that expand to runtime code are marked with a number in brackets, i.e. `[4]`, `[5]`. The implementation of `eql` consists of the following steps. - 1. Map the compared values `x` and `y` to their mirrors using the `reflect` method of the implicitly passed `Generic` evidence `(1)`, `(2)`. + 1. Map the compared values `x` and `y` to their mirrors using the `reflect` method of the implicitly passed `Generic` `(1)`, `(2)`. 2. Match at compile-time against the shape of the ADT given in `ev.Shape`. Dotty does not have a construct for matching types directly, but we can emulate it using an `inline` match over an `erasedValue`. Depending on the actual type `ev.Shape`, the match will reduce at compile time to one of its two alternatives. 3. If `ev.Shape` is of the form `Cases[alts]` for some tuple `alts` of alternative types, the equality test consists of comparing the ordinal values of the two mirrors `(3)` and, if they are equal, comparing the elements of the case indicated by that ordinal value. That second step is performed by code that results from the compile-time expansion of the `eqlCases` call `[4]`. 4. If `ev.Shape` is of the form `Case[elems]` for some tuple `elems` for element types, the elements of the case are compared by code that results from the compile-time expansion of the `eqlElems` call `[5]`. @@ -302,7 +301,7 @@ The last, and in a sense most interesting part of the derivation is the comparis case ev: Eql[T] => ev.eql(x, y) // (15) case _ => - error("No `Eql` representative was found for $T") + error("No `Eql` instance was found for $T") } ``` `tryEql` is an inline method that takes an element type `T` and two element values of that type as arguments. It is defined using an `implicit match` that tries to find a representative of `Eql[T]`. If a representative `ev` is found, it proceeds by comparing the arguments using `ev.eql`. On the other hand, if no representative is found diff --git a/docs/docs/reference/contextual-repr/extension-methods.md b/docs/docs/reference/contextual-repr/extension-methods.md index f030aac753de..fdb20d9e24c9 100644 --- a/docs/docs/reference/contextual-repr/extension-methods.md +++ b/docs/docs/reference/contextual-repr/extension-methods.md @@ -56,7 +56,7 @@ Then ```scala List("here", "is", "a", "list").longestStrings ``` -is legal everywhere `ops1` is available as a representative. 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 eligible. 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 @@ -80,7 +80,7 @@ So `circle.circumference` translates to `CircleOps.circumference(circle)`, provi ### Representatives for Extension Methods -Representatives that define extension methods can also be defined without a `for` clause. E.g., +Representatives that define extension methods can also be defined without an `of` clause. E.g., ```scala repr StringOps { @@ -94,12 +94,12 @@ repr { def (xs: List[T]) second[T] = xs.tail.head } ``` -If such representatives are anonymous (as in the second clause), their name is synthesized from the name +If such a representative is anonymous (as in the second clause), its name is synthesized from the name of the first defined extension method. ### Operators -The extension method syntax also applies to the definitions of operators. +The extension method syntax also applies to the definition of operators. In each case the definition syntax mirrors the way the operator is applied. Examples: ```scala diff --git a/docs/docs/reference/contextual-repr/import-implied.md b/docs/docs/reference/contextual-repr/import-implied.md index 66e0204c0827..33041ebf1225 100644 --- a/docs/docs/reference/contextual-repr/import-implied.md +++ b/docs/docs/reference/contextual-repr/import-implied.md @@ -18,7 +18,7 @@ object B { In the code above, the `import A._` clause of object `B` will import all members of `A` _except_ the representative `tc`. Conversely, the second import `import repr A._` will import _only_ that representative. -Generally, a normal import clause brings all definitions except representatives into scope whereas an `import repr` clause brings only representatives into scope. +Generally, a normal import clause brings all members except representatives into scope whereas an `import repr` clause brings only representatives into scope. There are two main benefits arising from these rules: @@ -29,7 +29,7 @@ There are two main benefits arising from these rules: can be anonymous, so the usual recourse of using named imports is not practical. -### Relationship with Old-Style Implicits +### Migration The rules of representatives above have the consequence that a library would have to migrate in lockstep with all its users from old style implicits and @@ -49,4 +49,4 @@ The following modifications avoid this hurdle to migration. These rules mean that library users can use `import repr` to access old-style implicits in Scala 3.0, and will be gently nudged and then forced to do so in later versions. Libraries can then switch to -representation clauses once their user base has migrated. +`repr` clauses once their user base has migrated. diff --git a/docs/docs/reference/contextual-repr/inferable-by-name-parameters.md b/docs/docs/reference/contextual-repr/inferable-by-name-parameters.md index ddbb7199d2ab..9c06db8848b3 100644 --- a/docs/docs/reference/contextual-repr/inferable-by-name-parameters.md +++ b/docs/docs/reference/contextual-repr/inferable-by-name-parameters.md @@ -40,7 +40,7 @@ The precise steps for synthesizing an argument for a by-name parameter of type ` ``` where `lv` is an arbitrary fresh name. - 1. This representative 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 representative is not immediately eligible as a candidate for argument inference (making it immediately eligible could result in a loop in the synthesized computation). But it becomes eligible in all nested contexts that look again for an implicit argument to a by-name parameter. 1. If this search succeeds with expression `E`, and `E` contains references to the representative `lv`, replace `E` by diff --git a/docs/docs/reference/contextual-repr/inferable-params.md b/docs/docs/reference/contextual-repr/inferable-params.md index ad80efcb0162..fdc758b44f6b 100644 --- a/docs/docs/reference/contextual-repr/inferable-params.md +++ b/docs/docs/reference/contextual-repr/inferable-params.md @@ -20,7 +20,7 @@ The `max` method can be applied as follows: ```scala max(2, 3).given(IntOrd) ``` -The `.given(IntOrd)` part provides the `IntOrd` representative as an argument for the `ord` parameter. But the point of +The `.given(IntOrd)` part passes `IntOrd` as an argument for the `ord` parameter. But the point of implicit parameters is that this argument can also be left out (and it usually is). So the following applications are equally valid: ```scala diff --git a/docs/docs/reference/contextual-repr/instance-defs.md b/docs/docs/reference/contextual-repr/instance-defs.md index dd07f4b1231a..428207b419b3 100644 --- a/docs/docs/reference/contextual-repr/instance-defs.md +++ b/docs/docs/reference/contextual-repr/instance-defs.md @@ -52,7 +52,9 @@ An alias can be used to define a representative that is equal to some expression ```scala repr ctx of ExecutionContext = new ForkJoinPool() ``` -This creates a representative `ctx` of type `ExecutionContext` that resolves to the right hand side `new ForkJoinPool()`. The first time a representative of `ExecutionContext` is demanded, a new `ForkJoinPool` is created, which is then returned for this and all subsequent accesses to `ctx`. +This creates a repreentative `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 representatives can be anonymous, e.g. ```scala @@ -62,7 +64,7 @@ An alias representative can have type and context parameters just like any other ## Representative Creation -A representative without type parameters or given clause is created on-demand, the first time it is accessed. No attempt is made to ensure safe publication, which means that different threads might create different representatives for the same `repr` clause. If a `repr` clause has type parameters or a given clause, a fresh representative is created for each reference. +A representative without type parameters or given clause is created on-demand, the first time it is accessed. It is not required to ensure safe publication, which means that different threads might create different representatives for the same `repr` clause. If a `repr` clause has type parameters or a given clause, a fresh representative is created for each reference. ## Syntax diff --git a/docs/docs/reference/contextual-repr/motivation.md b/docs/docs/reference/contextual-repr/motivation.md index d1353962d0cc..034d7de17ba2 100644 --- a/docs/docs/reference/contextual-repr/motivation.md +++ b/docs/docs/reference/contextual-repr/motivation.md @@ -51,7 +51,7 @@ The following pages introduce a redesign of contextual abstractions in Scala. Th 2. [Given Clauses](./inferable-params.html) are a new syntax for implicit _parameters_ and their _arguments_. Both are introduced with the same keyword, `given`. This unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several implicit parameter sections, and to have implicit parameters followed by normal ones. - 3. [Imports of Representatives](./import-implied.html) are new form of import that specifically imports representatives and nothing else. Representatives _must be_ imported with `import repr`, a plain import will no longer bring them into scope. + 3. [Import Repr](./import-implied.html) is new form of import that specifically imports representatives and nothing else. Representatives _must be_ imported with `import repr`, a plain import will no longer bring them into scope. 4. [Implicit Conversions](./conversions.html) are now expressed as representatives of a standard `Conversion` class. All other forms of implicit conversions will be phased out. diff --git a/docs/docs/reference/contextual-repr/multiversal-equality.md b/docs/docs/reference/contextual-repr/multiversal-equality.md index 19d76dc45730..516e3c7347fc 100644 --- a/docs/docs/reference/contextual-repr/multiversal-equality.md +++ b/docs/docs/reference/contextual-repr/multiversal-equality.md @@ -31,7 +31,7 @@ that derives `Eql`, e.g. ```scala class T derives Eql ``` -Alternatively, one can also provide an `Eql` representative directly, like this: +Alternatively, one can also define an `Eql` representative directly, like this: ```scala repr for Eql[T, T] = Eql.derived ``` @@ -75,7 +75,7 @@ defined as follows: def eqlAny[L, R]: Eql[L, R] = Eql.derived ``` -Even though `eqlAny` is not declared a representative, the compiler will still +Even though `eqlAny` is not declared as a representative, the compiler will still construct an `eqlAny` instance as answer to an implicit search for the type `Eql[L, R]`, unless `L` or `R` have `Eql` representatives defined on them, or the language feature `strictEquality` is enabled @@ -141,7 +141,7 @@ The `Eql` object defines representatives for - `java.lang.Number`, `java.lang.Boolean`, and `java.lang.Character`, - `scala.collection.Seq`, and `scala.collection.Set`. -Representative are defined so that every one of these types is has a reflexive `Eql` representative, and the following holds: +Representative are defined so that every one of these types has a reflexive `Eql` representative, and the following holds: - Primitive numeric types can be compared with each other. - Primitive numeric types can be compared with subtypes of `java.lang.Number` (and _vice versa_). diff --git a/docs/docs/reference/contextual-repr/query-types.md b/docs/docs/reference/contextual-repr/query-types.md index 040d48ac3eb9..aa8535b15104 100644 --- a/docs/docs/reference/contextual-repr/query-types.md +++ b/docs/docs/reference/contextual-repr/query-types.md @@ -28,7 +28,7 @@ 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 representatives in `E`. -Like their types, implicit function iterals are written with a `given` prefix. They differ from normal function literals in two ways: +Like their types, implicit function literals are written with a `given` prefix. They differ from normal function literals in two ways: 1. Their parameters are implicit. 2. Their types are implicit function types. diff --git a/docs/docs/reference/contextual-repr/relationship-implicits.md b/docs/docs/reference/contextual-repr/relationship-implicits.md index 6957cc414659..e756b3d0d6bc 100644 --- a/docs/docs/reference/contextual-repr/relationship-implicits.md +++ b/docs/docs/reference/contextual-repr/relationship-implicits.md @@ -28,17 +28,17 @@ Representative clauses can be mapped to combinations of implicit objects, classe class ListOrd[T](implicit ord: Ord[T]) extends Ord[List[T]] { ... } final implicit def ListOrd[T](implicit ord: Ord[T]): ListOrd[T] = new ListOrd[T] ``` - 3. Alias representatives map to implicit methods. If the representatives has neither type parameters nor a given clause, the result of creating an instance is cached in a variable. If in addition the right hand side is pure and cheap to compute, a simple `val` can be used instead. E.g., + 3. Alias representatives map to implicit methods. If the representative has neither type parameters nor a given clause, the result of creating an instance is cached in a variable. If in addition the right hand side is pure and cheap to compute, a simple `val` can be used instead. E.g., ```scala - repr ec of ExecutionContext = new ForkJoinContext() + repr global of ExecutionContext = new ForkJoinContext() repr config of Config = default.config ``` map to ```scala - private[this] var ec$cache: ExecutionContext | Null = null - final implicit def ec: ExecutionContext = { - if (ec$cache == null) ec$cache = new ForkJoinContext() - ec$cache + private[this] var global$cache: ExecutionContext | Null = null + final implicit def global: ExecutionContext = { + if (global$cache == null) global$cache = new ForkJoinContext() + global$cache } final implicit val config: Config = default.config diff --git a/docs/docs/reference/contextual-repr/typeclasses.md b/docs/docs/reference/contextual-repr/typeclasses.md index 8bc88276366a..fae1cc9a5bd3 100644 --- a/docs/docs/reference/contextual-repr/typeclasses.md +++ b/docs/docs/reference/contextual-repr/typeclasses.md @@ -3,7 +3,7 @@ layout: doc-page title: "Implementing Typeclasses" --- -Traits, representatives, extension methods and context bounds +Representatives, extension methods and context bounds allow a concise and natural expression of _typeclasses_. Typeclasses are just traits with canonical implementations defined by representatives. Here are some examples of standard typeclasses: