From 07bb30ef24b67f25be931047b6f78dc345703bb8 Mon Sep 17 00:00:00 2001 From: Adrien Piquerez Date: Wed, 12 May 2021 17:30:26 +0200 Subject: [PATCH 1/4] Fix more links --- _data/scala3-doc-nav-header.yml | 2 +- _ja/scala3/contribute-to-docs.md | 5 ++--- _ja/scala3/guides.md | 2 +- scala3/contribute-to-docs.md | 6 ++---- 4 files changed, 6 insertions(+), 9 deletions(-) diff --git a/_data/scala3-doc-nav-header.yml b/_data/scala3-doc-nav-header.yml index 823c440e3a..c390278c6d 100644 --- a/_data/scala3-doc-nav-header.yml +++ b/_data/scala3-doc-nav-header.yml @@ -10,7 +10,7 @@ - title: Macro Tutorial url: "/scala3/guides/macros/index.html" - title: Migrate - url: "https://scalacenter.github.io/scala-3-migration-guide" + url: "/scala3/guides/migration/compatibility-intro.html" - title: Reference url: "https://dotty.epfl.ch/docs/reference/overview.html" - title: API diff --git a/_ja/scala3/contribute-to-docs.md b/_ja/scala3/contribute-to-docs.md index b29b62dd17..dda4e2433e 100644 --- a/_ja/scala3/contribute-to-docs.md +++ b/_ja/scala3/contribute-to-docs.md @@ -42,9 +42,8 @@ Scala 3 の高品質なドキュメンテーションを作るためのいくつ ## Migration Guide [Scala 3 Migration Guide](/scala3/guides/migration/compatibility-intro.html) は Scala 2 と Scala 3 の互換性、移行に役立つツールの紹介、そして詳しい移行のガイドを含んだ包括的なドキュメントである。 -- [Contribution Overview](https://scalacenter.github.io/scala-3-migration-guide/docs/contributing.html) -- [Source](https://github.com/scalacenter/scala-3-migration-guide) -- [Issues](https://github.com/scalacenter/scala-3-migration-guide/issues) +- [Source](https://github.com/scala/docs.scala-lang/tree/master/_overviews/scala3-migration) +- [Issues](https://github.com/scalacenter/docs.scala-lang/issues) ## Scala 3 Language Reference diff --git a/_ja/scala3/guides.md b/_ja/scala3/guides.md index df6a0cf240..abb5f10772 100644 --- a/_ja/scala3/guides.md +++ b/_ja/scala3/guides.md @@ -8,7 +8,7 @@ scala3: true guides: - title: "Scala 2 から Scala 3 への移行" icon: suitcase - url: "https://scalacenter.github.io/scala-3-migration-guide" + url: "/scala3/guides/migration/compatibility-intro.html" description: "Scala 3 との互換性と移行について知っておくべきことすべて" - title: マクロ by: Nicolas Stucki diff --git a/scala3/contribute-to-docs.md b/scala3/contribute-to-docs.md index 5f3cd5af83..25d719a764 100644 --- a/scala3/contribute-to-docs.md +++ b/scala3/contribute-to-docs.md @@ -42,10 +42,8 @@ The [Scala 3 Migration Guide](/scala3/guides/migration/compatibility-intro.html) contains an comprehensive overview over compatibility between Scala 2 and Scala 3, a tour presenting the migration tools, and detailed migration guides. -- [Contribution Overview](https://scalacenter.github.io/scala-3-migration-guide/docs/contributing.html) -- [Source](https://github.com/scalacenter/scala-3-migration-guide) -- [Issues](https://github.com/scalacenter/scala-3-migration-guide/issues) - +- [Source](https://github.com/scala/docs.scala-lang/tree/master/_overviews/scala3-migration) +- [Issues](https://github.com/scalacenter/docs.scala-lang/issues) ## Scala 3 Language Reference The [Dotty reference](https://dotty.epfl.ch/docs/reference/overview.html) will evolve into the Scala 3 language, containing a formal presentation and detailed technical information about the various features of the language. From 2d2ea260b361fe92e20e58128241231b812553d2 Mon Sep 17 00:00:00 2001 From: Adrien Piquerez Date: Wed, 12 May 2021 17:33:05 +0200 Subject: [PATCH 2/4] Rename -no-indent Scala 3 option --- _overviews/scala3-migration/options-new.md | 2 +- _overviews/scala3-migration/tooling-syntax-rewriting.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_overviews/scala3-migration/options-new.md b/_overviews/scala3-migration/options-new.md index 2d4297bd2d..b5e030639b 100644 --- a/_overviews/scala3-migration/options-new.md +++ b/_overviews/scala3-migration/options-new.md @@ -19,7 +19,7 @@ The current page only contains the options that were added in Scala 3.0.x. | `-from-tasty` | Compile classes from tasty files. The arguments are .tasty or .jar files. | | `-indent` | Together with -rewrite, remove {...} syntax when possible due to significant indentation. | | `-new-syntax` | Require `then` and `do` in control expressions. | -| `-noindent` | Require classical {...} syntax, indentation is not significant. | +| `-no-indent` | Require classical {...} syntax, indentation is not significant. | | `-old-syntax` | Require `(...)` around conditions. | | `-pagewidth` | Set page width Default: 80. | | `-print-lines` | Show source code line numbers. | diff --git a/_overviews/scala3-migration/tooling-syntax-rewriting.md b/_overviews/scala3-migration/tooling-syntax-rewriting.md index 149bb658eb..c7c77a68b8 100644 --- a/_overviews/scala3-migration/tooling-syntax-rewriting.md +++ b/_overviews/scala3-migration/tooling-syntax-rewriting.md @@ -29,7 +29,7 @@ where possible standard options include: -indent Allow significant indentation ... -new-syntax Require `then` and `do` in control expressions. --noindent Require classical {...} syntax, indentation is not significant. +-no-indent Require classical {...} syntax, indentation is not significant. ... -old-syntax Require `(...)` around conditions. ... @@ -244,7 +244,7 @@ It is possible to mix the old and new syntax in a single code base. Although we would advise against it, since it would reduce the readability and make the code harder to maintain. A better approach is to choose one style and to consistently apply it to the entire code base. -`-noindent`, `-new-syntax` and `-old-syntax` can be used as standalone options to enforce a consistent syntax. +`-no-indent`, `-new-syntax` and `-old-syntax` can be used as standalone options to enforce a consistent syntax. For instance, with the `-new-syntax` option, the compiler issues an error when it encounters enclosing parentheses around an `if`-condition. From f35e6beefb4e2f94d7a0e7e196f4bd2b2a2832c7 Mon Sep 17 00:00:00 2001 From: Adrien Piquerez Date: Wed, 12 May 2021 17:56:14 +0200 Subject: [PATCH 3/4] Add kind-projector migration page --- _overviews/scala3-migration/options-new.md | 2 +- _overviews/scala3-migration/plugin-intro.md | 11 ++ .../scala3-migration/plugin-kind-projector.md | 127 ++++++++++++++++++ .../tutorial-prerequisites.md | 2 + 4 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 _overviews/scala3-migration/plugin-intro.md create mode 100644 _overviews/scala3-migration/plugin-kind-projector.md diff --git a/_overviews/scala3-migration/options-new.md b/_overviews/scala3-migration/options-new.md index b5e030639b..980f4c2712 100644 --- a/_overviews/scala3-migration/options-new.md +++ b/_overviews/scala3-migration/options-new.md @@ -4,7 +4,7 @@ type: section description: This chapter lists all the new compiler options in Scala 3 num: 23 previous-page: options-lookup -next-page: +next-page: plugin-intro --- The current page only contains the options that were added in Scala 3.0.x. diff --git a/_overviews/scala3-migration/plugin-intro.md b/_overviews/scala3-migration/plugin-intro.md new file mode 100644 index 0000000000..8662c8da93 --- /dev/null +++ b/_overviews/scala3-migration/plugin-intro.md @@ -0,0 +1,11 @@ +--- +title: Compiler Plugins +type: chapter +description: This section shows how to migrate from using Scala 2 compiler plugins +num: 24 +previous-page: options-new +next-page: plugin-kind-projector +--- + +Scala 3 includes some features that were previously provided by a compiler plugin. +This chapter gives more detail on how to migrate from using a specific compiler plugin to Scala 3. diff --git a/_overviews/scala3-migration/plugin-kind-projector.md b/_overviews/scala3-migration/plugin-kind-projector.md new file mode 100644 index 0000000000..c60b33b7b0 --- /dev/null +++ b/_overviews/scala3-migration/plugin-kind-projector.md @@ -0,0 +1,127 @@ +--- +title: Kind Projector Migration +type: section +description: This section shows how to migrate from the kind-projector plugin to Scala 3 kind-projector syntax +num: 25 +previous-page: plugin-intro +next-page: +--- + +In the future, Scala 3 will use the `_` underscore symbol for placeholders in type lambdas---just as the underscore is currently used for placeholders in (ordinary) term-level lambdas. + +The new type lambda syntax is not enabled by default, to enable it, use a compiler flag `-Ykind-projector:underscores`. Note that enabling underscore type lambdas will disable usage of `_` as a wildcard, you will only be able to write wildcards using the `?` symbol. + +If you wish to cross-compile a project for Scala 2 & Scala 3 while using underscore type lambdas for both, you may do so starting with [kind-projector](https://github.com/typelevel/kind-projector) version `0.13.0` and up and Scala 2 versions `2.13.6` and `2.12.14`. +To enable it, add the compiler flags `-Xsource:3 -P:kind-projector:underscore-placeholders` to your build. +As in Scala 3, this will disable usage of `_` as a wildcard, however, the flag `-Xsource:3` will allow you to replace it with the `?` symbol. + +The following `sbt` configuration will set up the correct flags to cross-compile with new syntax: + +```scala +ThisBuild / scalacOptions ++= { + CrossVersion.partialVersion(scalaVersion.value) match { + case Some((3, _)) => Seq("-Ykind-projector:underscores") + case Some((2, 13)) | Some((2, 12)) => Seq("-Xsource:3", "-P:kind-projector:underscore-placeholders")) + } +} +``` + +## Migrating to New Syntax + +To use underscores for type-lambdas in existing kind-projector enabled code, replace `*` or `?` type lambda placeholders with `_`. + +In turn, you will also have to rewrite all usages of `_` as the wildcard to use `?` symbol. + +For example the following usage of the wildcard: + +```scala +def getWidget(widgets: Set[_ <: Widget], name: String): Option[Widget] = widgets.find(_.name == name) +``` + +Must be rewritten to: + +```scala +def getWidget(widgets: Set[? <: Widget], name: String): Option[Widget] = widgets.find(_.name == name) +``` + +And the following usages of kind-projector's `*` placeholder: + +```scala +Tuple2[*, Double] // equivalent to: type R[A] = Tuple2[A, Double] +Either[Int, +*] // equivalent to: type R[+A] = Either[Int, A] +Function2[-*, Long, +*] // equivalent to: type R[-A, +B] = Function2[A, Long, B] +``` + +Must be rewritten to: + +```scala +Tuple2[_, Double] // equivalent to: type R[A] = Tuple2[A, Double] +Either[Int, +_] // equivalent to: type R[+A] = Either[Int, A] +Function2[-_, Long, +_] // equivalent to: type R[-A, +B] = Function2[A, Long, B] +``` + +## Compiling Existing Code + +Even without migrating to underscore type lambdas, you will likely be able to compile most of it with Scala 3 without changes. + +Use the flag `-Ykind-projector` to enable support for `*`-based type lambdas (without enabling underscore type lambdas), the following forms will now compile: + +```scala +Tuple2[*, Double] // equivalent to: type R[A] = Tuple2[A, Double] +Either[Int, +*] // equivalent to: type R[+A] = Either[Int, A] +Function2[-*, Long, +*] // equivalent to: type R[-A, +B] = Function2[A, Long, B] +``` + +## Rewriting Incompatible Constructs + +Scala 3's `-Ykind-projector` & `-Ykind-projector:underscores` implement only a subset of `kind-projector` syntax, in particular they do not implement: + +* higher-kinded type lambda placeholders +* higher-kinded named type lambda parameters +* The `Lambda` keyword (`λ` is still supported) + +You must rewrite ALL of the following forms: + +```scala +// classic +EitherT[*[_], Int, *] // equivalent to: type R[F[_], B] = EitherT[F, Int, B] +// underscores +EitherT[_[_], Int, _] // equivalent to: type R[F[_], B] = EitherT[F, Int, B] +// named λ +λ[(F[_], A) => EitherT[F, Int, A]] +// named Lambda +Lambda[(F[_], A) => EitherT[F, Int, A]] +``` + +Into the following long-form to cross-compile with Scala 3: + +```scala +type MyLambda[F[_], A] = EitherT[F, Int, A] +MyLambda +``` + +Alternatively you may use Scala 3's [Native Type Lambdas](https://dotty.epfl.ch/docs/reference/new-types/type-lambdas.html) if you do not need to cross-compile: + +```scala +[F[_], A] =>> EitherT[F, Int, A] +``` + +For `Lambda` you must rewrite the following form: + +```scala +Lambda[(`+E`, `+A`) => Either[E, A]] +``` + +To the following to cross-compile: + +```scala +λ[(`+E`, `+A`) => Either[E, A]] +``` + +Or alternatively to Scala 3 type lambdas: + +```scala +[E, A] =>> Either[E, A] +``` + +Note: Scala 3 type lambdas no longer need `-` or `+` variance markers on parameters, these are now inferred. diff --git a/_overviews/scala3-migration/tutorial-prerequisites.md b/_overviews/scala3-migration/tutorial-prerequisites.md index 45a0ea4360..b3b3571520 100644 --- a/_overviews/scala3-migration/tutorial-prerequisites.md +++ b/_overviews/scala3-migration/tutorial-prerequisites.md @@ -115,6 +115,8 @@ AdditionalLy, we now have the following features that make `kind-projector` not - [Polymorphic Functions](http://dotty.epfl.ch/docs/reference/new-types/polymorphic-function-types.html) - [Kind Polymorphism](http://dotty.epfl.ch/docs/reference/other-new-features/kind-polymorphism.html) +You can learn more about the Kind Projector migration in its [dedicated page](plugin-kind-projector.html). + ## Runtime reflection `scala-reflect` will not be ported to Scala 3 because it exposes Scala 2 compiler internals that do not exist in Scala 3. From 88e77808def97b3a372a02da8843f489aa74ee73 Mon Sep 17 00:00:00 2001 From: Adrien Piquerez Date: Wed, 12 May 2021 17:58:00 +0200 Subject: [PATCH 4/4] Fix typos --- _overviews/scala3-migration/incompat-other-changes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/_overviews/scala3-migration/incompat-other-changes.md b/_overviews/scala3-migration/incompat-other-changes.md index cb8ffc1607..8fae52925d 100644 --- a/_overviews/scala3-migration/incompat-other-changes.md +++ b/_overviews/scala3-migration/incompat-other-changes.md @@ -254,7 +254,6 @@ The solution depends on the situation. In the given example, you can either: Scala 3 cannot reduce the application of a higher-kinded abstract type member to the wildcard argument. -For instance, the following example does not compile. For instance, the following example does not compile. ```scala @@ -275,7 +274,7 @@ We can fix this by using a type parameter: But this simple solution does not work when `Foo` is itself used as a type argument. ```scala -def g(foos: Seq[Foo[_]]): Unit` +def g(foos: Seq[Foo[_]]): Unit ``` In such case, we can use a wrapper class around `Foo`: @@ -283,6 +282,6 @@ In such case, we can use a wrapper class around `Foo`: {% highlight diff %} +class FooWrapper[A](foo: Foo[A]) --def g(foos: Seq[Foo[_]]): Unit` +-def g(foos: Seq[Foo[_]]): Unit +def g(foos: Seq[FooWrapper[_]]): Unit {% endhighlight %}