Add doc page

Author: odersky

docs/docs/reference/changed-features/pattern-bindings.md

@@ -0,0 +1,64 @@
+---
+layout: doc-page
+title: "Pattern Bindings"
+---
+
+In Scala 2, pattern bindings in `val` definitions and `for` expressions are
+loosely typed. Potentially failing matches are still accepted at compile-time,
+but may influence the program's runtime behavior.
+From Scala 3.1 on, type checking rules will be tightened so that errors are reported at compile-time instead.
+
+## Bindings in Pattern Definitions
+
+```scala
+  val xs: List[Any] = List(1, 2, 3)
+  val (x: String) :: _ xs     // error: pattern's type String is more specialized
+                              // than the right hand side expression's type Any
+```
+This code gives a compile-time error in Scala 3.1 (and also in Scala 3.0 under the `-strict` setting) whereas it will fail at runtime with a `ClassCastException` in Scala 2. In Scala 3.1, a pattern binding is only allowed if the pattern is _irrefutable_, that is, if the right-hand side's type conforms to the pattern's type. For instance, the following is OK:
+```scala
+  val pair = (1, true)
+  val (x, y) = pair
+```
+Sometimes one wants to decompose data anyway, even though the pattern is refutable. For instance, if at some point one knows that a list `elems` is non-empty one might
+want to decompose it like this:
+```scala
+  val first :: rest = elems   // error
+```
+This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.1 it will give a type error. One can avoid the error by marking the pattern with an @unchecked annotation:
+```scala
+  val first :: rest : @unchecked = elems   // OK
+```
+This will make the compiler accept the pattern binding. It might give an error at runtime instead, if the underlying assumption that `elems` can never be empty is wrong.
+
+## Pattern Bindings in For Expressions
+
+Analogous changes apply to patterns in `for` expressions. For instance:
+
+```scala
+  val elems: List[Any] = List((1, 2), "hello", (3, 4))
+  for ((x, y) <- elems) yield (y, x) // error: pattern's type (Any, Any) is more specialized
+                                     // than the right hand side expression's type Any
+```
+This code gives a compile-time error in Scala 3.1 whereas in Scala 2 the list `elems`
+is filtered to retain only the elements of tuple type that match the pattern `(x, y)`.
+The filtering functionality can be obtained in Scala 3 by prefixing the pattern with `case`:
+```scala
+  for (case (x, y) <- elems) yield (y, x)  // returns List((2, 1), (4, 3))
+```
+
+## Syntax Changes
+
+There are two syntax changes relative to Scala 2: First, pattern definitions can carry ascriptions such as `: unchecked`. Second, generators in for expressions may be prefixed with `case`.
+```
+  PatDef         ::=  ids [‘:’ Type] ‘=’ Expr
+                   |  Pattern2 [‘:’ Type | Ascription] ‘=’ Expr
+  Generator      ::=  [‘case’] Pattern1 ‘<-’ Expr
+```
+
+## Migration
+
+The new syntax is supported in Dotty and Scala 3.0. However, to enable smooth cross compilation between Scala 2 and Scala 3, the changed behavior and additional type checks are only enabled under the `-strict` setting. They will be enabled by default in version 3.1 of the language.
+
+
+

docs/sidebar.yml

@@ -107,7 +107,9 @@ sidebar:
               url: docs/reference/changed-features/overload-resolution.html
             - title: Vararg Patterns
               url: docs/reference/changed-features/vararg-patterns.html
-            - title: Pattern matching
+            - title: Pattern Bindings
+              url: docs/reference/changed-features/pattern-bindings.html
+            - title: Pattern Matching
               url: docs/reference/changed-features/pattern-matching.html
             - title: Eta Expansion
               url: docs/reference/changed-features/eta-expansion.html

tests/neg-strict/filtering-fors.scala

@@ -16,6 +16,9 @@ object Test {
   for (case (x: String) <- xs; (y, z) <- xs) do () // error
   for ((x: String) <- xs; case (y, z) <- xs) do () // error
 
+  val pairs: List[Any] = List((1, 2), (3, 4))
+  for ((x, y) <- pairs) yield (y, x) // error
+
   for (case x: String <- xs) do ()      // OK
   for (case (x: String) <- xs) do ()    // OK
   for (case y@ (x: String) <- xs) do () // OK
@@ -24,4 +27,6 @@ object Test {
   for (case (x: String) <- xs if x.isEmpty) do ()   // OK
   for (case (x: String) <- xs; y = x) do ()          // OK
   for (case (x: String) <- xs; case (y, z) <- xs) do ()   // OK
+
+  for (case (x, y) <- pairs) yield (y, x) // OK
 }