Implement \cases (Proposal 302)

This commit implements proposal 302: \cases - Multi-way lambda
expressions.

This adds a new expression heralded by \cases, which works exactly like
\case, but can match multiple apats instead of a single pat.

Updates submodule haddock to support the ITlcases token.

Closes #20768

3 files changed, 25 insertions, 5 deletions

diff --git a/docs/users_guide/9.4.1-notes.rst b/docs/users_guide/9.4.1-notes.rst
index 2576a21cea..91d866d982 100644
--- a/docs/users_guide/9.4.1-notes.rst
+++ b/docs/users_guide/9.4.1-notes.rst
@@ -41,6 +41,12 @@ Language
     re-exported from ``Prelude``. When ``(~)`` is not in scope, its use results
     in a warning (:ghc-flag:`-Wtype-equality-out-of-scope`).
 
+- GHC Proposal `#302 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0302-cases.rst>`_ has been implemented.
+  This means under ``-XLambdaCase``, a new expression heralded by ``\cases`` is
+  available, which works like ``\case`` but can match on multiple patterns.
+  This means constructor patterns with arguments have to parenthesized here,
+  just like in lambda expressions.
+
 - There were previously cases around functional dependencies and injective
   type families where the result of type inference would depend on the order
   of constraints, as written in a source file. These cases are fundamentally ambiguous.
diff --git a/docs/users_guide/exts/empty_case.rst b/docs/users_guide/exts/empty_case.rst
index c42de22e9e..7a32f609e6 100644
--- a/docs/users_guide/exts/empty_case.rst
+++ b/docs/users_guide/exts/empty_case.rst
@@ -19,6 +19,9 @@ or ::
 
     \case { }       -- -XLambdaCase is also required
 
+Note that it is not allowed for ``\cases``, since it would be unclear how many
+patterns are being matched.
+
 This can be useful when you know that the expression being scrutinised
 has no non-bottom values. For example:
 
@@ -45,5 +48,3 @@ We much prefer (B). Why? Because GHC can figure out that
 is able to compile with :ghc-flag:`-Wincomplete-patterns` and
 :ghc-flag:`-Werror`. On the other hand (A) looks dangerous, and GHC doesn't
 check to make sure that, in fact, the function can never get called.
-
-
diff --git a/docs/users_guide/exts/lambda_case.rst b/docs/users_guide/exts/lambda_case.rst
index 74bc84e164..6872101698 100644
--- a/docs/users_guide/exts/lambda_case.rst
+++ b/docs/users_guide/exts/lambda_case.rst
@@ -18,7 +18,20 @@ which is equivalent to ::
 
       \freshName -> case freshName of { p1 -> e1; ...; pN -> eN }
 
-Note that ``\case`` starts a layout, so you can write ::
+Since GHC 9.4.1, it also allow expressions with multiple scrutinees (see GHC
+proposal `#302 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0302-cases.rst>`_)
+of the form ::
+
+      \cases { p11 ... pM1 -> e1; ...; p1N ... pMN -> eN }
+
+which is equivalent to a function defined as
+
+      f p11 ... pM1 -> e1
+      ...
+      f p1N ... pMN -> eN
+
+
+Note that both ``\case`` and ``\cases`` start a layout, so you can write ::
 
       \case
         p1 -> e1
@@ -26,8 +39,8 @@ Note that ``\case`` starts a layout, so you can write ::
         pN -> eN
 
 Additionally, since GHC 9.0.1, combining :extension:`LambdaCase` with
-:extension:`Arrows` allows ``\case`` syntax to be used as a command in
-``proc`` notation: ::
+:extension:`Arrows` allows ``\case`` (and since GHC 9.4.1 ``\cases``)
+syntax to be used as a command in ``proc`` notation: ::
 
       proc x -> (f -< x) `catchA` \case
         p1 -> cmd1