Skip to content

Fix example code in given-imports.md and adjust markdown format #9349

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

Merged
Merged
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
34 changes: 24 additions & 10 deletions docs/docs/reference/contextual/given-imports.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,41 @@ title: "Importing Givens"
---

A special form of import wildcard selector is used to import given instances. Example:

```scala
object A {
class TC
given tc as TC
def f(using TC) = ???
}

object B {
import A._
import A.{given _}
}
```

In the code above, the `import A._` clause of object `B` will import all members
of `A` _except_ the given instance `tc`. Conversely, the second import `import A.{given _}` will import _only_ that given instance.
The two import clauses can also be merged into one:

```scala
object B
object B {
import A.{given _, _}
}
```

Generally, a normal wildcard selector `_` brings all definitions other than givens or extensions into scope
whereas a `given _` selector brings all givens (including those resulting from extensions) into scope.

There are two main benefits arising from these rules:

- It is made clearer where givens in scope are coming from.
In particular, it is not possible to hide imported givens in a long list of regular wildcard imports.
- It enables importing all givens
without importing anything else. This is particularly important since givens
can be anonymous, so the usual recourse of using named imports is not
practical.
- It is made clearer where givens in scope are coming from.
In particular, it is not possible to hide imported givens in a long list of regular wildcard imports.
- It enables importing all givens
without importing anything else. This is particularly important since givens
can be anonymous, so the usual recourse of using named imports is not
practical.

### Importing By Type

Expand All @@ -42,31 +47,40 @@ Since givens can be anonymous it is not always practical to import them by their
```scala
import A.{given TC}
```

This imports any given in `A` that has a type which conforms to `TC`. Importing givens of several types `T1,...,Tn`
is expressed by multiple `given` selectors.
```

```scala
import A.{given T1, ..., given Tn}
```

Importing all given instances of a parameterized type is expressed by wildcard arguments.
For instance, assuming the object

```scala
object Instances {
given intOrd as Ordering[Int]
given [T: Ordering] listOrd as Ordering[List[T]]
given listOrd[T: Ordering] as Ordering[List[T]]
given ec as ExecutionContext = ...
given im as Monoid[Int]
}
```

the import

```scala
import Instances.{given Ordering[?], given ExecutionContext}
```

would import the `intOrd`, `listOrd`, and `ec` instances but leave out the `im` instance, since it fits none of the specified bounds.

By-type imports can be mixed with by-name imports. If both are present in an import clause, by-type imports come last. For instance, the import clause

```scala
import Instances.{im, given Ordering[?]}
```

would import `im`, `intOrd`, and `listOrd` but leave out `ec`.

<!--
Expand Down Expand Up @@ -115,4 +129,4 @@ ImportSelectors ::= id [‘=>’ id | ‘=>’ ‘_’] [‘,’ ImportSelect
WildCardSelector ::= ‘_'
| ‘given’ (‘_' | InfixType)
Export ::= ‘export’ ImportExpr {‘,’ ImportExpr}
```
```