From 4034fe00f5180038c03d8c291f3b7ba8185fadaa Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 16:32:17 -0800 Subject: [PATCH 1/7] Fix docs - Fix the syntax of a sentence - Fix a code example --- .../reference/changed-features/vararg-splices.md | 15 ++++++--------- docs/docs/reference/metaprogramming/inline.md | 4 +++- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/docs/reference/changed-features/vararg-splices.md b/docs/docs/reference/changed-features/vararg-splices.md index 085481a4c2c0..a787edd04225 100644 --- a/docs/docs/reference/changed-features/vararg-splices.md +++ b/docs/docs/reference/changed-features/vararg-splices.md @@ -7,23 +7,23 @@ The syntax of vararg splices in patterns and function arguments has changed. The ```scala val arr = Array(0, 1, 2, 3) -val lst = List(arr*) // vararg splice argument +val lst = List(arr*) // vararg splice argument lst match - case List(0, 1, xs*) => println(xs) // binds xs to Seq(2, 3) - case List(1, _*) => // wildcard pattern + case List(0, 1, xs*) => println(xs) // binds xs to Seq(2, 3) + case List(1, _*) => // wildcard pattern ``` The old syntax for splice arguments will be phased out. ```scala -/*!*/ val lst = List(arr: _*) // syntax error +/*!*/ val lst = List(arr: _*) // syntax error lst match - case List(1, 2, xs @ _*) // ok, equivalent to `xs*` + case List(0, 1, xs @ _*) // ok, equivalent to `xs*` ``` ## Syntax -``` +```ebnf ArgumentPatterns ::= ‘(’ [Patterns] ‘)’ | ‘(’ [Patterns ‘,’] Pattern2 ‘*’ ‘)’ @@ -37,6 +37,3 @@ To enable cross compilation between Scala 2 and Scala 3, the compiler will accept both the old and the new syntax. Under the `-source future` setting, an error will be emitted when the old syntax is encountered. An automatic rewrite from old to new syntax is offered under `-source future-migration`. - - - diff --git a/docs/docs/reference/metaprogramming/inline.md b/docs/docs/reference/metaprogramming/inline.md index 412ca594b2b5..9bb60a35e0b8 100644 --- a/docs/docs/reference/metaprogramming/inline.md +++ b/docs/docs/reference/metaprogramming/inline.md @@ -285,11 +285,13 @@ val one: 1 = zero + 1 ``` ### Transparent vs. non-transparent inline + As we already discussed, transparent inline methods may influence type checking at call site. Technically this implies that transparent inline methods must be expanded during type checking of the program. Other inline methods are inlined later after the program is fully typed. For example, the following two functions will be typed the same way but will be inlined at different times. + ```scala inline def f1: T = ... transparent inline def f2: T = (...): T @@ -298,7 +300,7 @@ transparent inline def f2: T = (...): T A noteworthy difference is the behavior of `transparent inline given`. If there is an error reported when inlining that definition, it will be considered as an implicit search mismatch and the search will continue. A `transparent inline given` can add a type ascription in its RHS (as in `f2` from the previous example) to avoid the precise type but keep the search behavior. -On the other hand, `inline given` be taken as the implicit and then inlined after typing. +On the other hand, an `inline given` is taken as an implicit and then inlined after typing. Any error will be emitted as usual. ## Inline Conditionals From 3301546f373d0847c2ca15acb0c3305f3dcce0c7 Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 22:46:12 -0800 Subject: [PATCH 2/7] Fix a code example by adding a close parenthesis --- docs/docs/reference/contextual/derivation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/reference/contextual/derivation.md b/docs/docs/reference/contextual/derivation.md index 7f1b7750266b..9a89fad25324 100644 --- a/docs/docs/reference/contextual/derivation.md +++ b/docs/docs/reference/contextual/derivation.md @@ -279,7 +279,7 @@ enum Opt[+T] derives Eq: case Sm(t: T) case Nn -@main def test = +@main def test(): Unit = import Opt.* val eqoi = summon[Eq[Opt[Int]]] assert(eqoi.eqv(Sm(23), Sm(23))) @@ -312,6 +312,7 @@ As a third example, using a higher level library such as Shapeless the type clas given eqSum[A](using inst: => K0.CoproductInstances[Eq, A]): Eq[A] with def eqv(x: A, y: A): Boolean = inst.fold2(x, y)(false)( [t] => (eqt: Eq[t], t0: t, t1: t) => eqt.eqv(t0, t1) + ) given eqProduct[A](using inst: K0.ProductInstances[Eq, A]): Eq[A] with def eqv(x: A, y: A): Boolean = inst.foldLeft2(x, y)(true: Boolean)( @@ -344,7 +345,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}] From d74107f6814efc597631dedc1e68e703c7af2d87 Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 22:50:25 -0800 Subject: [PATCH 3/7] Use _ to simplify some pattern matching code examples --- docs/docs/reference/changed-features/match-syntax.md | 10 +++++----- docs/docs/reference/contextual/extension-methods.md | 12 ++++++++++-- docs/docs/reference/enums/adts.md | 6 +++--- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/docs/reference/changed-features/match-syntax.md b/docs/docs/reference/changed-features/match-syntax.md index 38a469011382..67c2f675a704 100644 --- a/docs/docs/reference/changed-features/match-syntax.md +++ b/docs/docs/reference/changed-features/match-syntax.md @@ -11,9 +11,9 @@ The syntactical precedence of match expressions has been changed. ```scala xs match { case Nil => "empty" - case x :: xs1 => "nonempty" + case _ => "nonempty" } match { - case "empty" => 0 + case "empty" => 0 case "nonempty" => 1 } ``` @@ -23,7 +23,7 @@ The syntactical precedence of match expressions has been changed. ```scala xs match case Nil => "empty" - case x :: xs1 => "nonempty" + case _ => "nonempty" match case "empty" => 0 case "nonempty" => 1 @@ -34,7 +34,7 @@ The syntactical precedence of match expressions has been changed. ```scala if xs.match case Nil => false - case _ => true + case _ => true then "nonempty" else "empty" ``` @@ -46,7 +46,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/contextual/extension-methods.md b/docs/docs/reference/contextual/extension-methods.md index 01c70d578f56..93917e5b9412 100644 --- a/docs/docs/reference/contextual/extension-methods.md +++ b/docs/docs/reference/contextual/extension-methods.md @@ -76,30 +76,38 @@ extension [T: Numeric](x: T) Type parameters on extensions can also be combined with type parameters on the methods themselves: + ```scala extension [T](xs: List[T]) def sumBy[U](f: T => U)(using Numeric[U]): U = ... ``` Type arguments matching method type parameters are passed as usual: + ```scala List("a", "bb", "ccc").sumBy[Int](_.length) ``` + By contrast, type arguments matching type parameters following `extension` can be passed only if the method is referenced as a regular method: + ```scala List[String]("a", "bb", "ccc").sumBy(_.length) ``` + or, passing, both type arguments + ```scala List[String]("a", "bb", "ccc").sumBy[Int](_.length) ``` + Extensions can also take using clauses. For instance, the `+` extension above could equivalently be written with a using clause: ```scala extension [T](x: T)(using n: Numeric[T]) def + (y: T): T = n.plus(x, y) ``` + ### Collective Extensions Sometimes, one wants to define several extension methods that share the same @@ -214,7 +222,7 @@ class List[T]: object List: ... extension [T](xs: List[List[T]]) - def flatten: List[T] = xs.foldLeft(Nil: List[T])(_ ++ _) + def flatten: List[T] = xs.foldLeft(List.empty[T])(_ ++ _) given [T: Ordering]: Ordering[List[T]] with extension (xs: List[T]) @@ -276,7 +284,7 @@ def position(s: String)(ch: Char, n: Int): Int = Here are the syntax changes for extension methods and collective extensions relative to the [current syntax](../syntax.md). -``` +```ebnf BlockStat ::= ... | Extension TemplateStat ::= ... | Extension TopStat ::= ... | Extension diff --git a/docs/docs/reference/enums/adts.md b/docs/docs/reference/enums/adts.md index 6bfb188b349d..00f33c887998 100644 --- a/docs/docs/reference/enums/adts.md +++ b/docs/docs/reference/enums/adts.md @@ -65,7 +65,7 @@ enum Option[+T]: def isDefined: Boolean = this match case None => false - case some => true + case _ => true object Option: @@ -153,7 +153,7 @@ The changes are specified below as deltas with respect to the Scala syntax given 1. Enum definitions are defined as follows: - ``` + ```ebnf TmplDef ::= `enum' EnumDef EnumDef ::= id ClassConstr [`extends' [ConstrApps]] EnumBody EnumBody ::= [nl] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’ @@ -163,7 +163,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) ``` From bb838608d870123bd16855c2b66d64b933d1f412 Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 22:52:40 -0800 Subject: [PATCH 4/7] Fix a comment in a code example --- docs/docs/reference/metaprogramming/inline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/reference/metaprogramming/inline.md b/docs/docs/reference/metaprogramming/inline.md index 9bb60a35e0b8..28d9bf5a89cf 100644 --- a/docs/docs/reference/metaprogramming/inline.md +++ b/docs/docs/reference/metaprogramming/inline.md @@ -176,7 +176,7 @@ Inline methods can override other non-inline methods. The rules are as follows: B.f // OK val a: A = B - a.f // error: cannot inline f() in A. + a.f // error: cannot inline f in A. ``` ### Relationship to `@inline` From 9576c3eed5b54bd21e94a7b6cd4eeebffa17e657 Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 22:56:46 -0800 Subject: [PATCH 5/7] Change some code examples to follow the Scala coding style conventions --- docs/docs/reference/contextual/givens.md | 4 ++-- .../reference/dropped-features/nonlocal-returns.md | 2 +- docs/docs/reference/enums/desugarEnums.md | 12 ++++++------ docs/docs/reference/enums/enums.md | 3 +++ docs/docs/reference/metaprogramming/tasty-inspect.md | 7 +++---- 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/docs/reference/contextual/givens.md b/docs/docs/reference/contextual/givens.md index b289b6cf9bca..08539c081fb7 100644 --- a/docs/docs/reference/contextual/givens.md +++ b/docs/docs/reference/contextual/givens.md @@ -134,7 +134,7 @@ object Foo: given fooTagged[A](using Tagged[A]): Foo[A] = Foo(true) given fooNotTagged[A](using NotGiven[Tagged[A]]): Foo[A] = Foo(false) -@main def test() = +@main def test(): Unit = given Tagged[Int] with {} assert(summon[Foo[Int]].value) // fooTagged is found assert(!summon[Foo[String]].value) // fooNotTagged is found @@ -150,7 +150,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/dropped-features/nonlocal-returns.md b/docs/docs/reference/dropped-features/nonlocal-returns.md index b9b2b37c866b..dd1374c40342 100644 --- a/docs/docs/reference/dropped-features/nonlocal-returns.md +++ b/docs/docs/reference/dropped-features/nonlocal-returns.md @@ -19,7 +19,7 @@ extension [T](xs: List[T]) false } -@main def test = +@main def test(): Unit = val xs = List(1, 2, 3, 4, 5) assert(xs.has(2) == xs.contains(2)) ``` diff --git a/docs/docs/reference/enums/desugarEnums.md b/docs/docs/reference/enums/desugarEnums.md index ea8faf1774ad..6430724e8572 100644 --- a/docs/docs/reference/enums/desugarEnums.md +++ b/docs/docs/reference/enums/desugarEnums.md @@ -127,7 +127,6 @@ map into `case class`es or `val`s. starting from 0. The anonymous class also implements the abstract `Product` methods that it inherits from `Enum`. - It is an error if a value case refers to a type parameter of the enclosing `enum` in a type argument of ``. @@ -198,6 +197,7 @@ Even though translated enum cases are located in the enum's companion object, re this object or its members via `this` or a simple identifier is also illegal. The compiler typechecks enum cases in the scope of the enclosing companion object but flags any such illegal accesses as errors. ### Translation of Java-compatible enums + A Java-compatible enum is an enum that extends `java.lang.Enum`. The translation rules are the same as above, with the reservations defined in this section. It is a compile-time error for a Java-compatible enum to have class cases. @@ -206,9 +206,9 @@ Cases such as `case C` expand to a `@static val` as opposed to a `val`. This all ### Other Rules - - A normal case class which is not produced from an enum case is not allowed to extend -`scala.reflect.Enum`. This ensures that the only cases of an enum are the ones that are -explicitly declared in it. +- A normal case class which is not produced from an enum case is not allowed to extend + `scala.reflect.Enum`. This ensures that the only cases of an enum are the ones that are + explicitly declared in it. - - If an enum case has an `extends` clause, the enum class must be one of the - classes that's extended. +- If an enum case has an `extends` clause, the enum class must be one of the + classes that's extended. diff --git a/docs/docs/reference/enums/enums.md b/docs/docs/reference/enums/enums.md index 219a831a445e..b65d2f1e89a4 100644 --- a/docs/docs/reference/enums/enums.md +++ b/docs/docs/reference/enums/enums.md @@ -93,6 +93,7 @@ end Planet As a library author, you may want to signal that an enum case is no longer intended for use. However you could still want to gracefully handle the removal of a case from your public API, such as special casing deprecated cases. To illustrate, say that the `Planet` enum originally had an additional case: + ```diff enum Planet(mass: Double, radius: Double): ... @@ -128,9 +129,11 @@ object Planet { } } ``` + We could imagine that a library may use [type class derivation](../contextual/derivation.md) to automatically provide an instance for `Deprecations`. ### Compatibility with Java Enums + If you want to use the Scala-defined enums as [Java enums](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html), you can do so by extending the class `java.lang.Enum`, which is imported by default, as follows: diff --git a/docs/docs/reference/metaprogramming/tasty-inspect.md b/docs/docs/reference/metaprogramming/tasty-inspect.md index 757472110ef6..a08e15009af1 100644 --- a/docs/docs/reference/metaprogramming/tasty-inspect.md +++ b/docs/docs/reference/metaprogramming/tasty-inspect.md @@ -22,11 +22,11 @@ import scala.quoted.* import scala.tasty.inspector.* class MyInspector extends Inspector: - def inspect(using Quotes)(tastys: List[Tasty[quotes.type]]): Unit = + def inspect(using Quotes)(tastys: List[Tasty[quotes.type]]): Unit = import quotes.reflect.* for tasty <- tastys do - val tree = tasty.ast - // Do something with the tree + val tree = tasty.ast + // Do something with the tree ``` Then the consumer can be instantiated with the following code to get the tree of the `foo/Bar.tasty` file. @@ -36,7 +36,6 @@ object Test: def main(args: Array[String]): Unit = val tastyFiles = List("foo/Bar.tasty") TastyInspector.inspectTastyFiles(tastyFiles)(new MyInspector) - ``` Note that if we need to run the main (in the example below defined in an object called `Test`) after compilation we need to make the compiler available to the runtime: From 2f48b6eedf735c6a1c3d33ec4a932625ecbc6447 Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 23:32:06 -0800 Subject: [PATCH 6/7] Capitalize the initial letters of words in a title --- docs/docs/reference/dropped-features/wildcard-init.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/docs/reference/dropped-features/wildcard-init.md b/docs/docs/reference/dropped-features/wildcard-init.md index 0241d07651ee..bf8e60976057 100644 --- a/docs/docs/reference/dropped-features/wildcard-init.md +++ b/docs/docs/reference/dropped-features/wildcard-init.md @@ -1,18 +1,22 @@ --- layout: doc-page -title: "Dropped: wildcard initializer" +title: "Dropped: Wildcard Initializer" --- The syntax + ```scala var x: A = _ ``` + that was used to indicate an uninitialized field, has been dropped. -At its place there is a special value `uninitialized` in the `scala.compiletime` package. To get an uninitialized field, you now write +At its place there is a special value `uninitialized` in the `scala.compiletime` package. +To get an uninitialized field, you now write + ```scala import scala.compiletime.uninitialized var x: A = uninitialized ``` -To enable cross-compilation, `_` is still supported, but it will be dropped in a future 3.x version. +To enable cross-compilation, `_` is still supported, but it will be dropped in a future 3.x version. From a1fdf1ee37c08354b826cb58610930895a263f01 Mon Sep 17 00:00:00 2001 From: "Lan, Jian" Date: Mon, 15 Feb 2021 23:59:49 -0800 Subject: [PATCH 7/7] Change the way of writing a extension method header - This subsection explains generic extensions WITHOUT using clause(s) first, and then explains generic extensions WITH using clause(s). The changed code is for the first part, and don't introduce using clause(s) in it is more suitable in this context. --- docs/docs/reference/contextual/extension-methods.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/reference/contextual/extension-methods.md b/docs/docs/reference/contextual/extension-methods.md index 93917e5b9412..b0ea37effa4c 100644 --- a/docs/docs/reference/contextual/extension-methods.md +++ b/docs/docs/reference/contextual/extension-methods.md @@ -79,7 +79,7 @@ themselves: ```scala extension [T](xs: List[T]) - def sumBy[U](f: T => U)(using Numeric[U]): U = ... + def sumBy[U: Numeric](f: T => U): U = ... ``` Type arguments matching method type parameters are passed as usual: