Sketch pattern matching documentation

Author: OlivierBlanvillain

docs/docs/reference/pattern-matching.md

@@ -0,0 +1,52 @@
+---
+layout: doc-page
+title: "Option-less pattern matching"
+---
+
+Dotty pattern matching supports the following [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns):
+
+Boolean Pattern
+
+- Extractor defines `def unapply(x: T): Boolean`
+- Pattern-matching on exactly `0` patterns
+
+Product Pattern
+
+- Extractor defines `def unapply(x: T): U`
+- `U <: Product`
+- `N > 0` is the maximum number of consecutive (parameterless `def` or `val`) `_1: P1` ... `_N: PN` members in `U`
+- Pattern-matching on exactly `N` patterns with types `P1, P2, ..., PN`
+
+Seq Pattern
+
+- Extractor defines `def unapplySeq(x: T): U`
+- `U` has (parameterless `def` or `val`) members `isEmpty: Boolean` and `get: S`
+- `S <: Seq[V]`
+- Pattern-matching on any number of pattern with types `V, V, ..., V`
+
+Name Based Pattern
+
+- Extractor defines `def unapply(x: T): U`
+- `U` has (parameterless `def` or `val`) members `isEmpty: Boolean` and `get: S`
+- If there is exactly `1` pattern, pattern-matching on `1` pattern with type `S`
+- Otherwise `N > 0` is the maximum number of consecutive (parameterless `def` or `val`) `_1: P1` ... `_N: PN` members in `U`
+- Pattern-matching on exactly `N` patterns with types `P1, P2, ..., PN`
+
+In case of ambiguities, *Product Pattern* is preferred over *Name Based Pattern*.
+
+Dotty pattern matching is not special cased to case classes. Instead, allocation of Tuples and Options is avoided by desugaring case classes to use a *Product Pattern* extractor:
+
+```scala
+case class CC(i: Int, s: String)
+```
+
+becomes
+
+```scala
+class CC(val i: Int, val s: String) extends Product { ... }
+
+object {
+  def apply(i: Int, s: String): CC = new CC(i, s)
+  def unapply(cc: CC): CC = cc
+}
+```