Sketch pattern matching documentation

Author: OlivierBlanvillain

docs/docs/index.md

@@ -3,9 +3,9 @@ layout: doc-page
 title: "Dotty Documentation"
 ---
 
-Dotty is a platform to try out new language concepts and compiler technologies for Scala. 
-The focus is mainly on simplification. We remove extraneous syntax (e.g. no XML literals), 
-and try to boil down Scala’s types into a smaller set of more fundamental constructors. 
+Dotty is a platform to try out new language concepts and compiler technologies for Scala.
+The focus is mainly on simplification. We remove extraneous syntax (e.g. no XML literals),
+and try to boil down Scala’s types into a smaller set of more fundamental constructors.
 The theory behind these constructors is researched in DOT, a calculus for dependent object types.
 
 In this documentation you will find information on how to use the Dotty compiler on your machine, navigate through
@@ -22,6 +22,7 @@ Contents
     - [Algebraic Data Types](reference/adts.md)
     - [Enum Translation](reference/desugarEnums.md)
     - [By-Name Implicits](reference/implicit-by-name-parameters.md)
+    - [Option-less pattern matching](reference/pattern-matching.md)
 * Usage
     - [Migrating from Scala 2](usage/migrating.md): migration information
     - [Dotty projects with sbt](usage/sbt-projects.md): using sbt
@@ -32,7 +33,7 @@ Contents
     - [Workflow](contributing/workflow.md): common dev patterns and hints
     - [Eclipse](contributing/eclipse.md): setting up dev environment
     - [Intellij-IDEA](contributing/intellij-idea.md): setting up dev environment
-    - [Working with the Backend](contributing/backend.md): working with the scala backend 
+    - [Working with the Backend](contributing/backend.md): working with the scala backend
 * Internals document the compiler internals
     - [Syntax Summary](internals/syntax.md): brief analysis of the syntax
     - [Project Structure](internals/overall-structure.md): of the project

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
+}
+```

docs/sidebar.yml

@@ -17,6 +17,8 @@ sidebar:
           url: docs/reference/desugarEnums.html
         - title: By-Name Implicits
           url: docs/reference/implicit-by-name-parameters.html
+        - title: Option-less pattern matching
+          url: docs/reference/pattern-matching.html
     - title: Usage
       subsection:
         - title: sbt-projects