Skip to content

Update Reference Documentation #10783

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 3 commits into from
Dec 14, 2020
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
10 changes: 5 additions & 5 deletions docs/docs/reference/changed-features/compiler-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: doc-page
title: "Changes in Compiler Plugins"
---

Compiler plugins are supported by Dotty since 0.9. There are two notable changes
Compiler plugins are supported by Dotty (and Scala 3) since 0.9. There are two notable changes
compared to `scalac`:

- No support for analyzer plugins
Expand All @@ -13,14 +13,14 @@ compared to `scalac`:
normal type checking. This is a very powerful feature but for production usages,
a predictable and consistent type checker is more important.

For experimentation and research, Dotty introduces _research plugin_. Research plugins
For experimentation and research, Scala 3 introduces _research plugin_. Research plugins
are more powerful than `scalac` analyzer plugins as they let plugin authors customize
the whole compiler pipeline. One can easily replace the standard typer by a custom one or
create a parser for a domain-specific language. However, research plugins are only
enabled for nightly or snaphot releases of Dotty.
enabled for nightly or snaphot releases of Scala 3.

Common plugins that add new phases to the compiler pipeline are called
_standard plugins_ in Dotty. In terms of features, they are similar to
_standard plugins_ in Scala 3. In terms of features, they are similar to
`scalac` plugins, despite minor changes in the API.

## Using Compiler Plugins
Expand All @@ -41,7 +41,7 @@ pluginClass=dividezero.DivideZero

This is different from `scalac` plugins that required a `scalac-plugin.xml` file.

Starting from 1.1.5, `sbt` also supports Dotty compiler plugins. Please refer to the
Starting from 1.1.5, `sbt` also supports Scala 3 compiler plugins. Please refer to the
`sbt` [documentation][2] for more information.

## Writing a Standard Compiler Plugin
Expand Down
3 changes: 1 addition & 2 deletions docs/docs/reference/changed-features/eta-expansion.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,7 @@ rather than `next _`.
The reason for excluding nullary methods from automatic eta expansion
is that Scala implicitly inserts the `()` argument, which would
conflict with eta expansion. Automatic `()` insertion is
[limited](../dropped-features/auto-apply.md) in Dotty, but the fundamental ambiguity
[limited](../dropped-features/auto-apply.md) in Scala 3, but the fundamental ambiguity
remains.

[More details](eta-expansion-spec.md)

Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,8 @@ language:
```scala
implicit val m: Map[Int, String] = Map(1 -> "abc")

val x: String = 1 // scalac: assigns "abc" to x
// Dotty: type error
val x: String = 1 // Scala 2: assigns "abc" to x
// Scala 3: type error
```

This snippet contains a type error. The right hand side of `val x`
Expand All @@ -119,4 +119,3 @@ For more information about implicit resolution, see [Changes in
Implicit Resolution](implicit-resolution.md).
Other details are available in
[PR #2065](https://github.com/lampepfl/dotty/pull/2065)

4 changes: 2 additions & 2 deletions docs/docs/reference/changed-features/implicit-resolution.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: doc-page
title: "Changes in Implicit Resolution"
---
This page describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Dotty.
This page describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Scala 3.
Implicit resolution uses a new algorithm which caches implicit results
more aggressively for performance. There are also some changes that
affect implicits on the language level.
Expand Down Expand Up @@ -114,7 +114,7 @@ the implicit search for `Q` fails.
**5.** The treatment of divergence errors has also changed. A divergent implicit is treated as a normal failure, after which alternatives are still tried. This also makes sense: Encountering a divergent implicit means that we assume that no finite solution can be found on the corresponding path, but another path can still be tried. By contrast,
most (but not all) divergence errors in Scala 2 would terminate the implicit search as a whole.

**6.** Scala-2 gives a lower level of priority to implicit conversions with call-by-name parameters relative to implicit conversions with call-by-value parameters. Dotty drops this distinction. So the following code snippet would be ambiguous in Dotty:
**6.** Scala-2 gives a lower level of priority to implicit conversions with call-by-name parameters relative to implicit conversions with call-by-value parameters. Scala 3 drops this distinction. So the following code snippet would be ambiguous in Scala 3:

```scala
implicit def conv1(x: Int): A = new A(x)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: Escapes in interpolations

In Scala 2 there was no straightforward way to represent a single quote character `"` in a single quoted interpolation. A `\` character can't be used for that because interpolators themselves decide how to handle escaping, so the parser doesn't know whether the `"` should be escaped or used as a terminator.

In Dotty, you can use the `$` meta character of interpolations to escape a `"` character.
In Scala 3, you can use the `$` meta character of interpolations to escape a `"` character.

```scala
val inventor = "Thomas Edison"
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/reference/changed-features/lazy-vals-init.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: doc-page
title: Lazy Vals initialization
---

Dotty implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)
Scala 3 implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)
of the [SIP-20] improved lazy vals initialization proposal.

## Motivation
Expand All @@ -23,7 +23,7 @@ class Foo {
}
```

The Dotty compiler will generate code equivalent to:
The Scala 3 compiler will generate code equivalent to:

```scala
class Foo {
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/reference/changed-features/overload-resolution.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: doc-page
title: "Changes in Overload Resolution"
---

Overload resolution in Dotty improves on Scala 2 in two ways.
Overload resolution in Scala 3 improves on Scala 2 in two ways.
First, it takes all argument lists into account instead of
just the first argument list.
Second, it can infer parameter types of function values even if they
Expand Down Expand Up @@ -49,7 +49,7 @@ overload resolution based on additional argument blocks.
The handling of function values with missing parameter types has been improved. We can now
pass such values in the first argument list of an overloaded application, provided
that the remaining parameters suffice for picking a variant of the overloaded function.
For example, the following code compiles in Dotty, while it results in an
For example, the following code compiles in Scala 3, while it results in an
missing parameter type error in Scala2:
```scala
def f(x: Int, f2: Int => Int) = f2(x)
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/reference/changed-features/pattern-matching.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ layout: doc-page
title: "Option-less pattern matching"
---

Dotty implementation of pattern matching was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
The implementation of pattern matching in Scala 3 was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.

Dotty supports a superset of Scala 2 [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).
Scala 3 supports a superset of Scala 2 [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).

## Extractors

Expand Down
18 changes: 9 additions & 9 deletions docs/docs/reference/contextual/derivation.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,12 +122,12 @@ Mirror.Product {
Note the following properties of `Mirror` types,

+ Properties are encoded using types rather than terms. This means that they have no runtime footprint unless used and
also that they are a compile time feature for use with Dotty's metaprogramming facilities.
also that they are a compile time feature for use with Scala 3's metaprogramming facilities.
+ The kinds of `MirroredType` and `MirroredElemTypes` match the kind of the data type the mirror is an instance for.
This allows `Mirrors` to support ADTs of all kinds.
+ There is no distinct representation type for sums or products (ie. there is no `HList` or `Coproduct` type as in
Scala 2 versions of shapeless). Instead the collection of child types of a data type is represented by an ordinary,
possibly parameterized, tuple type. Dotty's metaprogramming facilities can be used to work with these tuple types
possibly parameterized, tuple type. Scala 3's metaprogramming facilities can be used to work with these tuple types
as-is, and higher level libraries can be built on top of them.
+ For both product and sum types, the elements of `MirroredElemTypes` are arranged in definition order (i.e. `Branch[T]`
precedes `Leaf[T]` in `MirroredElemTypes` for `Tree` because `Branch` is defined before `Leaf` in the source file).
Expand All @@ -152,20 +152,20 @@ provider of an ADT with a `derives` clause has to know about the derivation of a

Note that `derived` methods may have context `Mirror` parameters indirectly (e.g. by having a context argument which in turn
has a context `Mirror` parameter, or not at all (e.g. they might use some completely different user-provided mechanism, for
instance using Dotty macros or runtime reflection). We expect that (direct or indirect) `Mirror` based implementations
instance using Scala 3 macros or runtime reflection). We expect that (direct or indirect) `Mirror` based implementations
will be the most common and that is what this document emphasises.

Type class authors will most likely use higher level derivation or generic programming libraries to implement
`derived` methods. An example of how a `derived` method might be implemented using _only_ the low level facilities
described above and Dotty's general metaprogramming features is provided below. It is not anticipated that type class
described above and Scala 3's general metaprogramming features is provided below. It is not anticipated that type class
authors would normally implement a `derived` method in this way, however this walkthrough can be taken as a guide for
authors of the higher level derivation libraries that we expect typical type class authors will use (for a fully
worked out example of such a library, see [shapeless 3](https://github.com/milessabin/shapeless/tree/shapeless-3)).

#### How to write a type class `derived` method using low level mechanisms

The low-level method we will use to implement a type class `derived` method in this example exploits three new
type-level constructs in Dotty: inline methods, inline matches, and implicit searches via `summonInline` or `summonFrom`. Given this definition of the
type-level constructs in Scala 3: inline methods, inline matches, and implicit searches via `summonInline` or `summonFrom`. Given this definition of the
`Eq` type class,


Expand Down Expand Up @@ -194,7 +194,7 @@ call sites (for instance the compiler generated instance definitions in the comp

The body of this method (1) first materializes the `Eq` instances for all the child types of type the instance is
being derived for. This is either all the branches of a sum type or all the fields of a product type. The
implementation of `summonAll` is `inline` and uses Dotty's `summonInline` construct to collect the instances as a
implementation of `summonAll` is `inline` and uses Scala 3's `summonInline` construct to collect the instances as a
`List`,

```scala
Expand Down Expand Up @@ -319,7 +319,7 @@ given derived$Eq[T](using eqT: Eq[T]): Eq[Opt[T]] =
```

Alternative approaches can be taken to the way that `derived` methods can be defined. For example, more aggressively
inlined variants using Dotty macros, whilst being more involved for type class authors to write than the example
inlined variants using Scala 3 macros, whilst being more involved for type class authors to write than the example
above, can produce code for type classes like `Eq` which eliminate all the abstraction artefacts (eg. the `Lists` of
child instances in the above) and generate code which is indistinguishable from what a programmer might write by hand.
As a third example, using a higher level library such as shapeless the type class author could define an equivalent
Expand Down Expand Up @@ -402,8 +402,8 @@ lockstep and it has to assert this conformance in some places using casts. If ge
written these casts will never fail.

As mentioned, however, the compiler-provided mechanism is intentionally very low level and it is anticipated that
higher level type class derivation and generic programming libraries will build on this and Dotty's other
higher level type class derivation and generic programming libraries will build on this and Scala 3's other
metaprogramming facilities to hide these low-level details from type class authors and general users. Type class
derivation in the style of both shapeless and Magnolia are possible (a prototype of shapeless 3, which combines
aspects of both shapeless 2 and Magnolia has been developed alongside this language feature) as is a more aggressively
inlined style, supported by Dotty's new quote/splice macro and inlining facilities.
inlined style, supported by Scala 3's new quote/splice macro and inlining facilities.
3 changes: 1 addition & 2 deletions docs/docs/reference/contextual/motivation.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Particular criticisms are:
```
one cannot write `currentMap("abc")` since the string "abc" is taken as explicit argument to the implicit `ctx` parameter. One has to write `currentMap.apply("abc")` instead, which is awkward and irregular. For the same reason, a method definition can only have one implicit parameter section and it must always come last. This restriction not only reduces orthogonality, but also prevents some useful program constructs, such as a method with a regular parameter whose type depends on an implicit value. Finally, it's also a bit annoying that implicit parameters must have a name, even though in many cases that name is never referenced.

5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but docs like ScalaDoc that are based static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Dotty compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but docs like ScalaDoc that are based static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Scala 3 compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.

None of the shortcomings is fatal, after all implicits are very widely used, and many libraries and applications rely on them. But together, they make code using implicits a lot more cumbersome and less clear than it could be.

Expand Down Expand Up @@ -78,4 +78,3 @@ Could we achieve the same goals by tweaking existing implicits? After having tri
- Third, even if we would somehow succeed with migration, we still have the problem
how to teach this. We cannot make existing tutorials go away. Almost all existing tutorials start with implicit conversions, which will go away; they use normal imports, which will go away, and they explain calls to methods with implicit parameters by expanding them to plain applications, which will also go away. This means that we'd have
to add modifications and qualifications to all existing literature and courseware, likely causing more confusion with beginners instead of less. By contrast, with a new syntax there is a clear criterion: Any book or courseware that mentions `implicit` is outdated and should be updated.

16 changes: 8 additions & 8 deletions docs/docs/reference/contextual/relationship-implicits.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ asked for.

Context bounds are the same in both language versions. They expand to the respective forms of implicit parameters.

**Note:** To ease migration, context bounds in Dotty map for a limited time to old-style implicit parameters for which arguments can be passed either in a using clause or
**Note:** To ease migration, context bounds in Scala 3 map for a limited time to old-style implicit parameters for which arguments can be passed either in a using clause or
in a normal argument list. Once old-style implicits are deprecated, context bounds
will map to using clauses instead.

Expand Down Expand Up @@ -141,7 +141,7 @@ Implicit by-name parameters are not supported in Scala 2, but can be emulated to

### Implicit Conversions

Implicit conversion methods in Scala 2 can be expressed as given instances of the `scala.Conversion` class in Dotty. E.g. instead of
Implicit conversion methods in Scala 2 can be expressed as given instances of the `scala.Conversion` class in Scala 3. E.g. instead of

```scala
implicit def stringToToken(str: String): Token = new Keyword(str)
Expand All @@ -162,18 +162,18 @@ given stringToToken: Conversion[String, Token] = KeyWord(_)

### 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 given `Conversion` instance.
Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Scala 3. Other uses of implicit classes can be simulated by a pair of a regular class and a given `Conversion` instance.

### Implicit Values

Implicit `val` definitions in Scala 2 can be expressed in Dotty using a regular `val` definition and an alias given.
Implicit `val` definitions in Scala 2 can be expressed in Scala 3 using a regular `val` definition and an alias given.
E.g., Scala 2's

```scala
lazy implicit val pos: Position = tree.sourcePos
```

can be expressed in Dotty as
can be expressed in Scala 3 as

```scala
lazy val pos: Position = tree.sourcePos
Expand All @@ -182,13 +182,13 @@ given Position = pos

### Abstract Implicits

An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an alias given. E.g., Scala 2's
An abstract implicit `val` or `def` in Scala 2 can be expressed in Scala 3 using a regular abstract definition and an alias given. E.g., Scala 2's

```scala
implicit def symDecorator: SymDecorator
```

can be expressed in Dotty as
can be expressed in Scala 3 as

```scala
def symDecorator: SymDecorator
Expand All @@ -197,7 +197,7 @@ given SymDecorator = symDecorator

## Implementation Status and Timeline

The Dotty implementation implements both Scala-2's implicits and the new abstractions. In fact, support for Scala-2's implicits is an essential part of the common language subset between 2.13/2.14 and Dotty.
The Scala 3 implementation implements both Scala-2's implicits and the new abstractions. In fact, support for Scala-2's implicits is an essential part of the common language subset between 2.13/2.14 and Scala 3.
Migration to the new abstractions will be supported by making automatic rewritings available.

Depending on adoption patterns, old style implicits might start to be deprecated in a version following Scala 3.0.
Loading