Improve documentation for -XStrict
authorSimon Peyton Jones <simonpj@microsoft.com>
Tue, 15 Dec 2015 14:19:52 +0000 (14:19 +0000)
committerSimon Peyton Jones <simonpj@microsoft.com>
Tue, 15 Dec 2015 14:33:32 +0000 (14:33 +0000)
In particular, highlight that we do not put bangs on nested patterns

docs/users_guide/glasgow_exts.rst

index 853397a..566ecda 100644 (file)
@@ -12917,27 +12917,17 @@ optionally had by adding ``!`` in front of a variable.
      let !pat = ...
 
    Adding ``~`` in front of ``x`` gives the regular lazy
-   behavior. Notice that we do not put bangs on nested patterns. For
-   example ::
-
-     let (p,q) = if flob then (undefined, undefined) else (True, False)
-     in ...
-
-   will behave like ::
-
-     let !(p,q) = if flob then (undefined, undefined) else (True,False)
-     in ...
+   behavior.
+   The general rule is that we add an implicit bang on the outermost pattern,
+   unless disabled with ``~``.
 
-   which will strictly evaluate the right hand side, and bind ``p``
-   and ``q`` to the components of the pair. But the pair itself is
-   lazy (unless we also compile the ``Prelude`` with ``Strict``; see
-   :ref:`strict-modularity` below). So ``p`` and ``q`` may end up bound to
-   undefined. See also :ref:`recursive-and-polymorphic-let-bindings` below.
+-  **Pattern matching in case expressions, lambdas, do-notation, etc**
 
--  **Case expressions.**
-
-   The patterns of a case expression get an implicit bang, unless
-   disabled with ``~``. For example ::
+   The outermost pattern of all pattern matches gets an implicit bang,
+   unless disabled with ``~``.
+   This applies to case expressions, patterns in lambda, do-notation,
+   list comprehension, and so on.
+   For example ::
 
        case x of (a,b) -> rhs
 
@@ -12962,6 +12952,33 @@ optionally had by adding ``!`` in front of a variable.
    is lazy in Haskell; but with ``Strict`` the added bang makes it
    strict.
 
+   Similarly ::
+
+      \ x -> body
+      do { x <- rhs; blah }
+      [ e | x <- rhs; blah }
+
+   all get implicit bangs on the ``x`` pattern.
+
+-  ** Nested patterns **
+
+   Notice that we do *not* put bangs on nested patterns. For
+   example ::
+
+     let (p,q) = if flob then (undefined, undefined) else (True, False)
+     in ...
+
+   will behave like ::
+
+     let !(p,q) = if flob then (undefined, undefined) else (True,False)
+     in ...
+
+   which will strictly evaluate the right hand side, and bind ``p``
+   and ``q`` to the components of the pair. But the pair itself is
+   lazy (unless we also compile the ``Prelude`` with ``Strict``; see
+   :ref:`strict-modularity` below). So ``p`` and ``q`` may end up bound to
+   undefined. See also :ref:`recursive-and-polymorphic-let-bindings` below.
+
 -  **Top level bindings.**
 
    are unaffected by ``Strict``. For example: ::