diff --git a/docs/docs/reference/changed-features.md b/docs/docs/reference/changed-features.md new file mode 100644 index 000000000000..c23a9031bef0 --- /dev/null +++ b/docs/docs/reference/changed-features.md @@ -0,0 +1,9 @@ +--- +title: "Other Changed Features" +type: chapter +num: 51 +previous-page: /scala3/reference/other-new-features/type-test +next-page: /scala3/reference/changed-features/numeric-literals +--- + +The following pages document the features that have changed in Scala 3, compared to Scala 2. diff --git a/docs/docs/reference/changed-features/compiler-plugins.md b/docs/docs/reference/changed-features/compiler-plugins.md index 2a446e9cfb84..c77796d71df1 100644 --- a/docs/docs/reference/changed-features/compiler-plugins.md +++ b/docs/docs/reference/changed-features/compiler-plugins.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Changes in Compiler Plugins" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/compiler-plugins.html +type: section +num: 67 +previous-page: /scala3/reference/changed-features/eta-expansion +next-page: /scala3/reference/changed-features/lazy-vals-init --- Compiler plugins are supported by Dotty (and Scala 3) since 0.9. There are two notable changes diff --git a/docs/docs/reference/changed-features/eta-expansion-spec.md b/docs/docs/reference/changed-features/eta-expansion-spec.md index 67f7606d5b15..78d021003cc4 100644 --- a/docs/docs/reference/changed-features/eta-expansion-spec.md +++ b/docs/docs/reference/changed-features/eta-expansion-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Automatic Eta Expansion - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/eta-expansion-spec.html --- ## Motivation diff --git a/docs/docs/reference/changed-features/eta-expansion.md b/docs/docs/reference/changed-features/eta-expansion.md index 2ae9af870a55..91516edca5a5 100644 --- a/docs/docs/reference/changed-features/eta-expansion.md +++ b/docs/docs/reference/changed-features/eta-expansion.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Automatic Eta Expansion" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/eta-expansion.html +type: section +num: 66 +previous-page: /scala3/reference/changed-features/pattern-matching +next-page: /scala3/reference/changed-features/compiler-plugins --- The conversion of _methods_ into _functions_ has been improved and happens automatically for methods with one or more parameters. @@ -36,7 +38,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 Scala 3, but the fundamental ambiguity +[limited](../dropped-features/auto-apply.html) in Scala 3, but the fundamental ambiguity remains. -[More details](eta-expansion-spec.md) +[More details](eta-expansion-spec.html) diff --git a/docs/docs/reference/changed-features/implicit-conversions-spec.md b/docs/docs/reference/changed-features/implicit-conversions-spec.md index 47cfd941bf02..32bb641dbf74 100644 --- a/docs/docs/reference/changed-features/implicit-conversions-spec.md +++ b/docs/docs/reference/changed-features/implicit-conversions-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Implicit Conversions - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-conversions-spec.html --- ## Implementation @@ -82,7 +82,7 @@ implicit val myConverter: Int => String = _.toString implicit val myConverter: Conversion[Int, String] = _.toString ``` -Note that implicit conversions are also affected by the [changes to implicit resolution](implicit-resolution.md) between Scala 2 and Scala 3. +Note that implicit conversions are also affected by the [changes to implicit resolution](implicit-resolution.html) between Scala 2 and Scala 3. ## Motivation for the changes @@ -109,9 +109,9 @@ will report a type error, because `Map` isn't an instance of Implicit values that are used as views should see their type changed to `Conversion`. For the migration of implicit conversions that are affected by the -changes to implicit resolution, refer to the [Changes in Implicit Resolution](implicit-resolution.md) for more information. +changes to implicit resolution, refer to the [Changes in Implicit Resolution](implicit-resolution.html) for more information. ## Reference -For more information about implicit resolution, see [Changes in Implicit Resolution](implicit-resolution.md). +For more information about implicit resolution, see [Changes in Implicit Resolution](implicit-resolution.html). Other details are available in [PR #2065](https://github.com/lampepfl/dotty/pull/2065). diff --git a/docs/docs/reference/changed-features/implicit-conversions.md b/docs/docs/reference/changed-features/implicit-conversions.md index 2ee2583d3cd8..39b4cde31e63 100644 --- a/docs/docs/reference/changed-features/implicit-conversions.md +++ b/docs/docs/reference/changed-features/implicit-conversions.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Implicit Conversions" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-conversions.html +type: section +num: 60 +previous-page: /scala3/reference/changed-features/implicit-resolution +next-page: /scala3/reference/changed-features/overload-resolution --- An _implicit conversion_, also called _view_, is a conversion that @@ -61,4 +63,4 @@ implicitly[Ordering[A]] // Ok, will use the implicit conversion from // `A` to `Int` and the `Ordering` for `Int`. ``` -[More details](implicit-conversions-spec.md) +[More details](implicit-conversions-spec.html) diff --git a/docs/docs/reference/changed-features/implicit-resolution.md b/docs/docs/reference/changed-features/implicit-resolution.md index 8cb20fd51141..22d6ba7d1fca 100644 --- a/docs/docs/reference/changed-features/implicit-resolution.md +++ b/docs/docs/reference/changed-features/implicit-resolution.md @@ -1,8 +1,11 @@ --- -layout: doc-page title: "Changes in Implicit Resolution" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-resolution.html +type: section +num: 59 +previous-page: /scala3/reference/changed-features/type-inference +next-page: /scala3/reference/changed-features/implicit-conversions --- + This section 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 diff --git a/docs/docs/reference/changed-features/imports.md b/docs/docs/reference/changed-features/imports.md index 7d364ce68b92..39568769a270 100644 --- a/docs/docs/reference/changed-features/imports.md +++ b/docs/docs/reference/changed-features/imports.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Imports" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/imports.html +type: section +num: 56 +previous-page: /scala3/reference/changed-features/wildcards +next-page: /scala3/reference/changed-features/type-checking --- The syntax of wildcard and renaming imports (and exports) has changed. diff --git a/docs/docs/reference/changed-features/interpolation-escapes.md b/docs/docs/reference/changed-features/interpolation-escapes.md index d5b3a82d94cc..c61ef9828178 100644 --- a/docs/docs/reference/changed-features/interpolation-escapes.md +++ b/docs/docs/reference/changed-features/interpolation-escapes.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Escapes in interpolations" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/interpolation-escapes.html --- In Scala 2 there is 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. diff --git a/docs/docs/reference/changed-features/lazy-vals-init.md b/docs/docs/reference/changed-features/lazy-vals-init.md index 10abbb80a2be..a065cebb2a49 100644 --- a/docs/docs/reference/changed-features/lazy-vals-init.md +++ b/docs/docs/reference/changed-features/lazy-vals-init.md @@ -1,7 +1,9 @@ --- -layout: doc-page -title: Lazy Vals initialization -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/lazy-vals-init.html +title: Lazy Vals Initialization +type: section +num: 68 +previous-page: /scala3/reference/changed-features/compiler-plugins +next-page: /scala3/reference/changed-features/main-functions --- 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) diff --git a/docs/docs/reference/changed-features/main-functions.md b/docs/docs/reference/changed-features/main-functions.md index 9d166492d962..6f035278ed05 100644 --- a/docs/docs/reference/changed-features/main-functions.md +++ b/docs/docs/reference/changed-features/main-functions.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Main Methods" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/main-functions.html +type: section +num: 69 +previous-page: /scala3/reference/changed-features/lazy-vals-init +next-page: /scala3/reference/dropped-features --- Scala 3 offers a new way to define programs that can be invoked from the command line: @@ -57,7 +59,7 @@ The Scala compiler generates a program from a `@main` method `f` as follows: - The class has a static method `main` with the usual signature. It takes an `Array[String]` as argument and returns `Unit`. - The generated `main` method calls method `f` with arguments converted using - methods in the [`scala.util.CommandLineParser`](https://dotty.epfl.ch/api/scala/util/CommandLineParser$.html) object. + methods in the [`scala.util.CommandLineParser`](https://scala-lang.org/api/3.x/scala/util/CommandLineParser$.html) object. For instance, the `happyBirthDay` method above would generate additional code equivalent to the following class: @@ -85,5 +87,5 @@ object happyBirthday extends App: ... ``` -The previous functionality of `App`, which relied on the "magic" [`DelayedInit`](../dropped-features/delayed-init.md) trait, is no longer available. [`App`](https://dotty.epfl.ch/api/scala/App.html) still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build +The previous functionality of `App`, which relied on the "magic" [`DelayedInit`]({% link _scala3-reference/dropped-features/delayed-init.md %}) trait, is no longer available. [`App`](https://scala-lang.org/api/3.x/scala/App.html) still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build between Scala 2 and Scala 3, it is recommended to use an explicit `main` method with an `Array[String]` argument instead. diff --git a/docs/docs/reference/changed-features/match-syntax.md b/docs/docs/reference/changed-features/match-syntax.md index f7a7c17075d3..7ebc85b6d003 100644 --- a/docs/docs/reference/changed-features/match-syntax.md +++ b/docs/docs/reference/changed-features/match-syntax.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Match Expressions" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/match-syntax.html +type: section +num: 62 +previous-page: /scala3/reference/changed-features/overload-resolution +next-page: /scala3/reference/changed-features/vararg-splices --- The syntactical precedence of match expressions has been changed. @@ -47,7 +49,7 @@ The syntactical precedence of match expressions has been changed. The new syntax of match expressions is as follows. -```ebnf +``` InfixExpr ::= ... | InfixExpr MatchClause SimpleExpr ::= ... diff --git a/docs/docs/reference/changed-features/numeric-literals.md b/docs/docs/reference/changed-features/numeric-literals.md index 7705410ce369..8a21d97bd4a4 100644 --- a/docs/docs/reference/changed-features/numeric-literals.md +++ b/docs/docs/reference/changed-features/numeric-literals.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Numeric Literals" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/numeric-literals.html +type: section +num: 52 +previous-page: /scala3/reference/changed-features +next-page: /scala3/reference/changed-features/structural-types --- [Document was moved](../experimental/numeric-literals.md) \ No newline at end of file diff --git a/docs/docs/reference/changed-features/operators.md b/docs/docs/reference/changed-features/operators.md index 495eb8c5ede9..5e05c6bfbcae 100644 --- a/docs/docs/reference/changed-features/operators.md +++ b/docs/docs/reference/changed-features/operators.md @@ -1,13 +1,15 @@ --- -layout: doc-page title: "Rules for Operators" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/operators.html +type: section +num: 54 +previous-page: /scala3/reference/changed-features/structural-types +next-page: /scala3/reference/changed-features/wildcards --- The rules for infix operators have changed in some parts: First, an alphanumeric method can be used as an infix operator only if its definition carries an `infix` modifier. Second, it is recommended (but not enforced) to -augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.md). Finally, +augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.html). Finally, a syntax change allows infix operators to be written on the left in a multi-line expression. ## The `infix` Modifier @@ -97,7 +99,7 @@ or if the `-source future` option is given in Dotty/Scala 3. ## The `@targetName` Annotation -It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.md) that provides an encoding of the operator with an alphanumeric name. This has several benefits: +It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.html) that provides an encoding of the operator with an alphanumeric name. This has several benefits: - It helps interoperability between Scala and other languages. One can call a Scala-defined symbolic operator from another language using its target name, diff --git a/docs/docs/reference/changed-features/overload-resolution.md b/docs/docs/reference/changed-features/overload-resolution.md index e6c929f7a2ef..6b203299707f 100644 --- a/docs/docs/reference/changed-features/overload-resolution.md +++ b/docs/docs/reference/changed-features/overload-resolution.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Changes in Overload Resolution" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/overload-resolution.html +type: section +num: 61 +previous-page: /scala3/reference/changed-features/implicit-conversions +next-page: /scala3/reference/changed-features/match-syntax --- Overload resolution in Scala 3 improves on Scala 2 in two ways. @@ -42,7 +44,7 @@ resolution yields several competing alternatives when `n >= 1` parameter lists a into account, then resolution re-tried using `n + 1` argument lists. This change is motivated by the new language feature -[extension methods](../contextual/extension-methods.md), where emerges the need to do +[extension methods](../contextual/extension-methods.html), where emerges the need to do overload resolution based on additional argument blocks. ## Parameter Types of Function Values diff --git a/docs/docs/reference/changed-features/pattern-bindings.md b/docs/docs/reference/changed-features/pattern-bindings.md index 978bff2d7d7e..307ff6387cce 100644 --- a/docs/docs/reference/changed-features/pattern-bindings.md +++ b/docs/docs/reference/changed-features/pattern-bindings.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Pattern Bindings" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html +type: section +num: 64 +previous-page: /scala3/reference/changed-features/vararg-splices +next-page: /scala3/reference/changed-features/pattern-matching --- In Scala 2, pattern bindings in `val` definitions and `for` expressions are diff --git a/docs/docs/reference/changed-features/pattern-matching.md b/docs/docs/reference/changed-features/pattern-matching.md index b9115fe93233..2216d145a80d 100644 --- a/docs/docs/reference/changed-features/pattern-matching.md +++ b/docs/docs/reference/changed-features/pattern-matching.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Option-less pattern matching" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-matching.html +type: section +num: 65 +previous-page: /scala3/reference/changed-features/pattern-bindings +next-page: /scala3/reference/changed-features/eta-expansion --- 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. @@ -241,4 +243,4 @@ Abstract type testing with `ClassTag` is replaced with `TypeTest` or the alias ` - pattern `_: X` for an abstract type requires a `TypeTest` in scope - pattern `x @ X()` for an unapply that takes an abstract type requires a `TypeTest` in scope -[More details on `TypeTest`](../other-new-features/type-test.md) +[More details on `TypeTest`](../other-new-features/type-test.html) diff --git a/docs/docs/reference/changed-features/structural-types-spec.md b/docs/docs/reference/changed-features/structural-types-spec.md index 5c99afbcc1bb..eb7e653a780a 100644 --- a/docs/docs/reference/changed-features/structural-types-spec.md +++ b/docs/docs/reference/changed-features/structural-types-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Programmatic Structural Types - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/structural-types-spec.html --- ## Syntax @@ -81,7 +81,7 @@ and `Rs` are structural refinement declarations, and given `v.a` of type `U`, we Note that `v`'s static type does not necessarily have to conform to `Selectable`, nor does it need to have `selectDynamic` and `applyDynamic` as members. It suffices that there is an implicit conversion that can turn `v` into a `Selectable`, and the selection methods could also be available as -[extension methods](../contextual/extension-methods.md). +[extension methods](../contextual/extension-methods.html). ## Limitations of Structural Types diff --git a/docs/docs/reference/changed-features/structural-types.md b/docs/docs/reference/changed-features/structural-types.md index 904525a4655d..fe20a3aa5483 100644 --- a/docs/docs/reference/changed-features/structural-types.md +++ b/docs/docs/reference/changed-features/structural-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Programmatic Structural Types" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/structural-types.html +type: section +num: 53 +previous-page: /scala3/reference/changed-features/numeric-literals +next-page: /scala3/reference/changed-features/operators --- ## Motivation @@ -189,4 +191,4 @@ differences. `java.lang.Class` arguments indicating the method's formal parameter types. `Dynamic` comes with `updateDynamic`. -[More details](structural-types-spec.md) +[More details](structural-types-spec.html) diff --git a/docs/docs/reference/changed-features/type-checking.md b/docs/docs/reference/changed-features/type-checking.md index 09a62698d4c7..81ca345a6c7e 100644 --- a/docs/docs/reference/changed-features/type-checking.md +++ b/docs/docs/reference/changed-features/type-checking.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Changes in Type Checking" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/type-checking.html +type: section +num: 57 +previous-page: /scala3/reference/changed-features/imports +next-page: /scala3/reference/changed-features/type-inference --- *** **TO BE FILLED IN** *** diff --git a/docs/docs/reference/changed-features/type-inference.md b/docs/docs/reference/changed-features/type-inference.md index 020878444914..873c91831210 100644 --- a/docs/docs/reference/changed-features/type-inference.md +++ b/docs/docs/reference/changed-features/type-inference.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Changes in Type Inference" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/type-inference.html +type: section +num: 58 +previous-page: /scala3/reference/changed-features/type-checking +next-page: /scala3/reference/changed-features/implicit-resolution --- For more information, see the two presentations diff --git a/docs/docs/reference/changed-features/vararg-splices.md b/docs/docs/reference/changed-features/vararg-splices.md index d5a3b8eb6ab4..efa7f034acea 100644 --- a/docs/docs/reference/changed-features/vararg-splices.md +++ b/docs/docs/reference/changed-features/vararg-splices.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Vararg Splices" -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/vararg-splices.html +type: section +num: 63 +previous-page: /scala3/reference/changed-features/match-syntax +next-page: /scala3/reference/changed-features/pattern-bindings --- The syntax of vararg splices in patterns and function arguments has changed. The new syntax uses a postfix `*`, analogously to how a vararg parameter is declared. @@ -24,7 +26,7 @@ The old syntax for splice arguments will be phased out. ## Syntax -```ebnf +``` ArgumentPatterns ::= ‘(’ [Patterns] ‘)’ | ‘(’ [Patterns ‘,’] Pattern2 ‘*’ ‘)’ diff --git a/docs/docs/reference/changed-features/wildcards.md b/docs/docs/reference/changed-features/wildcards.md index de0b83339c22..fdf69fdcd954 100644 --- a/docs/docs/reference/changed-features/wildcards.md +++ b/docs/docs/reference/changed-features/wildcards.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: Wildcard Arguments in Types -movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/wildcards.html +type: section +num: 55 +previous-page: /scala3/reference/changed-features/operators +next-page: /scala3/reference/changed-features/imports --- The syntax of wildcard arguments in types has changed from `_` to `?`. Example: diff --git a/docs/docs/reference/contextual.md b/docs/docs/reference/contextual.md new file mode 100644 index 000000000000..1dfc5e6baa97 --- /dev/null +++ b/docs/docs/reference/contextual.md @@ -0,0 +1,85 @@ +--- +title: "Contextual Abstractions" +type: chapter +num: 13 +previous-page: /scala3/reference/enums/desugarEnums +next-page: /scala3/reference/contextual/givens +--- + +### Critique of the Status Quo + +Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them. + +Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g [Rust's traits](https://doc.rust-lang.org/rust-by-example/trait.html) or [Swift's protocol extensions](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID521). Design proposals are also on the table for Kotlin as [compile time dependency resolution](https://github.com/Kotlin/KEEP/blob/e863b25f8b3f2e9b9aaac361c6ee52be31453ee0/proposals/compile-time-dependency-resolution.md), for C# as [Shapes and Extensions](https://github.com/dotnet/csharplang/issues/164) +or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as [Coq](https://coq.inria.fr/refman/language/extensions/implicit-arguments.html) or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html). + +Even though these designs use widely different terminology, they are all variants of the core idea of _term inference_. Given a type, the compiler synthesizes a "canonical" term that has that type. Scala embodies the idea in a purer form than most other languages: An implicit parameter directly leads to an inferred argument term that could also be written down explicitly. By contrast, type class based designs are less direct since they hide term inference behind some form of type classification and do not offer the option of writing the inferred quantities (typically, dictionaries) explicitly. + +Given that term inference is where the industry is heading, and given that Scala has it in a very pure form, how come implicits are not more popular? In fact, it's fair to say that implicits are at the same time Scala's most distinguished and most controversial feature. I believe this is due to a number of aspects that together make implicits harder to learn than necessary and also make it harder to prevent abuses. + +Particular criticisms are: + +1. Being very powerful, implicits are easily over-used and mis-used. This observation holds in almost all cases when we talk about _implicit conversions_, which, even though conceptually different, share the same syntax with other implicit definitions. For instance, regarding the two definitions + + ```scala + implicit def i1(implicit x: T): C[T] = ... + implicit def i2(x: T): C[T] = ... + ``` + + the first of these is a conditional implicit _value_, the second an implicit _conversion_. Conditional implicit values are a cornerstone for expressing type classes, whereas most applications of implicit conversions have turned out to be of dubious value. The problem is that many newcomers to the language start with defining implicit conversions since they are easy to understand and seem powerful and convenient. Scala 3 will put under a language flag both definitions and applications of "undisciplined" implicit conversions between types defined elsewhere. This is a useful step to push back against overuse of implicit conversions. But the problem remains that syntactically, conversions and values just look too similar for comfort. + +2. Another widespread abuse is over-reliance on implicit imports. This often leads to inscrutable type errors that go away with the right import incantation, leaving a feeling of frustration. Conversely, it is hard to see what implicits a program uses since implicits can hide anywhere in a long list of imports. + +3. The syntax of implicit definitions is too minimal. It consists of a single modifier, `implicit`, that can be attached to a large number of language constructs. A problem with this for newcomers is that it conveys mechanism instead of intent. For instance, a type class instance is an implicit object or val if unconditional and an implicit def with implicit parameters referring to some class if conditional. This describes precisely what the implicit definitions translate to -- just drop the `implicit` modifier, and that's it! But the cues that define intent are rather indirect and can be easily misread, as demonstrated by the definitions of `i1` and `i2` above. + +4. The syntax of implicit parameters also has shortcomings. While implicit _parameters_ are designated specifically, arguments are not. Passing an argument to an implicit parameter looks like a regular application `f(arg)`. This is problematic because it means there can be confusion regarding what parameter gets instantiated in a call. For instance, in + + ```scala + def currentMap(implicit ctx: Context): Map[String, Int] + ``` + + 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 tools like [Scaladoc](https://docs.scala-lang.org/overviews/scaladoc/overview.html) that are based on 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. + +Historically, many of these shortcomings come from the way implicits were gradually "discovered" in Scala. Scala originally had only implicit conversions with the intended use case of "extending" a class or trait after it was defined, i.e. what is expressed by implicit classes in later versions of Scala. Implicit parameters and instance definitions came later in 2006 and we picked similar syntax since it seemed convenient. For the same reason, no effort was made to distinguish implicit imports or arguments from normal ones. + +Existing Scala programmers by and large have gotten used to the status quo and see little need for change. But for newcomers this status quo presents a big hurdle. I believe if we want to overcome that hurdle, we should take a step back and allow ourselves to consider a radically new design. + +### The New Design + +The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes: + +1. [Given Instances](./contextual/givens.html) are a new way to define basic terms that can be synthesized. They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types. + +2. [Using Clauses](./contextual/using-clauses.html) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition. + +3. ["Given" Imports](./contextual/given-imports.html) are a new class of import selectors that specifically import + givens and nothing else. + +4. [Implicit Conversions](./contextual/conversions.html) are now expressed as given instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out. + +This section also contains pages describing other language features that are related to context abstraction. These are: + +- [Context Bounds](./contextual/context-bounds.html), which carry over unchanged. +- [Extension Methods](./contextual/extension-methods.html) replace implicit classes in a way that integrates better with type classes. +- [Implementing Type Classes](./contextual/type-classes.html) demonstrates how some common type classes can be implemented using the new constructs. +- [Type Class Derivation](./contextual/derivation.html) introduces constructs to automatically derive type class instances for ADTs. +- [Multiversal Equality](./contextual/multiversal-equality.html) introduces a special type class to support type safe equality. +- [Context Functions](./contextual/context-functions.html) provide a way to abstract over context parameters. +- [By-Name Context Parameters](./contextual/by-name-context-parameters.html) are an essential tool to define recursive synthesized values without looping. +- [Relationship with Scala 2 Implicits](./contextual/relationship-implicits.html) discusses the relationship between old-style implicits and new-style givens and how to migrate from one to the other. + +Overall, the new design achieves a better separation of term inference from the rest of the language: There is a single way to define givens instead of a multitude of forms all taking an `implicit` modifier. There is a single way to introduce implicit parameters and arguments instead of conflating implicit with normal arguments. There is a separate way to import givens that does not allow them to hide in a sea of normal imports. And there is a single way to define an implicit conversion which is clearly marked as such and does not require special syntax. + +This design thus avoids feature interactions and makes the language more consistent and orthogonal. It will make implicits easier to learn and harder to abuse. It will greatly improve the clarity of the 95% of Scala programs that use implicits. It has thus the potential to fulfil the promise of term inference in a principled way that is also accessible and friendly. + +Could we achieve the same goals by tweaking existing implicits? After having tried for a long time, I believe now that this is impossible. + +- First, some of the problems are clearly syntactic and require different syntax to solve them. +- Second, there is the problem how to migrate. We cannot change the rules in mid-flight. At some stage of language evolution we need to accommodate both the new and the old rules. With a syntax change, this is easy: Introduce the new syntax with new rules, support the old syntax for a while to facilitate cross compilation, deprecate and phase out the old syntax at some later time. Keeping the same syntax does not offer this path, and in fact does not seem to offer any viable path for evolution +- 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. diff --git a/docs/docs/reference/contextual/by-name-context-parameters.md b/docs/docs/reference/contextual/by-name-context-parameters.md index 8e8427f7457f..c1777b625912 100644 --- a/docs/docs/reference/contextual/by-name-context-parameters.md +++ b/docs/docs/reference/contextual/by-name-context-parameters.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "By-Name Context Parameters" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/by-name-context-parameters.html +type: section +num: 25 +previous-page: /scala3/reference/contextual/conversions +next-page: /scala3/reference/contextual/relationship-implicits --- Context parameters can be declared by-name to avoid a divergent inferred expansion. Example: diff --git a/docs/docs/reference/contextual/context-bounds.md b/docs/docs/reference/contextual/context-bounds.md index e336f00cc463..5c7ea5cd5936 100644 --- a/docs/docs/reference/contextual/context-bounds.md +++ b/docs/docs/reference/contextual/context-bounds.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Context Bounds" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-bounds.html +type: section +num: 17 +previous-page: /scala3/reference/contextual/using-clauses +next-page: /scala3/reference/contextual/given-imports --- A context bound is a shorthand for expressing the common pattern of a context parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this: diff --git a/docs/docs/reference/contextual/context-functions-spec.md b/docs/docs/reference/contextual/context-functions-spec.md index bca56acad58d..9267eea23f49 100644 --- a/docs/docs/reference/contextual/context-functions-spec.md +++ b/docs/docs/reference/contextual/context-functions-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Context Functions - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-functions-spec.html --- ## Syntax @@ -66,7 +66,7 @@ itself a context function literal. This is analogous to the automatic insertion of `scala.Function0` around expressions in by-name argument position. Context function types generalize to `N > 22` in the same way that function types do, see [the corresponding -documentation](../dropped-features/limit22.md). +documentation](../dropped-features/limit22.html). ## Examples diff --git a/docs/docs/reference/contextual/context-functions.md b/docs/docs/reference/contextual/context-functions.md index c556a0cadf8f..1b930b3c8dfc 100644 --- a/docs/docs/reference/contextual/context-functions.md +++ b/docs/docs/reference/contextual/context-functions.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Context Functions" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-functions.html +type: section +num: 23 +previous-page: /scala3/reference/contextual/multiversal-equality +next-page: /scala3/reference/contextual/conversions --- _Context functions_ are functions with (only) context parameters. @@ -151,4 +153,4 @@ val s = For more information, see the [blog article](https://www.scala-lang.org/blog/2016/12/07/implicit-function-types.html), (which uses a different syntax that has been superseded). -[More details](./context-functions-spec.md) +[More details](./context-functions-spec.html) diff --git a/docs/docs/reference/contextual/conversions.md b/docs/docs/reference/contextual/conversions.md index 9928719663e2..5a222515adea 100644 --- a/docs/docs/reference/contextual/conversions.md +++ b/docs/docs/reference/contextual/conversions.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Implicit Conversions" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/conversions.html +type: section +num: 24 +previous-page: /scala3/reference/contextual/context-functions +next-page: /scala3/reference/contextual/by-name-context-parameters --- Implicit conversions are defined by given instances of the `scala.Conversion` class. diff --git a/docs/docs/reference/contextual/derivation-macro.md b/docs/docs/reference/contextual/derivation-macro.md index 47c1ee0d2e55..c9c657d7804f 100644 --- a/docs/docs/reference/contextual/derivation-macro.md +++ b/docs/docs/reference/contextual/derivation-macro.md @@ -1,10 +1,10 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "How to write a type class `derived` method using macros" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/derivation-macro.html --- -In the main [derivation](./derivation.md) documentation page, we explained the +In the main [derivation](./derivation.html) documentation page, we explained the details behind `Mirror`s and type class derivation. Here we demonstrate how to implement a type class `derived` method using macros only. We follow the same example of deriving `Eq` instances and for simplicity we support a `Product` @@ -98,7 +98,7 @@ One additional difference with the body of `derived` here as opposed to the one with `inline` is that with macros we need to synthesize the body of the code during the macro-expansion time. That is the rationale behind the `eqProductBody` function. Assuming that we calculate the equality of two `Person`s defined with a case -class that holds a name of type [`String`](https://dotty.epfl.ch/api/scala/Predef$.html#String) +class that holds a name of type [`String`](https://scala-lang.org/api/3.x/scala/Predef$.html#String-0) and an age of type `Int`, the equality check we want to generate is the following: ```scala @@ -109,7 +109,7 @@ and an age of type `Int`, the equality check we want to generate is the followin ## Calling the derived method inside the macro -Following the rules in [Macros](../metaprogramming/toc.md) we create two methods. +Following the rules in [Macros](../metaprogramming.html) we create two methods. One that hosts the top-level splice `eqv` and one that is the implementation. Alternatively and what is shown below is that we can call the `eqv` method directly. The `eqGen` can trigger the derivation. diff --git a/docs/docs/reference/contextual/derivation.md b/docs/docs/reference/contextual/derivation.md index 0a4a6b30968c..d7ec09c3705c 100644 --- a/docs/docs/reference/contextual/derivation.md +++ b/docs/docs/reference/contextual/derivation.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Type Class Derivation" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/derivation.html +type: section +num: 21 +previous-page: /scala3/reference/contextual/type-classes +next-page: /scala3/reference/contextual/multiversal-equality --- Type class derivation is a way to automatically generate given instances for type classes which satisfy some simple @@ -336,7 +338,7 @@ inline def derived[A](using gen: K0.Generic[A]): Eq[A] = The framework described here enables all three of these approaches without mandating any of them. For a brief discussion on how to use macros to write a type class `derived` -method please read more at [How to write a type class `derived` method using macros](./derivation-macro.md). +method please read more at [How to write a type class `derived` method using macros](./derivation-macro.html). ### Deriving instances elsewhere @@ -354,7 +356,7 @@ hand side of this definition in the same way as an instance defined in ADT compa ### Syntax -```ebnf +``` Template ::= InheritClauses [TemplateBody] EnumDef ::= id ClassConstr InheritClauses EnumBody InheritClauses ::= [‘extends’ ConstrApps] [‘derives’ QualId {‘,’ QualId}] diff --git a/docs/docs/reference/contextual/extension-methods.md b/docs/docs/reference/contextual/extension-methods.md index 46300ac1079f..06364baa507f 100644 --- a/docs/docs/reference/contextual/extension-methods.md +++ b/docs/docs/reference/contextual/extension-methods.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Extension Methods" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html +type: section +num: 19 +previous-page: /scala3/reference/contextual/given-imports +next-page: /scala3/reference/contextual/type-classes --- Extension methods allow one to add methods to a type after the type is defined. Example: @@ -61,7 +63,7 @@ the right-associative operator `+:` to an extension method. This is analogous to the implementation of right binding operators as normal methods. The Scala compiler preprocesses an infix operation `x +: xs` to `xs.+:(x)`, so the extension method ends up being applied to the sequence as first argument (in other words, the -two swaps cancel each other out). See [here for details](./right-associative-extension-methods.md). +two swaps cancel each other out). See [here for details](./right-associative-extension-methods.html). ### Generic Extensions @@ -283,9 +285,9 @@ def position(s: String)(ch: Char, n: Int): Int = ### Syntax Here are the syntax changes for extension methods and collective extensions relative -to the [current syntax](../syntax.md). +to the [current syntax](../syntax.html). -```ebnf +``` BlockStat ::= ... | Extension TemplateStat ::= ... | Extension TopStat ::= ... | Extension diff --git a/docs/docs/reference/contextual/given-imports.md b/docs/docs/reference/contextual/given-imports.md index 3e3bc3d275cc..7e498415888e 100644 --- a/docs/docs/reference/contextual/given-imports.md +++ b/docs/docs/reference/contextual/given-imports.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Importing Givens" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/given-imports.html +type: section +num: 18 +previous-page: /scala3/reference/contextual/context-bounds +next-page: /scala3/reference/contextual/extension-methods --- A special form of import wildcard selector is used to import given instances. Example: diff --git a/docs/docs/reference/contextual/givens.md b/docs/docs/reference/contextual/givens.md index fba3effdd495..0ca25c068c93 100644 --- a/docs/docs/reference/contextual/givens.md +++ b/docs/docs/reference/contextual/givens.md @@ -1,11 +1,13 @@ --- -layout: doc-page title: "Given Instances" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/givens.html +type: section +num: 15 +previous-page: /scala3/reference/contextual +next-page: /scala3/reference/contextual/using-clauses --- Given instances (or, simply, "givens") define "canonical" values of certain types -that serve for synthesizing arguments to [context parameters](./using-clauses.md). Example: +that serve for synthesizing arguments to [context parameters](./using-clauses.html). Example: ```scala trait Ord[T]: @@ -34,7 +36,7 @@ a given for the type `Ord[Int]` whereas `listOrd[T]` defines givens for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]` themselves. The `using` clause in `listOrd` defines a condition: There must be a given of type `Ord[T]` for a given of type `Ord[List[T]]` to exist. -Such conditions are expanded by the compiler to [context parameters](./using-clauses.md). +Such conditions are expanded by the compiler to [context parameters](./using-clauses.html). ## Anonymous Givens @@ -151,7 +153,7 @@ is created for each reference. Here is the syntax for given instances: -```ebnf +``` TmplDef ::= ... | ‘given’ GivenDef GivenDef ::= [GivenSig] StructuralInstance diff --git a/docs/docs/reference/contextual/motivation.md b/docs/docs/reference/contextual/motivation.md deleted file mode 100644 index 9a72ed5d1a5b..000000000000 --- a/docs/docs/reference/contextual/motivation.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -layout: doc-page -title: "Overview" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual.html ---- - -### Critique of the Status Quo - -Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them. - -Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g [Rust's traits](https://doc.rust-lang.org/rust-by-example/trait.html) or [Swift's protocol extensions](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID521). Design proposals are also on the table for Kotlin as [compile time dependency resolution](https://github.com/Kotlin/KEEP/blob/e863b25f8b3f2e9b9aaac361c6ee52be31453ee0/proposals/compile-time-dependency-resolution.md), for C# as [Shapes and Extensions](https://github.com/dotnet/csharplang/issues/164) -or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as [Coq](https://coq.inria.fr/refman/language/extensions/implicit-arguments.html) or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html). - -Even though these designs use widely different terminology, they are all variants of the core idea of _term inference_. Given a type, the compiler synthesizes a "canonical" term that has that type. Scala embodies the idea in a purer form than most other languages: An implicit parameter directly leads to an inferred argument term that could also be written down explicitly. By contrast, type class based designs are less direct since they hide term inference behind some form of type classification and do not offer the option of writing the inferred quantities (typically, dictionaries) explicitly. - -Given that term inference is where the industry is heading, and given that Scala has it in a very pure form, how come implicits are not more popular? In fact, it's fair to say that implicits are at the same time Scala's most distinguished and most controversial feature. I believe this is due to a number of aspects that together make implicits harder to learn than necessary and also make it harder to prevent abuses. - -Particular criticisms are: - -1. Being very powerful, implicits are easily over-used and mis-used. This observation holds in almost all cases when we talk about _implicit conversions_, which, even though conceptually different, share the same syntax with other implicit definitions. For instance, regarding the two definitions - - ```scala - implicit def i1(implicit x: T): C[T] = ... - implicit def i2(x: T): C[T] = ... - ``` - - the first of these is a conditional implicit _value_, the second an implicit _conversion_. Conditional implicit values are a cornerstone for expressing type classes, whereas most applications of implicit conversions have turned out to be of dubious value. The problem is that many newcomers to the language start with defining implicit conversions since they are easy to understand and seem powerful and convenient. Scala 3 will put under a language flag both definitions and applications of "undisciplined" implicit conversions between types defined elsewhere. This is a useful step to push back against overuse of implicit conversions. But the problem remains that syntactically, conversions and values just look too similar for comfort. - - 2. Another widespread abuse is over-reliance on implicit imports. This often leads to inscrutable type errors that go away with the right import incantation, leaving a feeling of frustration. Conversely, it is hard to see what implicits a program uses since implicits can hide anywhere in a long list of imports. - - 3. The syntax of implicit definitions is too minimal. It consists of a single modifier, `implicit`, that can be attached to a large number of language constructs. A problem with this for newcomers is that it conveys mechanism instead of intent. For instance, a type class instance is an implicit object or val if unconditional and an implicit def with implicit parameters referring to some class if conditional. This describes precisely what the implicit definitions translate to -- just drop the `implicit` modifier, and that's it! But the cues that define intent are rather indirect and can be easily misread, as demonstrated by the definitions of `i1` and `i2` above. - - 4. The syntax of implicit parameters also has shortcomings. While implicit _parameters_ are designated specifically, arguments are not. Passing an argument to an implicit parameter looks like a regular application `f(arg)`. This is problematic because it means there can be confusion regarding what parameter gets instantiated in a call. For instance, in - - ```scala - def currentMap(implicit ctx: Context): Map[String, Int] - ``` - - 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 tools like [Scaladoc](https://docs.scala-lang.org/overviews/scaladoc/overview.html) that are based on 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. - -Historically, many of these shortcomings come from the way implicits were gradually "discovered" in Scala. Scala originally had only implicit conversions with the intended use case of "extending" a class or trait after it was defined, i.e. what is expressed by implicit classes in later versions of Scala. Implicit parameters and instance definitions came later in 2006 and we picked similar syntax since it seemed convenient. For the same reason, no effort was made to distinguish implicit imports or arguments from normal ones. - -Existing Scala programmers by and large have gotten used to the status quo and see little need for change. But for newcomers this status quo presents a big hurdle. I believe if we want to overcome that hurdle, we should take a step back and allow ourselves to consider a radically new design. - -### The New Design - -The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes: - - 1. [Given Instances](./givens.md) are a new way to define basic terms that can be synthesized. They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types. - - 2. [Using Clauses](./using-clauses.md) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition. - - 3. ["Given" Imports](./given-imports.md) are a new class of import selectors that specifically import - givens and nothing else. - - 4. [Implicit Conversions](./conversions.md) are now expressed as given instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out. - -This section also contains pages describing other language features that are related to context abstraction. These are: - - - [Context Bounds](./context-bounds.md), which carry over unchanged. - - [Extension Methods](./extension-methods.md) replace implicit classes in a way that integrates better with type classes. - - [Implementing Type Classes](type-classes.md) demonstrates how some common type classes can be implemented using the new constructs. - - [Type Class Derivation](./derivation.md) introduces constructs to automatically derive type class instances for ADTs. - - [Multiversal Equality](./multiversal-equality.md) introduces a special type class to support type safe equality. - - [Context Functions](./context-functions.md) provide a way to abstract over context parameters. - - [By-Name Context Parameters](./by-name-context-parameters.md) are an essential tool to define recursive synthesized values without looping. - - [Relationship with Scala 2 Implicits](./relationship-implicits.md) discusses the relationship between old-style implicits and new-style givens and how to migrate from one to the other. - -Overall, the new design achieves a better separation of term inference from the rest of the language: There is a single way to define givens instead of a multitude of forms all taking an `implicit` modifier. There is a single way to introduce implicit parameters and arguments instead of conflating implicit with normal arguments. There is a separate way to import givens that does not allow them to hide in a sea of normal imports. And there is a single way to define an implicit conversion which is clearly marked as such and does not require special syntax. - -This design thus avoids feature interactions and makes the language more consistent and orthogonal. It will make implicits easier to learn and harder to abuse. It will greatly improve the clarity of the 95% of Scala programs that use implicits. It has thus the potential to fulfil the promise of term inference in a principled way that is also accessible and friendly. - -Could we achieve the same goals by tweaking existing implicits? After having tried for a long time, I believe now that this is impossible. - - - First, some of the problems are clearly syntactic and require different syntax to solve them. - - Second, there is the problem how to migrate. We cannot change the rules in mid-flight. At some stage of language evolution we need to accommodate both the new and the old rules. With a syntax change, this is easy: Introduce the new syntax with new rules, support the old syntax for a while to facilitate cross compilation, deprecate and phase out the old syntax at some later time. Keeping the same syntax does not offer this path, and in fact does not seem to offer any viable path for evolution - - 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. diff --git a/docs/docs/reference/contextual/multiversal-equality.md b/docs/docs/reference/contextual/multiversal-equality.md index 1af1786374bc..19b44c654494 100644 --- a/docs/docs/reference/contextual/multiversal-equality.md +++ b/docs/docs/reference/contextual/multiversal-equality.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Multiversal Equality" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/multiversal-equality.html +type: section +num: 22 +previous-page: /scala3/reference/contextual/derivation +next-page: /scala3/reference/contextual/context-functions --- Previously, Scala had universal equality: Two values of any types @@ -104,7 +106,7 @@ Instead of defining `CanEqual` instances directly, it is often more convenient t class Box[T](x: T) derives CanEqual ``` -By the usual rules of [type class derivation](./derivation.md), +By the usual rules of [type class derivation](./derivation.html), this generates the following `CanEqual` instance in the companion object of `Box`: ```scala diff --git a/docs/docs/reference/contextual/relationship-implicits.md b/docs/docs/reference/contextual/relationship-implicits.md index 4a23e781bd70..9be698affdd8 100644 --- a/docs/docs/reference/contextual/relationship-implicits.md +++ b/docs/docs/reference/contextual/relationship-implicits.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Relationship with Scala 2 Implicits" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/relationship-implicits.html +type: section +num: 26 +previous-page: /scala3/reference/contextual/by-name-context-parameters +next-page: /scala3/reference/metaprogramming --- Many, but not all, of the new contextual abstraction features in Scala 3 can be mapped to Scala 2's implicits. This page gives a rundown on the relationships between new and old features. diff --git a/docs/docs/reference/contextual/right-associative-extension-methods.md b/docs/docs/reference/contextual/right-associative-extension-methods.md index 7c2cf6b02675..b77e6dccdd78 100644 --- a/docs/docs/reference/contextual/right-associative-extension-methods.md +++ b/docs/docs/reference/contextual/right-associative-extension-methods.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Right-Associative Extension Methods: Details" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/right-associative-extension-methods.html --- The most general form of leading parameters of an extension method is as follows: diff --git a/docs/docs/reference/contextual/type-classes.md b/docs/docs/reference/contextual/type-classes.md index c4648b3baf28..4c80e7b53b14 100644 --- a/docs/docs/reference/contextual/type-classes.md +++ b/docs/docs/reference/contextual/type-classes.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Implementing Type classes" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/type-classes.html +type: section +num: 20 +previous-page: /scala3/reference/contextual/extension-methods +next-page: /scala3/reference/contextual/derivation --- A _type class_ is an abstract, parameterized type that lets you add new behavior to any closed data type without using sub-typing. This can be useful in multiple use-cases, for example: @@ -98,7 +100,7 @@ assertTransformation(List("a1", "b1"), List("a", "b"), elt => s"${elt}1") ``` That's a first step, but in practice we probably would like the `map` function to be a method directly accessible on the type `F`. So that we can call `map` directly on instances of `F`, and get rid of the `summon[Functor[F]]` part. -As in the previous example of Monoids, [`extension` methods](extension-methods.md) help achieving that. Let's re-define the `Functor` type class with extension methods. +As in the previous example of Monoids, [`extension` methods](extension-methods.html) help achieving that. Let's re-define the `Functor` type class with extension methods. ```scala trait Functor[F[_]]: @@ -235,7 +237,7 @@ given configDependentMonad: Monad[ConfigDependent] with end configDependentMonad ``` -The type `ConfigDependent` can be written using [type lambdas](../new-types/type-lambdas.md): +The type `ConfigDependent` can be written using [type lambdas](../new-types/type-lambdas.html): ```scala type ConfigDependent = [Result] =>> Config => Result diff --git a/docs/docs/reference/contextual/using-clauses.md b/docs/docs/reference/contextual/using-clauses.md index e8a077ccdc0a..4f98c760ffef 100644 --- a/docs/docs/reference/contextual/using-clauses.md +++ b/docs/docs/reference/contextual/using-clauses.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Using Clauses" -movedTo: https://docs.scala-lang.org/scala3/reference/contextual/using-clauses.html +type: section +num: 16 +previous-page: /scala3/reference/contextual/givens +next-page: /scala3/reference/contextual/context-bounds --- Functional programming tends to express most dependencies as simple function parameterization. @@ -9,7 +11,7 @@ This is clean and powerful, but it sometimes leads to functions that take many p functions. Context parameters can help here since they enable the compiler to synthesize repetitive arguments instead of the programmer having to write them explicitly. -For example, with the [given instances](./givens.md) defined previously, +For example, with the [given instances](./givens.html) defined previously, a `max` function that works for any arguments for which an ordering exists can be defined as follows: ```scala @@ -64,7 +66,7 @@ class GivenIntBox2(using givenInt: Int): //def n = summon[Int] // ambiguous ``` -The `given` member is importable as explained in the section on [importing `given`s](./given-imports.md): +The `given` member is importable as explained in the section on [importing `given`s](./given-imports.html): ```scala val b = GivenIntBox(using 23) @@ -142,7 +144,7 @@ def summon[T](using x: T): x.type = x ## Syntax -Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](../syntax.md). `using` is a soft keyword, recognized only at the start of a parameter or argument list. It can be used as a normal identifier everywhere else. +Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](../syntax.html). `using` is a soft keyword, recognized only at the start of a parameter or argument list. It can be used as a normal identifier everywhere else. ``` ClsParamClause ::= ... | UsingClsParamClause diff --git a/docs/docs/reference/dropped-features.md b/docs/docs/reference/dropped-features.md new file mode 100644 index 000000000000..fdffc6954293 --- /dev/null +++ b/docs/docs/reference/dropped-features.md @@ -0,0 +1,9 @@ +--- +title: Dropped Features +type: chapter +num: 70 +previous-page: /scala3/reference/changed-features/main-functions +next-page: /scala3/reference/dropped-features/delayed-init +--- + +The following pages document the features of Scala 2 that have been dropped in Scala 3. diff --git a/docs/docs/reference/dropped-features/auto-apply.md b/docs/docs/reference/dropped-features/auto-apply.md index c5424ffff22d..8670850f7903 100644 --- a/docs/docs/reference/dropped-features/auto-apply.md +++ b/docs/docs/reference/dropped-features/auto-apply.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Auto-Application" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/auto-apply.html +type: section +num: 83 +previous-page: /scala3/reference/dropped-features/symlits +next-page: /scala3/reference/dropped-features/weak-conformance --- Previously an empty argument list `()` was implicitly inserted when diff --git a/docs/docs/reference/dropped-features/class-shadowing-spec.md b/docs/docs/reference/dropped-features/class-shadowing-spec.md index 98acff828cd3..d1d5d4b34bb4 100644 --- a/docs/docs/reference/dropped-features/class-shadowing-spec.md +++ b/docs/docs/reference/dropped-features/class-shadowing-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Dropped: Class Shadowing - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/class-shadowing-spec.html --- Spec diff: in section [5.1.4 Overriding](https://www.scala-lang.org/files/archive/spec/2.13/05-classes-and-objects.html#Overriding), add *M' must not be a class*. diff --git a/docs/docs/reference/dropped-features/class-shadowing.md b/docs/docs/reference/dropped-features/class-shadowing.md index 839b40253169..b3a4ab2dc1ad 100644 --- a/docs/docs/reference/dropped-features/class-shadowing.md +++ b/docs/docs/reference/dropped-features/class-shadowing.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Class Shadowing" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/class-shadowing.html +type: section +num: 79 +previous-page: /scala3/reference/dropped-features/early-initializers +next-page: /scala3/reference/dropped-features/limit22 --- Scala 2 so far allowed patterns like this: @@ -30,4 +32,4 @@ other, but classes in Scala 2 cannot be overridden. To keep things clean (and its internal operations consistent) the Scala 3 compiler forces you to rename the inner classes so that their names are different. -[More details](./class-shadowing-spec.md) +[More details](./class-shadowing-spec.html) diff --git a/docs/docs/reference/dropped-features/delayed-init.md b/docs/docs/reference/dropped-features/delayed-init.md index 875ccec5132e..5673db5dfb8e 100644 --- a/docs/docs/reference/dropped-features/delayed-init.md +++ b/docs/docs/reference/dropped-features/delayed-init.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: DelayedInit" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/delayed-init.html +type: section +num: 71 +previous-page: /scala3/reference/dropped-features +next-page: /scala3/reference/dropped-features/macros --- The special handling of the `DelayedInit` trait is no longer supported. @@ -27,4 +29,4 @@ object Hello: ``` On the other hand, Scala 3 offers a convenient alternative to such "program" objects -with [`@main` methods](../changed-features/main-functions.md). +with [`@main` methods](../changed-features/main-functions.html). diff --git a/docs/docs/reference/dropped-features/do-while.md b/docs/docs/reference/dropped-features/do-while.md index 5f5ca5feeea2..3fd59430ac3b 100644 --- a/docs/docs/reference/dropped-features/do-while.md +++ b/docs/docs/reference/dropped-features/do-while.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Do-While" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/do-while.html +type: section +num: 75 +previous-page: /scala3/reference/dropped-features/type-projection +next-page: /scala3/reference/dropped-features/procedure-syntax --- The syntax construct @@ -38,4 +40,4 @@ do print(".") ### Why Drop The Construct? - `do-while` is used relatively rarely and it can be expressed faithfully using just `while`. So there seems to be little point in having it as a separate syntax construct. - - Under the [new syntax rules](../other-new-features/control-syntax.md) `do` is used as a statement continuation, which would clash with its meaning as a statement introduction. + - Under the [new syntax rules](../other-new-features/control-syntax.html) `do` is used as a statement continuation, which would clash with its meaning as a statement introduction. diff --git a/docs/docs/reference/dropped-features/early-initializers.md b/docs/docs/reference/dropped-features/early-initializers.md index cb2ffea94376..18d97640b12f 100644 --- a/docs/docs/reference/dropped-features/early-initializers.md +++ b/docs/docs/reference/dropped-features/early-initializers.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Early Initializers" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/early-initializers.html +type: section +num: 78 +previous-page: /scala3/reference/dropped-features/package-objects +next-page: /scala3/reference/dropped-features/class-shadowing --- Early initializers of the form @@ -11,6 +13,6 @@ class C extends { ... } with SuperClass ... ``` have been dropped. They were rarely used, and mostly to compensate for the lack of -[trait parameters](../other-new-features/trait-parameters.md), which are now directly supported in Scala 3. +[trait parameters](../other-new-features/trait-parameters.html), which are now directly supported in Scala 3. For more information, see [SLS §5.1.6](https://www.scala-lang.org/files/archive/spec/2.13/05-classes-and-objects.html#early-definitions). diff --git a/docs/docs/reference/dropped-features/existential-types.md b/docs/docs/reference/dropped-features/existential-types.md index 4d7d9e2f8c10..df624cbd0721 100644 --- a/docs/docs/reference/dropped-features/existential-types.md +++ b/docs/docs/reference/dropped-features/existential-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Existential Types" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/existential-types.html +type: section +num: 73 +previous-page: /scala3/reference/dropped-features/macros +next-page: /scala3/reference/dropped-features/type-projection --- Existential types using `forSome` (as in diff --git a/docs/docs/reference/dropped-features/limit22.md b/docs/docs/reference/dropped-features/limit22.md index ffbf6eb196dc..2e21efec58f6 100644 --- a/docs/docs/reference/dropped-features/limit22.md +++ b/docs/docs/reference/dropped-features/limit22.md @@ -1,17 +1,19 @@ --- -layout: doc-page title: "Dropped: Limit 22" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/limit22.html +type: section +num: 80 +previous-page: /scala3/reference/dropped-features/class-shadowing +next-page: /scala3/reference/dropped-features/xml --- The limits of 22 for the maximal number of parameters of function types and the maximal number of fields in tuple types have been dropped. * Functions can now have an arbitrary number of parameters. Functions beyond - [`scala.Function22`](https://www.scala-lang.org/api/current/scala/Function22.html) are erased to a new trait [`scala.runtime.FunctionXXL`](https://dotty.epfl.ch/api/scala/runtime/FunctionXXL.html). + [`scala.Function22`](https://www.scala-lang.org/api/current/scala/Function22.html) are erased to a new trait [`scala.runtime.FunctionXXL`](https://scala-lang.org/api/3.x/scala/runtime/FunctionXXL.html). * Tuples can also have an arbitrary number of fields. Tuples beyond [`scala.Tuple22`](https://www.scala-lang.org/api/current/scala/Tuple22.html) - are erased to a new class [`scala.runtime.TupleXXL`](https://dotty.epfl.ch/api/scala/runtime/TupleXXL.html) (which extends the trait [`scala.Product`](https://dotty.epfl.ch/api/scala/Product.html)). Furthermore, they support generic + are erased to a new class [`scala.runtime.TupleXXL`](https://scala-lang.org/api/3.x/scala/runtime/TupleXXL.html) (which extends the trait [`scala.Product`](https://scala-lang.org/api/3.x/scala/Product.html)). Furthermore, they support generic operation such as concatenation and indexing. Both of these are implemented using arrays. diff --git a/docs/docs/reference/dropped-features/macros.md b/docs/docs/reference/dropped-features/macros.md index e71bf120fe13..f7a23edb0057 100644 --- a/docs/docs/reference/dropped-features/macros.md +++ b/docs/docs/reference/dropped-features/macros.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Scala 2 Macros" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/macros.html +type: section +num: 72 +previous-page: /scala3/reference/dropped-features/delayed-init +next-page: /scala3/reference/dropped-features/existential-types --- The previous, experimental macro system has been dropped. @@ -11,6 +13,6 @@ Instead, there is a cleaner, more restricted system based on two complementary c In this setting, a definition marked as inlined containing a `${ ... }` is a macro, the code inside the `${ ... }` is executed at compile-time and produces code in the form of `'{ ... }`. Additionally, the contents of code can be inspected and created with a more complex reflection API as an extension of `'{ ... }`/`${ ... }` framework. -* `inline` has been [implemented](../metaprogramming/inline.md) in Scala 3. -* Quotes `'{ ... }` and splices `${ ... }` has been [implemented](../metaprogramming/macros.md) in Scala 3. -* [TASTy reflect](../metaprogramming/reflection.md) provides more complex tree based APIs to inspect or create quoted code. +* `inline` has been [implemented](../metaprogramming/inline.html) in Scala 3. +* Quotes `'{ ... }` and splices `${ ... }` has been [implemented](../metaprogramming/macros.html) in Scala 3. +* [TASTy reflect](../metaprogramming/reflection.html) provides more complex tree based APIs to inspect or create quoted code. diff --git a/docs/docs/reference/dropped-features/nonlocal-returns.md b/docs/docs/reference/dropped-features/nonlocal-returns.md index 1b23485e6a00..89b244f122b4 100644 --- a/docs/docs/reference/dropped-features/nonlocal-returns.md +++ b/docs/docs/reference/dropped-features/nonlocal-returns.md @@ -1,14 +1,14 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Deprecated: Nonlocal Returns" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/nonlocal-returns.html --- Returning from nested anonymous functions has been deprecated. Nonlocal returns are implemented by throwing and catching `scala.runtime.NonLocalReturnException`-s. This is rarely what is intended by the programmer. It can be problematic because of the hidden performance cost of throwing and catching exceptions. Furthermore, it is a leaky implementation: a catch-all exception handler can intercept a `NonLocalReturnException`. -A drop-in library replacement is provided in [`scala.util.control.NonLocalReturns`](http://dotty.epfl.ch/api/scala/util/control/NonLocalReturns$.html). Example: +A drop-in library replacement is provided in [`scala.util.control.NonLocalReturns`](https://scala-lang.org/api/3.x/scala/util/control/NonLocalReturns$.html). Example: ```scala import scala.util.control.NonLocalReturns.* diff --git a/docs/docs/reference/dropped-features/package-objects.md b/docs/docs/reference/dropped-features/package-objects.md index 69a47b340cf0..35e21d56a23c 100644 --- a/docs/docs/reference/dropped-features/package-objects.md +++ b/docs/docs/reference/dropped-features/package-objects.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Package Objects" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/package-objects.html +type: section +num: 77 +previous-page: /scala3/reference/dropped-features/procedure-syntax +next-page: /scala3/reference/dropped-features/early-initializers --- Package objects diff --git a/docs/docs/reference/dropped-features/procedure-syntax.md b/docs/docs/reference/dropped-features/procedure-syntax.md index cc82636d370d..f3bf8cc9d47f 100644 --- a/docs/docs/reference/dropped-features/procedure-syntax.md +++ b/docs/docs/reference/dropped-features/procedure-syntax.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Procedure Syntax" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/procedure-syntax.html +type: section +num: 76 +previous-page: /scala3/reference/dropped-features/do-while +next-page: /scala3/reference/dropped-features/package-objects --- Procedure syntax diff --git a/docs/docs/reference/dropped-features/symlits.md b/docs/docs/reference/dropped-features/symlits.md index 33c3e6ee0c39..3cb7243af964 100644 --- a/docs/docs/reference/dropped-features/symlits.md +++ b/docs/docs/reference/dropped-features/symlits.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Symbol Literals" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/symlits.html +type: section +num: 82 +previous-page: /scala3/reference/dropped-features/xml +next-page: /scala3/reference/dropped-features/auto-apply --- Symbol literals are no longer supported. diff --git a/docs/docs/reference/dropped-features/this-qualifier.md b/docs/docs/reference/dropped-features/this-qualifier.md index 0017573be129..c25f896415f5 100644 --- a/docs/docs/reference/dropped-features/this-qualifier.md +++ b/docs/docs/reference/dropped-features/this-qualifier.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: private[this] and protected[this]" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/this-qualifier.html +type: section +num: 85 +previous-page: /scala3/reference/dropped-features/weak-conformance +next-page: /scala3/reference/dropped-features/wildcard-init --- The `private[this]` and `protected[this]` access modifiers are deprecated and will be phased out. diff --git a/docs/docs/reference/dropped-features/type-projection.md b/docs/docs/reference/dropped-features/type-projection.md index f45eff5c423f..fb87ef79be23 100644 --- a/docs/docs/reference/dropped-features/type-projection.md +++ b/docs/docs/reference/dropped-features/type-projection.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: General Type Projection" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/type-projection.html +type: section +num: 74 +previous-page: /scala3/reference/dropped-features/existential-types +next-page: /scala3/reference/dropped-features/do-while --- Scala so far allowed general type projection `T#A` where `T` is an arbitrary type diff --git a/docs/docs/reference/dropped-features/weak-conformance-spec.md b/docs/docs/reference/dropped-features/weak-conformance-spec.md index 1432782a8e38..147298f5573a 100644 --- a/docs/docs/reference/dropped-features/weak-conformance-spec.md +++ b/docs/docs/reference/dropped-features/weak-conformance-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Dropped: Weak Conformance - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/weak-conformance-spec.html --- To simplify the underlying type theory, Scala 3 drops the notion of diff --git a/docs/docs/reference/dropped-features/weak-conformance.md b/docs/docs/reference/dropped-features/weak-conformance.md index c2dabe39e7c7..deca70b60714 100644 --- a/docs/docs/reference/dropped-features/weak-conformance.md +++ b/docs/docs/reference/dropped-features/weak-conformance.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Weak Conformance" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/weak-conformance.html +type: section +num: 84 +previous-page: /scala3/reference/dropped-features/auto-apply +next-page: /scala3/reference/dropped-features/this-qualifier --- In some situations, Scala used a _weak conformance_ relation when @@ -44,4 +46,4 @@ Therefore, Scala 3 drops the general notion of weak conformance, and instead keeps one rule: `Int` literals are adapted to other numeric types if necessary. -[More details](weak-conformance-spec.md) +[More details](weak-conformance-spec.html) diff --git a/docs/docs/reference/dropped-features/wildcard-init.md b/docs/docs/reference/dropped-features/wildcard-init.md index c4b89674b11d..be633fb1ca21 100644 --- a/docs/docs/reference/dropped-features/wildcard-init.md +++ b/docs/docs/reference/dropped-features/wildcard-init.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: Wildcard Initializer" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/wildcard-init.html +type: section +num: 86 +previous-page: /scala3/reference/dropped-features/this-qualifier +next-page: /scala3/reference/syntax --- The syntax diff --git a/docs/docs/reference/dropped-features/xml.md b/docs/docs/reference/dropped-features/xml.md index 9de06ca30f2e..cab3d0663a55 100644 --- a/docs/docs/reference/dropped-features/xml.md +++ b/docs/docs/reference/dropped-features/xml.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dropped: XML Literals" -movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/xml.html +type: section +num: 81 +previous-page: /scala3/reference/dropped-features/limit22 +next-page: /scala3/reference/dropped-features/symlits --- XML Literals are still supported, but will be dropped in the near future, to diff --git a/docs/docs/reference/enums.md b/docs/docs/reference/enums.md new file mode 100644 index 000000000000..e8c63c237704 --- /dev/null +++ b/docs/docs/reference/enums.md @@ -0,0 +1,9 @@ +--- +title: "Enums" +type: chapter +num: 9 +previous-page: /scala3/reference/new-types/polymorphic-function-types +next-page: /scala3/reference/enums/enums +--- + +This chapter documents enums in Scala 3. diff --git a/docs/docs/reference/enums/adts.md b/docs/docs/reference/enums/adts.md index 927b5fcf2ca4..10558707b543 100644 --- a/docs/docs/reference/enums/adts.md +++ b/docs/docs/reference/enums/adts.md @@ -1,10 +1,12 @@ --- -layout: doc-page title: "Algebraic Data Types" -movedTo: https://docs.scala-lang.org/scala3/reference/enums/adts.html +type: section +num: 11 +previous-page: /scala3/reference/enums/enums +next-page: /scala3/reference/enums/desugarEnums --- -The [`enum` concept](./enums.md) is general enough to also support algebraic data +The [`enum` concept](./enums.html) is general enough to also support algebraic data types (ADTs) and their generalized version (GADTs). Here is an example how an `Option` type can be represented as an ADT: @@ -150,11 +152,11 @@ enum View[-T, +U] extends (T => U): ### Syntax of Enums Changes to the syntax fall in two categories: enum definitions and cases inside enums. -The changes are specified below as deltas with respect to the Scala syntax given [here](../syntax.md) +The changes are specified below as deltas with respect to the Scala syntax given [here](../syntax.html) 1. Enum definitions are defined as follows: - ```ebnf + ``` TmplDef ::= `enum' EnumDef EnumDef ::= id ClassConstr [`extends' [ConstrApps]] EnumBody EnumBody ::= [nl] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’ @@ -164,7 +166,7 @@ The changes are specified below as deltas with respect to the Scala syntax given 2. Cases of enums are defined as follows: - ```ebnf + ``` EnumCase ::= `case' (id ClassConstr [`extends' ConstrApps]] | ids) ``` diff --git a/docs/docs/reference/enums/desugarEnums.md b/docs/docs/reference/enums/desugarEnums.md index 95df1a7513ce..efcc41d5b2f6 100644 --- a/docs/docs/reference/enums/desugarEnums.md +++ b/docs/docs/reference/enums/desugarEnums.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Translation of Enums and ADTs" -movedTo: https://docs.scala-lang.org/scala3/reference/enums/desugarEnums.html +type: section +num: 12 +previous-page: /scala3/reference/enums/adts +next-page: /scala3/reference/contextual --- The compiler expands enums and their cases to code that only uses @@ -155,7 +157,7 @@ map into `case class`es or `val`s. case C(ps) extends P1, ..., Pn ``` are treated specially. A call `C(ts)` of the apply method is ascribed the underlying type - `P1 & ... & Pn` (dropping any [transparent traits](../other-new-features/transparent-traits.md)) + `P1 & ... & Pn` (dropping any [transparent traits](../other-new-features/transparent-traits.html)) as long as that type is still compatible with the expected type at the point of application. A call `t.copy(ts)` of `C`'s `copy` method is treated in the same way. diff --git a/docs/docs/reference/enums/enums.md b/docs/docs/reference/enums/enums.md index e68f54fa0dd1..96d11e874212 100644 --- a/docs/docs/reference/enums/enums.md +++ b/docs/docs/reference/enums/enums.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Enumerations" -movedTo: https://docs.scala-lang.org/scala3/reference/enums/enums.html +type: section +num: 10 +previous-page: /scala3/reference/enums +next-page: /scala3/reference/enums/adts --- An enumeration is used to define a type consisting of a set of named values. @@ -131,7 +133,7 @@ object Planet { } ``` -We could imagine that a library may use [type class derivation](../contextual/derivation.md) to automatically provide an instance for `Deprecations`. +We could imagine that a library may use [type class derivation](../contextual/derivation.html) to automatically provide an instance for `Deprecations`. ### Compatibility with Java Enums diff --git a/docs/docs/reference/experimental/canthrow.md b/docs/docs/reference/experimental/canthrow.md index 989d766a4e1e..88fa77d785a4 100644 --- a/docs/docs/reference/experimental/canthrow.md +++ b/docs/docs/reference/experimental/canthrow.md @@ -1,6 +1,7 @@ --- -layout: doc-page -title: CanThrow Capabilities +layout: singlepage-overview +scala3: true +title: CanThrow Abilities author: Martin Odersky --- @@ -60,7 +61,7 @@ In the _effects as capabilities_ model, an effect is expressed as an (implicit) ```scala erased class CanThrow[-E <: Exception] ``` -This shows another experimental Scala feature: [erased definitions](./erased-defs). Roughly speaking, values of an erased class do not generate runtime code; they are erased before code generation. This means that all `CanThrow` capabilities are compile-time only artifacts; they do not have a runtime footprint. +This shows another experimental Scala feature: [erased definitions]({% link _scala3-reference/experimental/erased-defs.md %}). Roughly speaking, values of an erased class do not generate runtime code; they are erased before code generation. This means that all `CanThrow` capabilities are compile-time only artifacts; they do not have a runtime footprint. Now, if the compiler sees a `throw Exc()` construct where `Exc` is a checked exception, it will check that there is a capability of type `CanThrow[Exc]` that can be summoned as a given. It's a compile-time error if that's not the case. diff --git a/docs/docs/reference/experimental/erased-defs-spec.md b/docs/docs/reference/experimental/erased-defs-spec.md index ed8490f7e30e..7905e4776fed 100644 --- a/docs/docs/reference/experimental/erased-defs-spec.md +++ b/docs/docs/reference/experimental/erased-defs-spec.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Erased Definitions: More Details" --- diff --git a/docs/docs/reference/experimental/erased-defs.md b/docs/docs/reference/experimental/erased-defs.md index fa39f6df59dc..47d25583b34c 100644 --- a/docs/docs/reference/experimental/erased-defs.md +++ b/docs/docs/reference/experimental/erased-defs.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Erased Definitions" --- @@ -160,7 +161,7 @@ object Machine: // State must be Off ``` -Note that in [Inline](../metaprogramming/inline.md) we discussed `erasedValue` and inline +Note that in [Inline](../metaprogramming/inline.html) we discussed `erasedValue` and inline matches. `erasedValue` is implemented with `erased`, so the state machine above can be encoded as follows: @@ -227,4 +228,4 @@ val err: Any = CanRead() // error: illegal reference to erased class CanRead ``` Here, the type of `err` is `Any`, so `err` is not considered erased. Yet its initializing value is a reference to the erased class `CanRead`. -[More Details](./erased-defs-spec.md) +[More Details](./erased-defs-spec.html) diff --git a/docs/docs/reference/experimental/named-typeargs-spec.md b/docs/docs/reference/experimental/named-typeargs-spec.md index 404f96852aca..ddd808559825 100644 --- a/docs/docs/reference/experimental/named-typeargs-spec.md +++ b/docs/docs/reference/experimental/named-typeargs-spec.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Named Type Arguments - More Details" --- diff --git a/docs/docs/reference/features-classification.md b/docs/docs/reference/features-classification.md index 6196394b572a..528b2ffccd70 100644 --- a/docs/docs/reference/features-classification.md +++ b/docs/docs/reference/features-classification.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "A Classification of Proposed Language Features" date: April 6, 2019 author: Martin Odersky @@ -16,11 +17,11 @@ The current document reflects the state of things as of April, 2019. It will be These new constructs directly model core features of [DOT](https://www.scala-lang.org/blog/2016/02/03/essence-of-scala.html), higher-kinded types, and the [SI calculus for implicit resolution](https://infoscience.epfl.ch/record/229878/files/simplicitly_1.pdf). - - [Intersection types](new-types/intersection-types.md), replacing compound types, - - [Union types](new-types/union-types.md), - - [Type lambdas](new-types/type-lambdas.md), + - [Intersection types](new-types/intersection-types.html), replacing compound types, + - [Union types](new-types/union-types.html), + - [Type lambdas](new-types/type-lambdas.html), replacing encodings using structural types and type projection. - - [Context functions](contextual/context-functions.md) offering abstraction over given parameters. + - [Context functions](contextual/context-functions.html) offering abstraction over given parameters. **Status: essential** @@ -34,19 +35,19 @@ Since these are additions, there's generally no migration cost for old code. An These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style. - - [Trait parameters](other-new-features/trait-parameters.md) replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct. - - [Given instances](contextual/givens.md) + - [Trait parameters](other-new-features/trait-parameters.html) replace [early initializers](dropped-features/early-initializers.html) with a more generally useful construct. + - [Given instances](contextual/givens.html) replace implicit objects and defs, focussing on intent over mechanism. - - [Using clauses](contextual/using-clauses.md) replace implicit parameters, avoiding their ambiguities. - - [Extension methods](contextual/extension-methods.md) replace implicit classes with a clearer and simpler mechanism. - - [Opaque type aliases](other-new-features/opaques.md) replace most uses + - [Using clauses](contextual/using-clauses.html) replace implicit parameters, avoiding their ambiguities. + - [Extension methods](contextual/extension-methods.html) replace implicit classes with a clearer and simpler mechanism. + - [Opaque type aliases](other-new-features/opaques.html) replace most uses of value classes while guaranteeing absence of boxing. - - [Top-level definitions](dropped-features/package-objects.md) replace package objects, dropping syntactic boilerplate. - - [Export clauses](other-new-features/export.md) + - [Top-level definitions](dropped-features/package-objects.html) replace package objects, dropping syntactic boilerplate. + - [Export clauses](other-new-features/export.html) provide a simple and general way to express aggregation, which can replace the previous facade pattern of package objects inheriting from classes. - - [Vararg splices](changed-features/vararg-splices.md) now use the form `*` instead of `@ _*`, mirroring vararg expressions, - - [Creator applications](other-new-features/creator-applications.md) allow using simple function call syntax + - [Vararg splices](changed-features/vararg-splices.html) now use the form `*` instead of `@ _*`, mirroring vararg expressions, + - [Creator applications](other-new-features/creator-applications.html) allow using simple function call syntax instead of `new` expressions. `new` expressions stay around as a fallback for the cases where creator applications cannot be used. @@ -69,10 +70,10 @@ For the next several versions, old features will remain available and deprecatio These constructs are restricted to make the language safer. - - [Implicit Conversions](contextual/conversions.md): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import. - - [Given Imports](contextual/given-imports.md): implicits now require a special form of import, to make the import clearly visible. - - [Type Projection](dropped-features/type-projection.md): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound. - - [Multiversal equality](contextual/multiversal-equality.md) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`. + - [Implicit Conversions](contextual/conversions.html): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import. + - [Given Imports](contextual/given-imports.html): implicits now require a special form of import, to make the import clearly visible. + - [Type Projection](dropped-features/type-projection.html): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound. + - [Multiversal equality](contextual/multiversal-equality.html) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`. - [infix](https://github.com/lampepfl/dotty/pull/5975) makes method application syntax uniform across code bases. @@ -92,15 +93,15 @@ These are essential restrictions. If we decide to adopt them, we should do it fo These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation. - - [DelayedInit](dropped-features/delayed-init.md), - - [Existential types](dropped-features/existential-types.md), - - [Procedure syntax](dropped-features/procedure-syntax.md), - - [Class shadowing](dropped-features/class-shadowing.md), - - [XML literals](dropped-features/xml.md), - - [Symbol literals](dropped-features/symlits.md), - - [Auto application](dropped-features/auto-apply.md), - - [Weak conformance](dropped-features/weak-conformance.md), - - [Compound types](new-types/intersection-types.md), + - [DelayedInit](dropped-features/delayed-init.html), + - [Existential types](dropped-features/existential-types.html), + - [Procedure syntax](dropped-features/procedure-syntax.html), + - [Class shadowing](dropped-features/class-shadowing.html), + - [XML literals](dropped-features/xml.html), + - [Symbol literals](dropped-features/symlits.html), + - [Auto application](dropped-features/auto-apply.html), + - [Weak conformance](dropped-features/weak-conformance.html), + - [Compound types](new-types/intersection-types.html), - [Auto tupling](https://github.com/lampepfl/dotty/pull/4311) (implemented, but not merged). The date when these constructs are dropped varies. The current status is: @@ -127,10 +128,10 @@ and sometimes need to be manual (e.g. class shadowing, auto tupling). Sometimes These constructs have undergone changes to make them more regular and useful. - - [Structural Types](changed-features/structural-types.md): They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo. - - [Name-based pattern matching](changed-features/pattern-matching.md): The existing undocumented Scala 2 implementation has been codified in a slightly simplified form. - - [Eta expansion](changed-features/eta-expansion.md) is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0. - - [Implicit Resolution](changed-features/implicit-resolution.md): The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes. + - [Structural Types](changed-features/structural-types.html): They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo. + - [Name-based pattern matching](changed-features/pattern-matching.html): The existing undocumented Scala 2 implementation has been codified in a slightly simplified form. + - [Eta expansion](changed-features/eta-expansion.html) is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0. + - [Implicit Resolution](changed-features/implicit-resolution.html): The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes. Most aspects of old-style implicit resolution are still available under `-source 3.0-migration`. The other changes in this list are applied unconditionally. @@ -146,11 +147,11 @@ Only a few programs should require changes, but some necessary changes might be These are additions to the language that make it more powerful or pleasant to use. - - [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md). - - [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring. - - [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types. + - [Enums](enums/enums.html) provide concise syntax for enumerations and [algebraic data types](enums/adts.html). + - [Parameter untupling](other-new-features/parameter-untupling.html) avoids having to use `case` for tupled parameter destructuring. + - [Dependent function types](new-types/dependent-function-types.html) generalize dependent methods to dependent function values and types. - [Polymorphic function types](https://github.com/lampepfl/dotty/pull/4672) generalize polymorphic methods to dependent function values and types. _Current status_: There is a proposal, and a prototype implementation, but the implementation has not been finalized or merged yet. - - [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors. + - [Kind polymorphism](other-new-features/kind-polymorphism.html) allows the definition of operators working equally on types and type constructors. **Status: mixed** @@ -168,12 +169,12 @@ It's worth noting that macros were never included in the [Scala 2 language speci To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority. -- [Match types](new-types/match-types.md) allow computation on types. -- [Inline](metaprogramming/inline.md) provides +- [Match types](new-types/match-types.html) allow computation on types. +- [Inline](metaprogramming/inline.html) provides by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros. -- [Quotes and splices](metaprogramming/macros.md) provide a principled way to express macros and staging with a unified set of abstractions. -- [Type class derivation](contextual/derivation.md) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro. -- [Implicit by-name parameters](contextual/by-name-context-parameters.md) provide a more robust in-language implementation of the `Lazy` macro in Shapeless. +- [Quotes and splices](metaprogramming/macros.html) provide a principled way to express macros and staging with a unified set of abstractions. +- [Type class derivation](contextual/derivation.html) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro. +- [Implicit by-name parameters](contextual/by-name-context-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless. **Status: not yet settled** diff --git a/docs/docs/reference/language-versions.md b/docs/docs/reference/language-versions.md new file mode 100644 index 000000000000..a7606d9b2ced --- /dev/null +++ b/docs/docs/reference/language-versions.md @@ -0,0 +1,36 @@ +--- +title: Language Versions +type: chapter +description: This page lists the different flavours of language supported by the Scala 3 compiler. +num: 100 +previous-page: overview +--- + +The default Scala language version currently supported by the Dotty compiler is `3.0`. There are also other language versions that can be specified instead: + +- `3.0-migration`: Same as `3.0` but with a Scala 2 compatibility mode that helps moving Scala 2.13 sources over to Scala 3. In particular, it + + - flags some Scala 2 constructs that are disallowed in Scala 3 as migration warnings instead of hard errors, + - changes some rules to be more lenient and backwards compatible with Scala 2.13 + - gives some additional warnings where the semantics has changed between Scala 2.13 and 3.0 + - in conjunction with `-rewrite`, offer code rewrites from Scala 2.13 to 3.0. + +- `future`: A preview of changes introduced in the next versions after 3.0. In the doc pages here we refer to the language version with these changes as `3.1`, but it might be that some of these changes will be rolled out in later `3.x` versions. + +Some Scala-2 specific idioms will be dropped in this version. The feature set supported by this version will be refined over time as we approach its release. + +- `future-migration`: Same as `future` but with additional helpers to migrate from `3.0`. Similarly to the helpers available under `3.0-migration`, these include migration warnings and optional rewrites. + +There are two ways to specify a language version. + +- With a `-source` command line setting, e.g. `-source 3.0-migration`. +- With a `scala.language` import at the top of a source file, e.g: + +```scala +package p +import scala.language.`future-migration` + +class C { ... } +``` + +Language imports supersede command-line settings in the source files where they are specified. Only one language import specifying a source version is allowed in a source file, and it must come before any definitions in that file. diff --git a/docs/docs/reference/metaprogramming/toc.md b/docs/docs/reference/metaprogramming.md similarity index 76% rename from docs/docs/reference/metaprogramming/toc.md rename to docs/docs/reference/metaprogramming.md index 12becbfa22e6..18664703a079 100644 --- a/docs/docs/reference/metaprogramming/toc.md +++ b/docs/docs/reference/metaprogramming.md @@ -1,13 +1,15 @@ --- -layout: doc-page -title: "Overview" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming.html +title: "Metaprogramming" +type: chapter +num: 27 +previous-page: /scala3/reference/contextual/relationship-implicits +next-page: /scala3/reference/metaprogramming/inline --- The following pages introduce the redesign of metaprogramming in Scala. They introduce the following fundamental facilities: -1. [`inline`](./inline.md) is a new modifier that guarantees that +1. [`inline`](./metaprogramming/inline.html) is a new modifier that guarantees that a definition will be inlined at the point of use. The primary motivation behind inline is to reduce the overhead behind function calls and access to values. The expansion will be performed by the Scala compiler during the @@ -18,10 +20,10 @@ introduce the following fundamental facilities: programming), macros (enabling compile-time, generative, metaprogramming) and runtime code generation (multi-stage programming). -2. [Compile-time ops](./compiletime-ops.md) are helper definitions in the +2. [Compile-time ops](./metaprogramming/compiletime-ops.html) are helper definitions in the standard library that provide support for compile-time operations over values and types. -3. [Macros](./macros.md) are built on two well-known fundamental +3. [Macros](./metaprogramming/macros.html) are built on two well-known fundamental operations: quotation and splicing. Quotation converts program code to data, specifically, a (tree-like) representation of this code. It is expressed as `'{...}` for expressions and as `'[...]` for types. Splicing, @@ -29,19 +31,19 @@ introduce the following fundamental facilities: to program code. Together with `inline`, these two abstractions allow to construct program code programmatically. -4. [Runtime Staging](./staging.md) Where macros construct code at _compile-time_, +4. [Runtime Staging](./metaprogramming/staging.html) Where macros construct code at _compile-time_, staging lets programs construct new code at _runtime_. That way, code generation can depend not only on static data but also on data available at runtime. This splits the evaluation of the program in two or more phases or ... stages. Consequently, this method of generative programming is called "Multi-Stage Programming". Staging is built on the same foundations as macros. It uses quotes and splices, but leaves out `inline`. -5. [Reflection](./reflection.md) Quotations are a "black-box" +5. [Reflection](./metaprogramming/reflection.html) Quotations are a "black-box" representation of code. They can be parameterized and composed using splices, but their structure cannot be analyzed from the outside. TASTy reflection gives a way to analyze code structure by partly revealing the representation type of a piece of code in a standard API. The representation type is a form of typed abstract syntax tree, which gives rise to the `TASTy` moniker. -6. [TASTy Inspection](./tasty-inspect.md) Typed abstract syntax trees are serialized +6. [TASTy Inspection](./metaprogramming/tasty-inspect.html) Typed abstract syntax trees are serialized in a custom compressed binary format stored in `.tasty` files. TASTy inspection allows to load these files and analyze their content's tree structure. diff --git a/docs/docs/reference/metaprogramming/compiletime-ops.md b/docs/docs/reference/metaprogramming/compiletime-ops.md index 3a31efb58d52..9bf0bc537930 100644 --- a/docs/docs/reference/metaprogramming/compiletime-ops.md +++ b/docs/docs/reference/metaprogramming/compiletime-ops.md @@ -1,12 +1,14 @@ --- -layout: doc-page title: "Compile-time operations" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/compiletime-ops.html +type: section +num: 29 +previous-page: /scala3/reference/metaprogramming/inline +next-page: /scala3/reference/metaprogramming/macros --- ## The `scala.compiletime` Package -The [`scala.compiletime`](https://dotty.epfl.ch/api/scala/compiletime.html) package contains helper definitions that provide support for compile-time operations over values. They are described in the following. +The [`scala.compiletime`](https://scala-lang.org/api/3.x/scala/compiletime.html) package contains helper definitions that provide support for compile-time operations over values. They are described in the following. ### `constValue` and `constValueOpt` @@ -52,7 +54,7 @@ Using `erasedValue`, we can then define `defaultValue` as follows: ```scala import scala.compiletime.erasedValue -inline def defaultValue[T] = +transparent inline def defaultValue[T] = inline erasedValue[T] match case _: Byte => Some(0: Byte) case _: Char => Some(0: Char) @@ -126,7 +128,7 @@ fail(identity("foo")) // error: failed on: identity("foo") ### The `scala.compiletime.ops` package -The [`scala.compiletime.ops`](https://dotty.epfl.ch/api/scala/compiletime/ops.html) package contains types that provide support for +The [`scala.compiletime.ops`](https://scala-lang.org/api/3.x/scala/compiletime/ops.html) package contains types that provide support for primitive operations on singleton types. For example, `scala.compiletime.ops.int.*` provides support for multiplying two singleton `Int` types, and `scala.compiletime.ops.boolean.&&` for the conjunction of two @@ -213,7 +215,7 @@ would use it as follows: import scala.compiletime.summonFrom inline def setFor[T]: Set[T] = summonFrom { - case ord: Ordering[T] => new TreeSet[T](using ord) + case ord: Ordering[T] => new TreeSet[T]()(using ord) case _ => new HashSet[T] } ``` diff --git a/docs/docs/reference/metaprogramming/inline.md b/docs/docs/reference/metaprogramming/inline.md index 8ccef49872b7..2e55b8e63cd0 100644 --- a/docs/docs/reference/metaprogramming/inline.md +++ b/docs/docs/reference/metaprogramming/inline.md @@ -1,12 +1,14 @@ --- -layout: doc-page title: Inline -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/inline.html +type: section +num: 28 +previous-page: /scala3/reference/metaprogramming +next-page: /scala3/reference/metaprogramming/compiletime-ops --- ## Inline Definitions -`inline` is a new [soft modifier](../soft-modifier.md) that guarantees that a +`inline` is a new [soft modifier](../soft-modifier.html) that guarantees that a definition will be inlined at the point of use. Example: ```scala diff --git a/docs/docs/reference/metaprogramming/macros-spec.md b/docs/docs/reference/metaprogramming/macros-spec.md index d152377e6d62..aa819c5ecb52 100644 --- a/docs/docs/reference/metaprogramming/macros-spec.md +++ b/docs/docs/reference/metaprogramming/macros-spec.md @@ -1,14 +1,14 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Macros Spec" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/macros-spec.html --- ## Implementation ### Syntax -Compared to the [Scala 3 reference grammar](../syntax.md) +Compared to the [Scala 3 reference grammar](../syntax.html) there are the following syntax changes: ``` SimpleExpr ::= ... @@ -159,7 +159,7 @@ environments and terms. Es |- 't: expr T ``` The meta theory of a slightly simplified 2-stage variant of this calculus -is studied [separately](./simple-smp.md). +is studied [separately](./simple-smp.html). ## Going Further diff --git a/docs/docs/reference/metaprogramming/macros.md b/docs/docs/reference/metaprogramming/macros.md index 16af18d3c831..9d70230c1356 100644 --- a/docs/docs/reference/metaprogramming/macros.md +++ b/docs/docs/reference/metaprogramming/macros.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Macros" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/macros.html +type: section +num: 30 +previous-page: /scala3/reference/metaprogramming/compiletime-ops +next-page: /scala3/reference/metaprogramming/staging --- > When developing macros enable `-Xcheck-macros` scalac option flag to have extra runtime checks. @@ -18,7 +20,7 @@ schemes with the familiar string interpolation syntax. println(s"Hello, $name, here is the result of 1 + 1 = ${1 + 1}") ``` -In string interpolation we _quoted_ a string and then we _spliced_ into it, two others. The first, `name`, is a reference to a value of type [`String`](https://dotty.epfl.ch/api/scala/Predef$.html#String), and the second is an arithmetic expression that will be _evaluated_ followed by the splicing of its string representation. +In string interpolation we _quoted_ a string and then we _spliced_ into it, two others. The first, `name`, is a reference to a value of type [`String`](https://scala-lang.org/api/3.x/scala/Predef$.html#String-0), and the second is an arithmetic expression that will be _evaluated_ followed by the splicing of its string representation. Quotes and splices in this section allow us to treat code in a similar way, effectively supporting macros. The entry point for macros is an inline method @@ -83,7 +85,7 @@ and it takes types `T` to expressions of type `Type[T]`. Splicing takes expressions of type `Expr[T]` to expressions of type `T` and it takes expressions of type `Type[T]` to types `T`. -The two types can be defined in package [`scala.quoted`](https://dotty.epfl.ch/api/scala/quoted.html) as follows: +The two types can be defined in package [`scala.quoted`](https://scala-lang.org/api/3.x/scala/quoted.html) as follows: ```scala package scala.quoted @@ -503,7 +505,7 @@ and allow for undefined compiler behavior if they are not. This is analogous to the status of pattern guards in Scala, which are also required, but not verified, to be pure. -[Multi-Stage Programming](./staging.md) introduces one additional method where +[Multi-Stage Programming](./staging.html) introduces one additional method where you can expand code at runtime with a method `run`. There is also a problem with that invocation of `run` in splices. Consider the following expression: @@ -625,7 +627,7 @@ def setForExpr[T: Type](using Quotes): Expr[Set[T]] = ## Relationship with Transparent Inline -[Inline](./inline.md) documents inlining. The code below introduces a transparent +[Inline](./inline.html) documents inlining. The code below introduces a transparent inline method that can calculate either a value of type `Int` or a value of type `String`. @@ -820,4 +822,4 @@ To match an actual application we can use braces on the function part `${b}(a1, ## More details -[More details](./macros-spec.md) +[More details](./macros-spec.html) diff --git a/docs/docs/reference/metaprogramming/reflection.md b/docs/docs/reference/metaprogramming/reflection.md index 74bb4f693e1b..a7c65cff680a 100644 --- a/docs/docs/reference/metaprogramming/reflection.md +++ b/docs/docs/reference/metaprogramming/reflection.md @@ -1,20 +1,22 @@ --- -layout: doc-page title: "Reflection" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/reflection.html +type: section +num: 32 +previous-page: /scala3/reference/metaprogramming/staging +next-page: /scala3/reference/metaprogramming/tasty-inspect --- Reflection enables inspection and construction of Typed Abstract Syntax Trees (Typed-AST). It may be used on quoted expressions (`quoted.Expr`) and quoted -types (`quoted.Type`) from [Macros](./macros.md) or on full TASTy files. +types (`quoted.Type`) from [Macros](./macros.html) or on full TASTy files. -If you are writing macros, please first read [Macros](./macros.md). +If you are writing macros, please first read [Macros](./macros.html). You may find all you need without using quote reflection. ## API: From quotes and splices to TASTy reflect trees and back With `quoted.Expr` and `quoted.Type` we can compute code but also analyze code -by inspecting the ASTs. [Macros](./macros.md) provide the guarantee that the +by inspecting the ASTs. [Macros](./macros.html) provide the guarantee that the generation of code will be type-correct. Using quote reflection will break these guarantees and may fail at macro expansion time, hence additional explicit checks must be done. diff --git a/docs/docs/reference/metaprogramming/simple-smp.md b/docs/docs/reference/metaprogramming/simple-smp.md index 7335135869c7..6a7e2c0fbae1 100644 --- a/docs/docs/reference/metaprogramming/simple-smp.md +++ b/docs/docs/reference/metaprogramming/simple-smp.md @@ -1,10 +1,11 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "The Meta-theory of Symmetric Metaprogramming" --- This note presents a simplified variant of -[principled metaprogramming](./macros.md) +[principled metaprogramming](./macros.html) and sketches its soundness proof. The variant treats only dialogues between two stages. A program can have quotes which can contain splices (which can contain quotes, which can contain splices, and so diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md index 2b76df3f5fd5..0e90966c85b2 100644 --- a/docs/docs/reference/metaprogramming/staging.md +++ b/docs/docs/reference/metaprogramming/staging.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Runtime Multi-Stage Programming" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/staging.html +type: section +num: 31 +previous-page: /scala3/reference/metaprogramming/macros +next-page: /scala3/reference/metaprogramming/reflection --- The framework expresses at the same time compile-time metaprogramming and @@ -97,7 +99,7 @@ scala -with-compiler -classpath out Test ## Example -Now take exactly the same example as in [Macros](./macros.md). Assume that we +Now take exactly the same example as in [Macros](./macros.html). Assume that we do not want to pass an array statically but generate code at run-time and pass the value, also at run-time. Note, how we make a future-stage function of type `Expr[Array[Int] => Int]` in line 6 below. Using `staging.run { ... }` we can evaluate an diff --git a/docs/docs/reference/metaprogramming/tasty-inspect.md b/docs/docs/reference/metaprogramming/tasty-inspect.md index 2ab2ce84c354..32bc2efa4313 100644 --- a/docs/docs/reference/metaprogramming/tasty-inspect.md +++ b/docs/docs/reference/metaprogramming/tasty-inspect.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "TASTy Inspection" -movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/tasty-inspect.html +type: section +num: 33 +previous-page: /scala3/reference/metaprogramming/reflection +next-page: /scala3/reference/other-new-features --- ```scala diff --git a/docs/docs/reference/new-types.md b/docs/docs/reference/new-types.md new file mode 100644 index 000000000000..e5d26e9c5982 --- /dev/null +++ b/docs/docs/reference/new-types.md @@ -0,0 +1,9 @@ +--- +title: New Types +type: chapter +num: 2 +previous-page: /scala3/reference/overview +next-page: /scala3/reference/new-types/intersection-types +--- + +This chapter documents the new types introduced in Scala 3. diff --git a/docs/docs/reference/new-types/dependent-function-types-spec.md b/docs/docs/reference/new-types/dependent-function-types-spec.md index b89f04327989..07a07b74287c 100644 --- a/docs/docs/reference/new-types/dependent-function-types-spec.md +++ b/docs/docs/reference/new-types/dependent-function-types-spec.md @@ -1,14 +1,14 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Dependent Function Types - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/dependent-function-types-spec.html --- Initial implementation in [PR #3464](https://github.com/lampepfl/dotty/pull/3464). ## Syntax -```ebnf +``` FunArgTypes ::= InfixType | ‘(’ [ FunArgType {',' FunArgType } ] ‘)’ | ‘(’ TypedFunParam {',' TypedFunParam } ‘)’ @@ -39,7 +39,7 @@ dependent function types for methods with dependent result types. Dependent functions can be implicit, and generalize to arity `N > 22` in the same way that other functions do, see -[the corresponding documentation](../dropped-features/limit22.md). +[the corresponding documentation](../dropped-features/limit22.html). ## Examples diff --git a/docs/docs/reference/new-types/dependent-function-types.md b/docs/docs/reference/new-types/dependent-function-types.md index 45e86120af6f..ffa9012c4ad3 100644 --- a/docs/docs/reference/new-types/dependent-function-types.md +++ b/docs/docs/reference/new-types/dependent-function-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Dependent Function Types" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/dependent-function-types.html +type: section +num: 7 +previous-page: /scala3/reference/new-types/match-types +next-page: /scala3/reference/new-types/polymorphic-function-types --- A dependent function type is a function type whose result depends @@ -36,7 +38,7 @@ This type describes function values that take any argument `e` of type `Entry` and return a result of type `e.Key`. Recall that a normal function type `A => B` is represented as an -instance of the [`Function1` trait](https://dotty.epfl.ch/api/scala/Function1.html) +instance of the [`Function1` trait](https://scala-lang.org/api/3.x/scala/Function1.html) (i.e. `Function1[A, B]`) and analogously for functions with more parameters. Dependent functions are also represented as instances of these traits, but they get an additional refinement. In fact, the dependent function type above is just syntactic sugar for @@ -46,4 +48,4 @@ Function1[Entry, Entry#Key]: def apply(e: Entry): e.Key ``` -[More details](./dependent-function-types-spec.md) +[More details](./dependent-function-types-spec.html) diff --git a/docs/docs/reference/new-types/intersection-types-spec.md b/docs/docs/reference/new-types/intersection-types-spec.md index 4d236c37dcc3..aeceeac04868 100644 --- a/docs/docs/reference/new-types/intersection-types-spec.md +++ b/docs/docs/reference/new-types/intersection-types-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Intersection Types - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/intersection-types-spec.html --- ## Syntax diff --git a/docs/docs/reference/new-types/intersection-types.md b/docs/docs/reference/new-types/intersection-types.md index d498e664d150..e912ec699457 100644 --- a/docs/docs/reference/new-types/intersection-types.md +++ b/docs/docs/reference/new-types/intersection-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page -title: "Intersection Types" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/intersection-types.html +title: Intersection Types +type: section +num: 3 +previous-page: /scala3/reference/new-types +next-page: /scala3/reference/new-types/union-types --- Used on types, the `&` operator creates an intersection type. @@ -65,4 +67,4 @@ class C extends A, B: ``` -[More details](./intersection-types-spec.md) +[More details](./intersection-types-spec.html) diff --git a/docs/docs/reference/new-types/match-types.md b/docs/docs/reference/new-types/match-types.md index 0ec8f3e58932..2516fe78e3ce 100644 --- a/docs/docs/reference/new-types/match-types.md +++ b/docs/docs/reference/new-types/match-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Match Types" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/match-types.html +type: section +num: 6 +previous-page: /scala3/reference/new-types/type-lambdas +next-page: /scala3/reference/new-types/dependent-function-types --- A match type reduces to one of its right-hand sides, depending on the type of diff --git a/docs/docs/reference/new-types/polymorphic-function-types.md b/docs/docs/reference/new-types/polymorphic-function-types.md index 2a803f5e65db..58224ef0de43 100644 --- a/docs/docs/reference/new-types/polymorphic-function-types.md +++ b/docs/docs/reference/new-types/polymorphic-function-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Polymorphic Function Types" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/polymorphic-function-types.html +type: section +num: 8 +previous-page: /scala3/reference/new-types/dependent-function-types +next-page: /scala3/reference/enums --- A polymorphic function type is a function type which accepts type parameters. @@ -81,7 +83,7 @@ println(e1) // Apply(Apply(Var(wrap),Var(f)),Apply(Var(wrap),Var(a))) ## Relationship With Type Lambdas Polymorphic function types are not to be confused with -[_type lambdas_](type-lambdas.md). +[_type lambdas_](type-lambdas.html). While the former describes the _type_ of a polymorphic _value_, the latter is an actual function value _at the type level_. diff --git a/docs/docs/reference/new-types/type-lambdas-spec.md b/docs/docs/reference/new-types/type-lambdas-spec.md index de6bd293d201..06bd314512c4 100644 --- a/docs/docs/reference/new-types/type-lambdas-spec.md +++ b/docs/docs/reference/new-types/type-lambdas-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Type Lambdas - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/type-lambdas-spec.html --- ## Syntax @@ -105,7 +105,7 @@ would be treated as covariant, `X` is used covariantly on its right-hand side. **Note**: The decision to treat `Nothing` as universal bottom type is provisional, and might be changed after further discussion. -**Note**: Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.md) +**Note**: Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.html) ## Curried Type Parameters diff --git a/docs/docs/reference/new-types/type-lambdas.md b/docs/docs/reference/new-types/type-lambdas.md index 8ede3f9305c7..8b12fbcece57 100644 --- a/docs/docs/reference/new-types/type-lambdas.md +++ b/docs/docs/reference/new-types/type-lambdas.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Type Lambdas" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/type-lambdas.html +type: section +num: 5 +previous-page: /scala3/reference/new-types/union-types +next-page: /scala3/reference/new-types/match-types --- A _type lambda_ lets one express a higher-kinded type directly, without @@ -14,4 +16,4 @@ a type definition. For instance, the type above defines a binary type constructor, which maps arguments `X` and `Y` to `Map[Y, X]`. Type parameters of type lambdas can have bounds, but they cannot carry `+` or `-` variance annotations. -[More details](./type-lambdas-spec.md) +[More details](./type-lambdas-spec.html) diff --git a/docs/docs/reference/new-types/union-types-spec.md b/docs/docs/reference/new-types/union-types-spec.md index d12e651536c5..9cfa27f619c3 100644 --- a/docs/docs/reference/new-types/union-types-spec.md +++ b/docs/docs/reference/new-types/union-types-spec.md @@ -1,13 +1,13 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Union Types - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/union-types-spec.html --- ## Syntax Syntactically, unions follow the same rules as intersections, but have a lower precedence, see -[Intersection Types - More Details](./intersection-types-spec.md). +[Intersection Types - More Details](./intersection-types-spec.html). ### Interaction with pattern matching syntax `|` is also used in pattern matching to separate pattern alternatives and has diff --git a/docs/docs/reference/new-types/union-types.md b/docs/docs/reference/new-types/union-types.md index 9c52cff3864d..7b2922fe3415 100644 --- a/docs/docs/reference/new-types/union-types.md +++ b/docs/docs/reference/new-types/union-types.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Union Types" -movedTo: https://docs.scala-lang.org/scala3/reference/new-types/union-types.html +type: section +num: 4 +previous-page: /scala3/reference/new-types/intersection-types +next-page: /scala3/reference/new-types/type-lambdas --- A union type `A | B` has as values all values of type `A` and also all values of type `B`. @@ -43,4 +45,4 @@ The type of `res2` is `Object & Product`, which is a supertype of UserName`. If we want the least supertype, we have to give it explicitly, as is done for the type of `either`. -[More details](./union-types-spec.md) +[More details](./union-types-spec.html) diff --git a/docs/docs/reference/other-new-features.md b/docs/docs/reference/other-new-features.md new file mode 100644 index 000000000000..faa2aefc6a91 --- /dev/null +++ b/docs/docs/reference/other-new-features.md @@ -0,0 +1,9 @@ +--- +title: "Other New Features" +type: chapter +num: 34 +previous-page: /scala3/reference/metaprogramming/tasty-inspect +next-page: /scala3/reference/other-new-features/trait-parameters +--- + +The following pages document new features of Scala 3. diff --git a/docs/docs/reference/other-new-features/control-syntax.md b/docs/docs/reference/other-new-features/control-syntax.md index 2f0bbde41331..0fefba262bf5 100644 --- a/docs/docs/reference/other-new-features/control-syntax.md +++ b/docs/docs/reference/other-new-features/control-syntax.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: New Control Syntax -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/control-syntax.html +type: section +num: 46 +previous-page: /scala3/reference/other-new-features/targetName +next-page: /scala3/reference/other-new-features/indentation --- Scala 3 has a new "quiet" syntax for control expressions that does not rely on diff --git a/docs/docs/reference/other-new-features/creator-applications.md b/docs/docs/reference/other-new-features/creator-applications.md index 17bc1574f763..0422bbfac77c 100644 --- a/docs/docs/reference/other-new-features/creator-applications.md +++ b/docs/docs/reference/other-new-features/creator-applications.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Universal Apply Methods" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/creator-applications.html +type: section +num: 37 +previous-page: /scala3/reference/other-new-features/transparent-traits +next-page: /scala3/reference/other-new-features/export --- Scala case classes generate apply methods, so that values of case classes can be created using simple diff --git a/docs/docs/reference/other-new-features/explicit-nulls.md b/docs/docs/reference/other-new-features/explicit-nulls.md index abcaaac58196..a0dac187ae60 100644 --- a/docs/docs/reference/other-new-features/explicit-nulls.md +++ b/docs/docs/reference/other-new-features/explicit-nulls.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Explicit Nulls" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/explicit-nulls.html +type: section +num: 48 +previous-page: /scala3/reference/other-new-features/indentation +next-page: /scala3/reference/other-new-features/safe-initialization --- Explicit nulls is an opt-in feature that modifies the Scala type system, which makes reference types @@ -13,7 +15,7 @@ This means the following code will no longer typecheck: val x: String = null // error: found `Null`, but required `String` ``` -Instead, to mark a type as nullable we use a [union type](../new-types/union-types.md) +Instead, to mark a type as nullable we use a [union type](../new-types/union-types.html) ```scala val x: String | Null = null // ok @@ -36,7 +38,7 @@ When explicit nulls are enabled, the type hierarchy changes so that `Null` is on This is the new type hierarchy: -!["Type Hierarchy for Explicit Nulls"](/images/explicit-nulls/explicit-nulls-type-hierarchy.png) +!["Type Hierarchy for Explicit Nulls"](/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png) After erasure, `Null` remains a subtype of all reference types (as forced by the JVM). @@ -81,7 +83,7 @@ val c = new C() ``` The unsoundness above can be caught by the compiler with the option `-Ysafe-init`. -More details can be found in [safe initialization](./safe-initialization.md). +More details can be found in [safe initialization](./safe-initialization.html). ## Equality @@ -535,4 +537,4 @@ Our strategy for binary compatibility with Scala binaries that predate explicit and new libraries compiled without `-Yexplicit-nulls` is to leave the types unchanged and be compatible but unsound. -[More details](../../internals/explicit-nulls.md) +[More details](https://dotty.epfl.ch/docs/internals/explicit-nulls.html) diff --git a/docs/docs/reference/other-new-features/export.md b/docs/docs/reference/other-new-features/export.md index 59f227858320..49a190c4c923 100644 --- a/docs/docs/reference/other-new-features/export.md +++ b/docs/docs/reference/other-new-features/export.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Export Clauses" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/export.html +type: section +num: 38 +previous-page: /scala3/reference/other-new-features/creator-applications +next-page: /scala3/reference/other-new-features/opaques --- An export clause defines aliases for selected members of an object. Example: @@ -136,7 +138,7 @@ ImportSpec ::= NamedSelector | WildcardSelector | ‘{’ ImportSelectors) ‘}’ NamedSelector ::= id [‘as’ (id | ‘_’)] -WildCardSelector ::= ‘*' | ‘given’ [InfixType] +WildCardSelector ::= ‘*’ | ‘given’ [InfixType] ImportSelectors ::= NamedSelector [‘,’ ImportSelectors] | WildCardSelector {‘,’ WildCardSelector} ``` diff --git a/docs/docs/reference/other-new-features/indentation-experimental.md b/docs/docs/reference/other-new-features/indentation-experimental.md index ed6e838fd5a4..389219d8e877 100644 --- a/docs/docs/reference/other-new-features/indentation-experimental.md +++ b/docs/docs/reference/other-new-features/indentation-experimental.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Fewer Braces" --- diff --git a/docs/docs/reference/other-new-features/indentation.md b/docs/docs/reference/other-new-features/indentation.md index c7a6fdbb7453..6a71e351f3c1 100644 --- a/docs/docs/reference/other-new-features/indentation.md +++ b/docs/docs/reference/other-new-features/indentation.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Optional Braces" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/indentation.html +type: section +num: 47 +previous-page: /scala3/reference/other-new-features/control-syntax +next-page: /scala3/reference/other-new-features/explicit-nulls --- Scala 3 enforces some rules on indentation and allows some occurrences of braces `{...}` to be optional: @@ -85,7 +87,7 @@ There are two rules: then else do catch finally yield match ``` - if the first token on the next line is a - [leading infix operator](../changed-features/operators.md). + [leading infix operator](../changed-features/operators.html). then its indentation width is less then the current indentation width, and it either matches a previous indentation width or is also less than the enclosing indentation width. @@ -409,7 +411,7 @@ Significant indentation is enabled by default. It can be turned off by giving an The Scala 3 compiler can rewrite source code to indented code and back. When invoked with options `-rewrite -indent` it will rewrite braces to indented regions where possible. When invoked with options `-rewrite -no-indent` it will rewrite in the reverse direction, inserting braces for indentation regions. -The `-indent` option only works on [new-style syntax](./control-syntax.md). So to go from old-style syntax to new-style indented code one has to invoke the compiler twice, first with options `-rewrite -new-syntax`, then again with options +The `-indent` option only works on [new-style syntax](./control-syntax.html). So to go from old-style syntax to new-style indented code one has to invoke the compiler twice, first with options `-rewrite -new-syntax`, then again with options `-rewrite -indent`. To go in the opposite direction, from indented code to old-style syntax, it's `-rewrite -no-indent`, followed by `-rewrite -old-syntax`. ### Variant: Indentation Marker `:` diff --git a/docs/docs/reference/other-new-features/kind-polymorphism.md b/docs/docs/reference/other-new-features/kind-polymorphism.md index 7dbcf3e96927..7e69bca4ea51 100644 --- a/docs/docs/reference/other-new-features/kind-polymorphism.md +++ b/docs/docs/reference/other-new-features/kind-polymorphism.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Kind Polymorphism" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/kind-polymorphism.html +type: section +num: 42 +previous-page: /scala3/reference/other-new-features/parameter-untupling +next-page: /scala3/reference/other-new-features/matchable --- Normally type parameters in Scala are partitioned into _kinds_. First-level types are types of values. Higher-kinded types are type constructors diff --git a/docs/docs/reference/other-new-features/matchable.md b/docs/docs/reference/other-new-features/matchable.md index fdce97dab8f0..12b33e63f17d 100644 --- a/docs/docs/reference/other-new-features/matchable.md +++ b/docs/docs/reference/other-new-features/matchable.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "The Matchable Trait" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/matchable.html +type: section +num: 43 +previous-page: /scala3/reference/other-new-features/kind-polymorphism +next-page: /scala3/reference/other-new-features/threadUnsafe-annotation --- A new trait `Matchable` controls the ability to pattern match. @@ -132,7 +134,7 @@ Here, universal `equals` will return true for Meter(10).equals(Second(10)) ``` -even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.md) one can mitigate that problem somewhat by turning +even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.html) one can mitigate that problem somewhat by turning ```scala Meter(10) == Second(10) diff --git a/docs/docs/reference/other-new-features/named-typeargs.md b/docs/docs/reference/other-new-features/named-typeargs.md index 11179c365da0..98009d4f3b7d 100644 --- a/docs/docs/reference/other-new-features/named-typeargs.md +++ b/docs/docs/reference/other-new-features/named-typeargs.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Named Type Arguments" --- diff --git a/docs/docs/reference/other-new-features/opaques-details.md b/docs/docs/reference/other-new-features/opaques-details.md index ecfb78db48b7..b7891a86c081 100644 --- a/docs/docs/reference/other-new-features/opaques-details.md +++ b/docs/docs/reference/other-new-features/opaques-details.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Opaque Type Aliases: More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/opaques-details.html --- ### Syntax @@ -11,7 +11,7 @@ Modifier ::= ... | ‘opaque’ ``` -`opaque` is a [soft modifier](../soft-modifier.md). It can still be used as a normal identifier when it is not in front of a definition keyword. +`opaque` is a [soft modifier](../soft-modifier.html). It can still be used as a normal identifier when it is not in front of a definition keyword. Opaque type aliases must be members of classes, traits, or objects, or they are defined at the top-level. They cannot be defined in local blocks. diff --git a/docs/docs/reference/other-new-features/opaques.md b/docs/docs/reference/other-new-features/opaques.md index 402440bad90c..cb4cf635678b 100644 --- a/docs/docs/reference/other-new-features/opaques.md +++ b/docs/docs/reference/other-new-features/opaques.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Opaque Type Aliases" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/opaques.html +type: section +num: 39 +previous-page: /scala3/reference/other-new-features/export +next-page: /scala3/reference/other-new-features/open-classes --- Opaque types aliases provide type abstraction without any overhead. Example: @@ -164,4 +166,4 @@ l1.mul(x, z) // error: found l2.Logarithm, required l1.Logarithm ``` In general, one can think of an opaque type as being only transparent in the scope of `private[this]`. -[More details](opaques-details.md) +[More details](opaques-details.html) diff --git a/docs/docs/reference/other-new-features/open-classes.md b/docs/docs/reference/other-new-features/open-classes.md index f1ddcf8c190f..342faed61ad4 100644 --- a/docs/docs/reference/other-new-features/open-classes.md +++ b/docs/docs/reference/other-new-features/open-classes.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Open Classes" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/open-classes.html +type: section +num: 40 +previous-page: /scala3/reference/other-new-features/opaques +next-page: /scala3/reference/other-new-features/parameter-untupling --- An `open` modifier on a class signals that the class is planned for extensions. Example: diff --git a/docs/docs/reference/other-new-features/parameter-untupling-spec.md b/docs/docs/reference/other-new-features/parameter-untupling-spec.md index feedb77aa774..dbabf9d5d7d7 100644 --- a/docs/docs/reference/other-new-features/parameter-untupling-spec.md +++ b/docs/docs/reference/other-new-features/parameter-untupling-spec.md @@ -1,7 +1,7 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: "Parameter Untupling - More Details" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/parameter-untupling-spec.html --- ## Motivation diff --git a/docs/docs/reference/other-new-features/parameter-untupling.md b/docs/docs/reference/other-new-features/parameter-untupling.md index 1beed4968d4f..de58f8c61fd0 100644 --- a/docs/docs/reference/other-new-features/parameter-untupling.md +++ b/docs/docs/reference/other-new-features/parameter-untupling.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Parameter Untupling" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/parameter-untupling.html +type: section +num: 41 +previous-page: /scala3/reference/other-new-features/open-classes +next-page: /scala3/reference/other-new-features/kind-polymorphism --- Say you have a list of pairs @@ -42,5 +44,5 @@ function type of the form `((T_1, ..., T_n)) => U`. For more information see: -* [More details](./parameter-untupling-spec.md) +* [More details](./parameter-untupling-spec.html) * [Issue #897](https://github.com/lampepfl/dotty/issues/897). diff --git a/docs/docs/reference/other-new-features/safe-initialization.md b/docs/docs/reference/other-new-features/safe-initialization.md index 09bb495f9263..7ecafb9a2888 100644 --- a/docs/docs/reference/other-new-features/safe-initialization.md +++ b/docs/docs/reference/other-new-features/safe-initialization.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Safe Initialization" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/safe-initialization.html +type: section +num: 49 +previous-page: /scala3/reference/other-new-features/explicit-nulls +next-page: /scala3/reference/other-new-features/type-test --- Scala 3 implements experimental safe initialization check, which can be enabled by the compiler option `-Ysafe-init`. diff --git a/docs/docs/reference/other-new-features/targetName.md b/docs/docs/reference/other-new-features/targetName.md index a83c4247c1ef..377bd2db10b0 100644 --- a/docs/docs/reference/other-new-features/targetName.md +++ b/docs/docs/reference/other-new-features/targetName.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "The @targetName annotation" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/targetName.html +type: section +num: 45 +previous-page: /scala3/reference/other-new-features/threadUnsafe-annotation +next-page: /scala3/reference/other-new-features/control-syntax --- A `@targetName` annotation on a definition defines an alternate name for the implementation of that definition. Example: diff --git a/docs/docs/reference/other-new-features/threadUnsafe-annotation.md b/docs/docs/reference/other-new-features/threadUnsafe-annotation.md index 99a16413f310..0916f6ff9b7b 100644 --- a/docs/docs/reference/other-new-features/threadUnsafe-annotation.md +++ b/docs/docs/reference/other-new-features/threadUnsafe-annotation.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "The @threadUnsafe annotation" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/threadUnsafe-annotation.html +type: section +num: 44 +previous-page: /scala3/reference/other-new-features/matchable +next-page: /scala3/reference/other-new-features/targetName --- A new annotation `@threadUnsafe` can be used on a field which defines diff --git a/docs/docs/reference/other-new-features/trait-parameters.md b/docs/docs/reference/other-new-features/trait-parameters.md index 9cc55c4e060b..a3a692f91cc7 100644 --- a/docs/docs/reference/other-new-features/trait-parameters.md +++ b/docs/docs/reference/other-new-features/trait-parameters.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Trait Parameters" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/trait-parameters.html +type: section +num: 35 +previous-page: /scala3/reference/other-new-features +next-page: /scala3/reference/other-new-features/transparent-traits --- Scala 3 allows traits to have parameters, just like classes have parameters. @@ -56,7 +58,7 @@ class E extends Greeting("Bob"), FormalGreeting ### Traits With Context Parameters This "explicit extension required" rule is relaxed if the missing trait contains only -[context parameters](../contextual/using-clauses). In that case the trait reference is +[context parameters]({% link _scala3-reference/contextual/using-clauses.md %}). In that case the trait reference is implicitly inserted as an additional parent with inferred arguments. For instance, here's a variant of greetings where the addressee is a context parameter of type `ImpliedName`: diff --git a/docs/docs/reference/other-new-features/transparent-traits.md b/docs/docs/reference/other-new-features/transparent-traits.md index 20141213db0a..236f0c64d7b8 100644 --- a/docs/docs/reference/other-new-features/transparent-traits.md +++ b/docs/docs/reference/other-new-features/transparent-traits.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "Transparent Traits" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/transparent-traits.html +type: section +num: 36 +previous-page: /scala3/reference/other-new-features/trait-parameters +next-page: /scala3/reference/other-new-features/creator-applications --- Traits are used in two roles: @@ -20,7 +22,7 @@ val x = Set(if condition then Val else Var) Here, the inferred type of `x` is `Set[Kind & Product & Serializable]` whereas one would have hoped it to be `Set[Kind]`. The reasoning for this particular type to be inferred is as follows: -- The type of the conditional above is the [union type](../new-types/union-types.md) `Val | Var`. +- The type of the conditional above is the [union type](../new-types/union-types.html) `Val | Var`. - A union type is widened in type inference to the least supertype that is not a union type. In the example, this type is `Kind & Product & Serializable` since all three traits are traits of both `Val` and `Var`. So that type becomes the inferred element type of the set. @@ -42,7 +44,7 @@ appear in the inferred type. The traits `scala.Product`, `java.lang.Serializable` and `java.lang.Comparable` are treated automatically as transparent. Other traits are turned into transparent traits using the modifier `transparent`. Scala 2 traits can also be made transparent -by adding a [`@transparentTrait` annotation](https://dotty.epfl.ch/api/scala/annotation/transparentTrait.html). This annotation is defined in `scala.annotation`. It will be deprecated and phased out once Scala 2/3 interopability is no longer needed. +by adding a [`@transparentTrait` annotation](https://scala-lang.org/api/3.x/scala/annotation/transparentTrait.html). This annotation is defined in `scala.annotation`. It will be deprecated and phased out once Scala 2/3 interopability is no longer needed. Typically, transparent traits are traits that influence the implementation of inheriting classes and traits that are not usually used as types by themselves. Two examples from the standard collection library are: diff --git a/docs/docs/reference/other-new-features/type-test.md b/docs/docs/reference/other-new-features/type-test.md index da9fa6a1c2b3..1fab03490e98 100644 --- a/docs/docs/reference/other-new-features/type-test.md +++ b/docs/docs/reference/other-new-features/type-test.md @@ -1,7 +1,9 @@ --- -layout: doc-page title: "TypeTest" -movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/type-test.html +type: section +num: 50 +previous-page: /scala3/reference/other-new-features/safe-initialization +next-page: /scala3/reference/changed-features --- ## TypeTest diff --git a/docs/docs/reference/overview.md b/docs/docs/reference/overview.md index 27f91a000e76..20995b4567cb 100644 --- a/docs/docs/reference/overview.md +++ b/docs/docs/reference/overview.md @@ -1,8 +1,10 @@ --- -layout: doc-page -title: "Overview" -movedTo: https://docs.scala-lang.org/scala3/reference/overview.html +title: Overview +type: chapter +num: 1 +next-page: /scala3/reference/new-types --- + Scala 3 implements many language changes and improvements over Scala 2. In this reference, we discuss design decisions and present important differences compared to Scala 2. @@ -25,37 +27,37 @@ Corresponding to these goals, the language changes fall into seven categories: These new constructs directly model core features of DOT, higher-kinded types, and the [SI calculus for implicit resolution](https://infoscience.epfl.ch/record/229878/files/simplicitly_1.pdf). -- [Intersection types](new-types/intersection-types.md), replacing compound types, -- [Union types](new-types/union-types.md), -- [Type lambdas](new-types/type-lambdas.md), replacing encodings using structural types and type projection. -- [Context functions](contextual/context-functions.md), offering abstraction over given parameters. +- [Intersection types](new-types/intersection-types.html), replacing compound types, +- [Union types](new-types/union-types.html), +- [Type lambdas](new-types/type-lambdas.html), replacing encodings using structural types and type projection. +- [Context functions](contextual/context-functions.html), offering abstraction over given parameters. ## Simplifications These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style. -- [Trait parameters](other-new-features/trait-parameters.md) - replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct. -- [Given instances](contextual/givens.md) +- [Trait parameters](other-new-features/trait-parameters.html) + replace [early initializers](dropped-features/early-initializers.html) with a more generally useful construct. +- [Given instances](contextual/givens.html) replace implicit objects and defs, focussing on intent over mechanism. -- [Using clauses](contextual/using-clauses.md) +- [Using clauses](contextual/using-clauses.html) replace implicit parameters, avoiding their ambiguities. -- [Extension methods](contextual/extension-methods.md) +- [Extension methods](contextual/extension-methods.html) replace implicit classes with a clearer and simpler mechanism. -- [Opaque type aliases](other-new-features/opaques.md) +- [Opaque type aliases](other-new-features/opaques.html) replace most uses of value classes while guaranteeing absence of boxing. -- [Top-level definitions](dropped-features/package-objects.md) +- [Top-level definitions](dropped-features/package-objects.html) replace package objects, dropping syntactic boilerplate. -- [Export clauses](other-new-features/export.md) +- [Export clauses](other-new-features/export.html) provide a simple and general way to express aggregation, which can replace the previous facade pattern of package objects inheriting from classes. -- [Vararg splices](changed-features/vararg-splices.md) +- [Vararg splices](changed-features/vararg-splices.html) now use the form `xs*` in function arguments and patterns instead of `xs: _*` and `xs @ _*`, -- [Universal apply methods](other-new-features/creator-applications.md) +- [Universal apply methods](other-new-features/creator-applications.html) allow using simple function call syntax instead of `new` expressions. `new` expressions stay around as a fallback for the cases where creator applications cannot be used. -With the exception of [early initializers](dropped-features/early-initializers.md) and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later. +With the exception of [early initializers](dropped-features/early-initializers.html) and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later. Value classes (superseded by opaque type aliases) are a special case. There are currently no deprecation plans for value classes, since we might bring them back in a more general form if they are supported natively by the JVM as is planned by [project Valhalla](https://openjdk.java.net/projects/valhalla/). @@ -63,15 +65,15 @@ Value classes (superseded by opaque type aliases) are a special case. There are These constructs are restricted to make the language safer. -- [Implicit Conversions](contextual/conversions.md): +- [Implicit Conversions](contextual/conversions.html): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import. -- [Given Imports](contextual/given-imports.md): +- [Given Imports](contextual/given-imports.html): implicits now require a special form of import, to make the import clearly visible. -- [Type Projection](dropped-features/type-projection.md): +- [Type Projection](dropped-features/type-projection.html): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound. -- [Multiversal Equality](contextual/multiversal-equality.md): +- [Multiversal Equality](contextual/multiversal-equality.html): implement an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`. -- [infix](changed-features/operators.md): +- [infix](changed-features/operators.html): make method application syntax uniform across code bases. Unrestricted implicit conversions continue to be available in Scala 3.0, but will be deprecated and removed later. Unrestricted versions of the other constructs in the list above are available only under `-source 3.0-migration`. @@ -80,37 +82,37 @@ Unrestricted implicit conversions continue to be available in Scala 3.0, but wil These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation. -- [DelayedInit](dropped-features/delayed-init.md), -- [Existential types](dropped-features/existential-types.md), -- [Procedure syntax](dropped-features/procedure-syntax.md), -- [Class shadowing](dropped-features/class-shadowing.md), -- [XML literals](dropped-features/xml.md), -- [Symbol literals](dropped-features/symlits.md), -- [Auto application](dropped-features/auto-apply.md), -- [Weak conformance](dropped-features/weak-conformance.md), -- Compound types (replaced by [Intersection types](new-types/intersection-types.md)), +- [DelayedInit](dropped-features/delayed-init.html), +- [Existential types](dropped-features/existential-types.html), +- [Procedure syntax](dropped-features/procedure-syntax.html), +- [Class shadowing](dropped-features/class-shadowing.html), +- [XML literals](dropped-features/xml.html), +- [Symbol literals](dropped-features/symlits.html), +- [Auto application](dropped-features/auto-apply.html), +- [Weak conformance](dropped-features/weak-conformance.html), +- Compound types (replaced by [Intersection types](new-types/intersection-types.html)), - [Auto tupling](https://github.com/lampepfl/dotty/pull/4311) (implemented, but not merged). The date when these constructs are dropped varies. The current status is: - Not implemented at all: - - DelayedInit, existential types, weak conformance. + - DelayedInit, existential types, weak conformance. - Supported under `-source 3.0-migration`: - - procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form. + - procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form. - Supported in 3.0, to be deprecated and phased out later: - - [XML literals](dropped-features/xml.md), compound types. + - [XML literals](dropped-features/xml.html), compound types. ## Changes These constructs have undergone changes to make them more regular and useful. -- [Structural Types](changed-features/structural-types.md): +- [Structural Types](changed-features/structural-types.html): They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo. -- [Name-based pattern matching](changed-features/pattern-matching.md): +- [Name-based pattern matching](changed-features/pattern-matching.html): The existing undocumented Scala 2 implementation has been codified in a slightly simplified form. -- [Automatic Eta expansion](changed-features/eta-expansion.md): +- [Automatic Eta expansion](changed-features/eta-expansion.html): Eta expansion is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0. -- [Implicit Resolution](changed-features/implicit-resolution.md): +- [Implicit Resolution](changed-features/implicit-resolution.html): The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes. Most aspects of old-style implicit resolution are still available under `-source 3.0-migration`. The other changes in this list are applied unconditionally. @@ -119,13 +121,13 @@ Most aspects of old-style implicit resolution are still available under `-source These are additions to the language that make it more powerful or pleasant to use. -- [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md). -- [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring. -- [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types. -- [Polymorphic function types](new-types/polymorphic-function-types.md) generalize polymorphic methods to polymorphic function values and types. +- [Enums](enums/enums.html) provide concise syntax for enumerations and [algebraic data types](enums/adts.html). +- [Parameter untupling](other-new-features/parameter-untupling.html) avoids having to use `case` for tupled parameter destructuring. +- [Dependent function types](new-types/dependent-function-types.html) generalize dependent methods to dependent function values and types. +- [Polymorphic function types](new-types/polymorphic-function-types.html) generalize polymorphic methods to polymorphic function values and types. _Current status_: There is a proposal and a merged prototype implementation, but the implementation has not been finalized (it is notably missing type inference support). -- [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors. -- [`@targetName` annotations](other-new-features/targetName.md) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes. +- [Kind polymorphism](other-new-features/kind-polymorphism.html) allows the definition of operators working equally on types and type constructors. +- [`@targetName` annotations](other-new-features/targetName.html) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes. ## Metaprogramming @@ -135,19 +137,19 @@ It's worth noting that macros were never included in the [Scala 2 language speci To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority. -- [Match Types](new-types/match-types.md) +- [Match Types](new-types/match-types.html) allow computation on types. -- [Inline](metaprogramming/inline.md) +- [Inline](metaprogramming/inline.html) provides by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros. -- [Quotes and Splices](metaprogramming/macros.md) +- [Quotes and Splices](metaprogramming/macros.html) provide a principled way to express macros and staging with a unified set of abstractions. -- [Type class derivation](contextual/derivation.md) +- [Type class derivation](contextual/derivation.html) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro. -- [By-name context parameters](contextual/by-name-context-parameters.md) +- [By-name context parameters](contextual/by-name-context-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in [Shapeless](https://github.com/milessabin/shapeless). ## See Also -[A classification of proposed language features](./features-classification.md) is +[A classification of proposed language features](./features-classification.html) is an expanded version of this page that adds the status (i.e. relative importance to be a part of Scala 3, and relative urgency when to decide this) and expected migration cost of each language construct. diff --git a/docs/docs/reference/soft-modifier.md b/docs/docs/reference/soft-modifier.md index 2b81e39afb04..625f180b871c 100644 --- a/docs/docs/reference/soft-modifier.md +++ b/docs/docs/reference/soft-modifier.md @@ -1,5 +1,6 @@ --- -layout: doc-page +layout: singlepage-overview +scala3: true title: Soft Keywords --- diff --git a/docs/docs/reference/syntax.md b/docs/docs/reference/syntax.md index 8e5a7c3d6c52..365d861f4688 100644 --- a/docs/docs/reference/syntax.md +++ b/docs/docs/reference/syntax.md @@ -1,7 +1,8 @@ --- -layout: doc-page title: "Scala 3 Syntax Summary" -movedTo: https://docs.scala-lang.org/scala3/reference/syntax.html +type: chapter +num: 87 +previous-page: /scala3/reference/dropped-features/wildcard-init --- The following description of Scala tokens uses literal characters `‘c’` when @@ -10,7 +11,7 @@ referring to the ASCII fragment `\u0000` – `\u007F`. _Unicode escapes_ are used to represent the [Unicode character](https://www.w3.org/International/articles/definitions-characters/) with the given hexadecimal code: -```ebnf +``` UnicodeEscape ::= ‘\’ ‘u’ {‘u’} hexDigit hexDigit hexDigit hexDigit hexDigit ::= ‘0’ | … | ‘9’ | ‘A’ | … | ‘F’ | ‘a’ | … | ‘f’ ``` @@ -22,7 +23,7 @@ Informal descriptions are typeset as `“some comment”`. The lexical syntax of Scala is given by the following grammar in EBNF form. -```ebnf +``` whiteSpace ::= ‘\u0020’ | ‘\u0009’ | ‘\u000D’ | ‘\u000A’ upper ::= ‘A’ | … | ‘Z’ | ‘\$’ | ‘_’ “… and Unicode category Lu” lower ::= ‘a’ | … | ‘z’ “… and Unicode category Ll” @@ -90,7 +91,7 @@ semi ::= ‘;’ | nl {nl} ## Optional Braces -The lexical analyzer also inserts `indent` and `outdent` tokens that represent regions of indented code [at certain points](./other-new-features/indentation.md). +The lexical analyzer also inserts `indent` and `outdent` tokens that represent regions of indented code [at certain points](./other-new-features/indentation.html). In the context-free productions below we use the notation `<<< ts >>>` to indicate a token sequence `ts` that is either enclosed in a pair of braces `{ ts }` or that constitutes an indented region `indent ts outdent`. Analogously, the @@ -125,7 +126,7 @@ type val var while with yield as derives end extension infix inline opaque open transparent using | * + - ``` -See the [separate section on soft keywords](./soft-modifier.md) for additional +See the [separate section on soft keywords](./soft-modifier.html) for additional details on where a soft keyword is recognized. ## Context-free Syntax @@ -134,7 +135,7 @@ The context-free syntax of Scala is given by the following EBNF grammar: ### Literals and Paths -```ebnf +``` SimpleLiteral ::= [‘-’] integerLiteral | [‘-’] floatingPointLiteral | booleanLiteral @@ -156,7 +157,7 @@ ClassQualifier ::= ‘[’ id ‘]’ ``` ### Types -```ebnf +``` Type ::= FunType | HkTypeParamClause ‘=>>’ Type | FunParamClause ‘=>>’ Type @@ -201,7 +202,7 @@ Types ::= Type {‘,’ Type} ``` ### Expressions -```ebnf +``` Expr ::= FunParams (‘=>’ | ‘?=>’) Expr | HkTypeParamClause ‘=>’ Expr | Expr1 @@ -303,7 +304,7 @@ ArgumentPatterns ::= ‘(’ [Patterns] ‘)’ ``` ### Type and Value Parameters -```ebnf +``` ClsTypeParamClause::= ‘[’ ClsTypeParam {‘,’ ClsTypeParam} ‘]’ ClsTypeParam ::= {Annotation} [‘+’ | ‘-’] id [HkTypeParamClause] TypeParamBounds @@ -331,7 +332,7 @@ DefParam ::= {Annotation} [‘inline’] Param ``` ### Bindings and Imports -```ebnf +``` Bindings ::= ‘(’ [Binding {‘,’ Binding}] ‘)’ Binding ::= (id | ‘_’) [‘:’ Type] @@ -369,7 +370,7 @@ EndMarkerTag ::= id | ‘if’ | ‘while’ | ‘for’ | ‘match’ | ``` ### Declarations and Definitions -```ebnf +``` RefineDcl ::= ‘val’ ValDcl | ‘def’ DefDcl | ‘type’ {nl} TypeDcl diff --git a/docs/docs/usage/scaladoc/blog.md b/docs/docs/usage/scaladoc/blog.md index a12804ad4757..1e3c371c8e19 100644 --- a/docs/docs/usage/scaladoc/blog.md +++ b/docs/docs/usage/scaladoc/blog.md @@ -1,9 +1,12 @@ --- +layout: multipage-overview title: Built-in blog +partof: scala3-scaladoc +num: 5 +previous-page: static-site +next-page: site-versioning --- -# {{page.title}} - Scaladoc allows you to include a simple blog in your documentation. For now, it provides only basic features. In the future, we plan to include more advanced features like tagging or author pages. @@ -22,7 +25,7 @@ All your blogposts must be put under `blog/_posts` directory. │ └── index.html ``` -If you are using yaml [sidebar](./staticSite.html#sidebar) don't forget to place +If you are using yaml [sidebar]({% link _overviews/scala3-scaladoc/static-site.md %}#sidebar) don't forget to place ``` sidebar: diff --git a/docs/docs/usage/scaladoc/scaladocDocstrings.md b/docs/docs/usage/scaladoc/docstrings.md similarity index 97% rename from docs/docs/usage/scaladoc/scaladocDocstrings.md rename to docs/docs/usage/scaladoc/docstrings.md index 115ef3395c80..5efb8b5f38da 100644 --- a/docs/docs/usage/scaladoc/scaladocDocstrings.md +++ b/docs/docs/usage/scaladoc/docstrings.md @@ -1,9 +1,12 @@ --- -title: Scaladoc docstrings - specific Tags and Features +layout: multipage-overview +title: Docstrings - specific Tags and Features +partof: scala3-scaladoc +num: 2 +previous-page: index +next-page: linking --- -# {{page.title}} - This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc. Since many things are the same as in the old scaladoc, some parts are reused from this [article](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html) @@ -192,4 +195,4 @@ Further information on the formatting and style recommendations can be found in Scaladoc allows linking to API documentation with Wiki-style links. Linking to `scala.collection.immutable.List` is as simple as -`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./linkingDocumentation.html#definition-links). +`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation]({% link _overviews/scala3-scaladoc/linking.md %}#definition-links). diff --git a/docs/docs/usage/scaladoc/index.md b/docs/docs/usage/scaladoc/index.md index ef0db90daebf..b158e9d89e74 100644 --- a/docs/docs/usage/scaladoc/index.md +++ b/docs/docs/usage/scaladoc/index.md @@ -1,26 +1,11 @@ --- -title: scaladoc +layout: multipage-overview +title: Scaladoc +partof: scala3-scaladoc +num: 1 +next-page: docstrings --- -![scaladoc logo](/images/scaladoc-logo.png) +![scaladoc logo]({{ site.baseurl }}/resources/images/scala3/scaladoc/logo.svg) -scaladoc is a tool to generate documentation for your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`. - -As you probably have guessed, this whole site was created using scaladoc. - - -{% for post in site.posts %} -## [{{ post.title }}](/{{ post.url }}) - -{{ post.excerpt }} - -[ (read more) ](/{{ post.url }}) - -{% endfor %} - -## Other extensions - -We would love to have your feedback on what you think would be good in order to -render the documentation you want! Perhaps you would like to render method -definitions or members? Do you want to have runnable code snippets? Let us know -by filing [issues](https://github.com/lampepfl/dotty/issues/new)! +scaladoc is a tool to generate the API documentation of your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`. diff --git a/docs/docs/usage/scaladoc/linkingDocumentation.md b/docs/docs/usage/scaladoc/linking.md similarity index 97% rename from docs/docs/usage/scaladoc/linkingDocumentation.md rename to docs/docs/usage/scaladoc/linking.md index f965e8bd8963..635c461abdd3 100644 --- a/docs/docs/usage/scaladoc/linkingDocumentation.md +++ b/docs/docs/usage/scaladoc/linking.md @@ -1,9 +1,12 @@ --- +layout: multipage-overview title: Linking documentation +partof: scala3-scaladoc +num: 3 +previous-page: docstrings +next-page: static-site --- -# {{ page.title }} - Scaladoc's main feature is creating API documentation from code comments. By default, the code comments are understood as Markdown, though we also support diff --git a/docs/docs/usage/scaladoc/search-engine.md b/docs/docs/usage/scaladoc/search-engine.md new file mode 100644 index 000000000000..06d0d13eec4a --- /dev/null +++ b/docs/docs/usage/scaladoc/search-engine.md @@ -0,0 +1,86 @@ +--- +layout: multipage-overview +title: Type-based search +partof: scala3-scaladoc +num: 7 +previous-page: site-versioning +next-page: settings +--- + +Searching for functions by their symbolic names can be time-consuming. +That is why the new scaladoc allows searching for methods and fields by their types. + + +Consider the following extension method definition: +``` +extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... +``` +Instead of searching for `span` we can also search for `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. + +To use this feature, type the signature of the member you are looking for in the scaladoc searchbar. This is how it works: + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) + +This feature is provided by the [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with the development of this feature, follow the [Inkuire repository](https://github.com/VirtusLab/Inkuire). + +## Examples of queries + +Some examples of queries with intended results: +- `List[Int] => (Int => Long) => List[Long]` -> `map` +- `Seq[A] => (A => B) => Seq[B]` -> `map` +- `(A, B) => A` -> `_1` +- `Set[Long] => Long => Boolean` -> `contains` +- `Int => Long => Int` -> `const` +- `String => Int => Char` -> `apply` +- `(Int & Float) => (String | Double)` -> `toDouble`, `toString` +- `F[A] => Int` -> `length` + +## Query syntax + +In order for a scaladoc searchbar query to be searched using Inkuire instead of the default search engine, the query has to contain the `=>` character sequence. + +Accepted input is similar to a curried function signature in Scala 3. With some differences: +- AndTypes, OrTypes and Functions have to be enclosed in parentheses e.g. `(Int & Any) => String` +- fields and parameterless methods can be found by preceding their type with `=>`, e.g., `=> Int` +- A wildcard `_` can be used to indicate that we want to match any type in a given place e.g. `Long => Double => _` +- Types in the form of single letter e.g. `A` or a letter with a digit `X1` are automatically assumed to be type variables +- Other type variables can be declared just like in polymorphic functions e.g. `[AVariable, AlsoAVariable] => AVariable => AlsoAVariable => AVariable` + +### Working with type aliases and method receivers + +When it comes to how the code is mapped to InkuireDb entries, there are some transformations to make the engine more opinionated (though open to suggestions and changes). Firstly, the receiver (non-module owner) of a function can be treated as a first argument. Automatic currying is also applied, so that the results don't depend on argument lists. When finding matches, `val`s and `def`s are not distinguished. + +So the following declarations should be found by query `Num => Int => Int => Int`: +``` +class Num(): + def a(i: Int, j: Int): Int + def b(i: Int)(j: Int): Int + def c(i: Int): (Int => Int) + val d: Int => Int => Int + val e: Int => Int => Int + val f: (Int, Int) => Int +end Num + +def g(i: Num, j: Int, k: Int): Int +extension (i: Num) def h(j: Int, k: Int): Int +def i(i: Num, j: Int)(k: Int): Int +extension (i: Num) def j(j: Int)(k: Int): Int +... +``` + +When it comes to type aliases, they are desugared on both the declaration and the query signature. This means that for declarations: +``` +type Name = String + +def fromName(name: Name): String +def fromString(str: String): Name +``` +both methods, `fromName` and `fromString`, should be found for queries `Name => Name`, `String => String`, `Name => String` and `String => Name`. + +## How it works + +Inkuire works as a JavaScript worker in the browser thanks to the power of [ScalaJS](https://www.scala-js.org/). + +To enable Inkuire when running scaladoc, add the flag `-Ygenerate-inkuire`. By adding this flag two files are generated: +- `inkuire-db.json` - this is the file containing all the searchable declarations from the currently documented project in a format readable to the Inkuire search engine. +- `inkuire-config.json` - this file contains the locations of the database files that should be searchable from the documentation of the current project. By default, it will be generated with the location of the local db file as well as the default implied locations of database files in [External mappings](/scala3/guides/scaladoc/settings.html#-external-mappings). diff --git a/docs/docs/usage/scaladoc/settings.md b/docs/docs/usage/scaladoc/settings.md index 4881c9790d4e..16a0e879a2c9 100644 --- a/docs/docs/usage/scaladoc/settings.md +++ b/docs/docs/usage/scaladoc/settings.md @@ -1,9 +1,11 @@ --- -title: Scaladoc settings +layout: multipage-overview +title: Settings +partof: scala3-scaladoc +num: 8 +previous-page: search-engine --- -# {{page.title}} - This chapter lists the configuration options that can be used when calling scaladoc. Some of the information shown here can be found by calling scaladoc with the `-help` flag. ## Parity with scaladoc for Scala 2 @@ -77,7 +79,7 @@ In such case paths used in templates will be relativized against `` Mapping between regexes matching classpath entries and external documentation. Example external mapping is: -`-external-mappings:.*scala.*::scaladoc3::http://dotty.epfl.ch/api/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/` +`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/` A mapping is of the form '\::\[scaladoc3|scaladoc|javadoc]::\'. You can supply several mappings, separated by commas, as shown in the example. @@ -158,7 +160,7 @@ compile - Enables snippet checking. nocompile - Disables snippet checking. fail - Enables snippet checking, asserts that snippet doesn't compile. -The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page](docs/reference/other-new-features/opaques.html) +The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page]({% link _scala3-reference/other-new-features/opaques.md %}) Example usage: diff --git a/docs/docs/usage/scaladoc/site-versioning.md b/docs/docs/usage/scaladoc/site-versioning.md index 9cd1e3d9fc5f..d15fc49ab363 100644 --- a/docs/docs/usage/scaladoc/site-versioning.md +++ b/docs/docs/usage/scaladoc/site-versioning.md @@ -1,9 +1,12 @@ --- +layout: multipage-overview title: Site versioning +partof: scala3-scaladoc +num: 6 +previous-page: blog +next-page: search-engine --- -# {{ page.title }} - Scaladoc provides a convenient way to switch between different versions of the documentation. The feature is useful if we want to expose older docs for users that didn't migrate to the new version of our library. ### How to setup it @@ -33,4 +36,4 @@ doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/v Providing a JSON file via `-versions-dictionary-url` enables scaladoc to link between versions. It is also convenient to be able to change the revision label in the drop-down menu. Everything will change automatically. -![](images/scaladoc/nightly.gif) +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/nightly.gif) diff --git a/docs/docs/usage/scaladoc/staticSite.md b/docs/docs/usage/scaladoc/static-site.md similarity index 78% rename from docs/docs/usage/scaladoc/staticSite.md rename to docs/docs/usage/scaladoc/static-site.md index f9d61342cba7..e7516ea09c07 100644 --- a/docs/docs/usage/scaladoc/staticSite.md +++ b/docs/docs/usage/scaladoc/static-site.md @@ -1,9 +1,12 @@ --- +layout: multipage-overview title: Static documentation +partof: scala3-scaladoc +num: 4 +previous-page: linking +next-page: blog --- -# {{ page.title }} - Scaladoc can generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/). Having a combined tool allows providing interaction between static documentation and API, thus allowing the two to blend naturally. @@ -41,6 +44,7 @@ In Scaladoc, all templates can contain YAML front-matter. The front-matter is parsed and put into the `page` variable available in templates via Liquid. Example front-matter + ``` --- title: My custom title @@ -51,10 +55,10 @@ Scaladoc uses some predefined properties to controls some aspects of page. Predefined properties: - - **title** provide page title that will be used in navigation and HTML metadata. - - **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** - - **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** - - **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.** +- **title** provide page title that will be used in navigation and HTML metadata. +- **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** +- **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** +- **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.** - **layout** - predefined layout to use, see below. **This setting is not exported to the template engine.** @@ -105,26 +109,26 @@ Scaladoc by default uses layout of files in `docs` directory to create table of ```yaml sidebar: - - title: Blog - - title: My title - page: my-page1.md - - page: my-page2.md - - page: my-page3/subsection - - title: Reference - subsection: - - page: my-page3.md - - index: my-page4/index.md - subsection: - - page: my-page4/my-page4.md - - title: My subsection - index: my-page5/index.md - subsection: - - page: my-page5/my-page5.md - - index: my-page6/index.md - subsection: - - index: my-page6/my-page6/index.md - subsection: - - page: my-page6/my-page6/my-page6.md + - title: Blog + - title: My title + page: my-page1.md + - page: my-page2.md + - page: my-page3/subsection + - title: Reference + subsection: + - page: my-page3.md + - index: my-page4/index.md + subsection: + - page: my-page4/my-page4.md + - title: My subsection + index: my-page5/index.md + subsection: + - page: my-page5/my-page5.md + - index: my-page6/index.md + subsection: + - index: my-page6/my-page6/index.md + subsection: + - page: my-page6/my-page6/my-page6.md ``` The `sidebar` key is mandatory. @@ -134,16 +138,14 @@ On each level, you can have three different types of entries: `page`, `blog` or - `title` (optional) - title of the page - `page` (mandatory) - path to the file that will represent the page, it can be either html or markdown file to be rendered, there is also the possibility to pass the `directory` path. If so, the scaladoc will render the directory and all its content as if there were no `sidebar.yml` basing on its tree structure and index files. -The `page` property - -`subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are: +The `page` property `subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are: - `title` (optional) - title of the page - `index` (optional) - path to the file that will represent the index file of the subsection, it can be either html or markdown file to be rendered - `subsection` (mandatory) - nested nodes, can be either pages or subsections In `subsection`s, you can omit `title` or `index`, however not specifying any of these properties prevents you from specifying the title of the section. -`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here](blog.md). +`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here]({% link _overviews/scala3-scaladoc/blog.md %}). ``` ├── blog @@ -198,5 +200,4 @@ For example, consider the following situation: You can refer to the assets from within any of the files using markdown links: ``` -This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf) -``` +This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)``` diff --git a/project/Build.scala b/project/Build.scala index 791047dbacb8..27ece53a6c5a 100644 --- a/project/Build.scala +++ b/project/Build.scala @@ -1418,8 +1418,9 @@ object Build { "-versions-dictionary-url", "https://scala-lang.org/api/versions.json", "-Ydocument-synthetic-types", - s"-snippet-compiler:${dottyLibRoot}/scala/quoted=compile" - ) ++ (if (justAPI) Nil else Seq("-siteroot", "docs", "-Yapi-subdirectory"))) + s"-snippet-compiler:${dottyLibRoot}/scala/quoted=compile", + ) + ) if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") } else if (justAPI) generateDocTask diff --git a/project/scripts/genDocs b/project/scripts/genDocs index aa061d59b613..37f6257f0acb 100755 --- a/project/scripts/genDocs +++ b/project/scripts/genDocs @@ -19,7 +19,7 @@ mkdir -pv "$PREVIOUS_SNAPSHOTS_DIR" git remote add doc-remote "https://github.com/lampepfl/dotty-website.git" git fetch doc-remote gh-pages git checkout gh-pages -(cp -vr [03].*/ "$PREVIOUS_SNAPSHOTS_DIR"; true) # Don't fail if no `3.*` found to copy +(cp -vr 3.*/ 0.*/ docs/ blog/ index.html "$PREVIOUS_SNAPSHOTS_DIR"; true) # Don't fail if no `3.*` found to copy git checkout "$GIT_HEAD" ### Generate the current snapshot of the website ### @@ -34,5 +34,5 @@ if [ ! -d "$SITE_OUT_DIR" ]; then fi ### Move previous versions' snapshots to _site ### -mv -v "$PREVIOUS_SNAPSHOTS_DIR"/* "$SITE_OUT_DIR" +mv -vf "$PREVIOUS_SNAPSHOTS_DIR"/* "$SITE_OUT_DIR" rm -rf "$PREVIOUS_SNAPSHOTS_DIR"