Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport "Clear the not-backported documentation changes queue" to LTS #20919

Merged
merged 6 commits into from
Jul 2, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/_docs/reference/changed-features/wildcards.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Wildcard Arguments in Types
nightlyOf: https://docs.scala-lang.org/scala3/reference/changed-features/wildcards.html
---

The syntax of wildcard arguments in types has changed from `_` to `?`. Example:
The syntax of wildcard arguments in types is changing from `_` to `?`. Example:
```scala
List[?]
Map[? <: AnyRef, ? >: Null]
Expand All @@ -14,8 +14,8 @@ Map[? <: AnyRef, ? >: Null]

We would like to use the underscore syntax `_` to stand for an anonymous type parameter, aligning it with its meaning in
value parameter lists. So, just as `f(_)` is a shorthand for the lambda `x => f(x)`, in the future `C[_]` will be a shorthand
for the type lambda `[X] =>> C[X]`. This makes higher-kinded types easier to use. It also removes the wart that, used as a type
parameter, `F[_]` means `F` is a type constructor whereas used as a type, `F[_]` means it is a wildcard (i.e. existential) type.
for the type lambda `[X] =>> C[X]`. This will make higher-kinded types easier to use. It will also remove the wart that, used as a type
parameter, `F[_]` means `F` is a type constructor, whereas used as a type, `F[_]` means it is a wildcard (i.e. existential) type.
In the future, `F[_]` will mean the same thing, no matter where it is used.

We pick `?` as a replacement syntax for wildcard types, since it aligns with
Expand All @@ -28,11 +28,11 @@ compiler plugin still uses the reverse convention, with `?` meaning parameter pl

A step-by-step migration is made possible with the following measures:

1. In Scala 3.0, both `_` and `?` are legal names for wildcards.
2. In Scala 3.1, `_` is deprecated in favor of `?` as a name for a wildcard. A `-rewrite` option is
1. In earlier versions of Scala 3, both `_` and `?` are legal names for wildcards.
2. In Scala 3.4, `_` will be deprecated in favor of `?` as a name for wildcards. A `-rewrite` option is
available to rewrite one to the other.
3. In Scala 3.2, the meaning of `_` changes from wildcard to placeholder for type parameter.
4. The Scala 3.1 behavior is already available today under the `-source future` setting.
3. At some later point in the future, the meaning of `_` will change from wildcard to placeholder for type parameters.
4. Some deprecation warnings are already available under the `-source future` setting.

To smooth the transition for codebases that use kind-projector, we adopt the following measures under the command line
option `-Ykind-projector`:
Expand All @@ -42,7 +42,7 @@ option `-Ykind-projector`:
available to rewrite one to the other.
3. In Scala 3.3, `*` is removed again, and all type parameter placeholders will be expressed with `_`.

These rules make it possible to cross build between Scala 2 using the kind projector plugin and Scala 3.0 - 3.2 using the compiler option `-Ykind-projector`.
These rules make it possible to cross-build between Scala 2 using the kind projector plugin and Scala 3.0 - 3.2 using the compiler option `-Ykind-projector`.

There is also a migration path for users that want a one-time transition to syntax with `_` as a type parameter placeholder.
With option `-Ykind-projector:underscores` Scala 3 will regard `_` as a type parameter placeholder, leaving `?` as the only syntax for wildcards.
Expand Down
124 changes: 67 additions & 57 deletions docs/_docs/reference/contextual/context-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,29 @@ _Context functions_ are functions with (only) context parameters.
Their types are _context function types_. Here is an example of a context function type:

```scala
import scala.concurrent.ExecutionContext

type Executable[T] = ExecutionContext ?=> T
```
Context functions are written using `?=>` as the "arrow" sign.
They are applied to synthesized arguments, in
the same way methods with context parameters are applied. For instance:
```scala
given ec: ExecutionContext = ...
given ec: ExecutionContext = ...

def f(x: Int): ExecutionContext ?=> Int = ...
def f(x: Int): ExecutionContext ?=> Int = ...

// could be written as follows with the type alias from above
// def f(x: Int): Executable[Int] = ...
// could be written as follows with the type alias from above
// def f(x: Int): Executable[Int] = ...

f(2)(using ec) // explicit argument
f(2) // argument is inferred
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
`(T_1, ..., T_n) ?=> U` and `E` is not already an
context function literal, `E` is converted to a context function literal by rewriting it to
```scala
(x_1: T1, ..., x_n: Tn) ?=> E
(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`
Expand All @@ -38,14 +40,14 @@ Like their types, context function literals are written using `?=>` as the arrow

For example, continuing with the previous definitions,
```scala
def g(arg: Executable[Int]) = ...
def g(arg: Executable[Int]) = ...

g(22) // is expanded to g((ev: ExecutionContext) ?=> 22)
g(22) // is expanded to g((ev: ExecutionContext) ?=> 22)

g(f(2)) // is expanded to g((ev: ExecutionContext) ?=> f(2)(using ev))
g(f(2)) // is expanded to g((ev: ExecutionContext) ?=> f(2)(using ev))

g((ctx: ExecutionContext) ?=> f(3)) // is expanded to g((ctx: ExecutionContext) ?=> f(3)(using ctx))
g((ctx: ExecutionContext) ?=> f(3)(using ctx)) // is left as it is
g((ctx: ExecutionContext) ?=> f(3)) // is expanded to g((ctx: ExecutionContext) ?=> f(3)(using ctx))
g((ctx: ExecutionContext) ?=> f(3)(using ctx)) // is left as it is
```

## Example: Builder Pattern
Expand All @@ -54,63 +56,65 @@ 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")
}
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 the
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(", ", ", ")")
import scala.collection.mutable.ArrayBuffer

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(", ", ", ")")
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)
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: Table = Table()
init
t

def row(init: Row ?=> Unit)(using t: Table) =
given r: Row = Row()
init
t.add(r)

def cell(str: String)(using r: Row) =
r.add(new Cell(str))
def table(init: Table ?=> Unit) =
given t: Table = Table()
init
t

def row(init: Row ?=> Unit)(using t: Table) =
given r: Row = Row()
init
t.add(r)

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")(using $r)
cell("top right")(using $r)
}(using $t)

row { ($r: Row) ?=>
cell("bottom left")(using $r)
cell("bottom right")(using $r)
}(using $t)
}
table { ($t: Table) ?=>

row { ($r: Row) ?=>
cell("top left")(using $r)
cell("top right")(using $r)
}(using $t)

row { ($r: Row) ?=>
cell("bottom left")(using $r)
cell("bottom right")(using $r)
}(using $t)
}
```
## Example: Postconditions

Expand All @@ -131,12 +135,18 @@ import PostConditions.{ensuring, result}

val s = List(1, 2, 3).sum.ensuring(result == 6)
```
**Explanations**: We use a context function type `WrappedResult[T] ?=> Boolean`
### Explanation

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
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
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 close in efficiency to the best possible code one could write by hand:

Expand Down
Loading