User manual improvments
authorSimon Peyton Jones <simonpj@microsoft.com>
Fri, 12 Feb 2016 14:38:22 +0000 (14:38 +0000)
committerSimon Peyton Jones <simonpj@microsoft.com>
Fri, 12 Feb 2016 17:37:11 +0000 (17:37 +0000)
- Document that you can use 'forall' in instance decls

- Change the sections a bit, so that big sections (like
  lexically scoped type variables, pattern synonyms,
  implicit parameters) become more visible

docs/users_guide/glasgow_exts.rst

index 774805b..481ff5f 100644 (file)
@@ -617,3833 +617,3833 @@ follows:
    alpha-equivalence, so two instances of ``(x, view x -> y)`` will not
    be coalesced.
 
-.. _pattern-synonyms:
-
-Pattern synonyms
-----------------
+.. _n-k-patterns:
 
-.. ghc-flag:: -XPatternSynonyms
+n+k patterns
+------------
 
-    :since: 7.8.1
+.. ghc-flag:: -XNPlusKPatterns
 
-    Allow the definition of pattern synonyms.
+    Enable use of ``n+k`` patterns.
 
-Pattern synonyms are enabled by the flag :ghc-flag:`-XPatternSynonyms`, which is
-required for defining them, but *not* for using them. More information
-and examples of view patterns can be found on the
-`Wiki page <PatternSynonyms>`.
+.. _recursive-do-notation:
 
-Pattern synonyms enable giving names to parametrized pattern schemes.
-They can also be thought of as abstract constructors that don't have a
-bearing on data representation. For example, in a programming language
-implementation, we might represent types of the language as follows: ::
+The recursive do-notation
+-------------------------
 
-    data Type = App String [Type]
+.. ghc-flag:: -XRecursiveDo
 
-Here are some examples of using said representation. Consider a few
-types of the ``Type`` universe encoded like this: ::
+    Allow the use of recursive ``do`` notation.
 
-      App "->" [t1, t2]          -- t1 -> t2
-      App "Int" []               -- Int
-      App "Maybe" [App "Int" []] -- Maybe Int
+The do-notation of Haskell 98 does not allow *recursive bindings*, that
+is, the variables bound in a do-expression are visible only in the
+textually following code block. Compare this to a let-expression, where
+bound variables are visible in the entire binding group.
 
-This representation is very generic in that no types are given special
-treatment. However, some functions might need to handle some known types
-specially, for example the following two functions collect all argument
-types of (nested) arrow types, and recognize the ``Int`` type,
-respectively: ::
+It turns out that such recursive bindings do indeed make sense for a
+variety of monads, but not all. In particular, recursion in this sense
+requires a fixed-point operator for the underlying monad, captured by
+the ``mfix`` method of the ``MonadFix`` class, defined in
+``Control.Monad.Fix`` as follows: ::
 
-      collectArgs :: Type -> [Type]
-      collectArgs (App "->" [t1, t2]) = t1 : collectArgs t2
-      collectArgs _                   = []
+    class Monad m => MonadFix m where
+       mfix :: (a -> m a) -> m a
 
-      isInt :: Type -> Bool
-      isInt (App "Int" []) = True
-      isInt _              = False
+Haskell's ``Maybe``, ``[]`` (list), ``ST`` (both strict and lazy
+versions), ``IO``, and many other monads have ``MonadFix`` instances. On
+the negative side, the continuation monad, with the signature
+``(a -> r) -> r``, does not.
 
-Matching on ``App`` directly is both hard to read and error prone to
-write. And the situation is even worse when the matching is nested: ::
+For monads that do belong to the ``MonadFix`` class, GHC provides an
+extended version of the do-notation that allows recursive bindings. The
+:ghc-flag:`-XRecursiveDo` (language pragma: ``RecursiveDo``) provides the
+necessary syntactic support, introducing the keywords ``mdo`` and
+``rec`` for higher and lower levels of the notation respectively. Unlike
+bindings in a ``do`` expression, those introduced by ``mdo`` and ``rec``
+are recursively defined, much like in an ordinary let-expression. Due to
+the new keyword ``mdo``, we also call this notation the *mdo-notation*.
 
-      isIntEndo :: Type -> Bool
-      isIntEndo (App "->" [App "Int" [], App "Int" []]) = True
-      isIntEndo _                                       = False
+Here is a simple (albeit contrived) example:
 
-Pattern synonyms permit abstracting from the representation to expose
-matchers that behave in a constructor-like manner with respect to
-pattern matching. We can create pattern synonyms for the known types we
-care about, without committing the representation to them (note that
-these don't have to be defined in the same module as the ``Type`` type): ::
+::
 
-      pattern Arrow t1 t2 = App "->"    [t1, t2]
-      pattern Int         = App "Int"   []
-      pattern Maybe t     = App "Maybe" [t]
+    {-# LANGUAGE RecursiveDo #-}
+    justOnes = mdo { xs <- Just (1:xs)
+                   ; return (map negate xs) }
 
-Which enables us to rewrite our functions in a much cleaner style: ::
+or equivalently
 
-      collectArgs :: Type -> [Type]
-      collectArgs (Arrow t1 t2) = t1 : collectArgs t2
-      collectArgs _             = []
+::
 
-      isInt :: Type -> Bool
-      isInt Int = True
-      isInt _   = False
+    {-# LANGUAGE RecursiveDo #-}
+    justOnes = do { rec { xs <- Just (1:xs) }
+                  ; return (map negate xs) }
 
-      isIntEndo :: Type -> Bool
-      isIntEndo (Arrow Int Int) = True
-      isIntEndo _               = False
+As you can guess ``justOnes`` will evaluate to ``Just [-1,-1,-1,...``.
 
-In general there are three kinds of pattern synonyms. Unidirectional,
-bidirectional and explicitly bidirectional. The examples given so far are
-examples of bidirectional pattern synonyms. A bidirectional synonym
-behaves the same as an ordinary data constructor. We can use it in a pattern
-context to deconstruct values and in an expression context to construct values.
-For example, we can construct the value `intEndo` using the pattern synonyms
-`Arrow` and `Int` as defined previously. ::
+GHC's implementation the mdo-notation closely follows the original
+translation as described in the paper `A recursive do for
+Haskell <https://sites.google.com/site/leventerkok/recdo.pdf>`__, which
+in turn is based on the work `Value Recursion in Monadic
+Computations <http://sites.google.com/site/leventerkok/erkok-thesis.pdf>`__.
+Furthermore, GHC extends the syntax described in the former paper with a
+lower level syntax flagged by the ``rec`` keyword, as we describe next.
 
-      intEndo :: Type
-      intEndo = Arrow Int Int
+Recursive binding groups
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-This example is equivalent to the much more complicated construction if we had
-directly used the `Type` constructors. ::
+The flag :ghc-flag:`-XRecursiveDo` also introduces a new keyword ``rec``, which
+wraps a mutually-recursive group of monadic statements inside a ``do``
+expression, producing a single statement. Similar to a ``let`` statement
+inside a ``do``, variables bound in the ``rec`` are visible throughout
+the ``rec`` group, and below it. For example, compare
 
-      intEndo :: Type
-      intEndo = App "->" [App "Int" [], App "Int" []]
+::
 
+        do { a <- getChar            do { a <- getChar
+           ; let { r1 = f a r2          ; rec { r1 <- f a r2
+           ;     ; r2 = g r1 }          ;     ; r2 <- g r1 }
+           ; return (r1 ++ r2) }        ; return (r1 ++ r2) }
 
-Unidirectional synonyms can only be used in a pattern context and are
-defined as follows:
+In both cases, ``r1`` and ``r2`` are available both throughout the
+``let`` or ``rec`` block, and in the statements that follow it. The
+difference is that ``let`` is non-monadic, while ``rec`` is monadic. (In
+Haskell ``let`` is really ``letrec``, of course.)
 
+The semantics of ``rec`` is fairly straightforward. Whenever GHC finds a
+``rec`` group, it will compute its set of bound variables, and will
+introduce an appropriate call to the underlying monadic value-recursion
+operator ``mfix``, belonging to the ``MonadFix`` class. Here is an
+example:
 
 ::
 
-      pattern Head x <- x:xs
+    rec { b <- f a c     ===>    (b,c) <- mfix (\ ~(b,c) -> do { b <- f a c
+        ; c <- f b a }                                         ; c <- f b a
+                                                               ; return (b,c) })
 
-In this case, ``Head`` ⟨x⟩ cannot be used in expressions, only patterns,
-since it wouldn't specify a value for the ⟨xs⟩ on the right-hand side. However,
-we can define an explicitly bidirectional pattern synonym by separately
-specifying how to construct and deconstruct a type. The syntax for
-doing this is as follows:
+As usual, the meta-variables ``b``, ``c`` etc., can be arbitrary
+patterns. In general, the statement ``rec ss`` is desugared to the
+statement
 
 ::
 
-      pattern HeadC x <- x:xs where
-        HeadC x = [x]
+    vs <- mfix (\ ~vs -> do { ss; return vs })
 
-We can then use ``HeadC`` in both expression and pattern contexts. In a pattern
-context it will match the head of any list with length at least one. In an
-expression context it will construct a singleton list.
+where ``vs`` is a tuple of the variables bound by ``ss``.
 
-The table below summarises where each kind of pattern synonym can be used.
+Note in particular that the translation for a ``rec`` block only
+involves wrapping a call to ``mfix``: it performs no other analysis on
+the bindings. The latter is the task for the ``mdo`` notation, which is
+described next.
 
-+---------------+----------------+---------------+---------------------------+
-| Context       | Unidirectional | Bidirectional | Explicitly Bidirectional  |
-+===============+================+===============+===========================+
-| Pattern       | Yes            | Yes           | Yes                       |
-+---------------+----------------+---------------+---------------------------+
-| Expression    | No             | Yes (Inferred)| Yes (Explicit)            |
-+---------------+----------------+---------------+---------------------------+
+The ``mdo`` notation
+~~~~~~~~~~~~~~~~~~~~
 
-.. _record-patsyn:
+A ``rec``-block tells the compiler where precisely the recursive knot
+should be tied. It turns out that the placement of the recursive knots
+can be rather delicate: in particular, we would like the knots to be
+wrapped around as minimal groups as possible. This process is known as
+*segmentation*, and is described in detail in Section 3.2 of `A
+recursive do for
+Haskell <https://sites.google.com/site/leventerkok/recdo.pdf>`__.
+Segmentation improves polymorphism and reduces the size of the recursive
+knot. Most importantly, it avoids unnecessary interference caused by a
+fundamental issue with the so-called *right-shrinking* axiom for monadic
+recursion. In brief, most monads of interest (IO, strict state, etc.) do
+*not* have recursion operators that satisfy this axiom, and thus not
+performing segmentation can cause unnecessary interference, changing the
+termination behavior of the resulting translation. (Details can be found
+in Sections 3.1 and 7.2.2 of `Value Recursion in Monadic
+Computations <http://sites.google.com/site/leventerkok/erkok-thesis.pdf>`__.)
 
-Record Pattern Synonyms
-~~~~~~~~~~~~~~~~~~~~~~~
+The ``mdo`` notation removes the burden of placing explicit ``rec``
+blocks in the code. Unlike an ordinary ``do`` expression, in which
+variables bound by statements are only in scope for later statements,
+variables bound in an ``mdo`` expression are in scope for all statements
+of the expression. The compiler then automatically identifies minimal
+mutually recursively dependent segments of statements, treating them as
+if the user had wrapped a ``rec`` qualifier around them.
 
-It is also possible to define pattern synonyms which behave just like record
-constructors. The syntax for doing this is as follows:
+The definition is syntactic:
 
-::
+-  A generator ⟨g⟩ *depends* on a textually following generator ⟨g'⟩, if
 
-      pattern Point :: (Int, Int)
-      pattern Point{x, y} = (x, y)
+   -  ⟨g'⟩ defines a variable that is used by ⟨g⟩, or
 
-The idea is that we can then use ``Point`` just as if we had defined a new
-datatype ``MyPoint`` with two fields ``x`` and ``y``.
+   -  ⟨g'⟩ textually appears between ⟨g⟩ and ⟨g''⟩, where ⟨g⟩ depends on
+      ⟨g''⟩.
 
-::
+-  A *segment* of a given ``mdo``-expression is a minimal sequence of
+   generators such that no generator of the sequence depends on an
+   outside generator. As a special case, although it is not a generator,
+   the final expression in an ``mdo``-expression is considered to form a
+   segment by itself.
 
-    data MyPoint = Point { x :: Int, y :: Int }
+Segments in this sense are related to *strongly-connected components*
+analysis, with the exception that bindings in a segment cannot be
+reordered and must be contiguous.
 
-Whilst a normal pattern synonym can be used in two ways, there are then seven
-ways in which to use ``Point``. Precisely the ways in which a normal record
-constructor can be used.
+Here is an example ``mdo``-expression, and its translation to ``rec``
+blocks:
 
-=======================================   ==================================
-Usage                                     Example
-=======================================   ==================================
-As a constructor                          ``zero = Point 0 0``
-As a constructor with record syntax       ``zero = Point { x = 0, y = 0}``
-In a pattern context                      ``isZero (Point 0 0) = True``
-In a pattern context with record syntax   ``isZero (Point { x = 0, y = 0 }``
-In a pattern context with field puns      ``getX (Point {x}) = x``
-In a record update                        ``(0, 0) { x = 1 } == (1,0)``
-Using record selectors                    ``x (0,0) == 0``
-=======================================   ==================================
+::
 
-For a unidirectional record pattern synonym we define record selectors but do
-not allow record updates or construction.
+    mdo { a <- getChar      ===> do { a <- getChar
+        ; b <- f a c                ; rec { b <- f a c
+        ; c <- f b a                ;     ; c <- f b a }
+        ; z <- h a b                ; z <- h a b
+        ; d <- g d e                ; rec { d <- g d e
+        ; e <- g a z                ;     ; e <- g a z }
+        ; putChar c }               ; putChar c }
 
-The syntax and semantics of pattern synonyms are elaborated in the
-following subsections. See the :ghc-wiki:`Wiki page <PatternSynonyms>` for more
-details.
+Note that a given ``mdo`` expression can cause the creation of multiple
+``rec`` blocks. If there are no recursive dependencies, ``mdo`` will
+introduce no ``rec`` blocks. In this latter case an ``mdo`` expression
+is precisely the same as a ``do`` expression, as one would expect.
 
-Syntax and scoping of pattern synonyms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In summary, given an ``mdo`` expression, GHC first performs
+segmentation, introducing ``rec`` blocks to wrap over minimal recursive
+groups. Then, each resulting ``rec`` is desugared, using a call to
+``Control.Monad.Fix.mfix`` as described in the previous section. The
+original ``mdo``-expression typechecks exactly when the desugared
+version would do so.
 
-A pattern synonym declaration can be either unidirectional,
-bidirectional or explicitly bidirectional.
-The syntax for unidirectional pattern synonyms is: ::
+Here are some other important points in using the recursive-do notation:
 
-      pattern pat_lhs <- pat
+-  It is enabled with the flag :ghc-flag:`-XRecursiveDo`, or the
+   ``LANGUAGE RecursiveDo`` pragma. (The same flag enables both
+   ``mdo``-notation, and the use of ``rec`` blocks inside ``do``
+   expressions.)
 
-the syntax for bidirectional pattern synonyms is: ::
+-  ``rec`` blocks can also be used inside ``mdo``-expressions, which
+   will be treated as a single statement. However, it is good style to
+   either use ``mdo`` or ``rec`` blocks in a single expression.
 
-      pattern pat_lhs = pat
+-  If recursive bindings are required for a monad, then that monad must
+   be declared an instance of the ``MonadFix`` class.
 
-and the syntax for explicitly bidirectional pattern synonyms is: ::
+-  The following instances of ``MonadFix`` are automatically provided:
+   List, Maybe, IO. Furthermore, the ``Control.Monad.ST`` and
+   ``Control.Monad.ST.Lazy`` modules provide the instances of the
+   ``MonadFix`` class for Haskell's internal state monad (strict and
+   lazy, respectively).
 
-      pattern pat_lhs <- pat where
-        pat_lhs = expr
+-  Like ``let`` and ``where`` bindings, name shadowing is not allowed
+   within an ``mdo``-expression or a ``rec``-block; that is, all the
+   names bound in a single ``rec`` must be distinct. (GHC will complain
+   if this is not the case.)
 
-We can define either prefix, infix or record pattern synonyms by modifying
-the form of `pat_lhs`. The syntax for these is as follows:
+.. _applicative-do:
 
-======= ============================
-Prefix  ``Name args``
-------- ----------------------------
-Infix   ``arg1 `Name` arg2``
-        or ``arg1 op arg2``
-------- ----------------------------
-Record  ``Name{arg1,arg2,...,argn}``
-======= ============================
+Applicative do-notation
+-----------------------
 
+.. index::
+   single: Applicative do-notation
+   single: do-notation; Applicative
 
-Pattern synonym declarations can only occur in the top level of a
-module. In particular, they are not allowed as local definitions.
+.. ghc-flag:: -XApplicativeDo
 
-The variables in the left-hand side of the definition are bound by the
-pattern on the right-hand side. For bidirectional pattern
-synonyms, all the variables of the right-hand side must also occur on
-the left-hand side; also, wildcard patterns and view patterns are not
-allowed. For unidirectional and explicitly bidirectional pattern
-synonyms, there is no restriction on the right-hand side pattern.
+    :since: 8.0.1
 
-Pattern synonyms cannot be defined recursively.
+    Allow use of ``Applicative`` ``do`` notation.
 
-.. _patsyn-impexp:
+The language option :ghc-flag:`-XApplicativeDo` enables an alternative translation for
+the do-notation, which uses the operators ``<$>``, ``<*>``, along with ``join``
+as far as possible. There are two main reasons for wanting to do this:
 
-Import and export of pattern synonyms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-  We can use do-notation with types that are an instance of ``Applicative`` and
+   ``Functor``, but not ``Monad``
+-  In some monads, using the applicative operators is more efficient than monadic
+   bind. For example, it may enable more parallelism.
 
-The name of the pattern synonym is in the same namespace as proper data
-constructors. Like normal data constructors, pattern synonyms can be imported
-and exported through association with a type constructor or independently.
+Applicative do-notation desugaring preserves the original semantics, provided
+that the ``Applicative`` instance satisfies ``<*> = ap`` and ``pure = return``
+(these are true of all the common monadic types). Thus, you can normally turn on
+:ghc-flag:`-XApplicativeDo` without fear of breaking your program. There is one pitfall
+to watch out for; see :ref:`applicative-do-pitfall`.
 
-To export them on their own, in an export or import specification, you must
-prefix pattern names with the ``pattern`` keyword, e.g.: ::
+There are no syntactic changes with :ghc-flag:`-XApplicativeDo`. The only way it shows
+up at the source level is that you can have a ``do`` expression that doesn't
+require a ``Monad`` constraint. For example, in GHCi: ::
 
-      module Example (pattern Zero) where
+    Prelude> :set -XApplicativeDo
+    Prelude> :t \m -> do { x <- m; return (not x) }
+    \m -> do { x <- m; return (not x) }
+      :: Functor f => f Bool -> f Bool
 
-      data MyNum = MkNum Int
+This example only requires ``Functor``, because it is translated into ``(\x ->
+not x) <$> m``. A more complex example requires ``Applicative``, ::
 
-      pattern Zero :: MyNum
-      pattern Zero = MkNum 0
+    Prelude> :t \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) }
+    \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) }
+      :: Applicative f => (Char -> f Bool) -> f Bool
 
-Without the ``pattern`` prefix, ``Zero`` would be interpreted as a
-type constructor in the export list.
+Here GHC has translated the expression into ::
 
-You may also use the ``pattern`` keyword in an import/export
-specification to import or export an ordinary data constructor. For
-example: ::
+    (\x y -> x || y) <$> m 'a' <*> m 'b'
 
-      import Data.Maybe( pattern Just )
+It is possible to see the actual translation by using :ghc-flag:`-ddump-ds`, but be
+warned, the output is quite verbose.
 
-would bring into scope the data constructor ``Just`` from the ``Maybe``
-type, without also bringing the type constructor ``Maybe`` into scope.
+Note that if the expression can't be translated into uses of ``<$>``, ``<*>``
+only, then it will incur a ``Monad`` constraint as usual. This happens when
+there is a dependency on a value produced by an earlier statement in the
+``do``-block: ::
 
-To bundle a pattern synonym with a type constructor, we list the pattern
-synonym in the export list of a module which exports the type constructor.
-For example, to bundle ``Zero`` with ``MyNum`` we could write the following: ::
+    Prelude> :t \m -> do { x <- m True; y <- m x; return (x || y) }
+    \m -> do { x <- m True; y <- m x; return (x || y) }
+      :: Monad m => (Bool -> m Bool) -> m Bool
 
-      module Example ( MyNum(Zero) ) where
+Here, ``m x`` depends on the value of ``x`` produced by the first statement, so
+the expression cannot be translated using ``<*>``.
 
-If a module was then to import ``MyNum`` from ``Example``, it would also import
-the pattern synonym ``Zero``.
+In general, the rule for when a ``do`` statement incurs a ``Monad`` constraint
+is as follows. If the do-expression has the following form: ::
 
-It is also possible to use the special token ``..`` in an export list to mean
-all currently bundled constructors. For example, we could write: ::
+    do p1 <- E1; ...; pn <- En; return E
 
-      module Example ( MyNum(.., Zero) ) where
+where none of the variables defined by ``p1...pn`` are mentioned in ``E1...En``,
+then the expression will only require ``Applicative``. Otherwise, the expression
+will require ``Monad``.
 
-in which case, ``Example`` would export the type constructor ``MyNum`` with
-the data constructor ``MkNum`` and also the pattern synonym ``Zero``.
 
-Bundled patterns synoyms are type checked to ensure that they are of the same
-type as the type constructor which they are bundled with. A pattern synonym
-``P`` can not be bundled with a type constructor ``T`` if ``P``\'s type is visibly
-incompatible with ``T``.
+.. _applicative-do-pitfall:
 
-A module which imports ``MyNum(..)`` from ``Example`` and then re-exports
-``MyNum(..)`` will also export any pattern synonyms bundled with ``MyNum`` in
-``Example``. A more complete specification can be found on the
-:ghc-wiki:`wiki. <PatternSynonyms/AssociatingSynonyms>`
+Things to watch out for
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Typing of pattern synonyms
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Your code should just work as before when :ghc-flag:`-XApplicativeDo` is enabled,
+provided you use conventional ``Applicative`` instances. However, if you define
+a ``Functor`` or ``Applicative`` instance using do-notation, then it will likely
+get turned into an infinite loop by GHC. For example, if you do this: ::
 
-Given a pattern synonym definition of the form ::
+    instance Functor MyType where
+        fmap f m = do x <- m; return (f x)
 
-      pattern P var1 var2 ... varN <- pat
+Then applicative desugaring will turn it into ::
 
-it is assigned a *pattern type* of the form ::
+    instance Functor MyType where
+        fmap f m = fmap (\x -> f x) m
 
-      pattern P :: CReq => CProv => t1 -> t2 -> ... -> tN -> t
+And the program will loop at runtime. Similarly, an ``Applicative`` instance
+like this ::
 
-where ⟨CProv⟩ and ⟨CReq⟩ are type contexts, and ⟨t1⟩, ⟨t2⟩, ..., ⟨tN⟩
-and ⟨t⟩ are types. Notice the unusual form of the type, with two
-contexts ⟨CProv⟩ and ⟨CReq⟩:
+    instance Applicative MyType where
+        pure = return
+        x <*> y = do f <- x; a <- y; return (f a)
 
--  ⟨CProv⟩ are the constraints *made available (provided)* by a
-   successful pattern match.
+will result in an infinte loop when ``<*>`` is called.
 
--  ⟨CReq⟩ are the constraints *required* to match the pattern.
+Just as you wouldn't define a ``Monad`` instance using the do-notation, you
+shouldn't define ``Functor`` or ``Applicative`` instance using do-notation (when
+using ``ApplicativeDo``) either. The correct way to define these instances in
+terms of ``Monad`` is to use the ``Monad`` operations directly, e.g. ::
 
-For example, consider ::
+    instance Functor MyType where
+        fmap f m = m >>= return . f
 
-    data T a where
-      MkT :: (Show b) => a -> b -> T a
+    instance Applicative MyType where
+        pure = return
+        (<*>) = ap
 
-    f1 :: (Eq a, Num a) => T a -> String
-    f1 (MkT 42 x) = show x
 
-    pattern ExNumPat :: (Num a, Eq a) => (Show b) => b -> T a
-    pattern ExNumPat x = MkT 42 x
+.. _parallel-list-comprehensions:
 
-    f2 :: (Eq a, Num a) => T a -> String
-    f2 (ExNumPat x) = show x
+Parallel List Comprehensions
+----------------------------
 
-Here ``f1`` does not use pattern synonyms. To match against the numeric
-pattern ``42`` *requires* the caller to satisfy the constraints
-``(Num a, Eq a)``, so they appear in ``f1``'s type. The call to ``show``
-generates a ``(Show b)`` constraint, where ``b`` is an existentially
-type variable bound by the pattern match on ``MkT``. But the same
-pattern match also *provides* the constraint ``(Show b)`` (see ``MkT``'s
-type), and so all is well.
+.. index::
+   single: list comprehensions; parallel
+   single: parallel list comprehensions
 
-Exactly the same reasoning applies to ``ExNumPat``: matching against
-``ExNumPat`` *requires* the constraints ``(Num a, Eq a)``, and
-*provides* the constraint ``(Show b)``.
+.. ghc-flag:: -XParallelListComp
 
-Note also the following points
+    Allow parallel list comprehension syntax.
 
--  In the common case where ``Prov`` is empty, ``()``, it can be omitted
-   altogether.
+Parallel list comprehensions are a natural extension to list
+comprehensions. List comprehensions can be thought of as a nice syntax
+for writing maps and filters. Parallel comprehensions extend this to
+include the ``zipWith`` family.
 
--  You may specify an explicit *pattern signature*, as we did for
-   ``ExNumPat`` above, to specify the type of a pattern, just as you can
-   for a function. As usual, the type signature can be less polymorphic
-   than the inferred type. For example
+A parallel list comprehension has multiple independent branches of
+qualifier lists, each separated by a ``|`` symbol. For example, the
+following zips together two lists: ::
 
-   ::
+       [ (x, y) | x <- xs | y <- ys ]
 
-         -- Inferred type would be 'a -> [a]'
-         pattern SinglePair :: (a, a) -> [(a, a)]
-         pattern SinglePair x = [x]
+The behaviour of parallel list comprehensions follows that of zip, in
+that the resulting list will have the same length as the shortest
+branch.
 
--  The GHCi :ghci-cmd:`:info` command shows pattern types in this format.
+We can define parallel list comprehensions by translation to regular
+comprehensions. Here's the basic idea:
 
--  For a bidirectional pattern synonym, a use of the pattern synonym as
-   an expression has the type
+Given a parallel comprehension of the form: ::
 
-   ::
+       [ e | p1 <- e11, p2 <- e12, ...
+           | q1 <- e21, q2 <- e22, ...
+           ...
+       ]
 
-         (CReq, CProv) => t1 -> t2 -> ... -> tN -> t
+This will be translated to: ::
 
-   So in the previous example, when used in an expression, ``ExNumPat``
-   has type
+       [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...]
+                                             [(q1,q2) | q1 <- e21, q2 <- e22, ...]
+                                             ...
+       ]
 
-   ::
+where ``zipN`` is the appropriate zip for the given number of branches.
 
-         ExNumPat :: (Num a, Eq a, Show b) => b -> T t
+.. _generalised-list-comprehensions:
 
-   Notice that this is a tiny bit more restrictive than the expression
-   ``MkT 42 x`` which would not require ``(Eq a)``.
+Generalised (SQL-like) List Comprehensions
+------------------------------------------
 
--  Consider these two pattern synonyms: ::
+.. index::
+   single: list comprehensions; generalised
+   single: extended list comprehensions
+   single: group
+   single: SQL
 
-       data S a where
-          S1 :: Bool -> S Bool
+.. ghc-flag:: -XTransformListComp
 
-       pattern P1 :: Bool -> Maybe Bool
-       pattern P1 b = Just b
+    Allow use of generalised list (SQL-like) comprehension syntax. This
+    introduces the ``group``, ``by``, and ``using`` keywords.
 
-       pattern P2 :: () => (b ~ Bool) => Bool -> S b
-       pattern P2 b = S1 b
+Generalised list comprehensions are a further enhancement to the list
+comprehension syntactic sugar to allow operations such as sorting and
+grouping which are familiar from SQL. They are fully described in the
+paper `Comprehensive comprehensions: comprehensions with "order by" and
+"group by" <http://research.microsoft.com/~simonpj/papers/list-comp>`__,
+except that the syntax we use differs slightly from the paper.
 
-       f :: Maybe a -> String
-       f (P1 x) = "no no no"     -- Type-incorrect
+The extension is enabled with the flag :ghc-flag:`-XTransformListComp`.
 
-       g :: S a -> String
-       g (P2 b) = "yes yes yes"  -- Fine
+Here is an example:
 
-   Pattern ``P1`` can only match against a value of type ``Maybe Bool``,
-   so function ``f`` is rejected because the type signature is
-   ``Maybe a``. (To see this, imagine expanding the pattern synonym.)
+::
 
-   On the other hand, function ``g`` works fine, because matching
-   against ``P2`` (which wraps the GADT ``S``) provides the local
-   equality ``(a~Bool)``. If you were to give an explicit pattern
-   signature ``P2 :: Bool -> S Bool``, then ``P2`` would become less
-   polymorphic, and would behave exactly like ``P1`` so that ``g`` would
-   then be rejected.
+    employees = [ ("Simon", "MS", 80)
+                , ("Erik", "MS", 100)
+                , ("Phil", "Ed", 40)
+                , ("Gordon", "Ed", 45)
+                , ("Paul", "Yale", 60) ]
 
-   In short, if you want GADT-like behaviour for pattern synonyms, then
-   (unlike unlike concrete data constructors like ``S1``) you must write
-   its type with explicit provided equalities. For a concrete data
-   constructor like ``S1`` you can write its type signature as either
-   ``S1 :: Bool -> S Bool`` or ``S1 :: (b~Bool) => Bool -> S b``; the
-   two are equivalent. Not so for pattern synonyms: the two forms are
-   different, in order to distinguish the two cases above. (See
-   :ghc-ticket:`9953` for discussion of this choice.)
+    output = [ (the dept, sum salary)
+             | (name, dept, salary) <- employees
+             , then group by dept using groupWith
+             , then sortWith by (sum salary)
+             , then take 5 ]
 
-Matching of pattern synonyms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In this example, the list ``output`` would take on the value:
 
-A pattern synonym occurrence in a pattern is evaluated by first matching
-against the pattern synonym itself, and then on the argument patterns.
-For example, in the following program, ``f`` and ``f'`` are equivalent: ::
+::
 
-    pattern Pair x y <- [x, y]
+    [("Yale", 60), ("Ed", 85), ("MS", 180)]
 
-    f (Pair True True) = True
-    f _                = False
+There are three new keywords: ``group``, ``by``, and ``using``. (The
+functions ``sortWith`` and ``groupWith`` are not keywords; they are
+ordinary functions that are exported by ``GHC.Exts``.)
 
-    f' [x, y] | True <- x, True <- y = True
-    f' _                              = False
+There are five new forms of comprehension qualifier, all introduced by
+the (existing) keyword ``then``:
 
-Note that the strictness of ``f`` differs from that of ``g`` defined
-below:
+-  ::
 
-.. code-block:: none
+       then f
 
-    g [True, True] = True
-    g _            = False
+   This statement requires that
+   f
+   have the type
+   forall a. [a] -> [a]
+   . You can see an example of its use in the motivating example, as
+   this form is used to apply
+   take 5
+   .
+-  ::
 
-    *Main> f (False:undefined)
-    *** Exception: Prelude.undefined
-    *Main> g (False:undefined)
-    False
+       then f by e
 
-.. _n-k-patterns:
+   This form is similar to the previous one, but allows you to create a
+   function which will be passed as the first argument to f. As a
+   consequence f must have the type
+   ``forall a. (a -> t) -> [a] -> [a]``. As you can see from the type,
+   this function lets f "project out" some information from the elements
+   of the list it is transforming.
 
-n+k patterns
-------------
+   An example is shown in the opening example, where ``sortWith`` is
+   supplied with a function that lets it find out the ``sum salary`` for
+   any item in the list comprehension it transforms.
 
-.. ghc-flag:: -XNPlusKPatterns
+-  ::
 
-    Enable use of ``n+k`` patterns.
+       then group by e using f
 
-.. _recursive-do-notation:
+   This is the most general of the grouping-type statements. In this
+   form, f is required to have type
+   ``forall a. (a -> t) -> [a] -> [[a]]``. As with the ``then f by e``
+   case above, the first argument is a function supplied to f by the
+   compiler which lets it compute e on every element of the list being
+   transformed. However, unlike the non-grouping case, f additionally
+   partitions the list into a number of sublists: this means that at
+   every point after this statement, binders occurring before it in the
+   comprehension refer to *lists* of possible values, not single values.
+   To help understand this, let's look at an example:
 
-The recursive do-notation
--------------------------
+   ::
 
-.. ghc-flag:: -XRecursiveDo
+       -- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
+       groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
+       groupRuns f = groupBy (\x y -> f x == f y)
 
-    Allow the use of recursive ``do`` notation.
+       output = [ (the x, y)
+       | x <- ([1..3] ++ [1..2])
+       , y <- [4..6]
+       , then group by x using groupRuns ]
 
-The do-notation of Haskell 98 does not allow *recursive bindings*, that
-is, the variables bound in a do-expression are visible only in the
-textually following code block. Compare this to a let-expression, where
-bound variables are visible in the entire binding group.
+   This results in the variable ``output`` taking on the value below:
 
-It turns out that such recursive bindings do indeed make sense for a
-variety of monads, but not all. In particular, recursion in this sense
-requires a fixed-point operator for the underlying monad, captured by
-the ``mfix`` method of the ``MonadFix`` class, defined in
-``Control.Monad.Fix`` as follows: ::
+   ::
 
-    class Monad m => MonadFix m where
-       mfix :: (a -> m a) -> m a
+       [(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
 
-Haskell's ``Maybe``, ``[]`` (list), ``ST`` (both strict and lazy
-versions), ``IO``, and many other monads have ``MonadFix`` instances. On
-the negative side, the continuation monad, with the signature
-``(a -> r) -> r``, does not.
+   Note that we have used the ``the`` function to change the type of x
+   from a list to its original numeric type. The variable y, in
+   contrast, is left unchanged from the list form introduced by the
+   grouping.
 
-For monads that do belong to the ``MonadFix`` class, GHC provides an
-extended version of the do-notation that allows recursive bindings. The
-:ghc-flag:`-XRecursiveDo` (language pragma: ``RecursiveDo``) provides the
-necessary syntactic support, introducing the keywords ``mdo`` and
-``rec`` for higher and lower levels of the notation respectively. Unlike
-bindings in a ``do`` expression, those introduced by ``mdo`` and ``rec``
-are recursively defined, much like in an ordinary let-expression. Due to
-the new keyword ``mdo``, we also call this notation the *mdo-notation*.
+-  ::
 
-Here is a simple (albeit contrived) example:
+       then group using f
 
-::
+   With this form of the group statement, f is required to simply have
+   the type ``forall a. [a] -> [[a]]``, which will be used to group up
+   the comprehension so far directly. An example of this form is as
+   follows:
 
-    {-# LANGUAGE RecursiveDo #-}
-    justOnes = mdo { xs <- Just (1:xs)
-                   ; return (map negate xs) }
+   ::
 
-or equivalently
+       output = [ x
+       | y <- [1..5]
+       , x <- "hello"
+       , then group using inits]
 
-::
+   This will yield a list containing every prefix of the word "hello"
+   written out 5 times:
 
-    {-# LANGUAGE RecursiveDo #-}
-    justOnes = do { rec { xs <- Just (1:xs) }
-                  ; return (map negate xs) }
+   ::
 
-As you can guess ``justOnes`` will evaluate to ``Just [-1,-1,-1,...``.
+       ["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
 
-GHC's implementation the mdo-notation closely follows the original
-translation as described in the paper `A recursive do for
-Haskell <https://sites.google.com/site/leventerkok/recdo.pdf>`__, which
-in turn is based on the work `Value Recursion in Monadic
-Computations <http://sites.google.com/site/leventerkok/erkok-thesis.pdf>`__.
-Furthermore, GHC extends the syntax described in the former paper with a
-lower level syntax flagged by the ``rec`` keyword, as we describe next.
+.. _monad-comprehensions:
 
-Recursive binding groups
-~~~~~~~~~~~~~~~~~~~~~~~~
+Monad comprehensions
+--------------------
 
-The flag :ghc-flag:`-XRecursiveDo` also introduces a new keyword ``rec``, which
-wraps a mutually-recursive group of monadic statements inside a ``do``
-expression, producing a single statement. Similar to a ``let`` statement
-inside a ``do``, variables bound in the ``rec`` are visible throughout
-the ``rec`` group, and below it. For example, compare
+.. index::
+   single: monad comprehensions
 
-::
+Monad comprehensions generalise the list comprehension notation,
+including parallel comprehensions (:ref:`parallel-list-comprehensions`)
+and transform comprehensions (:ref:`generalised-list-comprehensions`) to
+work for any monad.
 
-        do { a <- getChar            do { a <- getChar
-           ; let { r1 = f a r2          ; rec { r1 <- f a r2
-           ;     ; r2 = g r1 }          ;     ; r2 <- g r1 }
-           ; return (r1 ++ r2) }        ; return (r1 ++ r2) }
+Monad comprehensions support:
 
-In both cases, ``r1`` and ``r2`` are available both throughout the
-``let`` or ``rec`` block, and in the statements that follow it. The
-difference is that ``let`` is non-monadic, while ``rec`` is monadic. (In
-Haskell ``let`` is really ``letrec``, of course.)
+-  Bindings: ::
 
-The semantics of ``rec`` is fairly straightforward. Whenever GHC finds a
-``rec`` group, it will compute its set of bound variables, and will
-introduce an appropriate call to the underlying monadic value-recursion
-operator ``mfix``, belonging to the ``MonadFix`` class. Here is an
-example:
+       [ x + y | x <- Just 1, y <- Just 2 ]
 
-::
+   Bindings are translated with the ``(>>=)`` and ``return`` functions
+   to the usual do-notation: ::
 
-    rec { b <- f a c     ===>    (b,c) <- mfix (\ ~(b,c) -> do { b <- f a c
-        ; c <- f b a }                                         ; c <- f b a
-                                                               ; return (b,c) })
+       do x <- Just 1
+          y <- Just 2
+          return (x+y)
 
-As usual, the meta-variables ``b``, ``c`` etc., can be arbitrary
-patterns. In general, the statement ``rec ss`` is desugared to the
-statement
+-  Guards: ::
 
-::
+       [ x | x <- [1..10], x <= 5 ]
 
-    vs <- mfix (\ ~vs -> do { ss; return vs })
+   Guards are translated with the ``guard`` function, which requires a
+   ``MonadPlus`` instance: ::
 
-where ``vs`` is a tuple of the variables bound by ``ss``.
+       do x <- [1..10]
+          guard (x <= 5)
+          return x
 
-Note in particular that the translation for a ``rec`` block only
-involves wrapping a call to ``mfix``: it performs no other analysis on
-the bindings. The latter is the task for the ``mdo`` notation, which is
-described next.
-
-The ``mdo`` notation
-~~~~~~~~~~~~~~~~~~~~
-
-A ``rec``-block tells the compiler where precisely the recursive knot
-should be tied. It turns out that the placement of the recursive knots
-can be rather delicate: in particular, we would like the knots to be
-wrapped around as minimal groups as possible. This process is known as
-*segmentation*, and is described in detail in Section 3.2 of `A
-recursive do for
-Haskell <https://sites.google.com/site/leventerkok/recdo.pdf>`__.
-Segmentation improves polymorphism and reduces the size of the recursive
-knot. Most importantly, it avoids unnecessary interference caused by a
-fundamental issue with the so-called *right-shrinking* axiom for monadic
-recursion. In brief, most monads of interest (IO, strict state, etc.) do
-*not* have recursion operators that satisfy this axiom, and thus not
-performing segmentation can cause unnecessary interference, changing the
-termination behavior of the resulting translation. (Details can be found
-in Sections 3.1 and 7.2.2 of `Value Recursion in Monadic
-Computations <http://sites.google.com/site/leventerkok/erkok-thesis.pdf>`__.)
-
-The ``mdo`` notation removes the burden of placing explicit ``rec``
-blocks in the code. Unlike an ordinary ``do`` expression, in which
-variables bound by statements are only in scope for later statements,
-variables bound in an ``mdo`` expression are in scope for all statements
-of the expression. The compiler then automatically identifies minimal
-mutually recursively dependent segments of statements, treating them as
-if the user had wrapped a ``rec`` qualifier around them.
-
-The definition is syntactic:
-
--  A generator ⟨g⟩ *depends* on a textually following generator ⟨g'⟩, if
-
-   -  ⟨g'⟩ defines a variable that is used by ⟨g⟩, or
-
-   -  ⟨g'⟩ textually appears between ⟨g⟩ and ⟨g''⟩, where ⟨g⟩ depends on
-      ⟨g''⟩.
+-  Transform statements (as with :ghc-flag:`-XTransformListComp`): ::
 
--  A *segment* of a given ``mdo``-expression is a minimal sequence of
-   generators such that no generator of the sequence depends on an
-   outside generator. As a special case, although it is not a generator,
-   the final expression in an ``mdo``-expression is considered to form a
-   segment by itself.
+       [ x+y | x <- [1..10], y <- [1..x], then take 2 ]
 
-Segments in this sense are related to *strongly-connected components*
-analysis, with the exception that bindings in a segment cannot be
-reordered and must be contiguous.
+   This translates to: ::
 
-Here is an example ``mdo``-expression, and its translation to ``rec``
-blocks:
+       do (x,y) <- take 2 (do x <- [1..10]
+                              y <- [1..x]
+                              return (x,y))
+          return (x+y)
 
-::
+-  Group statements (as with :ghc-flag:`-XTransformListComp`):
 
-    mdo { a <- getChar      ===> do { a <- getChar
-        ; b <- f a c                ; rec { b <- f a c
-        ; c <- f b a                ;     ; c <- f b a }
-        ; z <- h a b                ; z <- h a b
-        ; d <- g d e                ; rec { d <- g d e
-        ; e <- g a z                ;     ; e <- g a z }
-        ; putChar c }               ; putChar c }
+   ::
 
-Note that a given ``mdo`` expression can cause the creation of multiple
-``rec`` blocks. If there are no recursive dependencies, ``mdo`` will
-introduce no ``rec`` blocks. In this latter case an ``mdo`` expression
-is precisely the same as a ``do`` expression, as one would expect.
+       [ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ]
+       [ x | x <- [1,1,2,2,3], then group using myGroup ]
 
-In summary, given an ``mdo`` expression, GHC first performs
-segmentation, introducing ``rec`` blocks to wrap over minimal recursive
-groups. Then, each resulting ``rec`` is desugared, using a call to
-``Control.Monad.Fix.mfix`` as described in the previous section. The
-original ``mdo``-expression typechecks exactly when the desugared
-version would do so.
+-  Parallel statements (as with :ghc-flag:`-XParallelListComp`):
 
-Here are some other important points in using the recursive-do notation:
+   ::
 
--  It is enabled with the flag :ghc-flag:`-XRecursiveDo`, or the
-   ``LANGUAGE RecursiveDo`` pragma. (The same flag enables both
-   ``mdo``-notation, and the use of ``rec`` blocks inside ``do``
-   expressions.)
+       [ (x+y) | x <- [1..10]
+               | y <- [11..20]
+               ]
 
--  ``rec`` blocks can also be used inside ``mdo``-expressions, which
-   will be treated as a single statement. However, it is good style to
-   either use ``mdo`` or ``rec`` blocks in a single expression.
+   Parallel statements are translated using the ``mzip`` function, which
+   requires a ``MonadZip`` instance defined in
+   :base-ref:`Control.Monad.Zip <Control-Monad-Zip.html>`:
 
--  If recursive bindings are required for a monad, then that monad must
-   be declared an instance of the ``MonadFix`` class.
+   ::
 
--  The following instances of ``MonadFix`` are automatically provided:
-   List, Maybe, IO. Furthermore, the ``Control.Monad.ST`` and
-   ``Control.Monad.ST.Lazy`` modules provide the instances of the
-   ``MonadFix`` class for Haskell's internal state monad (strict and
-   lazy, respectively).
+       do (x,y) <- mzip (do x <- [1..10]
+                            return x)
+                        (do y <- [11..20]
+                            return y)
+          return (x+y)
 
--  Like ``let`` and ``where`` bindings, name shadowing is not allowed
-   within an ``mdo``-expression or a ``rec``-block; that is, all the
-   names bound in a single ``rec`` must be distinct. (GHC will complain
-   if this is not the case.)
+All these features are enabled by default if the ``MonadComprehensions``
+extension is enabled. The types and more detailed examples on how to use
+comprehensions are explained in the previous chapters
+:ref:`generalised-list-comprehensions` and
+:ref:`parallel-list-comprehensions`. In general you just have to replace
+the type ``[a]`` with the type ``Monad m => m a`` for monad
+comprehensions.
 
-.. _applicative-do:
+.. note::
+    Even though most of these examples are using the list monad, monad
+    comprehensions work for any monad. The ``base`` package offers all
+    necessary instances for lists, which make ``MonadComprehensions``
+    backward compatible to built-in, transform and parallel list
+    comprehensions.
 
-Applicative do-notation
------------------------
+More formally, the desugaring is as follows. We write ``D[ e | Q]`` to
+mean the desugaring of the monad comprehension ``[ e | Q]``:
 
-.. index::
-   single: Applicative do-notation
-   single: do-notation; Applicative
+::
 
-.. ghc-flag:: -XApplicativeDo
+    Expressions: e
+    Declarations: d
+    Lists of qualifiers: Q,R,S
 
-    :since: 8.0.1
+    -- Basic forms
+    D[ e | ]               = return e
+    D[ e | p <- e, Q ]  = e >>= \p -> D[ e | Q ]
+    D[ e | e, Q ]          = guard e >> \p -> D[ e | Q ]
+    D[ e | let d, Q ]      = let d in D[ e | Q ]
 
-    Allow use of ``Applicative`` ``do`` notation.
+    -- Parallel comprehensions (iterate for multiple parallel branches)
+    D[ e | (Q | R), S ]    = mzip D[ Qv | Q ] D[ Rv | R ] >>= \(Qv,Rv) -> D[ e | S ]
 
-The language option :ghc-flag:`-XApplicativeDo` enables an alternative translation for
-the do-notation, which uses the operators ``<$>``, ``<*>``, along with ``join``
-as far as possible. There are two main reasons for wanting to do this:
+    -- Transform comprehensions
+    D[ e | Q then f, R ]                  = f D[ Qv | Q ] >>= \Qv -> D[ e | R ]
 
--  We can use do-notation with types that are an instance of ``Applicative`` and
-   ``Functor``, but not ``Monad``
--  In some monads, using the applicative operators is more efficient than monadic
-   bind. For example, it may enable more parallelism.
+    D[ e | Q then f by b, R ]             = f (\Qv -> b) D[ Qv | Q ] >>= \Qv -> D[ e | R ]
 
-Applicative do-notation desugaring preserves the original semantics, provided
-that the ``Applicative`` instance satisfies ``<*> = ap`` and ``pure = return``
-(these are true of all the common monadic types). Thus, you can normally turn on
-:ghc-flag:`-XApplicativeDo` without fear of breaking your program. There is one pitfall
-to watch out for; see :ref:`applicative-do-pitfall`.
+    D[ e | Q then group using f, R ]      = f D[ Qv | Q ] >>= \ys ->
+                                            case (fmap selQv1 ys, ..., fmap selQvn ys) of
+                                             Qv -> D[ e | R ]
 
-There are no syntactic changes with :ghc-flag:`-XApplicativeDo`. The only way it shows
-up at the source level is that you can have a ``do`` expression that doesn't
-require a ``Monad`` constraint. For example, in GHCi: ::
+    D[ e | Q then group by b using f, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \ys ->
+                                            case (fmap selQv1 ys, ..., fmap selQvn ys) of
+                                               Qv -> D[ e | R ]
 
-    Prelude> :set -XApplicativeDo
-    Prelude> :t \m -> do { x <- m; return (not x) }
-    \m -> do { x <- m; return (not x) }
-      :: Functor f => f Bool -> f Bool
+    where  Qv is the tuple of variables bound by Q (and used subsequently)
+           selQvi is a selector mapping Qv to the ith component of Qv
 
-This example only requires ``Functor``, because it is translated into ``(\x ->
-not x) <$> m``. A more complex example requires ``Applicative``, ::
+    Operator     Standard binding       Expected type
+    --------------------------------------------------------------------
+    return       GHC.Base               t1 -> m t2
+    (>>=)        GHC.Base               m1 t1 -> (t2 -> m2 t3) -> m3 t3
+    (>>)         GHC.Base               m1 t1 -> m2 t2         -> m3 t3
+    guard        Control.Monad          t1 -> m t2
+    fmap         GHC.Base               forall a b. (a->b) -> n a -> n b
+    mzip         Control.Monad.Zip      forall a b. m a -> m b -> m (a,b)
 
-    Prelude> :t \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) }
-    \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) }
-      :: Applicative f => (Char -> f Bool) -> f Bool
+The comprehension should typecheck when its desugaring would typecheck,
+except that (as discussed in :ref:`generalised-list-comprehensions`) in the
+"then ``f``" and "then group using ``f``" clauses, when the "by ``b``" qualifier
+is omitted, argument ``f`` should have a polymorphic type. In particular, "then
+``Data.List.sort``" and "then group using ``Data.List.group``" are
+insufficiently polymorphic.
 
-Here GHC has translated the expression into ::
+Monad comprehensions support rebindable syntax
+(:ref:`rebindable-syntax`). Without rebindable syntax, the operators
+from the "standard binding" module are used; with rebindable syntax, the
+operators are looked up in the current lexical scope. For example,
+parallel comprehensions will be typechecked and desugared using whatever
+"``mzip``" is in scope.
 
-    (\x y -> x || y) <$> m 'a' <*> m 'b'
+The rebindable operators must have the "Expected type" given in the
+table above. These types are surprisingly general. For example, you can
+use a bind operator with the type
 
-It is possible to see the actual translation by using :ghc-flag:`-ddump-ds`, but be
-warned, the output is quite verbose.
+::
 
-Note that if the expression can't be translated into uses of ``<$>``, ``<*>``
-only, then it will incur a ``Monad`` constraint as usual. This happens when
-there is a dependency on a value produced by an earlier statement in the
-``do``-block: ::
+    (>>=) :: T x y a -> (a -> T y z b) -> T x z b
 
-    Prelude> :t \m -> do { x <- m True; y <- m x; return (x || y) }
-    \m -> do { x <- m True; y <- m x; return (x || y) }
-      :: Monad m => (Bool -> m Bool) -> m Bool
+In the case of transform comprehensions, notice that the groups are
+parameterised over some arbitrary type ``n`` (provided it has an
+``fmap``, as well as the comprehension being over an arbitrary monad.
 
-Here, ``m x`` depends on the value of ``x`` produced by the first statement, so
-the expression cannot be translated using ``<*>``.
+.. _monadfail-desugaring:
 
-In general, the rule for when a ``do`` statement incurs a ``Monad`` constraint
-is as follows. If the do-expression has the following form: ::
+New monadic failure desugaring mechanism
+----------------------------------------
 
-    do p1 <- E1; ...; pn <- En; return E
+.. ghc-flag:: -XMonadFailDesugaring
 
-where none of the variables defined by ``p1...pn`` are mentioned in ``E1...En``,
-then the expression will only require ``Applicative``. Otherwise, the expression
-will require ``Monad``.
+    :since: 8.0.1
 
+    Use the ``MonadFail.fail`` instead of the legacy ``Monad.fail`` function
+    when desugaring refutable patterns in ``do`` blocks.
 
-.. _applicative-do-pitfall:
+The ``-XMonadFailDesugaring`` extension switches the desugaring of
+``do``-blocks to use ``MonadFail.fail`` instead of ``Monad.fail``. This will
+eventually be the default behaviour in a future GHC release, under the
+`MonadFail Proposal (MFP)
+<https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
 
-Things to watch out for
-~~~~~~~~~~~~~~~~~~~~~~~
+This extension is temporary, and will be deprecated in a future release. It is
+included so that library authors have a hard check for whether their code
+will work with future GHC versions.
 
-Your code should just work as before when :ghc-flag:`-XApplicativeDo` is enabled,
-provided you use conventional ``Applicative`` instances. However, if you define
-a ``Functor`` or ``Applicative`` instance using do-notation, then it will likely
-get turned into an infinite loop by GHC. For example, if you do this: ::
+.. _rebindable-syntax:
 
-    instance Functor MyType where
-        fmap f m = do x <- m; return (f x)
+Rebindable syntax and the implicit Prelude import
+-------------------------------------------------
 
-Then applicative desugaring will turn it into ::
+.. ghc-flag:: -XNoImplicitPrelude
 
-    instance Functor MyType where
-        fmap f m = fmap (\x -> f x) m
+    Don't import ``Prelude`` by default.
 
-And the program will loop at runtime. Similarly, an ``Applicative`` instance
-like this ::
+GHC normally imports ``Prelude.hi`` files for
+you. If you'd rather it didn't, then give it a ``-XNoImplicitPrelude``
+option. The idea is that you can then import a Prelude of your own. (But
+don't call it ``Prelude``; the Haskell module namespace is flat, and you
+must not conflict with any Prelude module.)
 
-    instance Applicative MyType where
-        pure = return
-        x <*> y = do f <- x; a <- y; return (f a)
+.. ghc-flag:: -XRebindableSyntax
 
-will result in an infinte loop when ``<*>`` is called.
+    :implies: :ghc-flag:`-XNoImplicitPrelude`
+    :since: 7.0.1
 
-Just as you wouldn't define a ``Monad`` instance using the do-notation, you
-shouldn't define ``Functor`` or ``Applicative`` instance using do-notation (when
-using ``ApplicativeDo``) either. The correct way to define these instances in
-terms of ``Monad`` is to use the ``Monad`` operations directly, e.g. ::
+    Enable rebinding of a variety of usually-built-in operations.
 
-    instance Functor MyType where
-        fmap f m = m >>= return . f
+Suppose you are importing a Prelude of your own in order to define your
+own numeric class hierarchy. It completely defeats that purpose if the
+literal "1" means "``Prelude.fromInteger 1``", which is what the Haskell
+Report specifies. So the :ghc-flag:`-XRebindableSyntax` flag causes the
+following pieces of built-in syntax to refer to *whatever is in scope*,
+not the Prelude versions:
 
-    instance Applicative MyType where
-        pure = return
-        (<*>) = ap
+-  An integer literal ``368`` means "``fromInteger (368::Integer)``",
+   rather than "``Prelude.fromInteger (368::Integer)``".
 
+-  Fractional literals are handed in just the same way, except that the
+   translation is ``fromRational (3.68::Rational)``.
 
-.. _parallel-list-comprehensions:
+-  The equality test in an overloaded numeric pattern uses whatever
+   ``(==)`` is in scope.
 
-Parallel List Comprehensions
-----------------------------
+-  The subtraction operation, and the greater-than-or-equal test, in
+   ``n+k`` patterns use whatever ``(-)`` and ``(>=)`` are in scope.
 
-.. index::
-   single: list comprehensions; parallel
-   single: parallel list comprehensions
+-  Negation (e.g. "``- (f x)``") means "``negate (f x)``", both in
+   numeric patterns, and expressions.
 
-.. ghc-flag:: -XParallelListComp
+-  Conditionals (e.g. "``if`` e1 ``then`` e2 ``else`` e3") means
+   "``ifThenElse`` e1 e2 e3". However ``case`` expressions are
+   unaffected.
 
-    Allow parallel list comprehension syntax.
+-  "Do" notation is translated using whatever functions ``(>>=)``,
+   ``(>>)``, and ``fail``, are in scope (not the Prelude versions). List
+   comprehensions, ``mdo`` (:ref:`recursive-do-notation`), and parallel
+   array comprehensions, are unaffected.
 
-Parallel list comprehensions are a natural extension to list
-comprehensions. List comprehensions can be thought of as a nice syntax
-for writing maps and filters. Parallel comprehensions extend this to
-include the ``zipWith`` family.
+-  Arrow notation (see :ref:`arrow-notation`) uses whatever ``arr``,
+   ``(>>>)``, ``first``, ``app``, ``(|||)`` and ``loop`` functions are
+   in scope. But unlike the other constructs, the types of these
+   functions must match the Prelude types very closely. Details are in
+   flux; if you want to use this, ask!
 
-A parallel list comprehension has multiple independent branches of
-qualifier lists, each separated by a ``|`` symbol. For example, the
-following zips together two lists: ::
+:ghc-flag:`-XRebindableSyntax` implies :ghc-flag:`-XNoImplicitPrelude`.
 
-       [ (x, y) | x <- xs | y <- ys ]
+In all cases (apart from arrow notation), the static semantics should be
+that of the desugared form, even if that is a little unexpected. For
+example, the static semantics of the literal ``368`` is exactly that of
+``fromInteger (368::Integer)``; it's fine for ``fromInteger`` to have
+any of the types: ::
 
-The behaviour of parallel list comprehensions follows that of zip, in
-that the resulting list will have the same length as the shortest
-branch.
+    fromInteger :: Integer -> Integer
+    fromInteger :: forall a. Foo a => Integer -> a
+    fromInteger :: Num a => a -> Integer
+    fromInteger :: Integer -> Bool -> Bool
 
-We can define parallel list comprehensions by translation to regular
-comprehensions. Here's the basic idea:
+Be warned: this is an experimental facility, with fewer checks than
+usual. Use ``-dcore-lint`` to typecheck the desugared program. If Core
+Lint is happy you should be all right.
 
-Given a parallel comprehension of the form: ::
+.. _postfix-operators:
 
-       [ e | p1 <- e11, p2 <- e12, ...
-           | q1 <- e21, q2 <- e22, ...
-           ...
-       ]
+Postfix operators
+-----------------
 
-This will be translated to: ::
+.. ghc-flag:: -XPostfixOperators
 
-       [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...]
-                                             [(q1,q2) | q1 <- e21, q2 <- e22, ...]
-                                             ...
-       ]
+    Allow the use of post-fix operators
 
-where ``zipN`` is the appropriate zip for the given number of branches.
+The :ghc-flag:`-XPostfixOperators` flag enables a small extension to the syntax
+of left operator sections, which allows you to define postfix operators.
+The extension is this: the left section ::
 
-.. _generalised-list-comprehensions:
+      (e !)
 
-Generalised (SQL-like) List Comprehensions
-------------------------------------------
+is equivalent (from the point of view of both type checking and
+execution) to the expression ::
 
-.. index::
-   single: list comprehensions; generalised
-   single: extended list comprehensions
-   single: group
-   single: SQL
+      ((!) e)
 
-.. ghc-flag:: -XTransformListComp
+(for any expression ``e`` and operator ``(!)``. The strict Haskell 98
+interpretation is that the section is equivalent to ::
 
-    Allow use of generalised list (SQL-like) comprehension syntax. This
-    introduces the ``group``, ``by``, and ``using`` keywords.
+      (\y -> (!) e y)
 
-Generalised list comprehensions are a further enhancement to the list
-comprehension syntactic sugar to allow operations such as sorting and
-grouping which are familiar from SQL. They are fully described in the
-paper `Comprehensive comprehensions: comprehensions with "order by" and
-"group by" <http://research.microsoft.com/~simonpj/papers/list-comp>`__,
-except that the syntax we use differs slightly from the paper.
+That is, the operator must be a function of two arguments. GHC allows it
+to take only one argument, and that in turn allows you to write the
+function postfix.
 
-The extension is enabled with the flag :ghc-flag:`-XTransformListComp`.
+The extension does not extend to the left-hand side of function
+definitions; you must define such a function in prefix form.
 
-Here is an example:
+.. _tuple-sections:
 
-::
+Tuple sections
+--------------
 
-    employees = [ ("Simon", "MS", 80)
-                , ("Erik", "MS", 100)
-                , ("Phil", "Ed", 40)
-                , ("Gordon", "Ed", 45)
-                , ("Paul", "Yale", 60) ]
+.. ghc-flag:: -XTupleSections
 
-    output = [ (the dept, sum salary)
-             | (name, dept, salary) <- employees
-             , then group by dept using groupWith
-             , then sortWith by (sum salary)
-             , then take 5 ]
+    Allow the use of tuple section syntax
 
-In this example, the list ``output`` would take on the value:
+The :ghc-flag:`-XTupleSections` flag enables Python-style partially applied
+tuple constructors. For example, the following program ::
 
-::
+      (, True)
 
-    [("Yale", 60), ("Ed", 85), ("MS", 180)]
+is considered to be an alternative notation for the more unwieldy
+alternative ::
 
-There are three new keywords: ``group``, ``by``, and ``using``. (The
-functions ``sortWith`` and ``groupWith`` are not keywords; they are
-ordinary functions that are exported by ``GHC.Exts``.)
+      \x -> (x, True)
 
-There are five new forms of comprehension qualifier, all introduced by
-the (existing) keyword ``then``:
+You can omit any combination of arguments to the tuple, as in the
+following ::
 
--  ::
+      (, "I", , , "Love", , 1337)
 
-       then f
+which translates to ::
 
-   This statement requires that
-   f
-   have the type
-   forall a. [a] -> [a]
-   . You can see an example of its use in the motivating example, as
-   this form is used to apply
-   take 5
-   .
--  ::
+      \a b c d -> (a, "I", b, c, "Love", d, 1337)
 
-       then f by e
+If you have `unboxed tuples <#unboxed-tuples>`__ enabled, tuple sections
+will also be available for them, like so ::
 
-   This form is similar to the previous one, but allows you to create a
-   function which will be passed as the first argument to f. As a
-   consequence f must have the type
-   ``forall a. (a -> t) -> [a] -> [a]``. As you can see from the type,
-   this function lets f "project out" some information from the elements
-   of the list it is transforming.
+      (# , True #)
 
-   An example is shown in the opening example, where ``sortWith`` is
-   supplied with a function that lets it find out the ``sum salary`` for
-   any item in the list comprehension it transforms.
+Because there is no unboxed unit tuple, the following expression ::
 
--  ::
+      (# #)
 
-       then group by e using f
+continues to stand for the unboxed singleton tuple data constructor.
 
-   This is the most general of the grouping-type statements. In this
-   form, f is required to have type
-   ``forall a. (a -> t) -> [a] -> [[a]]``. As with the ``then f by e``
-   case above, the first argument is a function supplied to f by the
-   compiler which lets it compute e on every element of the list being
-   transformed. However, unlike the non-grouping case, f additionally
-   partitions the list into a number of sublists: this means that at
-   every point after this statement, binders occurring before it in the
-   comprehension refer to *lists* of possible values, not single values.
-   To help understand this, let's look at an example:
+.. _lambda-case:
 
-   ::
+Lambda-case
+-----------
 
-       -- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
-       groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
-       groupRuns f = groupBy (\x y -> f x == f y)
+.. ghc-flag:: -XLambdaCase
 
-       output = [ (the x, y)
-       | x <- ([1..3] ++ [1..2])
-       , y <- [4..6]
-       , then group by x using groupRuns ]
+    :since: 7.6.1
 
-   This results in the variable ``output`` taking on the value below:
+    Allow the use of lambda-case syntax.
 
-   ::
+The :ghc-flag:`-XLambdaCase` flag enables expressions of the form ::
 
-       [(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
+      \case { p1 -> e1; ...; pN -> eN }
 
-   Note that we have used the ``the`` function to change the type of x
-   from a list to its original numeric type. The variable y, in
-   contrast, is left unchanged from the list form introduced by the
-   grouping.
+which is equivalent to ::
 
--  ::
+      \freshName -> case freshName of { p1 -> e1; ...; pN -> eN }
 
-       then group using f
+Note that ``\case`` starts a layout, so you can write ::
 
-   With this form of the group statement, f is required to simply have
-   the type ``forall a. [a] -> [[a]]``, which will be used to group up
-   the comprehension so far directly. An example of this form is as
-   follows:
+      \case
+        p1 -> e1
+        ...
+        pN -> eN
 
-   ::
+.. _empty-case:
 
-       output = [ x
-       | y <- [1..5]
-       , x <- "hello"
-       , then group using inits]
+Empty case alternatives
+-----------------------
 
-   This will yield a list containing every prefix of the word "hello"
-   written out 5 times:
+.. ghc-flag:: -XEmptyCase
 
-   ::
+    :since: 7.8.1
 
-       ["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
+    Allow empty case expressions.
 
-.. _monad-comprehensions:
+The :ghc-flag:`-XEmptyCase` flag enables case expressions, or lambda-case
+expressions, that have no alternatives, thus: ::
 
-Monad comprehensions
---------------------
+    case e of { }   -- No alternatives
 
-.. index::
-   single: monad comprehensions
+or ::
 
-Monad comprehensions generalise the list comprehension notation,
-including parallel comprehensions (:ref:`parallel-list-comprehensions`)
-and transform comprehensions (:ref:`generalised-list-comprehensions`) to
-work for any monad.
+    \case { }       -- -XLambdaCase is also required
 
-Monad comprehensions support:
+This can be useful when you know that the expression being scrutinised
+has no non-bottom values. For example:
 
--  Bindings: ::
+::
 
-       [ x + y | x <- Just 1, y <- Just 2 ]
+      data Void
+      f :: Void -> Int
+      f x = case x of { }
 
-   Bindings are translated with the ``(>>=)`` and ``return`` functions
-   to the usual do-notation: ::
+With dependently-typed features it is more useful (see :ghc-ticket:`2431``). For
+example, consider these two candidate definitions of ``absurd``:
 
-       do x <- Just 1
-          y <- Just 2
-          return (x+y)
+::
 
--  Guards: ::
+    data a :==: b where
+      Refl :: a :==: a
 
-       [ x | x <- [1..10], x <= 5 ]
+    absurd :: True :~: False -> a
+    absurd x = error "absurd"    -- (A)
+    absurd x = case x of {}      -- (B)
 
-   Guards are translated with the ``guard`` function, which requires a
-   ``MonadPlus`` instance: ::
+We much prefer (B). Why? Because GHC can figure out that
+``(True :~: False)`` is an empty type. So (B) has no partiality and GHC
+should be able to compile with :ghc-flag:`-Wincomplete-patterns`. (Though
+the pattern match checking is not yet clever enough to do that.) On the
+other hand (A) looks dangerous, and GHC doesn't check to make sure that,
+in fact, the function can never get called.
 
-       do x <- [1..10]
-          guard (x <= 5)
-          return x
+.. _multi-way-if:
 
--  Transform statements (as with :ghc-flag:`-XTransformListComp`): ::
+Multi-way if-expressions
+------------------------
 
-       [ x+y | x <- [1..10], y <- [1..x], then take 2 ]
+.. ghc-flag:: -XMultiWayIf
 
-   This translates to: ::
+    :since: 7.6.1
 
-       do (x,y) <- take 2 (do x <- [1..10]
-                              y <- [1..x]
-                              return (x,y))
-          return (x+y)
+    Allow the use of multi-way-``if`` syntax.
 
--  Group statements (as with :ghc-flag:`-XTransformListComp`):
+With :ghc-flag:`-XMultiWayIf` flag GHC accepts conditional expressions with
+multiple branches: ::
 
-   ::
+      if | guard1 -> expr1
+         | ...
+         | guardN -> exprN
 
-       [ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ]
-       [ x | x <- [1,1,2,2,3], then group using myGroup ]
+which is roughly equivalent to ::
 
--  Parallel statements (as with :ghc-flag:`-XParallelListComp`):
+      case () of
+        _ | guard1 -> expr1
+        ...
+        _ | guardN -> exprN
 
-   ::
+Multi-way if expressions introduce a new layout context. So the example
+above is equivalent to: ::
 
-       [ (x+y) | x <- [1..10]
-               | y <- [11..20]
-               ]
+      if { | guard1 -> expr1
+         ; | ...
+         ; | guardN -> exprN
+         }
 
-   Parallel statements are translated using the ``mzip`` function, which
-   requires a ``MonadZip`` instance defined in
-   :base-ref:`Control.Monad.Zip <Control-Monad-Zip.html>`:
+The following behaves as expected: ::
 
-   ::
+      if | guard1 -> if | guard2 -> expr2
+                        | guard3 -> expr3
+         | guard4 -> expr4
 
-       do (x,y) <- mzip (do x <- [1..10]
-                            return x)
-                        (do y <- [11..20]
-                            return y)
-          return (x+y)
+because layout translates it as ::
 
-All these features are enabled by default if the ``MonadComprehensions``
-extension is enabled. The types and more detailed examples on how to use
-comprehensions are explained in the previous chapters
-:ref:`generalised-list-comprehensions` and
-:ref:`parallel-list-comprehensions`. In general you just have to replace
-the type ``[a]`` with the type ``Monad m => m a`` for monad
-comprehensions.
+      if { | guard1 -> if { | guard2 -> expr2
+                          ; | guard3 -> expr3
+                          }
+         ; | guard4 -> expr4
+         }
 
-.. note::
-    Even though most of these examples are using the list monad, monad
-    comprehensions work for any monad. The ``base`` package offers all
-    necessary instances for lists, which make ``MonadComprehensions``
-    backward compatible to built-in, transform and parallel list
-    comprehensions.
+Layout with multi-way if works in the same way as other layout contexts,
+except that the semi-colons between guards in a multi-way if are
+optional. So it is not necessary to line up all the guards at the same
+column; this is consistent with the way guards work in function
+definitions and case expressions.
 
-More formally, the desugaring is as follows. We write ``D[ e | Q]`` to
-mean the desugaring of the monad comprehension ``[ e | Q]``:
+.. _local-fixity-declarations:
 
-::
+Local Fixity Declarations
+-------------------------
 
-    Expressions: e
-    Declarations: d
-    Lists of qualifiers: Q,R,S
+A careful reading of the Haskell 98 Report reveals that fixity
+declarations (``infix``, ``infixl``, and ``infixr``) are permitted to
+appear inside local bindings such those introduced by ``let`` and
+``where``. However, the Haskell Report does not specify the semantics of
+such bindings very precisely.
 
-    -- Basic forms
-    D[ e | ]               = return e
-    D[ e | p <- e, Q ]  = e >>= \p -> D[ e | Q ]
-    D[ e | e, Q ]          = guard e >> \p -> D[ e | Q ]
-    D[ e | let d, Q ]      = let d in D[ e | Q ]
+In GHC, a fixity declaration may accompany a local binding: ::
 
-    -- Parallel comprehensions (iterate for multiple parallel branches)
-    D[ e | (Q | R), S ]    = mzip D[ Qv | Q ] D[ Rv | R ] >>= \(Qv,Rv) -> D[ e | S ]
+    let f = ...
+        infixr 3 `f`
+    in
+        ...
 
-    -- Transform comprehensions
-    D[ e | Q then f, R ]                  = f D[ Qv | Q ] >>= \Qv -> D[ e | R ]
+and the fixity declaration applies wherever the binding is in scope. For
+example, in a ``let``, it applies in the right-hand sides of other
+``let``-bindings and the body of the ``let``\ C. Or, in recursive ``do``
+expressions (:ref:`recursive-do-notation`), the local fixity
+declarations of a ``let`` statement scope over other statements in the
+group, just as the bound name does.
 
-    D[ e | Q then f by b, R ]             = f (\Qv -> b) D[ Qv | Q ] >>= \Qv -> D[ e | R ]
+Moreover, a local fixity declaration *must* accompany a local binding
+of that name: it is not possible to revise the fixity of name bound
+elsewhere, as in ::
 
-    D[ e | Q then group using f, R ]      = f D[ Qv | Q ] >>= \ys ->
-                                            case (fmap selQv1 ys, ..., fmap selQvn ys) of
-                                             Qv -> D[ e | R ]
+    let infixr 9 $ in ...
 
-    D[ e | Q then group by b using f, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \ys ->
-                                            case (fmap selQv1 ys, ..., fmap selQvn ys) of
-                                               Qv -> D[ e | R ]
+Because local fixity declarations are technically Haskell 98, no flag is
+necessary to enable them.
 
-    where  Qv is the tuple of variables bound by Q (and used subsequently)
-           selQvi is a selector mapping Qv to the ith component of Qv
+.. _package-imports:
 
-    Operator     Standard binding       Expected type
-    --------------------------------------------------------------------
-    return       GHC.Base               t1 -> m t2
-    (>>=)        GHC.Base               m1 t1 -> (t2 -> m2 t3) -> m3 t3
-    (>>)         GHC.Base               m1 t1 -> m2 t2         -> m3 t3
-    guard        Control.Monad          t1 -> m t2
-    fmap         GHC.Base               forall a b. (a->b) -> n a -> n b
-    mzip         Control.Monad.Zip      forall a b. m a -> m b -> m (a,b)
+Import and export extensions
+----------------------------
 
-The comprehension should typecheck when its desugaring would typecheck,
-except that (as discussed in :ref:`generalised-list-comprehensions`) in the
-"then ``f``" and "then group using ``f``" clauses, when the "by ``b``" qualifier
-is omitted, argument ``f`` should have a polymorphic type. In particular, "then
-``Data.List.sort``" and "then group using ``Data.List.group``" are
-insufficiently polymorphic.
+Hiding things the imported module doesn't export
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Monad comprehensions support rebindable syntax
-(:ref:`rebindable-syntax`). Without rebindable syntax, the operators
-from the "standard binding" module are used; with rebindable syntax, the
-operators are looked up in the current lexical scope. For example,
-parallel comprehensions will be typechecked and desugared using whatever
-"``mzip``" is in scope.
+Technically in Haskell 2010 this is illegal: ::
 
-The rebindable operators must have the "Expected type" given in the
-table above. These types are surprisingly general. For example, you can
-use a bind operator with the type
+    module A( f ) where
+      f = True
 
-::
+    module B where
+      import A hiding( g )  -- A does not export g
+      g = f
 
-    (>>=) :: T x y a -> (a -> T y z b) -> T x z b
+The ``import A hiding( g )`` in module ``B`` is technically an error
+(`Haskell Report,
+5.3.1 <http://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-1020005.3.1>`__)
+because ``A`` does not export ``g``. However GHC allows it, in the
+interests of supporting backward compatibility; for example, a newer
+version of ``A`` might export ``g``, and you want ``B`` to work in
+either case.
 
-In the case of transform comprehensions, notice that the groups are
-parameterised over some arbitrary type ``n`` (provided it has an
-``fmap``, as well as the comprehension being over an arbitrary monad.
+The warning :ghc-flag:`-Wdodgy-imports`, which is off by default but included
+with :ghc-flag:`-W`, warns if you hide something that the imported module does
+not export.
 
-.. _monadfail-desugaring:
+.. _package-qualified-imports:
 
-New monadic failure desugaring mechanism
-----------------------------------------
+Package-qualified imports
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XMonadFailDesugaring
+.. ghc-flag:: -XPackageImports
 
-    :since: 8.0.1
+    Allow the use of package-qualified ``import`` syntax.
 
-    Use the ``MonadFail.fail`` instead of the legacy ``Monad.fail`` function
-    when desugaring refutable patterns in ``do`` blocks.
+With the :ghc-flag:`-XPackageImports` flag, GHC allows import declarations to be
+qualified by the package name that the module is intended to be imported
+from. For example: ::
 
-The ``-XMonadFailDesugaring`` extension switches the desugaring of
-``do``-blocks to use ``MonadFail.fail`` instead of ``Monad.fail``. This will
-eventually be the default behaviour in a future GHC release, under the
-`MonadFail Proposal (MFP)
-<https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
+    import "network" Network.Socket
 
-This extension is temporary, and will be deprecated in a future release. It is
-included so that library authors have a hard check for whether their code
-will work with future GHC versions.
+would import the module ``Network.Socket`` from the package ``network``
+(any version). This may be used to disambiguate an import when the same
+module is available from multiple packages, or is present in both the
+current package being built and an external package.
 
-.. _rebindable-syntax:
+The special package name ``this`` can be used to refer to the current
+package being built.
 
-Rebindable syntax and the implicit Prelude import
--------------------------------------------------
+.. note::
+   You probably don't need to use this feature, it was added mainly so that we
+   can build backwards-compatible versions of packages when APIs change. It can
+   lead to fragile dependencies in the common case: modules occasionally move
+   from one package to another, rendering any package-qualified imports broken.
+   See also :ref:`package-thinning-and-renaming` for an alternative way of
+   disambiguating between module names.
 
-.. ghc-flag:: -XNoImplicitPrelude
+.. _safe-imports-ext:
 
-    Don't import ``Prelude`` by default.
+Safe imports
+~~~~~~~~~~~~
 
-GHC normally imports ``Prelude.hi`` files for
-you. If you'd rather it didn't, then give it a ``-XNoImplicitPrelude``
-option. The idea is that you can then import a Prelude of your own. (But
-don't call it ``Prelude``; the Haskell module namespace is flat, and you
-must not conflict with any Prelude module.)
+.. ghc-flag:: -XSafe
+              -XTrustworthy
+              -XUnsafe
+    :noindex:
 
-.. ghc-flag:: -XRebindableSyntax
+    Declare the Safe Haskell state of the current module.
 
-    :implies: :ghc-flag:`-XNoImplicitPrelude`
-    :since: 7.0.1
+With the :ghc-flag:`-XSafe`, :ghc-flag:`-XTrustworthy` and :ghc-flag:`-XUnsafe`
+language flags, GHC extends the import declaration syntax to take an optional
+``safe`` keyword after the ``import`` keyword. This feature is part of the Safe
+Haskell GHC extension. For example: ::
 
-    Enable rebinding of a variety of usually-built-in operations.
+    import safe qualified Network.Socket as NS
 
-Suppose you are importing a Prelude of your own in order to define your
-own numeric class hierarchy. It completely defeats that purpose if the
-literal "1" means "``Prelude.fromInteger 1``", which is what the Haskell
-Report specifies. So the :ghc-flag:`-XRebindableSyntax` flag causes the
-following pieces of built-in syntax to refer to *whatever is in scope*,
-not the Prelude versions:
+would import the module ``Network.Socket`` with compilation only
+succeeding if ``Network.Socket`` can be safely imported. For a description of
+when a import is considered safe see :ref:`safe-haskell`.
 
--  An integer literal ``368`` means "``fromInteger (368::Integer)``",
-   rather than "``Prelude.fromInteger (368::Integer)``".
+.. _explicit-namespaces:
 
--  Fractional literals are handed in just the same way, except that the
-   translation is ``fromRational (3.68::Rational)``.
+Explicit namespaces in import/export
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  The equality test in an overloaded numeric pattern uses whatever
-   ``(==)`` is in scope.
+.. ghc-flag:: -XExplicitNamespaces
 
--  The subtraction operation, and the greater-than-or-equal test, in
-   ``n+k`` patterns use whatever ``(-)`` and ``(>=)`` are in scope.
+    :since: 7.6.1
 
--  Negation (e.g. "``- (f x)``") means "``negate (f x)``", both in
-   numeric patterns, and expressions.
+    Enable use of explicit namespaces in module export lists.
 
--  Conditionals (e.g. "``if`` e1 ``then`` e2 ``else`` e3") means
-   "``ifThenElse`` e1 e2 e3". However ``case`` expressions are
-   unaffected.
+In an import or export list, such as ::
 
--  "Do" notation is translated using whatever functions ``(>>=)``,
-   ``(>>)``, and ``fail``, are in scope (not the Prelude versions). List
-   comprehensions, ``mdo`` (:ref:`recursive-do-notation`), and parallel
-   array comprehensions, are unaffected.
+      module M( f, (++) ) where ...
+        import N( f, (++) )
+        ...
 
--  Arrow notation (see :ref:`arrow-notation`) uses whatever ``arr``,
-   ``(>>>)``, ``first``, ``app``, ``(|||)`` and ``loop`` functions are
-   in scope. But unlike the other constructs, the types of these
-   functions must match the Prelude types very closely. Details are in
-   flux; if you want to use this, ask!
+the entities ``f`` and ``(++)`` are *values*. However, with type
+operators (:ref:`type-operators`) it becomes possible to declare
+``(++)`` as a *type constructor*. In that case, how would you export or
+import it?
 
-:ghc-flag:`-XRebindableSyntax` implies :ghc-flag:`-XNoImplicitPrelude`.
+The :ghc-flag:`-XExplicitNamespaces` extension allows you to prefix the name of
+a type constructor in an import or export list with "``type``" to
+disambiguate this case, thus: ::
 
-In all cases (apart from arrow notation), the static semantics should be
-that of the desugared form, even if that is a little unexpected. For
-example, the static semantics of the literal ``368`` is exactly that of
-``fromInteger (368::Integer)``; it's fine for ``fromInteger`` to have
-any of the types: ::
+      module M( f, type (++) ) where ...
+        import N( f, type (++) )
+        ...
+      module N( f, type (++) ) where
+        data family a ++ b = L a | R b
 
-    fromInteger :: Integer -> Integer
-    fromInteger :: forall a. Foo a => Integer -> a
-    fromInteger :: Num a => a -> Integer
-    fromInteger :: Integer -> Bool -> Bool
+The extension :ghc-flag:`-XExplicitNamespaces` is implied by
+:ghc-flag:`-XTypeOperators` and (for some reason) by :ghc-flag:`-XTypeFamilies`.
 
-Be warned: this is an experimental facility, with fewer checks than
-usual. Use ``-dcore-lint`` to typecheck the desugared program. If Core
-Lint is happy you should be all right.
+In addition, with :ghc-flag:`-XPatternSynonyms` you can prefix the name of a
+data constructor in an import or export list with the keyword
+``pattern``, to allow the import or export of a data constructor without
+its parent type constructor (see :ref:`patsyn-impexp`).
 
-.. _postfix-operators:
+.. _visible-type-application:
 
-Postfix operators
------------------
+Visible type application
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XPostfixOperators
+.. ghc-flag:: -XTypeApplications
 
-    Allow the use of post-fix operators
+    :implies: :ghc-flag:`-XAllowAmbiguousTypes`
+    :since: 8.0.1
 
-The :ghc-flag:`-XPostfixOperators` flag enables a small extension to the syntax
-of left operator sections, which allows you to define postfix operators.
-The extension is this: the left section ::
+    Allow the use of type application syntax.
 
-      (e !)
+The :ghc-flag:`-XTypeApplications` extension allows you to use
+*visible type application* in expressions. Here is an
+example: ``show (read @Int "5")``. The ``@Int``
+is the visible type application; it specifies the value of the type variable
+in ``read``'s type.
 
-is equivalent (from the point of view of both type checking and
-execution) to the expression ::
+A visible type application is preceded with an ``@``
+sign. (To disambiguate the syntax, the ``@`` must be
+preceded with a non-identifier letter, usually a space. For example,
+``read@Int 5`` would not parse.) It can be used whenever
+the full polymorphic type of the function is known. If the function
+is an identifier (the common case), its type is considered known only when
+the identifier has been given a type signature. If the identifier does
+not have a type signature, visible type application cannot be used.
 
-      ((!) e)
+Here are the details:
 
-(for any expression ``e`` and operator ``(!)``. The strict Haskell 98
-interpretation is that the section is equivalent to ::
+- If an identifier's type signature does not include an
+  explicit ``forall``, the type variable arguments appear
+  in the left-to-right order in which the variables appear in the type.
+  So, ``foo :: Monad m => a b -> m (a c)``
+  will have its type variables
+  ordered as ``m, a, b, c``.
 
-      (\y -> (!) e y)
+- If any of the variables depend on other variables (that is, if some
+  of the variables are *kind* variables), the variables are reordered
+  so that kind variables come before type variables, preserving the
+  left-to-right order as much as possible. That is, GHC performs a
+  stable topological sort on the variables.
 
-That is, the operator must be a function of two arguments. GHC allows it
-to take only one argument, and that in turn allows you to write the
-function postfix.
+  For example: if we have ``bar :: Proxy (a :: (j, k)) -> b``, then
+  the variables are ordered ``j``, ``k``, ``a``, ``b``.
 
-The extension does not extend to the left-hand side of function
-definitions; you must define such a function in prefix form.
+- Class methods' type arguments include the class type
+  variables, followed by any variables an individual method is polymorphic
+  in. So, ``class Monad m where return :: a -> m a`` means
+  that ``return``'s type arguments are ``m, a``.
 
-.. _tuple-sections:
+- With the :ghc-flag:`-XRankNTypes` extension
+  (:ref:`universal-quantification`), it is possible to declare
+  type arguments somewhere other than the beginning of a type. For example,
+  we can have ``pair :: forall a. a -> forall b. b -> (a, b)``
+  and then say ``pair @Bool True @Char`` which would have
+  type ``Char -> (Bool, Char)``.
 
-Tuple sections
---------------
+- Partial type signatures (:ref:`partial-type-signatures`)
+  work nicely with visible type
+  application. If you want to specify only the second type argument to
+  ``wurble``, then you can say ``wurble @_ @Int``.
+  The first argument is a wildcard, just like in a partial type signature.
+  However, if used in a visible type application, it is *not*
+  necessary to specify :ghc-flag:`-XPartialTypeSignatures` and your
+  code will not generate a warning informing you of the omitted type.
 
-.. ghc-flag:: -XTupleSections
+.. _syntax-stolen:
 
-    Allow the use of tuple section syntax
+Summary of stolen syntax
+------------------------
+
+Turning on an option that enables special syntax *might* cause working
+Haskell 98 code to fail to compile, perhaps because it uses a variable
+name which has become a reserved word. This section lists the syntax
+that is "stolen" by language extensions. We use notation and nonterminal
+names from the Haskell 98 lexical syntax (see the Haskell 98 Report). We
+only list syntax changes here that might affect existing working
+programs (i.e. "stolen" syntax). Many of these extensions will also
+enable new context-free syntax, but in all cases programs written to use
+the new syntax would not be compilable without the option enabled.
 
-The :ghc-flag:`-XTupleSections` flag enables Python-style partially applied
-tuple constructors. For example, the following program ::
+There are two classes of special syntax:
 
-      (, True)
+-  New reserved words and symbols: character sequences which are no
+   longer available for use as identifiers in the program.
 
-is considered to be an alternative notation for the more unwieldy
-alternative ::
+-  Other special syntax: sequences of characters that have a different
+   meaning when this particular option is turned on.
 
-      \x -> (x, True)
+The following syntax is stolen:
 
-You can omit any combination of arguments to the tuple, as in the
-following ::
+``forall``
+    .. index::
+       single: forall
 
-      (, "I", , , "Love", , 1337)
+    Stolen (in types) by: :ghc-flag:`-XExplicitForAll`, and hence by
+    :ghc-flag:`-XScopedTypeVariables`, :ghc-flag:`-XLiberalTypeSynonyms`,
+    :ghc-flag:`-XRankNTypes`, :ghc-flag:`-XExistentialQuantification`
 
-which translates to ::
+``mdo``
+    .. index::
+       single: mdo
 
-      \a b c d -> (a, "I", b, c, "Love", d, 1337)
+    Stolen by: :ghc-flag:`-XRecursiveDo`
 
-If you have `unboxed tuples <#unboxed-tuples>`__ enabled, tuple sections
-will also be available for them, like so ::
+``foreign``
+    .. index::
+       single: foreign
 
-      (# , True #)
+    Stolen by: :ghc-flag:`-XForeignFunctionInterface`
 
-Because there is no unboxed unit tuple, the following expression ::
+``rec``, ``proc``, ``-<``, ``>-``, ``-<<``, ``>>-``, ``(|``, ``|)``
+    .. index::
+       single: proc
 
-      (# #)
+    Stolen by: :ghc-flag:`-XArrows`
 
-continues to stand for the unboxed singleton tuple data constructor.
+``?varid``
+    .. index::
+       single: implicit parameters
 
-.. _lambda-case:
+    Stolen by: :ghc-flag:`-XImplicitParams`
 
-Lambda-case
------------
+``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``$(``, ``$$(``, ``[||``, ``[e||``, ``$varid``, ``$$varid``
+    .. index::
+       single: Template Haskell
 
-.. ghc-flag:: -XLambdaCase
+    Stolen by: :ghc-flag:`-XTemplateHaskell`
 
-    :since: 7.6.1
+``[varid|``
+    .. index::
+       single: quasi-quotation
 
-    Allow the use of lambda-case syntax.
+    Stolen by: :ghc-flag:`-XQuasiQuotes`
 
-The :ghc-flag:`-XLambdaCase` flag enables expressions of the form ::
+⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##``
+    Stolen by: :ghc-flag:`-XMagicHash`
 
-      \case { p1 -> e1; ...; pN -> eN }
+``(#``, ``#)``
+    Stolen by: :ghc-flag:`-XUnboxedTuples`
 
-which is equivalent to ::
+⟨varid⟩, ``!``, ⟨varid⟩
+    Stolen by: :ghc-flag:`-XBangPatterns`
 
-      \freshName -> case freshName of { p1 -> e1; ...; pN -> eN }
+``pattern``
+    Stolen by: :ghc-flag:`-XPatternSynonyms`
 
-Note that ``\case`` starts a layout, so you can write ::
+.. _data-type-extensions:
 
-      \case
-        p1 -> e1
-        ...
-        pN -> eN
+Extensions to data types and type synonyms
+==========================================
 
-.. _empty-case:
+.. _nullary-types:
 
-Empty case alternatives
------------------------
+Data types with no constructors
+-------------------------------
 
-.. ghc-flag:: -XEmptyCase
+.. ghc-flag:: -XEmptyDataDecls
 
-    :since: 7.8.1
+    Allow definition of empty ``data`` types.
 
-    Allow empty case expressions.
+With the :ghc-flag:`-XEmptyDataDecls` flag (or equivalent ``LANGUAGE`` pragma), GHC
+lets you declare a data type with no constructors. For example: ::
 
-The :ghc-flag:`-XEmptyCase` flag enables case expressions, or lambda-case
-expressions, that have no alternatives, thus: ::
+      data S      -- S :: *
+      data T a    -- T :: * -> *
 
-    case e of { }   -- No alternatives
+Syntactically, the declaration lacks the "= constrs" part. The type can
+be parameterised over types of any kind, but if the kind is not ``*``
+then an explicit kind annotation must be used (see :ref:`kinding`).
 
-or ::
+Such data types have only one value, namely bottom. Nevertheless, they
+can be useful when defining "phantom types".
 
-    \case { }       -- -XLambdaCase is also required
+.. _datatype-contexts:
 
-This can be useful when you know that the expression being scrutinised
-has no non-bottom values. For example:
+Data type contexts
+------------------
 
-::
+.. ghc-flag:: -XDatatypeContexts
 
-      data Void
-      f :: Void -> Int
-      f x = case x of { }
+    :since: 7.0.1
 
-With dependently-typed features it is more useful (see :ghc-ticket:`2431``). For
-example, consider these two candidate definitions of ``absurd``:
+    Allow contexts on ``data`` types.
 
-::
+Haskell allows datatypes to be given contexts, e.g. ::
 
-    data a :==: b where
-      Refl :: a :==: a
+    data Eq a => Set a = NilSet | ConsSet a (Set a)
 
-    absurd :: True :~: False -> a
-    absurd x = error "absurd"    -- (A)
-    absurd x = case x of {}      -- (B)
+give constructors with types: ::
 
-We much prefer (B). Why? Because GHC can figure out that
-``(True :~: False)`` is an empty type. So (B) has no partiality and GHC
-should be able to compile with :ghc-flag:`-Wincomplete-patterns`. (Though
-the pattern match checking is not yet clever enough to do that.) On the
-other hand (A) looks dangerous, and GHC doesn't check to make sure that,
-in fact, the function can never get called.
+    NilSet :: Set a
+    ConsSet :: Eq a => a -> Set a -> Set a
 
-.. _multi-way-if:
+This is widely considered a misfeature, and is going to be removed from
+the language. In GHC, it is controlled by the deprecated extension
+``DatatypeContexts``.
 
-Multi-way if-expressions
-------------------------
+.. _infix-tycons:
 
-.. ghc-flag:: -XMultiWayIf
+Infix type constructors, classes, and type variables
+----------------------------------------------------
 
-    :since: 7.6.1
+GHC allows type constructors, classes, and type variables to be
+operators, and to be written infix, very much like expressions. More
+specifically:
 
-    Allow the use of multi-way-``if`` syntax.
+-  A type constructor or class can be any non-reserved operator.
+   Symbols used in types are always like capitalized identifiers; they
+   are never variables. Note that this is different from the lexical
+   syntax of data constructors, which are required to begin with a
+   ``:``.
 
-With :ghc-flag:`-XMultiWayIf` flag GHC accepts conditional expressions with
-multiple branches: ::
+-  Data type and type-synonym declarations can be written infix,
+   parenthesised if you want further arguments. E.g. ::
 
-      if | guard1 -> expr1
-         | ...
-         | guardN -> exprN
+         data a :*: b = Foo a b
+         type a :+: b = Either a b
+         class a :=: b where ...
 
-which is roughly equivalent to ::
+         data (a :**: b) x = Baz a b x
+         type (a :++: b) y = Either (a,b) y
 
-      case () of
-        _ | guard1 -> expr1
-        ...
-        _ | guardN -> exprN
+-  Types, and class constraints, can be written infix. For example ::
 
-Multi-way if expressions introduce a new layout context. So the example
-above is equivalent to: ::
+         x :: Int :*: Bool
+         f :: (a :=: b) => a -> b
 
-      if { | guard1 -> expr1
-         ; | ...
-         ; | guardN -> exprN
-         }
+-  Back-quotes work as for expressions, both for type constructors and
+   type variables; e.g. ``Int `Either` Bool``, or ``Int `a` Bool``.
+   Similarly, parentheses work the same; e.g. ``(:*:) Int Bool``.
 
-The following behaves as expected: ::
+-  Fixities may be declared for type constructors, or classes, just as
+   for data constructors. However, one cannot distinguish between the
+   two in a fixity declaration; a fixity declaration sets the fixity for
+   a data constructor and the corresponding type constructor. For
+   example: ::
 
-      if | guard1 -> if | guard2 -> expr2
-                        | guard3 -> expr3
-         | guard4 -> expr4
+         infixl 7 T, :*:
 
-because layout translates it as ::
+   sets the fixity for both type constructor ``T`` and data constructor
+   ``T``, and similarly for ``:*:``. ``Int `a` Bool``.
 
-      if { | guard1 -> if { | guard2 -> expr2
-                          ; | guard3 -> expr3
-                          }
-         ; | guard4 -> expr4
-         }
+-  Function arrow is ``infixr`` with fixity 0 (this might change; it's
+   not clear what it should be).
 
-Layout with multi-way if works in the same way as other layout contexts,
-except that the semi-colons between guards in a multi-way if are
-optional. So it is not necessary to line up all the guards at the same
-column; this is consistent with the way guards work in function
-definitions and case expressions.
+.. _type-operators:
 
-.. _local-fixity-declarations:
+Type operators
+--------------
 
-Local Fixity Declarations
--------------------------
+.. ghc-flag:: -XTypeOperators
 
-A careful reading of the Haskell 98 Report reveals that fixity
-declarations (``infix``, ``infixl``, and ``infixr``) are permitted to
-appear inside local bindings such those introduced by ``let`` and
-``where``. However, the Haskell Report does not specify the semantics of
-such bindings very precisely.
+    :implies: :ghc-flag:`-XExplicitNamespaces`
 
-In GHC, a fixity declaration may accompany a local binding: ::
+    Allow the use and definition of types with operator names.
 
-    let f = ...
-        infixr 3 `f`
-    in
-        ...
+In types, an operator symbol like ``(+)`` is normally treated as a type
+*variable*, just like ``a``. Thus in Haskell 98 you can say
 
-and the fixity declaration applies wherever the binding is in scope. For
-example, in a ``let``, it applies in the right-hand sides of other
-``let``-bindings and the body of the ``let``\ C. Or, in recursive ``do``
-expressions (:ref:`recursive-do-notation`), the local fixity
-declarations of a ``let`` statement scope over other statements in the
-group, just as the bound name does.
+::
 
-Moreover, a local fixity declaration *must* accompany a local binding
-of that name: it is not possible to revise the fixity of name bound
-elsewhere, as in ::
+    type T (+) = ((+), (+))
+    -- Just like: type T a = (a,a)
 
-    let infixr 9 $ in ...
+    f :: T Int -> Int
+    f (x,y)= x
 
-Because local fixity declarations are technically Haskell 98, no flag is
-necessary to enable them.
+As you can see, using operators in this way is not very useful, and
+Haskell 98 does not even allow you to write them infix.
 
-.. _package-imports:
+The language :ghc-flag:`-XTypeOperators` changes this behaviour:
 
-Import and export extensions
-----------------------------
+-  Operator symbols become type *constructors* rather than type
+   *variables*.
 
-Hiding things the imported module doesn't export
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-  Operator symbols in types can be written infix, both in definitions
+   and uses. For example: ::
 
-Technically in Haskell 2010 this is illegal: ::
+       data a + b = Plus a b
+       type Foo = Int + Bool
 
-    module A( f ) where
-      f = True
+-  There is now some potential ambiguity in import and export lists; for
+   example if you write ``import M( (+) )`` do you mean the *function*
+   ``(+)`` or the *type constructor* ``(+)``? The default is the former,
+   but with :ghc-flag:`-XExplicitNamespaces` (which is implied by
+   :ghc-flag:`-XTypeOperators`) GHC allows you to specify the latter by
+   preceding it with the keyword ``type``, thus: ::
 
-    module B where
-      import A hiding( g )  -- A does not export g
-      g = f
+       import M( type (+) )
 
-The ``import A hiding( g )`` in module ``B`` is technically an error
-(`Haskell Report,
-5.3.1 <http://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-1020005.3.1>`__)
-because ``A`` does not export ``g``. However GHC allows it, in the
-interests of supporting backward compatibility; for example, a newer
-version of ``A`` might export ``g``, and you want ``B`` to work in
-either case.
+   See :ref:`explicit-namespaces`.
 
-The warning :ghc-flag:`-Wdodgy-imports`, which is off by default but included
-with :ghc-flag:`-W`, warns if you hide something that the imported module does
-not export.
+-  The fixity of a type operator may be set using the usual fixity
+   declarations but, as in :ref:`infix-tycons`, the function and type
+   constructor share a single fixity.
 
-.. _package-qualified-imports:
+.. _type-synonyms:
 
-Package-qualified imports
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Liberalised type synonyms
+-------------------------
 
-.. ghc-flag:: -XPackageImports
+.. ghc-flag:: -XLiberalTypeSynonyms
 
-    Allow the use of package-qualified ``import`` syntax.
+    :implies: :ghc-flag:`-XExplicitForAll`
 
-With the :ghc-flag:`-XPackageImports` flag, GHC allows import declarations to be
-qualified by the package name that the module is intended to be imported
-from. For example: ::
+    Relax many of the Haskell 98 rules on type synonym definitions.
 
-    import "network" Network.Socket
+Type synonyms are like macros at the type level, but Haskell 98 imposes
+many rules on individual synonym declarations. With the
+:ghc-flag:`-XLiberalTypeSynonyms` extension, GHC does validity checking on types
+*only after expanding type synonyms*. That means that GHC can be very
+much more liberal about type synonyms than Haskell 98.
 
-would import the module ``Network.Socket`` from the package ``network``
-(any version). This may be used to disambiguate an import when the same
-module is available from multiple packages, or is present in both the
-current package being built and an external package.
+-  You can write a ``forall`` (including overloading) in a type synonym,
+   thus: ::
 
-The special package name ``this`` can be used to refer to the current
-package being built.
+         type Discard a = forall b. Show b => a -> b -> (a, String)
 
-.. note::
-   You probably don't need to use this feature, it was added mainly so that we
-   can build backwards-compatible versions of packages when APIs change. It can
-   lead to fragile dependencies in the common case: modules occasionally move
-   from one package to another, rendering any package-qualified imports broken.
-   See also :ref:`package-thinning-and-renaming` for an alternative way of
-   disambiguating between module names.
+         f :: Discard a
+         f x y = (x, show y)
 
-.. _safe-imports-ext:
+         g :: Discard Int -> (Int,String)    -- A rank-2 type
+         g f = f 3 True
 
-Safe imports
-~~~~~~~~~~~~
+-  If you also use :ghc-flag:`-XUnboxedTuples`, you can write an unboxed tuple
+   in a type synonym: ::
 
-.. ghc-flag:: -XSafe
-              -XTrustworthy
-              -XUnsafe
-    :noindex:
+         type Pr = (# Int, Int #)
 
-    Declare the Safe Haskell state of the current module.
+         h :: Int -> Pr
+         h x = (# x, x #)
 
-With the :ghc-flag:`-XSafe`, :ghc-flag:`-XTrustworthy` and :ghc-flag:`-XUnsafe`
-language flags, GHC extends the import declaration syntax to take an optional
-``safe`` keyword after the ``import`` keyword. This feature is part of the Safe
-Haskell GHC extension. For example: ::
+-  You can apply a type synonym to a forall type: ::
 
-    import safe qualified Network.Socket as NS
+         type Foo a = a -> a -> Bool
 
-would import the module ``Network.Socket`` with compilation only
-succeeding if ``Network.Socket`` can be safely imported. For a description of
-when a import is considered safe see :ref:`safe-haskell`.
+         f :: Foo (forall b. b->b)
 
-.. _explicit-namespaces:
+   After expanding the synonym, ``f`` has the legal (in GHC) type: ::
 
-Explicit namespaces in import/export
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+         f :: (forall b. b->b) -> (forall b. b->b) -> Bool
 
-.. ghc-flag:: -XExplicitNamespaces
+-  You can apply a type synonym to a partially applied type synonym: ::
 
-    :since: 7.6.1
+         type Generic i o = forall x. i x -> o x
+         type Id x = x
 
-    Enable use of explicit namespaces in module export lists.
+         foo :: Generic Id []
 
-In an import or export list, such as ::
+   After expanding the synonym, ``foo`` has the legal (in GHC) type: ::
 
-      module M( f, (++) ) where ...
-        import N( f, (++) )
-        ...
+         foo :: forall x. x -> [x]
 
-the entities ``f`` and ``(++)`` are *values*. However, with type
-operators (:ref:`type-operators`) it becomes possible to declare
-``(++)`` as a *type constructor*. In that case, how would you export or
-import it?
+GHC currently does kind checking before expanding synonyms (though even
+that could be changed)..
 
-The :ghc-flag:`-XExplicitNamespaces` extension allows you to prefix the name of
-a type constructor in an import or export list with "``type``" to
-disambiguate this case, thus: ::
+After expanding type synonyms, GHC does validity checking on types,
+looking for the following mal-formedness which isn't detected simply by
+kind checking:
 
-      module M( f, type (++) ) where ...
-        import N( f, type (++) )
-        ...
-      module N( f, type (++) ) where
-        data family a ++ b = L a | R b
+-  Type constructor applied to a type involving for-alls (if
+   :ghc-flag:`-XImpredicativeTypes` is off)
 
-The extension :ghc-flag:`-XExplicitNamespaces` is implied by
-:ghc-flag:`-XTypeOperators` and (for some reason) by :ghc-flag:`-XTypeFamilies`.
+-  Partially-applied type synonym.
 
-In addition, with :ghc-flag:`-XPatternSynonyms` you can prefix the name of a
-data constructor in an import or export list with the keyword
-``pattern``, to allow the import or export of a data constructor without
-its parent type constructor (see :ref:`patsyn-impexp`).
+So, for example, this will be rejected: ::
 
-.. _visible-type-application:
+      type Pr = forall a. a
 
-Visible type application
-~~~~~~~~~~~~~~~~~~~~~~~~
+      h :: [Pr]
+      h = ...
 
-.. ghc-flag:: -XTypeApplications
+because GHC does not allow type constructors applied to for-all types.
 
-    :implies: :ghc-flag:`-XAllowAmbiguousTypes`
-    :since: 8.0.1
+.. _existential-quantification:
 
-    Allow the use of type application syntax.
+Existentially quantified data constructors
+------------------------------------------
 
-The :ghc-flag:`-XTypeApplications` extension allows you to use
-*visible type application* in expressions. Here is an
-example: ``show (read @Int "5")``. The ``@Int``
-is the visible type application; it specifies the value of the type variable
-in ``read``'s type.
+.. ghc-flag:: -XExistentialQuantification
 
-A visible type application is preceded with an ``@``
-sign. (To disambiguate the syntax, the ``@`` must be
-preceded with a non-identifier letter, usually a space. For example,
-``read@Int 5`` would not parse.) It can be used whenever
-the full polymorphic type of the function is known. If the function
-is an identifier (the common case), its type is considered known only when
-the identifier has been given a type signature. If the identifier does
-not have a type signature, visible type application cannot be used.
+    :implies: :ghc-flag:`-XExplicitForAll`
 
-Here are the details:
+    Allow existentially quantified type variables in types.
 
-- If an identifier's type signature does not include an
-  explicit ``forall``, the type variable arguments appear
-  in the left-to-right order in which the variables appear in the type.
-  So, ``foo :: Monad m => a b -> m (a c)``
-  will have its type variables
-  ordered as ``m, a, b, c``.
+The idea of using existential quantification in data type declarations
+was suggested by Perry, and implemented in Hope+ (Nigel Perry, *The
+Implementation of Practical Functional Programming Languages*, PhD
+Thesis, University of London, 1991). It was later formalised by Laufer
+and Odersky (*Polymorphic type inference and abstract data types*,
+TOPLAS, 16(5), pp. 1411-1430, 1994). It's been in Lennart Augustsson's
+``hbc`` Haskell compiler for several years, and proved very useful.
+Here's the idea. Consider the declaration: ::
 
-- If any of the variables depend on other variables (that is, if some
-  of the variables are *kind* variables), the variables are reordered
-  so that kind variables come before type variables, preserving the
-  left-to-right order as much as possible. That is, GHC performs a
-  stable topological sort on the variables.
+      data Foo = forall a. MkFoo a (a -> Bool)
+               | Nil
 
-  For example: if we have ``bar :: Proxy (a :: (j, k)) -> b``, then
-  the variables are ordered ``j``, ``k``, ``a``, ``b``.
+The data type ``Foo`` has two constructors with types: ::
 
-- Class methods' type arguments include the class type
-  variables, followed by any variables an individual method is polymorphic
-  in. So, ``class Monad m where return :: a -> m a`` means
-  that ``return``'s type arguments are ``m, a``.
+      MkFoo :: forall a. a -> (a -> Bool) -> Foo
+      Nil   :: Foo
 
-- With the :ghc-flag:`-XRankNTypes` extension
-  (:ref:`universal-quantification`), it is possible to declare
-  type arguments somewhere other than the beginning of a type. For example,
-  we can have ``pair :: forall a. a -> forall b. b -> (a, b)``
-  and then say ``pair @Bool True @Char`` which would have
-  type ``Char -> (Bool, Char)``.
+Notice that the type variable ``a`` in the type of ``MkFoo`` does not
+appear in the data type itself, which is plain ``Foo``. For example, the
+following expression is fine: ::
 
-- Partial type signatures (:ref:`partial-type-signatures`)
-  work nicely with visible type
-  application. If you want to specify only the second type argument to
-  ``wurble``, then you can say ``wurble @_ @Int``.
-  The first argument is a wildcard, just like in a partial type signature.
-  However, if used in a visible type application, it is *not*
-  necessary to specify :ghc-flag:`-XPartialTypeSignatures` and your
-  code will not generate a warning informing you of the omitted type.
+      [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo]
 
-.. _syntax-stolen:
+Here, ``(MkFoo 3 even)`` packages an integer with a function ``even``
+that maps an integer to ``Bool``; and ``MkFoo 'c'
+isUpper`` packages a character with a compatible function. These two
+things are each of type ``Foo`` and can be put in a list.
 
-Summary of stolen syntax
-------------------------
+What can we do with a value of type ``Foo``? In particular, what
+happens when we pattern-match on ``MkFoo``? ::
 
-Turning on an option that enables special syntax *might* cause working
-Haskell 98 code to fail to compile, perhaps because it uses a variable
-name which has become a reserved word. This section lists the syntax
-that is "stolen" by language extensions. We use notation and nonterminal
-names from the Haskell 98 lexical syntax (see the Haskell 98 Report). We
-only list syntax changes here that might affect existing working
-programs (i.e. "stolen" syntax). Many of these extensions will also
-enable new context-free syntax, but in all cases programs written to use
-the new syntax would not be compilable without the option enabled.
+      f (MkFoo val fn) = ???
 
-There are two classes of special syntax:
+Since all we know about ``val`` and ``fn`` is that they are compatible,
+the only (useful) thing we can do with them is to apply ``fn`` to
+``val`` to get a boolean. For example: ::
 
--  New reserved words and symbols: character sequences which are no
-   longer available for use as identifiers in the program.
+      f :: Foo -> Bool
+      f (MkFoo val fn) = fn val
 
--  Other special syntax: sequences of characters that have a different
-   meaning when this particular option is turned on.
+What this allows us to do is to package heterogeneous values together
+with a bunch of functions that manipulate them, and then treat that
+collection of packages in a uniform manner. You can express quite a bit
+of object-oriented-like programming this way.
 
-The following syntax is stolen:
+.. _existential:
 
-``forall``
-    .. index::
-       single: forall
+Why existential?
+~~~~~~~~~~~~~~~~
 
-    Stolen (in types) by: :ghc-flag:`-XExplicitForAll`, and hence by
-    :ghc-flag:`-XScopedTypeVariables`, :ghc-flag:`-XLiberalTypeSynonyms`,
-    :ghc-flag:`-XRankNTypes`, :ghc-flag:`-XExistentialQuantification`
+What has this to do with *existential* quantification? Simply that
+``MkFoo`` has the (nearly) isomorphic type ::
 
-``mdo``
-    .. index::
-       single: mdo
+      MkFoo :: (exists a . (a, a -> Bool)) -> Foo
 
-    Stolen by: :ghc-flag:`-XRecursiveDo`
+But Haskell programmers can safely think of the ordinary *universally*
+quantified type given above, thereby avoiding adding a new existential
+quantification construct.
 
-``foreign``
-    .. index::
-       single: foreign
+.. _existential-with-context:
 
-    Stolen by: :ghc-flag:`-XForeignFunctionInterface`
+Existentials and type classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``rec``, ``proc``, ``-<``, ``>-``, ``-<<``, ``>>-``, ``(|``, ``|)``
-    .. index::
-       single: proc
+An easy extension is to allow arbitrary contexts before the constructor.
+For example: ::
 
-    Stolen by: :ghc-flag:`-XArrows`
+    data Baz = forall a. Eq a => Baz1 a a
+             | forall b. Show b => Baz2 b (b -> b)
 
-``?varid``
-    .. index::
-       single: implicit parameters
+The two constructors have the types you'd expect: ::
 
-    Stolen by: :ghc-flag:`-XImplicitParams`
+    Baz1 :: forall a. Eq a => a -> a -> Baz
+    Baz2 :: forall b. Show b => b -> (b -> b) -> Baz
 
-``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``$(``, ``$$(``, ``[||``, ``[e||``, ``$varid``, ``$$varid``
-    .. index::
-       single: Template Haskell
+But when pattern matching on ``Baz1`` the matched values can be compared
+for equality, and when pattern matching on ``Baz2`` the first matched
+value can be converted to a string (as well as applying the function to
+it). So this program is legal: ::
 
-    Stolen by: :ghc-flag:`-XTemplateHaskell`
+      f :: Baz -> String
+      f (Baz1 p q) | p == q    = "Yes"
+                   | otherwise = "No"
+      f (Baz2 v fn)            = show (fn v)
 
-``[varid|``
-    .. index::
-       single: quasi-quotation
+Operationally, in a dictionary-passing implementation, the constructors
+``Baz1`` and ``Baz2`` must store the dictionaries for ``Eq`` and
+``Show`` respectively, and extract it on pattern matching.
 
-    Stolen by: :ghc-flag:`-XQuasiQuotes`
+.. _existential-records:
 
-⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##``
-    Stolen by: :ghc-flag:`-XMagicHash`
+Record Constructors
+~~~~~~~~~~~~~~~~~~~
 
-``(#``, ``#)``
-    Stolen by: :ghc-flag:`-XUnboxedTuples`
+GHC allows existentials to be used with records syntax as well. For
+example: ::
 
-⟨varid⟩, ``!``, ⟨varid⟩
-    Stolen by: :ghc-flag:`-XBangPatterns`
+    data Counter a = forall self. NewCounter
+        { _this    :: self
+        , _inc     :: self -> self
+        , _display :: self -> IO ()
+        , tag      :: a
+        }
 
-``pattern``
-    Stolen by: :ghc-flag:`-XPatternSynonyms`
+Here ``tag`` is a public field, with a well-typed selector function
+``tag :: Counter a -> a``. The ``self`` type is hidden from the outside;
+any attempt to apply ``_this``, ``_inc`` or ``_display`` as functions
+will raise a compile-time error. In other words, *GHC defines a record
+selector function only for fields whose type does not mention the
+existentially-quantified variables*. (This example used an underscore in
+the fields for which record selectors will not be defined, but that is
+only programming style; GHC ignores them.)
 
-.. _data-type-extensions:
+To make use of these hidden fields, we need to create some helper
+functions: ::
 
-Extensions to data types and type synonyms
-==========================================
+    inc :: Counter a -> Counter a
+    inc (NewCounter x i d t) = NewCounter
+        { _this = i x, _inc = i, _display = d, tag = t }
 
-.. _nullary-types:
+    display :: Counter a -> IO ()
+    display NewCounter{ _this = x, _display = d } = d x
 
-Data types with no constructors
--------------------------------
+Now we can define counters with different underlying implementations: ::
 
-.. ghc-flag:: -XEmptyDataDecls
+    counterA :: Counter String
+    counterA = NewCounter
+        { _this = 0, _inc = (1+), _display = print, tag = "A" }
 
-    Allow definition of empty ``data`` types.
+    counterB :: Counter String
+    counterB = NewCounter
+        { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" }
 
-With the :ghc-flag:`-XEmptyDataDecls` flag (or equivalent ``LANGUAGE`` pragma), GHC
-lets you declare a data type with no constructors. For example: ::
+    main = do
+        display (inc counterA)         -- prints "1"
+        display (inc (inc counterB))   -- prints "##"
 
-      data S      -- S :: *
-      data T a    -- T :: * -> *
+Record update syntax is supported for existentials (and GADTs): ::
 
-Syntactically, the declaration lacks the "= constrs" part. The type can
-be parameterised over types of any kind, but if the kind is not ``*``
-then an explicit kind annotation must be used (see :ref:`kinding`).
+    setTag :: Counter a -> a -> Counter a
+    setTag obj t = obj{ tag = t }
 
-Such data types have only one value, namely bottom. Nevertheless, they
-can be useful when defining "phantom types".
+The rule for record update is this:
 
-.. _datatype-contexts:
+    the types of the updated fields may mention only the universally-quantified
+    type variables of the data constructor. For GADTs, the field may mention
+    only types that appear as a simple type-variable argument in the
+    constructor's result type.
 
-Data type contexts
-------------------
+For example: ::
 
-.. ghc-flag:: -XDatatypeContexts
+    data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
+    upd1 t x = t { f1=x }   -- OK:   upd1 :: T a b -> a' -> T a' b
+    upd2 t x = t { f3=x }   -- BAD   (f3's type mentions c, which is
+                            --        existentially quantified)
 
-    :since: 7.0.1
+    data G a b where { G1 { g1::a, g2::c } :: G a [c] }
+    upd3 g x = g { g1=x }   -- OK:   upd3 :: G a b -> c -> G c b
+    upd4 g x = g { g2=x }   -- BAD (f2's type mentions c, which is not a simple
+                            --      type-variable argument in G1's result type)
 
-    Allow contexts on ``data`` types.
+Restrictions
+~~~~~~~~~~~~
 
-Haskell allows datatypes to be given contexts, e.g. ::
+There are several restrictions on the ways in which existentially-quantified
+constructors can be used.
 
-    data Eq a => Set a = NilSet | ConsSet a (Set a)
+-  When pattern matching, each pattern match introduces a new, distinct,
+   type for each existential type variable. These types cannot be
+   unified with any other type, nor can they escape from the scope of
+   the pattern match. For example, these fragments are incorrect: ::
 
-give constructors with types: ::
+       f1 (MkFoo a f) = a
 
-    NilSet :: Set a
-    ConsSet :: Eq a => a -> Set a -> Set a
+   Here, the type bound by ``MkFoo`` "escapes", because ``a`` is the
+   result of ``f1``. One way to see why this is wrong is to ask what
+   type ``f1`` has: ::
 
-This is widely considered a misfeature, and is going to be removed from
-the language. In GHC, it is controlled by the deprecated extension
-``DatatypeContexts``.
+         f1 :: Foo -> a             -- Weird!
 
-.. _infix-tycons:
+   What is this "``a``" in the result type? Clearly we don't mean this: ::
 
-Infix type constructors, classes, and type variables
-----------------------------------------------------
+         f1 :: forall a. Foo -> a   -- Wrong!
 
-GHC allows type constructors, classes, and type variables to be
-operators, and to be written infix, very much like expressions. More
-specifically:
+   The original program is just plain wrong. Here's another sort of
+   error ::
 
--  A type constructor or class can be any non-reserved operator.
-   Symbols used in types are always like capitalized identifiers; they
-   are never variables. Note that this is different from the lexical
-   syntax of data constructors, which are required to begin with a
-   ``:``.
+         f2 (Baz1 a b) (Baz1 p q) = a==q
 
--  Data type and type-synonym declarations can be written infix,
-   parenthesised if you want further arguments. E.g. ::
+   It's ok to say ``a==b`` or ``p==q``, but ``a==q`` is wrong because it
+   equates the two distinct types arising from the two ``Baz1``
+   constructors.
 
-         data a :*: b = Foo a b
-         type a :+: b = Either a b
-         class a :=: b where ...
+-  You can't pattern-match on an existentially quantified constructor in
+   a ``let`` or ``where`` group of bindings. So this is illegal: ::
 
-         data (a :**: b) x = Baz a b x
-         type (a :++: b) y = Either (a,b) y
+         f3 x = a==b where { Baz1 a b = x }
 
--  Types, and class constraints, can be written infix. For example ::
+   Instead, use a ``case`` expression: ::
 
-         x :: Int :*: Bool
-         f :: (a :=: b) => a -> b
+         f3 x = case x of Baz1 a b -> a==b
 
--  Back-quotes work as for expressions, both for type constructors and
-   type variables; e.g. ``Int `Either` Bool``, or ``Int `a` Bool``.
-   Similarly, parentheses work the same; e.g. ``(:*:) Int Bool``.
+   In general, you can only pattern-match on an existentially-quantified
+   constructor in a ``case`` expression or in the patterns of a function
+   definition. The reason for this restriction is really an
+   implementation one. Type-checking binding groups is already a
+   nightmare without existentials complicating the picture. Also an
+   existential pattern binding at the top level of a module doesn't make
+   sense, because it's not clear how to prevent the
+   existentially-quantified type "escaping". So for now, there's a
+   simple-to-state restriction. We'll see how annoying it is.
 
--  Fixities may be declared for type constructors, or classes, just as
-   for data constructors. However, one cannot distinguish between the
-   two in a fixity declaration; a fixity declaration sets the fixity for
-   a data constructor and the corresponding type constructor. For
-   example: ::
+-  You can't use existential quantification for ``newtype``
+   declarations. So this is illegal: ::
 
-         infixl 7 T, :*:
+         newtype T = forall a. Ord a => MkT a
 
-   sets the fixity for both type constructor ``T`` and data constructor
-   ``T``, and similarly for ``:*:``. ``Int `a` Bool``.
+   Reason: a value of type ``T`` must be represented as a pair of a
+   dictionary for ``Ord t`` and a value of type ``t``. That contradicts
+   the idea that ``newtype`` should have no concrete representation. You
+   can get just the same efficiency and effect by using ``data`` instead
+   of ``newtype``. If there is no overloading involved, then there is
+   more of a case for allowing an existentially-quantified ``newtype``,
+   because the ``data`` version does carry an implementation cost, but
+   single-field existentially quantified constructors aren't much use.
+   So the simple restriction (no existential stuff on ``newtype``)
+   stands, unless there are convincing reasons to change it.
 
--  Function arrow is ``infixr`` with fixity 0 (this might change; it's
-   not clear what it should be).
+-  You can't use ``deriving`` to define instances of a data type with
+   existentially quantified data constructors. Reason: in most cases it
+   would not make sense. For example:; ::
 
-.. _type-operators:
+       data T = forall a. MkT [a] deriving( Eq )
 
-Type operators
---------------
+   To derive ``Eq`` in the standard way we would need to have equality
+   between the single component of two ``MkT`` constructors: ::
 
-.. ghc-flag:: -XTypeOperators
+       instance Eq T where
+         (MkT a) == (MkT b) = ???
 
-    :implies: :ghc-flag:`-XExplicitNamespaces`
+   But ``a`` and ``b`` have distinct types, and so can't be compared.
+   It's just about possible to imagine examples in which the derived
+   instance would make sense, but it seems altogether simpler simply to
+   prohibit such declarations. Define your own instances!
 
-    Allow the use and definition of types with operator names.
+.. _gadt-style:
 
-In types, an operator symbol like ``(+)`` is normally treated as a type
-*variable*, just like ``a``. Thus in Haskell 98 you can say
+Declaring data types with explicit constructor signatures
+---------------------------------------------------------
 
-::
+.. ghc-flag:: -XGADTSyntax
 
-    type T (+) = ((+), (+))
-    -- Just like: type T a = (a,a)
+    Allow the use of GADT syntax in data type definitions (but not GADTs
+    themselves; for this see :ghc-flag:`-XGADTs`)
 
-    f :: T Int -> Int
-    f (x,y)= x
+When the ``GADTSyntax`` extension is enabled, GHC allows you to declare
+an algebraic data type by giving the type signatures of constructors
+explicitly. For example: ::
 
-As you can see, using operators in this way is not very useful, and
-Haskell 98 does not even allow you to write them infix.
+      data Maybe a where
+          Nothing :: Maybe a
+          Just    :: a -> Maybe a
 
-The language :ghc-flag:`-XTypeOperators` changes this behaviour:
+The form is called a "GADT-style declaration" because Generalised
+Algebraic Data Types, described in :ref:`gadt`, can only be declared
+using this form.
 
--  Operator symbols become type *constructors* rather than type
-   *variables*.
+Notice that GADT-style syntax generalises existential types
+(:ref:`existential-quantification`). For example, these two declarations
+are equivalent: ::
 
--  Operator symbols in types can be written infix, both in definitions
-   and uses. For example: ::
+      data Foo = forall a. MkFoo a (a -> Bool)
+      data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' }
 
-       data a + b = Plus a b
-       type Foo = Int + Bool
+Any data type that can be declared in standard Haskell 98 syntax can
+also be declared using GADT-style syntax. The choice is largely
+stylistic, but GADT-style declarations differ in one important respect:
+they treat class constraints on the data constructors differently.
+Specifically, if the constructor is given a type-class context, that
+context is made available by pattern matching. For example: ::
 
--  There is now some potential ambiguity in import and export lists; for
-   example if you write ``import M( (+) )`` do you mean the *function*
-   ``(+)`` or the *type constructor* ``(+)``? The default is the former,
-   but with :ghc-flag:`-XExplicitNamespaces` (which is implied by
-   :ghc-flag:`-XTypeOperators`) GHC allows you to specify the latter by
-   preceding it with the keyword ``type``, thus: ::
+      data Set a where
+        MkSet :: Eq a => [a] -> Set a
 
-       import M( type (+) )
+      makeSet :: Eq a => [a] -> Set a
+      makeSet xs = MkSet (nub xs)
 
-   See :ref:`explicit-namespaces`.
+      insert :: a -> Set a -> Set a
+      insert a (MkSet as) | a `elem` as = MkSet as
+                          | otherwise   = MkSet (a:as)
 
--  The fixity of a type operator may be set using the usual fixity
-   declarations but, as in :ref:`infix-tycons`, the function and type
-   constructor share a single fixity.
+A use of ``MkSet`` as a constructor (e.g. in the definition of
+``makeSet``) gives rise to a ``(Eq a)`` constraint, as you would expect.
+The new feature is that pattern-matching on ``MkSet`` (as in the
+definition of ``insert``) makes *available* an ``(Eq a)`` context. In
+implementation terms, the ``MkSet`` constructor has a hidden field that
+stores the ``(Eq a)`` dictionary that is passed to ``MkSet``; so when
+pattern-matching that dictionary becomes available for the right-hand
+side of the match. In the example, the equality dictionary is used to
+satisfy the equality constraint generated by the call to ``elem``, so
+that the type of ``insert`` itself has no ``Eq`` constraint.
 
-.. _type-synonyms:
+For example, one possible application is to reify dictionaries: ::
 
-Liberalised type synonyms
--------------------------
+       data NumInst a where
+         MkNumInst :: Num a => NumInst a
 
-.. ghc-flag:: -XLiberalTypeSynonyms
+       intInst :: NumInst Int
+       intInst = MkNumInst
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+       plus :: NumInst a -> a -> a -> a
+       plus MkNumInst p q = p + q
 
-    Relax many of the Haskell 98 rules on type synonym definitions.
+Here, a value of type ``NumInst a`` is equivalent to an explicit
+``(Num a)`` dictionary.
 
-Type synonyms are like macros at the type level, but Haskell 98 imposes
-many rules on individual synonym declarations. With the
-:ghc-flag:`-XLiberalTypeSynonyms` extension, GHC does validity checking on types
-*only after expanding type synonyms*. That means that GHC can be very
-much more liberal about type synonyms than Haskell 98.
+All this applies to constructors declared using the syntax of
+:ref:`existential-with-context`. For example, the ``NumInst`` data type
+above could equivalently be declared like this: ::
 
--  You can write a ``forall`` (including overloading) in a type synonym,
-   thus: ::
+       data NumInst a
+          = Num a => MkNumInst (NumInst a)
 
-         type Discard a = forall b. Show b => a -> b -> (a, String)
+Notice that, unlike the situation when declaring an existential, there
+is no ``forall``, because the ``Num`` constrains the data type's
+universally quantified type variable ``a``. A constructor may have both
+universal and existential type variables: for example, the following two
+declarations are equivalent: ::
 
-         f :: Discard a
-         f x y = (x, show y)
+       data T1 a
+        = forall b. (Num a, Eq b) => MkT1 a b
+       data T2 a where
+        MkT2 :: (Num a, Eq b) => a -> b -> T2 a
 
-         g :: Discard Int -> (Int,String)    -- A rank-2 type
-         g f = f 3 True
+All this behaviour contrasts with Haskell 98's peculiar treatment of
+contexts on a data type declaration (Section 4.2.1 of the Haskell 98
+Report). In Haskell 98 the definition ::
 
--  If you also use :ghc-flag:`-XUnboxedTuples`, you can write an unboxed tuple
-   in a type synonym: ::
+      data Eq a => Set' a = MkSet' [a]
 
-         type Pr = (# Int, Int #)
+gives ``MkSet'`` the same type as ``MkSet`` above. But instead of
+*making available* an ``(Eq a)`` constraint, pattern-matching on
+``MkSet'`` *requires* an ``(Eq a)`` constraint! GHC faithfully
+implements this behaviour, odd though it is. But for GADT-style
+declarations, GHC's behaviour is much more useful, as well as much more
+intuitive.
 
-         h :: Int -> Pr
-         h x = (# x, x #)
+The rest of this section gives further details about GADT-style data
+type declarations.
 
--  You can apply a type synonym to a forall type: ::
+-  The result type of each data constructor must begin with the type
+   constructor being defined. If the result type of all constructors has
+   the form ``T a1 ... an``, where ``a1 ... an`` are distinct type
+   variables, then the data type is *ordinary*; otherwise is a
+   *generalised* data type (:ref:`gadt`).
 
-         type Foo a = a -> a -> Bool
+-  As with other type signatures, you can give a single signature for
+   several data constructors. In this example we give a single signature
+   for ``T1`` and ``T2``: ::
 
-         f :: Foo (forall b. b->b)
+         data T a where
+           T1,T2 :: a -> T a
+           T3 :: T a
 
-   After expanding the synonym, ``f`` has the legal (in GHC) type: ::
+-  The type signature of each constructor is independent, and is
+   implicitly universally quantified as usual. In particular, the type
+   variable(s) in the "``data T a where``" header have no scope, and
+   different constructors may have different universally-quantified type
+   variables: ::
 
-         f :: (forall b. b->b) -> (forall b. b->b) -> Bool
+         data T a where        -- The 'a' has no scope
+           T1,T2 :: b -> T b   -- Means forall b. b -> T b
+           T3 :: T a           -- Means forall a. T a
 
--  You can apply a type synonym to a partially applied type synonym: ::
+-  A constructor signature may mention type class constraints, which can
+   differ for different constructors. For example, this is fine: ::
 
-         type Generic i o = forall x. i x -> o x
-         type Id x = x
+         data T a where
+           T1 :: Eq b => b -> b -> T b
+           T2 :: (Show c, Ix c) => c -> [c] -> T c
 
-         foo :: Generic Id []
+   When pattern matching, these constraints are made available to
+   discharge constraints in the body of the match. For example: ::
 
-   After expanding the synonym, ``foo`` has the legal (in GHC) type: ::
+         f :: T a -> String
+         f (T1 x y) | x==y      = "yes"
+                    | otherwise = "no"
+         f (T2 a b)             = show a
 
-         foo :: forall x. x -> [x]
+   Note that ``f`` is not overloaded; the ``Eq`` constraint arising from
+   the use of ``==`` is discharged by the pattern match on ``T1`` and
+   similarly the ``Show`` constraint arising from the use of ``show``.
 
-GHC currently does kind checking before expanding synonyms (though even
-that could be changed)..
+-  Unlike a Haskell-98-style data type declaration, the type variable(s)
+   in the "``data Set a where``" header have no scope. Indeed, one can
+   write a kind signature instead: ::
 
-After expanding type synonyms, GHC does validity checking on types,
-looking for the following mal-formedness which isn't detected simply by
-kind checking:
+         data Set :: * -> * where ...
 
--  Type constructor applied to a type involving for-alls (if
-   :ghc-flag:`-XImpredicativeTypes` is off)
+   or even a mixture of the two: ::
 
--  Partially-applied type synonym.
+         data Bar a :: (* -> *) -> * where ...
 
-So, for example, this will be rejected: ::
+   The type variables (if given) may be explicitly kinded, so we could
+   also write the header for ``Foo`` like this: ::
 
-      type Pr = forall a. a
+         data Bar a (b :: * -> *) where ...
 
-      h :: [Pr]
-      h = ...
+-  You can use strictness annotations, in the obvious places in the
+   constructor type: ::
 
-because GHC does not allow type constructors applied to for-all types.
+         data Term a where
+             Lit    :: !Int -> Term Int
+             If     :: Term Bool -> !(Term a) -> !(Term a) -> Term a
+             Pair   :: Term a -> Term b -> Term (a,b)
 
-.. _existential-quantification:
+-  You can use a ``deriving`` clause on a GADT-style data type
+   declaration. For example, these two declarations are equivalent ::
 
-Existentially quantified data constructors
-------------------------------------------
+         data Maybe1 a where {
+             Nothing1 :: Maybe1 a ;
+             Just1    :: a -> Maybe1 a
+           } deriving( Eq, Ord )
 
-.. ghc-flag:: -XExistentialQuantification
+         data Maybe2 a = Nothing2 | Just2 a
+              deriving( Eq, Ord )
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+-  The type signature may have quantified type variables that do not
+   appear in the result type: ::
 
-    Allow existentially quantified type variables in types.
+         data Foo where
+            MkFoo :: a -> (a->Bool) -> Foo
+            Nil   :: Foo
 
-The idea of using existential quantification in data type declarations
-was suggested by Perry, and implemented in Hope+ (Nigel Perry, *The
-Implementation of Practical Functional Programming Languages*, PhD
-Thesis, University of London, 1991). It was later formalised by Laufer
-and Odersky (*Polymorphic type inference and abstract data types*,
-TOPLAS, 16(5), pp. 1411-1430, 1994). It's been in Lennart Augustsson's
-``hbc`` Haskell compiler for several years, and proved very useful.
-Here's the idea. Consider the declaration: ::
+   Here the type variable ``a`` does not appear in the result type of
+   either constructor. Although it is universally quantified in the type
+   of the constructor, such a type variable is often called
+   "existential". Indeed, the above declaration declares precisely the
+   same type as the ``data Foo`` in :ref:`existential-quantification`.
 
-      data Foo = forall a. MkFoo a (a -> Bool)
-               | Nil
+   The type may contain a class context too, of course: ::
 
-The data type ``Foo`` has two constructors with types: ::
+         data Showable where
+           MkShowable :: Show a => a -> Showable
 
-      MkFoo :: forall a. a -> (a -> Bool) -> Foo
-      Nil   :: Foo
+-  You can use record syntax on a GADT-style data type declaration: ::
 
-Notice that the type variable ``a`` in the type of ``MkFoo`` does not
-appear in the data type itself, which is plain ``Foo``. For example, the
-following expression is fine: ::
+         data Person where
+             Adult :: { name :: String, children :: [Person] } -> Person
+             Child :: Show a => { name :: !String, funny :: a } -> Person
 
-      [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo]
+   As usual, for every constructor that has a field ``f``, the type of
+   field ``f`` must be the same (modulo alpha conversion). The ``Child``
+   constructor above shows that the signature may have a context,
+   existentially-quantified variables, and strictness annotations, just
+   as in the non-record case. (NB: the "type" that follows the
+   double-colon is not really a type, because of the record syntax and
+   strictness annotations. A "type" of this form can appear only in a
+   constructor signature.)
 
-Here, ``(MkFoo 3 even)`` packages an integer with a function ``even``
-that maps an integer to ``Bool``; and ``MkFoo 'c'
-isUpper`` packages a character with a compatible function. These two
-things are each of type ``Foo`` and can be put in a list.
+-  Record updates are allowed with GADT-style declarations, only fields
+   that have the following property: the type of the field mentions no
+   existential type variables.
 
-What can we do with a value of type ``Foo``? In particular, what
-happens when we pattern-match on ``MkFoo``? ::
+-  As in the case of existentials declared using the Haskell-98-like
+   record syntax (:ref:`existential-records`), record-selector functions
+   are generated only for those fields that have well-typed selectors.
+   Here is the example of that section, in GADT-style syntax: ::
 
-      f (MkFoo val fn) = ???
+       data Counter a where
+           NewCounter :: { _this    :: self
+                         , _inc     :: self -> self
+                         , _display :: self -> IO ()
+                         , tag      :: a
+                         } -> Counter a
 
-Since all we know about ``val`` and ``fn`` is that they are compatible,
-the only (useful) thing we can do with them is to apply ``fn`` to
-``val`` to get a boolean. For example: ::
+   As before, only one selector function is generated here, that for
+   ``tag``. Nevertheless, you can still use all the field names in
+   pattern matching and record construction.
 
-      f :: Foo -> Bool
-      f (MkFoo val fn) = fn val
+-  In a GADT-style data type declaration there is no obvious way to
+   specify that a data constructor should be infix, which makes a
+   difference if you derive ``Show`` for the type. (Data constructors
+   declared infix are displayed infix by the derived ``show``.) So GHC
+   implements the following design: a data constructor declared in a
+   GADT-style data type declaration is displayed infix by ``Show`` iff
+   (a) it is an operator symbol, (b) it has two arguments, (c) it has a
+   programmer-supplied fixity declaration. For example
 
-What this allows us to do is to package heterogeneous values together
-with a bunch of functions that manipulate them, and then treat that
-collection of packages in a uniform manner. You can express quite a bit
-of object-oriented-like programming this way.
+   ::
 
-.. _existential:
+          infix 6 (:--:)
+          data T a where
+            (:--:) :: Int -> Bool -> T Int
 
-Why existential?
-~~~~~~~~~~~~~~~~
+.. _gadt:
 
-What has this to do with *existential* quantification? Simply that
-``MkFoo`` has the (nearly) isomorphic type ::
+Generalised Algebraic Data Types (GADTs)
+----------------------------------------
 
-      MkFoo :: (exists a . (a, a -> Bool)) -> Foo
+.. ghc-flag:: -XGADTs
 
-But Haskell programmers can safely think of the ordinary *universally*
-quantified type given above, thereby avoiding adding a new existential
-quantification construct.
+    :implies: :ghc-flag:`-XMonoLocalBinds`, :ghc-flag:`-XGADTSyntax`
 
-.. _existential-with-context:
+    Allow use of Generalised Algebraic Data Types (GADTs).
 
-Existentials and type classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Generalised Algebraic Data Types generalise ordinary algebraic data
+types by allowing constructors to have richer return types. Here is an
+example: ::
 
-An easy extension is to allow arbitrary contexts before the constructor.
-For example: ::
+      data Term a where
+          Lit    :: Int -> Term Int
+          Succ   :: Term Int -> Term Int
+          IsZero :: Term Int -> Term Bool
+          If     :: Term Bool -> Term a -> Term a -> Term a
+          Pair   :: Term a -> Term b -> Term (a,b)
 
-    data Baz = forall a. Eq a => Baz1 a a
-             | forall b. Show b => Baz2 b (b -> b)
+Notice that the return type of the constructors is not always
+``Term a``, as is the case with ordinary data types. This generality
+allows us to write a well-typed ``eval`` function for these ``Terms``: ::
 
-The two constructors have the types you'd expect: ::
+      eval :: Term a -> a
+      eval (Lit i)      = i
+      eval (Succ t)     = 1 + eval t
+      eval (IsZero t)   = eval t == 0
+      eval (If b e1 e2) = if eval b then eval e1 else eval e2
+      eval (Pair e1 e2) = (eval e1, eval e2)
 
-    Baz1 :: forall a. Eq a => a -> a -> Baz
-    Baz2 :: forall b. Show b => b -> (b -> b) -> Baz
+The key point about GADTs is that *pattern matching causes type
+refinement*. For example, in the right hand side of the equation ::
 
-But when pattern matching on ``Baz1`` the matched values can be compared
-for equality, and when pattern matching on ``Baz2`` the first matched
-value can be converted to a string (as well as applying the function to
-it). So this program is legal: ::
+      eval :: Term a -> a
+      eval (Lit i) =  ...
 
-      f :: Baz -> String
-      f (Baz1 p q) | p == q    = "Yes"
-                   | otherwise = "No"
-      f (Baz2 v fn)            = show (fn v)
+the type ``a`` is refined to ``Int``. That's the whole point! A precise
+specification of the type rules is beyond what this user manual aspires
+to, but the design closely follows that described in the paper `Simple
+unification-based type inference for
+GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt/>`__, (ICFP
+2006). The general principle is this: *type refinement is only carried
+out based on user-supplied type annotations*. So if no type signature is
+supplied for ``eval``, no type refinement happens, and lots of obscure
+error messages will occur. However, the refinement is quite general. For
+example, if we had: ::
 
-Operationally, in a dictionary-passing implementation, the constructors
-``Baz1`` and ``Baz2`` must store the dictionaries for ``Eq`` and
-``Show`` respectively, and extract it on pattern matching.
+      eval :: Term a -> a -> a
+      eval (Lit i) j =  i+j
 
-.. _existential-records:
+the pattern match causes the type ``a`` to be refined to ``Int``
+(because of the type of the constructor ``Lit``), and that refinement
+also applies to the type of ``j``, and the result type of the ``case``
+expression. Hence the addition ``i+j`` is legal.
 
-Record Constructors
-~~~~~~~~~~~~~~~~~~~
+These and many other examples are given in papers by Hongwei Xi, and Tim
+Sheard. There is a longer introduction `on the
+wiki <http://www.haskell.org/haskellwiki/GADT>`__, and Ralf Hinze's `Fun
+with phantom
+types <http://www.cs.ox.ac.uk/ralf.hinze/publications/With.pdf>`__ also
+has a number of examples. Note that papers may use different notation to
+that implemented in GHC.
 
-GHC allows existentials to be used with records syntax as well. For
-example: ::
+The rest of this section outlines the extensions to GHC that support
+GADTs. The extension is enabled with :ghc-flag:`-XGADTs`. The :ghc-flag:`-XGADTs` flag
+also sets :ghc-flag:`-XGADTSyntax` and :ghc-flag:`-XMonoLocalBinds`.
 
-    data Counter a = forall self. NewCounter
-        { _this    :: self
-        , _inc     :: self -> self
-        , _display :: self -> IO ()
-        , tag      :: a
-        }
+-  A GADT can only be declared using GADT-style syntax
+   (:ref:`gadt-style`); the old Haskell 98 syntax for data declarations
+   always declares an ordinary data type. The result type of each
+   constructor must begin with the type constructor being defined, but
+   for a GADT the arguments to the type constructor can be arbitrary
+   monotypes. For example, in the ``Term`` data type above, the type of
+   each constructor must end with ``Term ty``, but the ``ty`` need not
+   be a type variable (e.g. the ``Lit`` constructor).
 
-Here ``tag`` is a public field, with a well-typed selector function
-``tag :: Counter a -> a``. The ``self`` type is hidden from the outside;
-any attempt to apply ``_this``, ``_inc`` or ``_display`` as functions
-will raise a compile-time error. In other words, *GHC defines a record
-selector function only for fields whose type does not mention the
-existentially-quantified variables*. (This example used an underscore in
-the fields for which record selectors will not be defined, but that is
-only programming style; GHC ignores them.)
+-  It is permitted to declare an ordinary algebraic data type using
+   GADT-style syntax. What makes a GADT into a GADT is not the syntax,
+   but rather the presence of data constructors whose result type is not
+   just ``T a b``.
 
-To make use of these hidden fields, we need to create some helper
-functions: ::
+-  You cannot use a ``deriving`` clause for a GADT; only for an ordinary
+   data type.
 
-    inc :: Counter a -> Counter a
-    inc (NewCounter x i d t) = NewCounter
-        { _this = i x, _inc = i, _display = d, tag = t }
+-  As mentioned in :ref:`gadt-style`, record syntax is supported. For
+   example:
 
-    display :: Counter a -> IO ()
-    display NewCounter{ _this = x, _display = d } = d x
+   ::
 
-Now we can define counters with different underlying implementations: ::
+         data Term a where
+             Lit    :: { val  :: Int }      -> Term Int
+             Succ   :: { num  :: Term Int } -> Term Int
+             Pred   :: { num  :: Term Int } -> Term Int
+             IsZero :: { arg  :: Term Int } -> Term Bool
+             Pair   :: { arg1 :: Term a
+                       , arg2 :: Term b
+                       }                    -> Term (a,b)
+             If     :: { cnd  :: Term Bool
+                       , tru  :: Term a
+                       , fls  :: Term a
+                       }                    -> Term a
 
-    counterA :: Counter String
-    counterA = NewCounter
-        { _this = 0, _inc = (1+), _display = print, tag = "A" }
+   However, for GADTs there is the following additional constraint:
+   every constructor that has a field ``f`` must have the same result
+   type (modulo alpha conversion) Hence, in the above example, we cannot
+   merge the ``num`` and ``arg`` fields above into a single name.
+   Although their field types are both ``Term Int``, their selector
+   functions actually have different types:
 
-    counterB :: Counter String
-    counterB = NewCounter
-        { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" }
+   ::
 
-    main = do
-        display (inc counterA)         -- prints "1"
-        display (inc (inc counterB))   -- prints "##"
+         num :: Term Int -> Term Int
+         arg :: Term Bool -> Term Int
 
-Record update syntax is supported for existentials (and GADTs): ::
+-  When pattern-matching against data constructors drawn from a GADT,
+   for example in a ``case`` expression, the following rules apply:
 
-    setTag :: Counter a -> a -> Counter a
-    setTag obj t = obj{ tag = t }
+   -  The type of the scrutinee must be rigid.
 
-The rule for record update is this:
+   -  The type of the entire ``case`` expression must be rigid.
 
-    the types of the updated fields may mention only the universally-quantified
-    type variables of the data constructor. For GADTs, the field may mention
-    only types that appear as a simple type-variable argument in the
-    constructor's result type.
+   -  The type of any free variable mentioned in any of the ``case``
+      alternatives must be rigid.
 
-For example: ::
+   A type is "rigid" if it is completely known to the compiler at its
+   binding site. The easiest way to ensure that a variable a rigid type
+   is to give it a type signature. For more precise details see `Simple
+   unification-based type inference for
+   GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt>`__. The
+   criteria implemented by GHC are given in the Appendix.
 
-    data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
-    upd1 t x = t { f1=x }   -- OK:   upd1 :: T a b -> a' -> T a' b
-    upd2 t x = t { f3=x }   -- BAD   (f3's type mentions c, which is
-                            --        existentially quantified)
+.. _record-system-extensions:
 
-    data G a b where { G1 { g1::a, g2::c } :: G a [c] }
-    upd3 g x = g { g1=x }   -- OK:   upd3 :: G a b -> c -> G c b
-    upd4 g x = g { g2=x }   -- BAD (f2's type mentions c, which is not a simple
-                            --      type-variable argument in G1's result type)
+Extensions to the record system
+===============================
 
-Restrictions
-~~~~~~~~~~~~
+.. _traditional-record-syntax:
 
-There are several restrictions on the ways in which existentially-quantified
-constructors can be used.
+Traditional record syntax
+-------------------------
 
--  When pattern matching, each pattern match introduces a new, distinct,
-   type for each existential type variable. These types cannot be
-   unified with any other type, nor can they escape from the scope of
-   the pattern match. For example, these fragments are incorrect: ::
+.. ghc-flag:: -XNoTraditionalRecordSyntax
 
-       f1 (MkFoo a f) = a
+    :since: 7.4.1
 
-   Here, the type bound by ``MkFoo`` "escapes", because ``a`` is the
-   result of ``f1``. One way to see why this is wrong is to ask what
-   type ``f1`` has: ::
+    Disallow use of record syntax.
 
-         f1 :: Foo -> a             -- Weird!
+Traditional record syntax, such as ``C {f = x}``, is enabled by default.
+To disable it, you can use the :ghc-flag:`-XNoTraditionalRecordSyntax` flag.
 
-   What is this "``a``" in the result type? Clearly we don't mean this: ::
+.. _disambiguate-fields:
 
-         f1 :: forall a. Foo -> a   -- Wrong!
+Record field disambiguation
+---------------------------
+
+.. ghc-flag:: -XDisambiguateRecordFields
 
-   The original program is just plain wrong. Here's another sort of
-   error ::
+    Allow the compiler to automatically choose between identically-named
+    record selectors based on type (if the choice is unambiguous).
 
-         f2 (Baz1 a b) (Baz1 p q) = a==q
+In record construction and record pattern matching it is entirely
+unambiguous which field is referred to, even if there are two different
+data types in scope with a common field name. For example:
 
-   It's ok to say ``a==b`` or ``p==q``, but ``a==q`` is wrong because it
-   equates the two distinct types arising from the two ``Baz1``
-   constructors.
+::
 
--  You can't pattern-match on an existentially quantified constructor in
-   a ``let`` or ``where`` group of bindings. So this is illegal: ::
+    module M where
+      data S = MkS { x :: Int, y :: Bool }
 
-         f3 x = a==b where { Baz1 a b = x }
+    module Foo where
+      import M
 
-   Instead, use a ``case`` expression: ::
+      data T = MkT { x :: Int }
 
-         f3 x = case x of Baz1 a b -> a==b
+      ok1 (MkS { x = n }) = n+1   -- Unambiguous
+      ok2 n = MkT { x = n+1 }     -- Unambiguous
 
-   In general, you can only pattern-match on an existentially-quantified
-   constructor in a ``case`` expression or in the patterns of a function
-   definition. The reason for this restriction is really an
-   implementation one. Type-checking binding groups is already a
-   nightmare without existentials complicating the picture. Also an
-   existential pattern binding at the top level of a module doesn't make
-   sense, because it's not clear how to prevent the
-   existentially-quantified type "escaping". So for now, there's a
-   simple-to-state restriction. We'll see how annoying it is.
+      bad1 k = k { x = 3 }        -- Ambiguous
+      bad2 k = x k                -- Ambiguous
 
--  You can't use existential quantification for ``newtype``
-   declarations. So this is illegal: ::
+Even though there are two ``x``'s in scope, it is clear that the ``x``
+in the pattern in the definition of ``ok1`` can only mean the field
+``x`` from type ``S``. Similarly for the function ``ok2``. However, in
+the record update in ``bad1`` and the record selection in ``bad2`` it is
+not clear which of the two types is intended.
 
-         newtype T = forall a. Ord a => MkT a
+Haskell 98 regards all four as ambiguous, but with the
+:ghc-flag:`-XDisambiguateRecordFields` flag, GHC will accept the former two. The
+rules are precisely the same as those for instance declarations in
+Haskell 98, where the method names on the left-hand side of the method
+bindings in an instance declaration refer unambiguously to the method of
+that class (provided they are in scope at all), even if there are other
+variables in scope with the same name. This reduces the clutter of
+qualified names when you import two records from different modules that
+use the same field name.
 
-   Reason: a value of type ``T`` must be represented as a pair of a
-   dictionary for ``Ord t`` and a value of type ``t``. That contradicts
-   the idea that ``newtype`` should have no concrete representation. You
-   can get just the same efficiency and effect by using ``data`` instead
-   of ``newtype``. If there is no overloading involved, then there is
-   more of a case for allowing an existentially-quantified ``newtype``,
-   because the ``data`` version does carry an implementation cost, but
-   single-field existentially quantified constructors aren't much use.
-   So the simple restriction (no existential stuff on ``newtype``)
-   stands, unless there are convincing reasons to change it.
+Some details:
 
--  You can't use ``deriving`` to define instances of a data type with
-   existentially quantified data constructors. Reason: in most cases it
-   would not make sense. For example:; ::
+-  Field disambiguation can be combined with punning (see
+   :ref:`record-puns`). For example: ::
 
-       data T = forall a. MkT [a] deriving( Eq )
+       module Foo where
+         import M
+         x=True
+         ok3 (MkS { x }) = x+1   -- Uses both disambiguation and punning
 
-   To derive ``Eq`` in the standard way we would need to have equality
-   between the single component of two ``MkT`` constructors: ::
+-  With :ghc-flag:`-XDisambiguateRecordFields` you can use *unqualified* field
+   names even if the corresponding selector is only in scope *qualified*
+   For example, assuming the same module ``M`` as in our earlier
+   example, this is legal: ::
 
-       instance Eq T where
-         (MkT a) == (MkT b) = ???
+       module Foo where
+         import qualified M    -- Note qualified
 
-   But ``a`` and ``b`` have distinct types, and so can't be compared.
-   It's just about possible to imagine examples in which the derived
-   instance would make sense, but it seems altogether simpler simply to
-   prohibit such declarations. Define your own instances!
+         ok4 (M.MkS { x = n }) = n+1   -- Unambiguous
 
-.. _gadt-style:
+   Since the constructor ``MkS`` is only in scope qualified, you must
+   name it ``M.MkS``, but the field ``x`` does not need to be qualified
+   even though ``M.x`` is in scope but ``x`` is not (In effect, it is
+   qualified by the constructor).
 
-Declaring data types with explicit constructor signatures
----------------------------------------------------------
+.. _duplicate-record-fields:
 
-.. ghc-flag:: -XGADTSyntax
+Duplicate record fields
+-----------------------
 
-    Allow the use of GADT syntax in data type definitions (but not GADTs
-    themselves; for this see :ghc-flag:`-XGADTs`)
+.. ghc-flag:: -XDuplicateRecordFields
 
-When the ``GADTSyntax`` extension is enabled, GHC allows you to declare
-an algebraic data type by giving the type signatures of constructors
-explicitly. For example: ::
+    :implies: :ghc-flag:`-XDisambiguateRecordFields`
+    :since: 8.0.1
 
-      data Maybe a where
-          Nothing :: Maybe a
-          Just    :: a -> Maybe a
+    Allow definition of record types with identically-named fields.
 
-The form is called a "GADT-style declaration" because Generalised
-Algebraic Data Types, described in :ref:`gadt`, can only be declared
-using this form.
+Going beyond :ghc-flag:`-XDisambiguateRecordFields` (see :ref:`disambiguate-fields`),
+the :ghc-flag:`-XDuplicateRecordFields` extension allows multiple datatypes to be
+declared using the same field names in a single module. For example, it allows
+this: ::
 
-Notice that GADT-style syntax generalises existential types
-(:ref:`existential-quantification`). For example, these two declarations
-are equivalent: ::
+    module M where
+      data S = MkS { x :: Int }
+      data T = MkT { x :: Bool }
 
-      data Foo = forall a. MkFoo a (a -> Bool)
-      data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' }
+Uses of fields that are always unambiguous because they mention the constructor,
+including construction and pattern-matching, may freely use duplicated field
+names. For example, the following are permitted (just as with
+:ghc-flag:`-XDisambiguateRecordFields`): ::
 
-Any data type that can be declared in standard Haskell 98 syntax can
-also be declared using GADT-style syntax. The choice is largely
-stylistic, but GADT-style declarations differ in one important respect:
-they treat class constraints on the data constructors differently.
-Specifically, if the constructor is given a type-class context, that
-context is made available by pattern matching. For example: ::
+    s = MkS { x = 3 }
 
-      data Set a where
-        MkSet :: Eq a => [a] -> Set a
+    f (MkT { x = b }) = b
 
-      makeSet :: Eq a => [a] -> Set a
-      makeSet xs = MkSet (nub xs)
+Field names used as selector functions or in record updates must be unambiguous,
+either because there is only one such field in scope, or because a type
+signature is supplied, as described in the following sections.
 
-      insert :: a -> Set a -> Set a
-      insert a (MkSet as) | a `elem` as = MkSet as
-                          | otherwise   = MkSet (a:as)
+Selector functions
+~~~~~~~~~~~~~~~~~~
 
-A use of ``MkSet`` as a constructor (e.g. in the definition of
-``makeSet``) gives rise to a ``(Eq a)`` constraint, as you would expect.
-The new feature is that pattern-matching on ``MkSet`` (as in the
-definition of ``insert``) makes *available* an ``(Eq a)`` context. In
-implementation terms, the ``MkSet`` constructor has a hidden field that
-stores the ``(Eq a)`` dictionary that is passed to ``MkSet``; so when
-pattern-matching that dictionary becomes available for the right-hand
-side of the match. In the example, the equality dictionary is used to
-satisfy the equality constraint generated by the call to ``elem``, so
-that the type of ``insert`` itself has no ``Eq`` constraint.
+Fields may be used as selector functions only if they are unambiguous, so this
+is still not allowed if both ``S(x)`` and ``T(x)`` are in scope: ::
 
-For example, one possible application is to reify dictionaries: ::
+    bad r = x r
 
-       data NumInst a where
-         MkNumInst :: Num a => NumInst a
+An ambiguous selector may be disambiguated by the type being "pushed down" to
+the occurrence of the selector (see :ref:`higher-rank-type-inference` for more
+details on what "pushed down" means). For example, the following are permitted: ::
 
-       intInst :: NumInst Int
-       intInst = MkNumInst
+    ok1 = x :: S -> Int
 
-       plus :: NumInst a -> a -> a -> a
-       plus MkNumInst p q = p + q
+    ok2 :: S -> Int
+    ok2 = x
 
-Here, a value of type ``NumInst a`` is equivalent to an explicit
-``(Num a)`` dictionary.
+    ok3 = k x -- assuming we already have k :: (S -> Int) -> _
 
-All this applies to constructors declared using the syntax of
-:ref:`existential-with-context`. For example, the ``NumInst`` data type
-above could equivalently be declared like this: ::
+In addition, the datatype that is meant may be given as a type signature on the
+argument to the selector: ::
 
-       data NumInst a
-          = Num a => MkNumInst (NumInst a)
+    ok4 s = x (s :: S)
 
-Notice that, unlike the situation when declaring an existential, there
-is no ``forall``, because the ``Num`` constrains the data type's
-universally quantified type variable ``a``. A constructor may have both
-universal and existential type variables: for example, the following two
-declarations are equivalent: ::
+However, we do not infer the type of the argument to determine the datatype, or
+have any way of deferring the choice to the constraint solver. Thus the
+following is ambiguous: ::
 
-       data T1 a
-        = forall b. (Num a, Eq b) => MkT1 a b
-       data T2 a where
-        MkT2 :: (Num a, Eq b) => a -> b -> T2 a
+    bad :: S -> Int
+    bad s = x s
 
-All this behaviour contrasts with Haskell 98's peculiar treatment of
-contexts on a data type declaration (Section 4.2.1 of the Haskell 98
-Report). In Haskell 98 the definition ::
+Even though a field label is duplicated in its defining module, it may be
+possible to use the selector unambiguously elsewhere. For example, another
+module could import ``S(x)`` but not ``T(x)``, and then use ``x`` unambiguously.
 
-      data Eq a => Set' a = MkSet' [a]
+Record updates
+~~~~~~~~~~~~~~
 
-gives ``MkSet'`` the same type as ``MkSet`` above. But instead of
-*making available* an ``(Eq a)`` constraint, pattern-matching on
-``MkSet'`` *requires* an ``(Eq a)`` constraint! GHC faithfully
-implements this behaviour, odd though it is. But for GADT-style
-declarations, GHC's behaviour is much more useful, as well as much more
-intuitive.
+In a record update such as ``e { x = 1 }``, if there are multiple ``x`` fields
+in scope, then the type of the context must fix which record datatype is
+intended, or a type annotation must be supplied. Consider the following
+definitions: ::
 
-The rest of this section gives further details about GADT-style data
-type declarations.
+    data S = MkS { foo :: Int }
+    data T = MkT { foo :: Int, bar :: Int }
+    data U = MkU { bar :: Int, baz :: Int }
 
--  The result type of each data constructor must begin with the type
-   constructor being defined. If the result type of all constructors has
-   the form ``T a1 ... an``, where ``a1 ... an`` are distinct type
-   variables, then the data type is *ordinary*; otherwise is a
-   *generalised* data type (:ref:`gadt`).
+Without :ghc-flag:`-XDuplicateRecordFields`, an update mentioning ``foo`` will always be
+ambiguous if all these definitions were in scope. When the extension is enabled,
+there are several options for disambiguating updates:
 
--  As with other type signatures, you can give a single signature for
-   several data constructors. In this example we give a single signature
-   for ``T1`` and ``T2``: ::
+- Check for types that have all the fields being updated. For example: ::
 
-         data T a where
-           T1,T2 :: a -> T a
-           T3 :: T a
+      f x = x { foo = 3, bar = 2 }
 
--  The type signature of each constructor is independent, and is
-   implicitly universally quantified as usual. In particular, the type
-   variable(s) in the "``data T a where``" header have no scope, and
-   different constructors may have different universally-quantified type
-   variables: ::
+  Here ``f`` must be updating ``T`` because neither ``S`` nor ``U`` have both
+  fields.
 
-         data T a where        -- The 'a' has no scope
-           T1,T2 :: b -> T b   -- Means forall b. b -> T b
-           T3 :: T a           -- Means forall a. T a
+- Use the type being pushed in to the record update, as in the following: ::
 
--  A constructor signature may mention type class constraints, which can
-   differ for different constructors. For example, this is fine: ::
+      g1 :: T -> T
+      g1 x = x { foo = 3 }
 
-         data T a where
-           T1 :: Eq b => b -> b -> T b
-           T2 :: (Show c, Ix c) => c -> [c] -> T c
+      g2 x = x { foo = 3 } :: T
 
-   When pattern matching, these constraints are made available to
-   discharge constraints in the body of the match. For example: ::
+      g3 = k (x { foo = 3 }) -- assuming we already have k :: T -> _
 
-         f :: T a -> String
-         f (T1 x y) | x==y      = "yes"
-                    | otherwise = "no"
-         f (T2 a b)             = show a
+- Use an explicit type signature on the record expression, as in: ::
 
-   Note that ``f`` is not overloaded; the ``Eq`` constraint arising from
-   the use of ``==`` is discharged by the pattern match on ``T1`` and
-   similarly the ``Show`` constraint arising from the use of ``show``.
+      h x = (x :: T) { foo = 3 }
 
--  Unlike a Haskell-98-style data type declaration, the type variable(s)
-   in the "``data Set a where``" header have no scope. Indeed, one can
-   write a kind signature instead: ::
+The type of the expression being updated will not be inferred, and no
+constraint-solving will be performed, so the following will be rejected as
+ambiguous: ::
 
-         data Set :: * -> * where ...
+    let x :: T
+        x = blah
+    in x { foo = 3 }
 
-   or even a mixture of the two: ::
+    \x -> [x { foo = 3 },  blah :: T ]
 
-         data Bar a :: (* -> *) -> * where ...
+    \ (x :: T) -> x { foo = 3 }
 
-   The type variables (if given) may be explicitly kinded, so we could
-   also write the header for ``Foo`` like this: ::
+Import and export of record fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-         data Bar a (b :: * -> *) where ...
+When :ghc-flag:`-XDuplicateRecordFields` is enabled, an ambiguous field must be exported
+as part of its datatype, rather than at the top level. For example, the
+following is legal: ::
 
--  You can use strictness annotations, in the obvious places in the
-   constructor type: ::
+    module M (S(x), T(..)) where
+      data S = MkS { x :: Int }
+      data T = MkT { x :: Bool }
 
-         data Term a where
-             Lit    :: !Int -> Term Int
-             If     :: Term Bool -> !(Term a) -> !(Term a) -> Term a
-             Pair   :: Term a -> Term b -> Term (a,b)
+However, this would not be permitted, because ``x`` is ambiguous: ::
 
--  You can use a ``deriving`` clause on a GADT-style data type
-   declaration. For example, these two declarations are equivalent ::
+    module M (x) where ...
 
-         data Maybe1 a where {
-             Nothing1 :: Maybe1 a ;
-             Just1    :: a -> Maybe1 a
-           } deriving( Eq, Ord )
+Similar restrictions apply on import.
 
-         data Maybe2 a = Nothing2 | Just2 a
-              deriving( Eq, Ord )
+.. _record-puns:
 
--  The type signature may have quantified type variables that do not
-   appear in the result type: ::
+Record puns
+-----------
 
-         data Foo where
-            MkFoo :: a -> (a->Bool) -> Foo
-            Nil   :: Foo
+.. ghc-flag:: -XNamedFieldPuns
 
-   Here the type variable ``a`` does not appear in the result type of
-   either constructor. Although it is universally quantified in the type
-   of the constructor, such a type variable is often called
-   "existential". Indeed, the above declaration declares precisely the
-   same type as the ``data Foo`` in :ref:`existential-quantification`.
+    Allow use of record puns.
 
-   The type may contain a class context too, of course: ::
+Record puns are enabled by the flag :ghc-flag:`-XNamedFieldPuns`.
 
-         data Showable where
-           MkShowable :: Show a => a -> Showable
+When using records, it is common to write a pattern that binds a
+variable with the same name as a record field, such as: ::
 
--  You can use record syntax on a GADT-style data type declaration: ::
+    data C = C {a :: Int}
+    f (C {a = a}) = a
 
-         data Person where
-             Adult :: { name :: String, children :: [Person] } -> Person
-             Child :: Show a => { name :: !String, funny :: a } -> Person
+Record punning permits the variable name to be elided, so one can simply
+write ::
 
-   As usual, for every constructor that has a field ``f``, the type of
-   field ``f`` must be the same (modulo alpha conversion). The ``Child``
-   constructor above shows that the signature may have a context,
-   existentially-quantified variables, and strictness annotations, just
-   as in the non-record case. (NB: the "type" that follows the
-   double-colon is not really a type, because of the record syntax and
-   strictness annotations. A "type" of this form can appear only in a
-   constructor signature.)
+    f (C {a}) = a
 
--  Record updates are allowed with GADT-style declarations, only fields
-   that have the following property: the type of the field mentions no
-   existential type variables.
+to mean the same pattern as above. That is, in a record pattern, the
+pattern ``a`` expands into the pattern ``a = a`` for the same name
+``a``.
 
--  As in the case of existentials declared using the Haskell-98-like
-   record syntax (:ref:`existential-records`), record-selector functions
-   are generated only for those fields that have well-typed selectors.
-   Here is the example of that section, in GADT-style syntax: ::
+Note that:
 
-       data Counter a where
-           NewCounter :: { _this    :: self
-                         , _inc     :: self -> self
-                         , _display :: self -> IO ()
-                         , tag      :: a
-                         } -> Counter a
+-  Record punning can also be used in an expression, writing, for
+   example, ::
 
-   As before, only one selector function is generated here, that for
-   ``tag``. Nevertheless, you can still use all the field names in
-   pattern matching and record construction.
+       let a = 1 in C {a}
 
--  In a GADT-style data type declaration there is no obvious way to
-   specify that a data constructor should be infix, which makes a
-   difference if you derive ``Show`` for the type. (Data constructors
-   declared infix are displayed infix by the derived ``show``.) So GHC
-   implements the following design: a data constructor declared in a
-   GADT-style data type declaration is displayed infix by ``Show`` iff
-   (a) it is an operator symbol, (b) it has two arguments, (c) it has a
-   programmer-supplied fixity declaration. For example
+   instead of ::
 
-   ::
+       let a = 1 in C {a = a}
 
-          infix 6 (:--:)
-          data T a where
-            (:--:) :: Int -> Bool -> T Int
+   The expansion is purely syntactic, so the expanded right-hand side
+   expression refers to the nearest enclosing variable that is spelled
+   the same as the field name.
 
-.. _gadt:
+-  Puns and other patterns can be mixed in the same record: ::
 
-Generalised Algebraic Data Types (GADTs)
-----------------------------------------
+       data C = C {a :: Int, b :: Int}
+       f (C {a, b = 4}) = a
 
-.. ghc-flag:: -XGADTs
+-  Puns can be used wherever record patterns occur (e.g. in ``let``
+   bindings or at the top-level).
 
-    :implies: :ghc-flag:`-XMonoLocalBinds`, :ghc-flag:`-XGADTSyntax`
+-  A pun on a qualified field name is expanded by stripping off the
+   module qualifier. For example: ::
 
-    Allow use of Generalised Algebraic Data Types (GADTs).
+       f (C {M.a}) = a
 
-Generalised Algebraic Data Types generalise ordinary algebraic data
-types by allowing constructors to have richer return types. Here is an
-example: ::
+   means ::
 
-      data Term a where
-          Lit    :: Int -> Term Int
-          Succ   :: Term Int -> Term Int
-          IsZero :: Term Int -> Term Bool
-          If     :: Term Bool -> Term a -> Term a -> Term a
-          Pair   :: Term a -> Term b -> Term (a,b)
+       f (M.C {M.a = a}) = a
 
-Notice that the return type of the constructors is not always
-``Term a``, as is the case with ordinary data types. This generality
-allows us to write a well-typed ``eval`` function for these ``Terms``: ::
+   (This is useful if the field selector ``a`` for constructor ``M.C``
+   is only in scope in qualified form.)
 
-      eval :: Term a -> a
-      eval (Lit i)      = i
-      eval (Succ t)     = 1 + eval t
-      eval (IsZero t)   = eval t == 0
-      eval (If b e1 e2) = if eval b then eval e1 else eval e2
-      eval (Pair e1 e2) = (eval e1, eval e2)
+.. _record-wildcards:
 
-The key point about GADTs is that *pattern matching causes type
-refinement*. For example, in the right hand side of the equation ::
+Record wildcards
+----------------
 
-      eval :: Term a -> a
-      eval (Lit i) =  ...
+.. ghc-flag:: -XRecordWildCards
 
-the type ``a`` is refined to ``Int``. That's the whole point! A precise
-specification of the type rules is beyond what this user manual aspires
-to, but the design closely follows that described in the paper `Simple
-unification-based type inference for
-GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt/>`__, (ICFP
-2006). The general principle is this: *type refinement is only carried
-out based on user-supplied type annotations*. So if no type signature is
-supplied for ``eval``, no type refinement happens, and lots of obscure
-error messages will occur. However, the refinement is quite general. For
-example, if we had: ::
+    :implies: :ghc-flag:`-XDisambiguateRecordFields`.
 
-      eval :: Term a -> a -> a
-      eval (Lit i) j =  i+j
+    Allow the use of wildcards in record construction and pattern matching.
 
-the pattern match causes the type ``a`` to be refined to ``Int``
-(because of the type of the constructor ``Lit``), and that refinement
-also applies to the type of ``j``, and the result type of the ``case``
-expression. Hence the addition ``i+j`` is legal.
+Record wildcards are enabled by the flag :ghc-flag:`-XRecordWildCards`. This
+flag implies :ghc-flag:`-XDisambiguateRecordFields`.
 
-These and many other examples are given in papers by Hongwei Xi, and Tim
-Sheard. There is a longer introduction `on the
-wiki <http://www.haskell.org/haskellwiki/GADT>`__, and Ralf Hinze's `Fun
-with phantom
-types <http://www.cs.ox.ac.uk/ralf.hinze/publications/With.pdf>`__ also
-has a number of examples. Note that papers may use different notation to
-that implemented in GHC.
+For records with many fields, it can be tiresome to write out each field
+individually in a record pattern, as in ::
 
-The rest of this section outlines the extensions to GHC that support
-GADTs. The extension is enabled with :ghc-flag:`-XGADTs`. The :ghc-flag:`-XGADTs` flag
-also sets :ghc-flag:`-XGADTSyntax` and :ghc-flag:`-XMonoLocalBinds`.
+    data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
+    f (C {a = 1, b = b, c = c, d = d}) = b + c + d
 
--  A GADT can only be declared using GADT-style syntax
-   (:ref:`gadt-style`); the old Haskell 98 syntax for data declarations
-   always declares an ordinary data type. The result type of each
-   constructor must begin with the type constructor being defined, but
-   for a GADT the arguments to the type constructor can be arbitrary
-   monotypes. For example, in the ``Term`` data type above, the type of
-   each constructor must end with ``Term ty``, but the ``ty`` need not
-   be a type variable (e.g. the ``Lit`` constructor).
+Record wildcard syntax permits a "``..``" in a record pattern, where
+each elided field ``f`` is replaced by the pattern ``f = f``. For
+example, the above pattern can be written as ::
 
--  It is permitted to declare an ordinary algebraic data type using
-   GADT-style syntax. What makes a GADT into a GADT is not the syntax,
-   but rather the presence of data constructors whose result type is not
-   just ``T a b``.
+    f (C {a = 1, ..}) = b + c + d
 
--  You cannot use a ``deriving`` clause for a GADT; only for an ordinary
-   data type.
+More details:
 
--  As mentioned in :ref:`gadt-style`, record syntax is supported. For
-   example:
+-  Record wildcards in patterns can be mixed with other patterns,
+   including puns (:ref:`record-puns`); for example, in a pattern
+   ``(C {a = 1, b, ..})``. Additionally, record wildcards can be used
+   wherever record patterns occur, including in ``let`` bindings and at
+   the top-level. For example, the top-level binding ::
 
-   ::
+       C {a = 1, ..} = e
 
-         data Term a where
-             Lit    :: { val  :: Int }      -> Term Int
-             Succ   :: { num  :: Term Int } -> Term Int
-             Pred   :: { num  :: Term Int } -> Term Int
-             IsZero :: { arg  :: Term Int } -> Term Bool
-             Pair   :: { arg1 :: Term a
-                       , arg2 :: Term b
-                       }                    -> Term (a,b)
-             If     :: { cnd  :: Term Bool
-                       , tru  :: Term a
-                       , fls  :: Term a
-                       }                    -> Term a
+   defines ``b``, ``c``, and ``d``.
 
-   However, for GADTs there is the following additional constraint:
-   every constructor that has a field ``f`` must have the same result
-   type (modulo alpha conversion) Hence, in the above example, we cannot
-   merge the ``num`` and ``arg`` fields above into a single name.
-   Although their field types are both ``Term Int``, their selector
-   functions actually have different types:
+-  Record wildcards can also be used in an expression, when constructing
+   a record. For example, ::
 
-   ::
+       let {a = 1; b = 2; c = 3; d = 4} in C {..}
 
-         num :: Term Int -> Term Int
-         arg :: Term Bool -> Term Int
+   in place of ::
 
--  When pattern-matching against data constructors drawn from a GADT,
-   for example in a ``case`` expression, the following rules apply:
+       let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
 
-   -  The type of the scrutinee must be rigid.
+   The expansion is purely syntactic, so the record wildcard expression
+   refers to the nearest enclosing variables that are spelled the same
+   as the omitted field names.
 
-   -  The type of the entire ``case`` expression must be rigid.
+-  Record wildcards may *not* be used in record *updates*. For example
+   this is illegal: ::
 
-   -  The type of any free variable mentioned in any of the ``case``
-      alternatives must be rigid.
+       f r = r { x = 3, .. }
 
-   A type is "rigid" if it is completely known to the compiler at its
-   binding site. The easiest way to ensure that a variable a rigid type
-   is to give it a type signature. For more precise details see `Simple
-   unification-based type inference for
-   GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt>`__. The
-   criteria implemented by GHC are given in the Appendix.
+-  For both pattern and expression wildcards, the "``..``" expands to
+   the missing *in-scope* record fields. Specifically the expansion of
+   "``C {..}``" includes ``f`` if and only if:
 
-.. _record-system-extensions:
+   -  ``f`` is a record field of constructor ``C``.
 
-Extensions to the record system
-===============================
+   -  The record field ``f`` is in scope somehow (either qualified or
+      unqualified).
 
-.. _traditional-record-syntax:
+   -  In the case of expressions (but not patterns), the variable ``f``
+      is in scope unqualified, apart from the binding of the record
+      selector itself.
 
-Traditional record syntax
--------------------------
+   These rules restrict record wildcards to the situations in which the
+   user could have written the expanded version. For example ::
 
-.. ghc-flag:: -XNoTraditionalRecordSyntax
+       module M where
+         data R = R { a,b,c :: Int }
+       module X where
+         import M( R(a,c) )
+         f b = R { .. }
 
-    :since: 7.4.1
+   The ``R{..}`` expands to ``R{M.a=a}``, omitting ``b`` since the
+   record field is not in scope, and omitting ``c`` since the variable
+   ``c`` is not in scope (apart from the binding of the record selector
+   ``c``, of course).
 
-    Disallow use of record syntax.
+-  Record wildcards cannot be used (a) in a record update construct, and
+   (b) for data constructors that are not declared with record fields.
+   For example: ::
 
-Traditional record syntax, such as ``C {f = x}``, is enabled by default.
-To disable it, you can use the :ghc-flag:`-XNoTraditionalRecordSyntax` flag.
+       f x = x { v=True, .. }   -- Illegal (a)
 
-.. _disambiguate-fields:
+       data T = MkT Int Bool
+       g = MkT { .. }           -- Illegal (b)
+       h (MkT { .. }) = True    -- Illegal (b)
 
-Record field disambiguation
----------------------------
+.. _deriving:
 
-.. ghc-flag:: -XDisambiguateRecordFields
+Extensions to the "deriving" mechanism
+======================================
 
-    Allow the compiler to automatically choose between identically-named
-    record selectors based on type (if the choice is unambiguous).
+.. _deriving-inferred:
 
-In record construction and record pattern matching it is entirely
-unambiguous which field is referred to, even if there are two different
-data types in scope with a common field name. For example:
+Inferred context for deriving clauses
+-------------------------------------
 
-::
+The Haskell Report is vague about exactly when a ``deriving`` clause is
+legal. For example: ::
 
-    module M where
-      data S = MkS { x :: Int, y :: Bool }
+      data T0 f a = MkT0 a         deriving( Eq )
+      data T1 f a = MkT1 (f a)     deriving( Eq )
+      data T2 f a = MkT2 (f (f a)) deriving( Eq )
 
-    module Foo where
-      import M
+The natural generated ``Eq`` code would result in these instance
+declarations: ::
 
-      data T = MkT { x :: Int }
+      instance Eq a         => Eq (T0 f a) where ...
+      instance Eq (f a)     => Eq (T1 f a) where ...
+      instance Eq (f (f a)) => Eq (T2 f a) where ...
 
-      ok1 (MkS { x = n }) = n+1   -- Unambiguous
-      ok2 n = MkT { x = n+1 }     -- Unambiguous
+The first of these is obviously fine. The second is still fine, although
+less obviously. The third is not Haskell 98, and risks losing
+termination of instances.
 
-      bad1 k = k { x = 3 }        -- Ambiguous
-      bad2 k = x k                -- Ambiguous
+GHC takes a conservative position: it accepts the first two, but not the
+third. The rule is this: each constraint in the inferred instance
+context must consist only of type variables, with no repetitions.
 
-Even though there are two ``x``'s in scope, it is clear that the ``x``
-in the pattern in the definition of ``ok1`` can only mean the field
-``x`` from type ``S``. Similarly for the function ``ok2``. However, in
-the record update in ``bad1`` and the record selection in ``bad2`` it is
-not clear which of the two types is intended.
+This rule is applied regardless of flags. If you want a more exotic
+context, you can write it yourself, using the `standalone deriving
+mechanism <#stand-alone-deriving>`__.
 
-Haskell 98 regards all four as ambiguous, but with the
-:ghc-flag:`-XDisambiguateRecordFields` flag, GHC will accept the former two. The
-rules are precisely the same as those for instance declarations in
-Haskell 98, where the method names on the left-hand side of the method
-bindings in an instance declaration refer unambiguously to the method of
-that class (provided they are in scope at all), even if there are other
-variables in scope with the same name. This reduces the clutter of
-qualified names when you import two records from different modules that
-use the same field name.
+.. _stand-alone-deriving:
 
-Some details:
+Stand-alone deriving declarations
+---------------------------------
 
--  Field disambiguation can be combined with punning (see
-   :ref:`record-puns`). For example: ::
+.. ghc-flag:: -XStandaloneDeriving
 
-       module Foo where
-         import M
-         x=True
-         ok3 (MkS { x }) = x+1   -- Uses both disambiguation and punning
+    Allow the use of stand-alone ``deriving`` declarations.
 
--  With :ghc-flag:`-XDisambiguateRecordFields` you can use *unqualified* field
-   names even if the corresponding selector is only in scope *qualified*
-   For example, assuming the same module ``M`` as in our earlier
-   example, this is legal: ::
+GHC allows stand-alone ``deriving`` declarations, enabled by
+:ghc-flag:`-XStandaloneDeriving`: ::
 
-       module Foo where
-         import qualified M    -- Note qualified
+      data Foo a = Bar a | Baz String
 
-         ok4 (M.MkS { x = n }) = n+1   -- Unambiguous
+      deriving instance Eq a => Eq (Foo a)
 
-   Since the constructor ``MkS`` is only in scope qualified, you must
-   name it ``M.MkS``, but the field ``x`` does not need to be qualified
-   even though ``M.x`` is in scope but ``x`` is not (In effect, it is
-   qualified by the constructor).
+The syntax is identical to that of an ordinary instance declaration
+apart from (a) the keyword ``deriving``, and (b) the absence of the
+``where`` part.
 
-.. _duplicate-record-fields:
+However, standalone deriving differs from a ``deriving`` clause in a
+number of important ways:
 
-Duplicate record fields
------------------------
+-  The standalone deriving declaration does not need to be in the same
+   module as the data type declaration. (But be aware of the dangers of
+   orphan instances (:ref:`orphan-modules`).
 
-.. ghc-flag:: -XDuplicateRecordFields
+-  You must supply an explicit context (in the example the context is
+   ``(Eq a)``), exactly as you would in an ordinary instance
+   declaration. (In contrast, in a ``deriving`` clause attached to a
+   data type declaration, the context is inferred.)
 
-    :implies: :ghc-flag:`-XDisambiguateRecordFields`
-    :since: 8.0.1
+-  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
+   the instance can be more specific than the data type (assuming you
+   also use :ghc-flag:`-XFlexibleInstances`, :ref:`instance-rules`). Consider
+   for example ::
 
-    Allow definition of record types with identically-named fields.
+         data Foo a = Bar a | Baz String
 
-Going beyond :ghc-flag:`-XDisambiguateRecordFields` (see :ref:`disambiguate-fields`),
-the :ghc-flag:`-XDuplicateRecordFields` extension allows multiple datatypes to be
-declared using the same field names in a single module. For example, it allows
-this: ::
+         deriving instance Eq a => Eq (Foo [a])
+         deriving instance Eq a => Eq (Foo (Maybe a))
 
-    module M where
-      data S = MkS { x :: Int }
-      data T = MkT { x :: Bool }
+   This will generate a derived instance for ``(Foo [a])`` and
+   ``(Foo (Maybe a))``, but other types such as ``(Foo (Int,Bool))``
+   will not be an instance of ``Eq``.
 
-Uses of fields that are always unambiguous because they mention the constructor,
-including construction and pattern-matching, may freely use duplicated field
-names. For example, the following are permitted (just as with
-:ghc-flag:`-XDisambiguateRecordFields`): ::
+-  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
+   GHC does not restrict the form of the data type. Instead, GHC simply
+   generates the appropriate boilerplate code for the specified class,
+   and typechecks it. If there is a type error, it is your problem. (GHC
+   will show you the offending code if it has a type error.)
 
-    s = MkS { x = 3 }
+   The merit of this is that you can derive instances for GADTs and
+   other exotic data types, providing only that the boilerplate code
+   does indeed typecheck. For example: ::
 
-    f (MkT { x = b }) = b
+         data T a where
+            T1 :: T Int
+            T2 :: T Bool
 
-Field names used as selector functions or in record updates must be unambiguous,
-either because there is only one such field in scope, or because a type
-signature is supplied, as described in the following sections.
+         deriving instance Show (T a)
 
-Selector functions
-~~~~~~~~~~~~~~~~~~
+   In this example, you cannot say ``... deriving( Show )`` on the data
+   type declaration for ``T``, because ``T`` is a GADT, but you *can*
+   generate the instance declaration using stand-alone deriving.
 
-Fields may be used as selector functions only if they are unambiguous, so this
-is still not allowed if both ``S(x)`` and ``T(x)`` are in scope: ::
+   The down-side is that, if the boilerplate code fails to typecheck,
+   you will get an error message about that code, which you did not
+   write. Whereas, with a ``deriving`` clause the side-conditions are
+   necessarily more conservative, but any error message may be more
+   comprehensible.
 
-    bad r = x r
+In other ways, however, a standalone deriving obeys the same rules as
+ordinary deriving:
 
-An ambiguous selector may be disambiguated by the type being "pushed down" to
-the occurrence of the selector (see :ref:`higher-rank-type-inference` for more
-details on what "pushed down" means). For example, the following are permitted: ::
+-  A ``deriving instance`` declaration must obey the same rules
+   concerning form and termination as ordinary instance declarations,
+   controlled by the same flags; see :ref:`instance-decls`.
 
-    ok1 = x :: S -> Int
+-  The stand-alone syntax is generalised for newtypes in exactly the
+   same way that ordinary ``deriving`` clauses are generalised
+   (:ref:`newtype-deriving`). For example: ::
 
-    ok2 :: S -> Int
-    ok2 = x
+         newtype Foo a = MkFoo (State Int a)
 
-    ok3 = k x -- assuming we already have k :: (S -> Int) -> _
+         deriving instance MonadState Int Foo
 
-In addition, the datatype that is meant may be given as a type signature on the
-argument to the selector: ::
+   GHC always treats the *last* parameter of the instance (``Foo`` in
+   this example) as the type whose instance is being derived.
 
-    ok4 s = x (s :: S)
+.. _deriving-extra:
 
-However, we do not infer the type of the argument to determine the datatype, or
-have any way of deferring the choice to the constraint solver. Thus the
-following is ambiguous: ::
+Deriving instances of extra classes (``Data``, etc.)
+----------------------------------------------------
+
+.. ghc-flag:: -XDeriveGeneric
+
+    Allow automatic deriving of instances for the ``Generic`` typeclass.
 
-    bad :: S -> Int
-    bad s = x s
+.. ghc-flag:: -XDeriveFunctor
 
-Even though a field label is duplicated in its defining module, it may be
-possible to use the selector unambiguously elsewhere. For example, another
-module could import ``S(x)`` but not ``T(x)``, and then use ``x`` unambiguously.
+    Allow automatic deriving of instances for the ``Functor`` typeclass.
 
-Record updates
-~~~~~~~~~~~~~~
+.. ghc-flag:: -XDeriveFoldable
 
-In a record update such as ``e { x = 1 }``, if there are multiple ``x`` fields
-in scope, then the type of the context must fix which record datatype is
-intended, or a type annotation must be supplied. Consider the following
-definitions: ::
+    Allow automatic deriving of instances for the ``Foldable`` typeclass.
 
-    data S = MkS { foo :: Int }
-    data T = MkT { foo :: Int, bar :: Int }
-    data U = MkU { bar :: Int, baz :: Int }
+.. ghc-flag:: -XDeriveTraversable
 
-Without :ghc-flag:`-XDuplicateRecordFields`, an update mentioning ``foo`` will always be
-ambiguous if all these definitions were in scope. When the extension is enabled,
-there are several options for disambiguating updates:
+    :implies: :ghc-flag:`-XDeriveFoldable`, :ghc-flag:`-XDeriveFunctor`
 
-- Check for types that have all the fields being updated. For example: ::
+    Allow automatic deriving of instances for the ``Traversable`` typeclass.
 
-      f x = x { foo = 3, bar = 2 }
+Haskell 98 allows the programmer to add "``deriving( Eq, Ord )``" to a
+data type declaration, to generate a standard instance declaration for
+classes specified in the ``deriving`` clause. In Haskell 98, the only
+classes that may appear in the ``deriving`` clause are the standard
+classes ``Eq``, ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and
+``Show``.
 
-  Here ``f`` must be updating ``T`` because neither ``S`` nor ``U`` have both
-  fields.
+GHC extends this list with several more classes that may be
+automatically derived:
 
-- Use the type being pushed in to the record update, as in the following: ::
+-  With :ghc-flag:`-XDeriveGeneric`, you can derive instances of the classes
+   ``Generic`` and ``Generic1``, defined in ``GHC.Generics``. You can
+   use these to define generic functions, as described in
+   :ref:`generic-programming`.
 
-      g1 :: T -> T
-      g1 x = x { foo = 3 }
+-  With :ghc-flag:`-XDeriveFunctor`, you can derive instances of the class
+   ``Functor``, defined in ``GHC.Base``. See :ref:`deriving-functor`.
 
-      g2 x = x { foo = 3 } :: T
+-  With :ghc-flag:`-XDeriveDataTypeable`, you can derive instances of the class
+   ``Data``, defined in ``Data.Data``. See :ref:`deriving-typeable` for
+   deriving ``Typeable``.
 
-      g3 = k (x { foo = 3 }) -- assuming we already have k :: T -> _
+-  With :ghc-flag:`-XDeriveFoldable`, you can derive instances of the class
+   ``Foldable``, defined in ``Data.Foldable``. See
+   :ref:`deriving-foldable`.
 
-- Use an explicit type signature on the record expression, as in: ::
+-  With :ghc-flag:`-XDeriveTraversable`, you can derive instances of the class
+   ``Traversable``, defined in ``Data.Traversable``. Since the
+   ``Traversable`` instance dictates the instances of ``Functor`` and
+   ``Foldable``, you'll probably want to derive them too, so
+   :ghc-flag:`-XDeriveTraversable` implies :ghc-flag:`-XDeriveFunctor` and
+   :ghc-flag:`-XDeriveFoldable`. See :ref:`deriving-traversable`.
 
-      h x = (x :: T) { foo = 3 }
+-  With :ghc-flag:`-XDeriveLift`, you can derive instances of the class ``Lift``,
+   defined in the ``Language.Haskell.TH.Syntax`` module of the
+   ``template-haskell`` package. See :ref:`deriving-lift`.
 
-The type of the expression being updated will not be inferred, and no
-constraint-solving will be performed, so the following will be rejected as
-ambiguous: ::
+You can also use a standalone deriving declaration instead (see
+:ref:`stand-alone-deriving`).
 
-    let x :: T
-        x = blah
-    in x { foo = 3 }
+In each case the appropriate class must be in scope before it can be
+mentioned in the ``deriving`` clause.
 
-    \x -> [x { foo = 3 },  blah :: T ]
+.. _deriving-functor:
 
-    \ (x :: T) -> x { foo = 3 }
+Deriving ``Functor`` instances
+------------------------------
 
-Import and export of record fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+With :ghc-flag:`-XDeriveFunctor`, one can derive ``Functor`` instances for data types
+of kind ``* -> *``. For example, this declaration::
 
-When :ghc-flag:`-XDuplicateRecordFields` is enabled, an ambiguous field must be exported
-as part of its datatype, rather than at the top level. For example, the
-following is legal: ::
+    data Example a = Ex a Char (Example a) (Example Char)
+      deriving Functor
 
-    module M (S(x), T(..)) where
-      data S = MkS { x :: Int }
-      data T = MkT { x :: Bool }
+would generate the following instance: ::
 
-However, this would not be permitted, because ``x`` is ambiguous: ::
+    instance Functor Example where
+      fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4
 
-    module M (x) where ...
+The basic algorithm for :ghc-flag:`-XDeriveFunctor` walks the arguments of each
+constructor of a data type, applying a mapping function depending on the type
+of each argument. If a plain type variable is found that is syntactically
+equivalent to the last type parameter of the data type (``a`` in the above
+example), then we apply the function ``f`` directly to it. If a type is
+encountered that is not syntactically equivalent to the last type parameter
+*but does mention* the last type parameter somewhere in it, then a recursive
+call to ``fmap`` is made. If a type is found which doesn't mention the last
+type paramter at all, then it is left alone.
 
-Similar restrictions apply on import.
+The second of those cases, in which a type is unequal to the type parameter but
+does contain the type parameter, can be surprisingly tricky. For example, the
+following example compiles::
 
-.. _record-puns:
+    newtype Right a = Right (Either Int a) deriving Functor
 
-Record puns
------------
+Modifying the code slightly, however, produces code which will not compile::
 
-.. ghc-flag:: -XNamedFieldPuns
+    newtype Wrong a = Wrong (Either a Int) deriving Functor
 
-    Allow use of record puns.
+The difference involves the placement of the last type parameter, ``a``. In the
+``Right`` case, ``a`` occurs within the type ``Either Int a``, and moreover, it
+appears as the last type argument of ``Either``. In the ``Wrong`` case,
+however, ``a`` is not the last type argument to ``Either``; rather, ``Int`` is.
 
-Record puns are enabled by the flag :ghc-flag:`-XNamedFieldPuns`.
+This distinction is important because of the way :ghc-flag:`-XDeriveFunctor` works. The
+derived ``Functor Right`` instance would be::
 
-When using records, it is common to write a pattern that binds a
-variable with the same name as a record field, such as: ::
+    instance Functor Right where
+      fmap f (Right a) = Right (fmap f a)
 
-    data C = C {a :: Int}
-    f (C {a = a}) = a
+Given a value of type ``Right a``, GHC must produce a value of type
+``Right b``. Since the argument to the ``Right`` constructor has type
+``Either Int a``, the code recursively calls ``fmap`` on it to produce a value
+of type ``Either Int b``, which is used in turn to construct a final value of
+type ``Right b``.
 
-Record punning permits the variable name to be elided, so one can simply
-write ::
+The generated code for the ``Functor Wrong`` instance would look exactly the
+same, except with ``Wrong`` replacing every occurrence of ``Right``. The
+problem is now that ``fmap`` is being applied recursively to a value of type
+``Either a Int``. This cannot possibly produce a value of type
+``Either b Int``, as ``fmap`` can only change the last type parameter! This
+causes the generated code to be ill-typed.
 
-    f (C {a}) = a
+As a general rule, if a data type has a derived ``Functor`` instance and its
+last type parameter occurs on the right-hand side of the data declaration, then
+either it must (1) occur bare (e.g., ``newtype Id a = a``), or (2) occur as the
+last argument of a type constructor (as in ``Right`` above).
 
-to mean the same pattern as above. That is, in a record pattern, the
-pattern ``a`` expands into the pattern ``a = a`` for the same name
-``a``.
+There are two exceptions to this rule:
 
-Note that:
+#. Tuple types. When a non-unit tuple is used on the right-hand side of a data
+   declaration, :ghc-flag:`-XDeriveFunctor` treats it as a product of distinct types.
+   In other words, the following code::
 
--  Record punning can also be used in an expression, writing, for
-   example, ::
+       newtype Triple a = Triple (a, Int, [a]) deriving Functor
 
-       let a = 1 in C {a}
+   Would result in a generated ``Functor`` instance like so::
 
-   instead of ::
+       instance Functor Triple where
+         fmap f (Triple a) =
+           Triple (case a of
+                        (a1, a2, a3) -> (f a1, a2, fmap f a3))
 
-       let a = 1 in C {a = a}
+   That is, :ghc-flag:`-XDeriveFunctor` pattern-matches its way into tuples and maps
+   over each type that constitutes the tuple. The generated code is
+   reminiscient of what would be generated from
+   ``data Triple a = Triple a Int [a]``, except with extra machinery to handle
+   the tuple.
 
-   The expansion is purely syntactic, so the expanded right-hand side
-   expression refers to the nearest enclosing variable that is spelled
-   the same as the field name.
+#. Function types. The last type parameter can appear anywhere in a function
+   type as long as it occurs in a *covariant* position. To illustrate what this
+   means, consider the following three examples::
 
--  Puns and other patterns can be mixed in the same record: ::
+       newtype CovFun1 a = CovFun1 (Int -> a) deriving Functor
+       newtype CovFun2 a = CovFun2 ((a -> Int) -> a) deriving Functor
+       newtype CovFun3 a = CovFun3 (((Int -> a) -> Int) -> a) deriving Functor
 
-       data C = C {a :: Int, b :: Int}
-       f (C {a, b = 4}) = a
+   All three of these examples would compile without issue. On the other hand::
 
--  Puns can be used wherever record patterns occur (e.g. in ``let``
-   bindings or at the top-level).
+       newtype ContraFun1 a = ContraFun1 (a -> Int) deriving Functor
+       newtype ContraFun2 a = ContraFun2 ((Int -> a) -> Int) deriving Functor
+       newtype ContraFun3 a = ContraFun3 (((a -> Int) -> a) -> Int) deriving Functor
 
--  A pun on a qualified field name is expanded by stripping off the
-   module qualifier. For example: ::
+   While these examples look similar, none of them would successfully compile.
+   This is because all occurrences of the last type parameter ``a`` occur in *contravariant* positions, not covariant ones.
 
-       f (C {M.a}) = a
+   Intuitively, a covariant type is *produced*, and a contravariant type is
+   *consumed*. Most types in Haskell are covariant, but the function type is
+   special in that the lefthand side of a function arrow reverses variance. If
+   a function type ``a -> b`` appears in a covariant position (e.g.,
+   ``CovFun1`` above), then ``a`` is in a contravariant position and ``b`` is
+   in a covariant position. Similarly, if ``a -> b`` appears in a contravariant
+   position (e.g., ``CovFun2`` above), then ``a`` is in ``a`` covariant
+   position and ``b`` is in a contravariant position.
 
-   means ::
+   To see why a data type with a contravariant occurrence of its last type
+   parameter cannot have a derived ``Functor`` instance, let's suppose that a
+   ``Functor ContraFun1`` instance exists. The implementation would look
+   something like this::
 
-       f (M.C {M.a = a}) = a
+       instance Functor ContraFun1 where
+         fmap f (ContraFun g) = ContraFun (\x -> _)
 
-   (This is useful if the field selector ``a`` for constructor ``M.C``
-   is only in scope in qualified form.)
+   We have ``f :: a -> b``, ``g :: a -> Int``, and ``x :: b``. Using these, we
+   must somehow fill in the hole (denoted with an underscore) with a value of
+   type ``Int``. What are our options?
 
-.. _record-wildcards:
+   We could try applying ``g`` to ``x``. This won't work though, as ``g``
+   expects an argument of type ``a``, and ``x :: b``. Even worse, we can't turn
+   ``x`` into something of type ``a``, since ``f`` also needs an argument of
+   type ``a``! In short, there's no good way to make this work.
 
-Record wildcards
-----------------
+   On the other hand, a derived ``Functor`` instances for the ``CovFun``\ s are
+   within the realm of possibility::
 
-.. ghc-flag:: -XRecordWildCards
+       instance Functor CovFun1 where
+         fmap f (CovFun1 g) = CovFun1 (\x -> f (g x))
 
-    :implies: :ghc-flag:`-XDisambiguateRecordFields`.
+       instance Functor CovFun2 where
+         fmap f (CovFun2 g) = CovFun2 (\h -> f (g (\x -> h (f x))))
 
-    Allow the use of wildcards in record construction and pattern matching.
+       instance Functor CovFun3 where
+         fmap f (CovFun3 g) = CovFun3 (\h -> f (g (\k -> h (\x -> f (k x)))))
 
-Record wildcards are enabled by the flag :ghc-flag:`-XRecordWildCards`. This
-flag implies :ghc-flag:`-XDisambiguateRecordFields`.
+There are some other scenarios in which a derived ``Functor`` instance will
+fail to compile:
 
-For records with many fields, it can be tiresome to write out each field
-individually in a record pattern, as in ::
+#. A data type has no type parameters (e.g., ``data Nothing = Nothing``).
 
-    data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
-    f (C {a = 1, b = b, c = c, d = d}) = b + c + d
+#. A data type's last type variable is used in a :ghc-flag:`-XDatatypeContexts`
+   constraint (e.g., ``data Ord a => O a = O a``).
 
-Record wildcard syntax permits a "``..``" in a record pattern, where
-each elided field ``f`` is replaced by the pattern ``f = f``. For
-example, the above pattern can be written as ::
+#. A data type's last type variable is used in an
+   :ghc-flag:`-XExistentialQuantification` constraint, or is refined in a GADT. For
+   example, ::
+
+       data T a b where
+           T4 :: Ord b => b -> T a b
+           T5 :: b -> T b b
+           T6 :: T a (b,b)
 
-    f (C {a = 1, ..}) = b + c + d
+       deriving instance Functor (T a)
 
-More details:
+   would not compile successfully due to the way in which ``b`` is constrained.
 
--  Record wildcards in patterns can be mixed with other patterns,
-   including puns (:ref:`record-puns`); for example, in a pattern
-   ``(C {a = 1, b, ..})``. Additionally, record wildcards can be used
-   wherever record patterns occur, including in ``let`` bindings and at
-   the top-level. For example, the top-level binding ::
+.. _deriving-foldable:
 
-       C {a = 1, ..} = e
+Deriving ``Foldable`` instances
+-------------------------------
 
-   defines ``b``, ``c``, and ``d``.
+With :ghc-flag:`-XDeriveFoldable`, one can derive ``Foldable`` instances for data types
+of kind ``* -> *``. For example, this declaration::
 
--  Record wildcards can also be used in an expression, when constructing
-   a record. For example, ::
+    data Example a = Ex a Char (Example a) (Example Char)
+      deriving Foldable
 
-       let {a = 1; b = 2; c = 3; d = 4} in C {..}
+would generate the following instance::
 
-   in place of ::
+    instance Foldable Example where
+      foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3)
+      foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) (foldMap f a3)
 
-       let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
+The algorithm for :ghc-flag:`-XDeriveFoldable` is adapted from the :ghc-flag:`-XDeriveFunctor`
+algorithm, but it generates definitions for ``foldMap`` and ``foldr`` instead
+of ``fmap``. Here are the differences between the generated code in each
+extension:
 
-   The expansion is purely syntactic, so the record wildcard expression
-   refers to the nearest enclosing variables that are spelled the same
-   as the omitted field names.
+#. When a bare type variable ``a`` is encountered, :ghc-flag:`-XDeriveFunctor` would
+   generate ``f a`` for an ``fmap`` definition. :ghc-flag:`-XDeriveFoldable` would
+   generate ``f a z`` for ``foldr``, and ``f a`` for ``foldMap``.
 
--  Record wildcards may *not* be used in record *updates*. For example
-   this is illegal: ::
+#. When a type that is not syntactically equivalent to ``a``, but which does
+   contain ``a``, is encountered, :ghc-flag:`-XDeriveFunctor` recursively calls
+   ``fmap`` on it. Similarly, :ghc-flag:`-XDeriveFoldable` would recursively call
+   ``foldr`` and ``foldMap``.
 
-       f r = r { x = 3, .. }
+#. When a type that does not mention ``a`` is encountered, :ghc-flag:`-XDeriveFunctor`
+   leaves it alone. On the other hand, :ghc-flag:`-XDeriveFoldable` would generate
+   ``z`` (the state value) for ``foldr`` and ``mempty`` for ``foldMap``.
 
--  For both pattern and expression wildcards, the "``..``" expands to
-   the missing *in-scope* record fields. Specifically the expansion of
-   "``C {..}``" includes ``f`` if and only if:
+#. :ghc-flag:`-XDeriveFunctor` puts everything back together again at the end by
+   invoking the constructor. :ghc-flag:`-XDeriveFoldable`, however, builds up a value
+   of some type. For ``foldr``, this is accomplished by chaining applications
+   of ``f`` and recursive ``foldr`` calls on the state value ``z``. For
+   ``foldMap``, this happens by combining all values with ``mappend``.
 
-   -  ``f`` is a record field of constructor ``C``.
+There are some other differences regarding what data types can have derived
+``Foldable`` instances:
 
-   -  The record field ``f`` is in scope somehow (either qualified or
-      unqualified).
+#. Data types containing function types on the right-hand side cannot have
+   derived ``Foldable`` instances.
 
-   -  In the case of expressions (but not patterns), the variable ``f``
-      is in scope unqualified, apart from the binding of the record
-      selector itself.
+#. ``Foldable`` instances can be derived for data types in which the last type
+   parameter is existentially constrained or refined in a GADT. For example,
+   this data type::
 
-   These rules restrict record wildcards to the situations in which the
-   user could have written the expanded version. For example ::
+       data E a where
+           E1 :: (a ~ Int) => a   -> E a
+           E2 ::              Int -> E Int
+           E3 :: (a ~ Int) => a   -> E Int
+           E4 :: (a ~ Int) => Int -> E a
 
-       module M where
-         data R = R { a,b,c :: Int }
-       module X where
-         import M( R(a,c) )
-         f b = R { .. }
+       deriving instance Foldable E
 
-   The ``R{..}`` expands to ``R{M.a=a}``, omitting ``b`` since the
-   record field is not in scope, and omitting ``c`` since the variable
-   ``c`` is not in scope (apart from the binding of the record selector
-   ``c``, of course).
+   would have the following generated ``Foldable`` instance::
 
--  Record wildcards cannot be used (a) in a record update construct, and
-   (b) for data constructors that are not declared with record fields.
-   For example: ::
+       instance Foldable E where
+           foldr f z (E1 e) = f e z
+           foldr f z (E2 e) = z
+           foldr f z (E3 e) = z
+           foldr f z (E4 e) = z
 
-       f x = x { v=True, .. }   -- Illegal (a)
+           foldMap f (E1 e) = f e
+           foldMap f (E2 e) = mempty
+           foldMap f (E3 e) = mempty
+           foldMap f (E4 e) = mempty
 
-       data T = MkT Int Bool
-       g = MkT { .. }           -- Illegal (b)
-       h (MkT { .. }) = True    -- Illegal (b)
+   Notice how every constructor of ``E`` utilizes some sort of existential
+   quantification, but only the argument of ``E1`` is actually "folded over".
+   This is because we make a deliberate choice to only fold over universally
+   polymorphic types that are syntactically equivalent to the last type
+   parameter. In particular:
 
-.. _deriving:
+  -  We don't fold over the arguments of ``E1`` or ``E4`` beacause even though
+     ``(a ~ Int)``, ``Int`` is not syntactically equivalent to ``a``.
 
-Extensions to the "deriving" mechanism
-======================================
+  -  We don't fold over the argument of ``E3`` because ``a`` is not universally
+     polymorphic. The ``a`` in ``E3`` is (implicitly) existentially quantified,
+     so it is not the same as the last type parameter of ``E``.
 
-.. _deriving-inferred:
+.. _deriving-traversable:
 
-Inferred context for deriving clauses
--------------------------------------
+Deriving ``Traversable`` instances
+----------------------------------
 
-The Haskell Report is vague about exactly when a ``deriving`` clause is
-legal. For example: ::
+With :ghc-flag:`-XDeriveTraversable`, one can derive ``Traversable`` instances for data
+types of kind ``* -> *``. For example, this declaration::
 
-      data T0 f a = MkT0 a         deriving( Eq )
-      data T1 f a = MkT1 (f a)     deriving( Eq )
-      data T2 f a = MkT2 (f (f a)) deriving( Eq )
+    data Example a = Ex a Char (Example a) (Example Char)
+      deriving (Functor, Foldable, Traversable)
 
-The natural generated ``Eq`` code would result in these instance
-declarations: ::
+would generate the following ``Traversable`` instance::
 
-      instance Eq a         => Eq (T0 f a) where ...
-      instance Eq (f a)     => Eq (T1 f a) where ...
-      instance Eq (f (f a)) => Eq (T2 f a) where ...
+    instance Traversable Example where
+      traverse f (Ex a1 a2 a3 a4)
+        = fmap Ex (f a1) <*> traverse f a3
 
-The first of these is obviously fine. The second is still fine, although
-less obviously. The third is not Haskell 98, and risks losing
-termination of instances.
+The algorithm for :ghc-flag:`-XDeriveTraversable` is adapted from the
+:ghc-flag:`-XDeriveFunctor` algorithm, but it generates a definition for ``traverse``
+instead of ``fmap``. Here are the differences between the generated code in
+each extension:
 
-GHC takes a conservative position: it accepts the first two, but not the
-third. The rule is this: each constraint in the inferred instance
-context must consist only of type variables, with no repetitions.
+#. When a bare type variable ``a`` is encountered, both :ghc-flag:`-XDeriveFunctor` and
+   :ghc-flag:`-XDeriveTraversable` would generate ``f a`` for an ``fmap`` and
+   ``traverse`` definition, respectively.
 
-This rule is applied regardless of flags. If you want a more exotic
-context, you can write it yourself, using the `standalone deriving
-mechanism <#stand-alone-deriving>`__.
+#. When a type that is not syntactically equivalent to ``a``, but which does
+   contain ``a``, is encountered, :ghc-flag:`-XDeriveFunctor` recursively calls
+   ``fmap`` on it. Similarly, :ghc-flag:`-XDeriveTraversable` would recursively call
+   ``traverse``.
 
-.. _stand-alone-deriving:
+#. When a type that does not mention ``a`` is encountered, :ghc-flag:`-XDeriveFunctor`
+   leaves it alone. On the other hand, :ghc-flag:`-XDeriveTraversable` would call
+   ``pure`` on the value of that type.
 
-Stand-alone deriving declarations
----------------------------------
+#. :ghc-flag:`-XDeriveFunctor` puts everything back together again at the end by
+   invoking the constructor. :ghc-flag:`-XDeriveTraversable` does something similar,
+   but it works in an ``Applicative`` context by chaining everything together
+   with ``(<*>)``.
 
-.. ghc-flag:: -XStandaloneDeriving
+Unlike :ghc-flag:`-XDeriveFunctor`, :ghc-flag:`-XDeriveTraversable` cannot be used on data
+types containing a function type on the right-hand side.
 
-    Allow the use of stand-alone ``deriving`` declarations.
+For a full specification of the algorithms used in :ghc-flag:`-XDeriveFunctor`,
+:ghc-flag:`-XDeriveFoldable`, and :ghc-flag:`-XDeriveTraversable`, see
+:ghc-wiki:`this wiki page <Commentary/Compiler/DeriveFunctor>`.
 
-GHC allows stand-alone ``deriving`` declarations, enabled by
-:ghc-flag:`-XStandaloneDeriving`: ::
+.. _deriving-typeable:
 
-      data Foo a = Bar a | Baz String
+Deriving ``Typeable`` instances
+-------------------------------
 
-      deriving instance Eq a => Eq (Foo a)
+.. ghc-flag:: -XDeriveDataTypeable
 
-The syntax is identical to that of an ordinary instance declaration
-apart from (a) the keyword ``deriving``, and (b) the absence of the
-``where`` part.
+    Enable automatic deriving of instances for the ``Typeable`` typeclass
 
-However, standalone deriving differs from a ``deriving`` clause in a
-number of important ways:
+The class ``Typeable`` is very special:
 
--  The standalone deriving declaration does not need to be in the same
-   module as the data type declaration. (But be aware of the dangers of
-   orphan instances (:ref:`orphan-modules`).
+-  ``Typeable`` is kind-polymorphic (see :ref:`kind-polymorphism`).
 
--  You must supply an explicit context (in the example the context is
-   ``(Eq a)``), exactly as you would in an ordinary instance
-   declaration. (In contrast, in a ``deriving`` clause attached to a
-   data type declaration, the context is inferred.)
+-  GHC has a custom solver for discharging constraints that involve
+   class ``Typeable``, and handwritten instances are forbidden. This
+   ensures that the programmer cannot subvert the type system by writing
+   bogus instances.
 
--  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
-   the instance can be more specific than the data type (assuming you
-   also use :ghc-flag:`-XFlexibleInstances`, :ref:`instance-rules`). Consider
-   for example ::
+-  Derived instances of ``Typeable`` are ignored, and may be reported as
+   an error in a later version of the compiler.
 
-         data Foo a = Bar a | Baz String
+-  The rules for solving \`Typeable\` constraints are as follows:
 
-         deriving instance Eq a => Eq (Foo [a])
-         deriving instance Eq a => Eq (Foo (Maybe a))
+   -  A concrete type constructor applied to some types. ::
 
-   This will generate a derived instance for ``(Foo [a])`` and
-   ``(Foo (Maybe a))``, but other types such as ``(Foo (Int,Bool))``
-   will not be an instance of ``Eq``.
+          instance (Typeable t1, .., Typeable t_n) =>
+            Typeable (T t1 .. t_n)
 
--  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
-   GHC does not restrict the form of the data type. Instead, GHC simply
-   generates the appropriate boilerplate code for the specified class,
-   and typechecks it. If there is a type error, it is your problem. (GHC
-   will show you the offending code if it has a type error.)
+      This rule works for any concrete type constructor, including type
+      constructors with polymorphic kinds. The only restriction is that
+      if the type constructor has a polymorphic kind, then it has to be
+      applied to all of its kinds parameters, and these kinds need to be
+      concrete (i.e., they cannot mention kind variables).
 
-   The merit of this is that you can derive instances for GADTs and
-   other exotic data types, providing only that the boilerplate code
-   does indeed typecheck. For example: ::
+   -  ::
 
-         data T a where
-            T1 :: T Int
-            T2 :: T Bool
+          A type variable applied to some types.
+          instance (Typeable f, Typeable t1, .., Typeable t_n) =>
+            Typeable (f t1 .. t_n)
 
-         deriving instance Show (T a)
+   -  ::
 
-   In this example, you cannot say ``... deriving( Show )`` on the data
-   type declaration for ``T``, because ``T`` is a GADT, but you *can*
-   generate the instance declaration using stand-alone deriving.
+          A concrete type literal.
+          instance Typeable 0       -- Type natural literals
+          instance Typeable "Hello" -- Type-level symbols
 
-   The down-side is that, if the boilerplate code fails to typecheck,
-   you will get an error message about that code, which you did not
-   write. Whereas, with a ``deriving`` clause the side-conditions are
-   necessarily more conservative, but any error message may be more
-   comprehensible.
+.. _deriving-lift:
+
+Deriving ``Lift`` instances
+---------------------------
 
-In other ways, however, a standalone deriving obeys the same rules as
-ordinary deriving:
+.. ghc-flag:: -XDeriveLift
 
--  A ``deriving instance`` declaration must obey the same rules
-   concerning form and termination as ordinary instance declarations,
-   controlled by the same flags; see :ref:`instance-decls`.
+    :since: 8.0.1
 
--  The stand-alone syntax is generalised for newtypes in exactly the
-   same way that ordinary ``deriving`` clauses are generalised
-   (:ref:`newtype-deriving`). For example: ::
+    Enable automatic deriving of instances for the ``Lift`` typeclass for
+    Template Haskell.
 
-         newtype Foo a = MkFoo (State Int a)
+The class ``Lift``, unlike other derivable classes, lives in
+``template-haskell`` instead of ``base``. Having a data type be an instance of
+``Lift`` permits its values to be promoted to Template Haskell expressions (of
+type ``ExpQ``), which can then be spliced into Haskell source code.
 
-         deriving instance MonadState Int Foo
+Here is an example of how one can derive ``Lift``:
 
-   GHC always treats the *last* parameter of the instance (``Foo`` in
-   this example) as the type whose instance is being derived.
+::
 
-.. _deriving-extra:
+    {-# LANGUAGE DeriveLift #-}
+    module Bar where
 
-Deriving instances of extra classes (``Data``, etc.)
-----------------------------------------------------
+    import Language.Haskell.TH.Syntax
 
-.. ghc-flag:: -XDeriveGeneric
+    data Foo a = Foo a | a :^: a deriving Lift
 
-    Allow automatic deriving of instances for the ``Generic`` typeclass.
+    {-
+    instance (Lift a) => Lift (Foo a) where
+        lift (Foo a)
+        = appE
+            (conE
+                (mkNameG_d "package-name" "Bar" "Foo"))
+            (lift a)
+        lift (u :^: v)
+        = infixApp
+            (lift u)
+            (conE
+                (mkNameG_d "package-name" "Bar" ":^:"))
+            (lift v)
+    -}
 
-.. ghc-flag:: -XDeriveFunctor
+    -----
+    {-# LANGUAGE TemplateHaskell #-}
+    module Baz where
 
-    Allow automatic deriving of instances for the ``Functor`` typeclass.
+    import Bar
+    import Language.Haskell.TH.Lift
 
-.. ghc-flag:: -XDeriveFoldable
+    foo :: Foo String
+    foo = $(lift $ Foo "foo")
 
-    Allow automatic deriving of instances for the ``Foldable`` typeclass.
+    fooExp :: Lift a => Foo a -> Q Exp
+    fooExp f = [| f |]
 
-.. ghc-flag:: -XDeriveTraversable
+:ghc-flag:`-XDeriveLift` also works for certain unboxed types (``Addr#``, ``Char#``,
+``Double#``, ``Float#``, ``Int#``, and ``Word#``):
 
-    :implies: :ghc-flag:`-XDeriveFoldable`, :ghc-flag:`-XDeriveFunctor`
+::
 
-    Allow automatic deriving of instances for the ``Traversable`` typeclass.
+    {-# LANGUAGE DeriveLift, MagicHash #-}
+    module Unboxed where
 
-Haskell 98 allows the programmer to add "``deriving( Eq, Ord )``" to a
-data type declaration, to generate a standard instance declaration for
-classes specified in the ``deriving`` clause. In Haskell 98, the only
-classes that may appear in the ``deriving`` clause are the standard
-classes ``Eq``, ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and
-``Show``.
+    import GHC.Exts
+    import Language.Haskell.TH.Syntax
 
-GHC extends this list with several more classes that may be
-automatically derived:
+    data IntHash = IntHash Int# deriving Lift
 
--  With :ghc-flag:`-XDeriveGeneric`, you can derive instances of the classes
-   ``Generic`` and ``Generic1``, defined in ``GHC.Generics``. You can
-   use these to define generic functions, as described in
-   :ref:`generic-programming`.
+    {-
+    instance Lift IntHash where
+        lift (IntHash i)
+        = appE
+            (conE
+                (mkNameG_d "package-name" "Unboxed" "IntHash"))
+            (litE
+                (intPrimL (toInteger (I# i))))
+    -}
 
--  With :ghc-flag:`-XDeriveFunctor`, you can derive instances of the class
-   ``Functor``, defined in ``GHC.Base``. See :ref:`deriving-functor`.
 
--  With :ghc-flag:`-XDeriveDataTypeable`, you can derive instances of the class
-   ``Data``, defined in ``Data.Data``. See :ref:`deriving-typeable` for
-   deriving ``Typeable``.
+.. _newtype-deriving:
 
--  With :ghc-flag:`-XDeriveFoldable`, you can derive instances of the class
-   ``Foldable``, defined in ``Data.Foldable``. See
-   :ref:`deriving-foldable`.
+Generalised derived instances for newtypes
+------------------------------------------
 
--  With :ghc-flag:`-XDeriveTraversable`, you can derive instances of the class
-   ``Traversable``, defined in ``Data.Traversable``. Since the
-   ``Traversable`` instance dictates the instances of ``Functor`` and
-   ``Foldable``, you'll probably want to derive them too, so
-   :ghc-flag:`-XDeriveTraversable` implies :ghc-flag:`-XDeriveFunctor` and
-   :ghc-flag:`-XDeriveFoldable`. See :ref:`deriving-traversable`.
+.. ghc-flag:: -XGeneralisedNewtypeDeriving
+              -XGeneralizedNewtypeDeriving
 
--  With :ghc-flag:`-XDeriveLift`, you can derive instances of the class ``Lift``,
-   defined in the ``Language.Haskell.TH.Syntax`` module of the
-   ``template-haskell`` package. See :ref:`deriving-lift`.
+    Enable GHC's cunning generalised deriving mechanism for ``newtype``\s
 
-You can also use a standalone deriving declaration instead (see
-:ref:`stand-alone-deriving`).
+When you define an abstract type using ``newtype``, you may want the new
+type to inherit some instances from its representation. In Haskell 98,
+you can inherit instances of ``Eq``, ``Ord``, ``Enum`` and ``Bounded``
+by deriving them, but for any other classes you have to write an
+explicit instance declaration. For example, if you define ::
 
-In each case the appropriate class must be in scope before it can be
-mentioned in the ``deriving`` clause.
+      newtype Dollars = Dollars Int
 
-.. _deriving-functor:
+and you want to use arithmetic on ``Dollars``, you have to explicitly
+define an instance of ``Num``: ::
 
-Deriving ``Functor`` instances
-------------------------------
+      instance Num Dollars where
+        Dollars a + Dollars b = Dollars (a+b)
+        ...
 
-With :ghc-flag:`-XDeriveFunctor`, one can derive ``Functor`` instances for data types
-of kind ``* -> *``. For example, this declaration::
+All the instance does is apply and remove the ``newtype`` constructor.
+It is particularly galling that, since the constructor doesn't appear at
+run-time, this instance declaration defines a dictionary which is
+*wholly equivalent* to the ``Int`` dictionary, only slower!
 
-    data Example a = Ex a Char (Example a) (Example Char)
-      deriving Functor
+.. _generalized-newtype-deriving:
 
-would generate the following instance: ::
+Generalising the deriving clause
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    instance Functor Example where
-      fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4
+GHC now permits such instances to be derived instead, using the flag
+:ghc-flag:`-XGeneralizedNewtypeDeriving`, so one can write ::
 
-The basic algorithm for :ghc-flag:`-XDeriveFunctor` walks the arguments of each
-constructor of a data type, applying a mapping function depending on the type
-of each argument. If a plain type variable is found that is syntactically
-equivalent to the last type parameter of the data type (``a`` in the above
-example), then we apply the function ``f`` directly to it. If a type is
-encountered that is not syntactically equivalent to the last type parameter
-*but does mention* the last type parameter somewhere in it, then a recursive
-call to ``fmap`` is made. If a type is found which doesn't mention the last
-type paramter at all, then it is left alone.
+      newtype Dollars = Dollars Int deriving (Eq,Show,Num)
 
-The second of those cases, in which a type is unequal to the type parameter but
-does contain the type parameter, can be surprisingly tricky. For example, the
-following example compiles::
+and the implementation uses the *same* ``Num`` dictionary for
+``Dollars`` as for ``Int``. Notionally, the compiler derives an instance
+declaration of the form ::
 
-    newtype Right a = Right (Either Int a) deriving Functor
+      instance Num Int => Num Dollars
 
-Modifying the code slightly, however, produces code which will not compile::
+which just adds or removes the ``newtype`` constructor according to the
+type.
 
-    newtype Wrong a = Wrong (Either a Int) deriving Functor
+We can also derive instances of constructor classes in a similar way.
+For example, suppose we have implemented state and failure monad
+transformers, such that ::
 
-The difference involves the placement of the last type parameter, ``a``. In the
-``Right`` case, ``a`` occurs within the type ``Either Int a``, and moreover, it
-appears as the last type argument of ``Either``. In the ``Wrong`` case,
-however, ``a`` is not the last type argument to ``Either``; rather, ``Int`` is.
+      instance Monad m => Monad (State s m)
+      instance Monad m => Monad (Failure m)
 
-This distinction is important because of the way :ghc-flag:`-XDeriveFunctor` works. The
-derived ``Functor Right`` instance would be::
+In Haskell 98, we can define a parsing monad by ::
 
-    instance Functor Right where
-      fmap f (Right a) = Right (fmap f a)
+      type Parser tok m a = State [tok] (Failure m) a
 
-Given a value of type ``Right a``, GHC must produce a value of type
-``Right b``. Since the argument to the ``Right`` constructor has type
-``Either Int a``, the code recursively calls ``fmap`` on it to produce a value
-of type ``Either Int b``, which is used in turn to construct a final value of
-type ``Right b``.
+which is automatically a monad thanks to the instance declarations
+above. With the extension, we can make the parser type abstract, without
+needing to write an instance of class ``Monad``, via ::
 
-The generated code for the ``Functor Wrong`` instance would look exactly the
-same, except with ``Wrong`` replacing every occurrence of ``Right``. The
-problem is now that ``fmap`` is being applied recursively to a value of type
-``Either a Int``. This cannot possibly produce a value of type
-``Either b Int``, as ``fmap`` can only change the last type parameter! This
-causes the generated code to be ill-typed.
+      newtype Parser tok m a = Parser (State [tok] (Failure m) a)
+                             deriving Monad
 
-As a general rule, if a data type has a derived ``Functor`` instance and its
-last type parameter occurs on the right-hand side of the data declaration, then
-either it must (1) occur bare (e.g., ``newtype Id a = a``), or (2) occur as the
-last argument of a type constructor (as in ``Right`` above).
+In this case the derived instance declaration is of the form ::
 
-There are two exceptions to this rule:
+      instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
 
-#. Tuple types. When a non-unit tuple is used on the right-hand side of a data
-   declaration, :ghc-flag:`-XDeriveFunctor` treats it as a product of distinct types.
-   In other words, the following code::
+Notice that, since ``Monad`` is a constructor class, the instance is a
+*partial application* of the new type, not the entire left hand side. We
+can imagine that the type declaration is "eta-converted" to generate the
+context of the instance declaration.
 
-       newtype Triple a = Triple (a, Int, [a]) deriving Functor
+We can even derive instances of multi-parameter classes, provided the
+newtype is the last class parameter. In this case, a "partial
+application" of the class appears in the ``deriving`` clause. For
+example, given the class ::
 
-   Would result in a generated ``Functor`` instance like so::
+      class StateMonad s m | m -> s where ...
+      instance Monad m => StateMonad s (State s m) where ...
 
-       instance Functor Triple where
-         fmap f (Triple a) =
-           Triple (case a of
-                        (a1, a2, a3) -> (f a1, a2, fmap f a3))
+then we can derive an instance of ``StateMonad`` for ``Parser`` by ::
 
-   That is, :ghc-flag:`-XDeriveFunctor` pattern-matches its way into tuples and maps
-   over each type that constitutes the tuple. The generated code is
-   reminiscient of what would be generated from
-   ``data Triple a = Triple a Int [a]``, except with extra machinery to handle
-   the tuple.
+      newtype Parser tok m a = Parser (State [tok] (Failure m) a)
+                             deriving (Monad, StateMonad [tok])
 
-#. Function types. The last type parameter can appear anywhere in a function
-   type as long as it occurs in a *covariant* position. To illustrate what this
-   means, consider the following three examples::
+The derived instance is obtained by completing the application of the
+class to the new type: ::
 
-       newtype CovFun1 a = CovFun1 (Int -> a) deriving Functor
-       newtype CovFun2 a = CovFun2 ((a -> Int) -> a) deriving Functor
-       newtype CovFun3 a = CovFun3 (((Int -> a) -> Int) -> a) deriving Functor
+      instance StateMonad [tok] (State [tok] (Failure m)) =>
+               StateMonad [tok] (Parser tok m)
 
-   All three of these examples would compile without issue. On the other hand::
+As a result of this extension, all derived instances in newtype
+declarations are treated uniformly (and implemented just by reusing the
+dictionary for the representation type), *except* ``Show`` and ``Read``,
+which really behave differently for the newtype and its representation.
 
-       newtype ContraFun1 a = ContraFun1 (a -> Int) deriving Functor
-       newtype ContraFun2 a = ContraFun2 ((Int -> a) -> Int) deriving Functor
-       newtype ContraFun3 a = ContraFun3 (((a -> Int) -> a) -> Int) deriving Functor
+A more precise specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A derived instance is derived only for declarations of these forms
+(after expansion of any type synonyms) ::
 
-   While these examples look similar, none of them would successfully compile.
-   This is because all occurrences of the last type parameter ``a`` occur in *contravariant* positions, not covariant ones.
+      newtype T v1..vn                   = MkT (t vk+1..vn) deriving (C t1..tj)
+      newtype instance T s1..sk vk+1..vn = MkT (t vk+1..vn) deriving (C t1..tj)
 
-   Intuitively, a covariant type is *produced*, and a contravariant type is
-   *consumed*. Most types in Haskell are covariant, but the function type is
-   special in that the lefthand side of a function arrow reverses variance. If
-   a function type ``a -> b`` appears in a covariant position (e.g.,
-   ``CovFun1`` above), then ``a`` is in a contravariant position and ``b`` is
-   in a covariant position. Similarly, if ``a -> b`` appears in a contravariant
-   position (e.g., ``CovFun2`` above), then ``a`` is in ``a`` covariant
-   position and ``b`` is in a contravariant position.
+where
 
-   To see why a data type with a contravariant occurrence of its last type
-   parameter cannot have a derived ``Functor`` instance, let's suppose that a
-   ``Functor ContraFun1`` instance exists. The implementation would look
-   something like this::
+-  ``v1..vn`` are type variables, and ``t``, ``s1..sk``, ``t1..tj`` are
+   types.
 
-       instance Functor ContraFun1 where
-         fmap f (ContraFun g) = ContraFun (\x -> _)
+-  The ``(C t1..tj)`` is a partial applications of the class ``C``,
+   where the arity of ``C`` is exactly ``j+1``. That is, ``C`` lacks
+   exactly one type argument.
 
-   We have ``f :: a -> b``, ``g :: a -> Int``, and ``x :: b``. Using these, we
-   must somehow fill in the hole (denoted with an underscore) with a value of
-   type ``Int``. What are our options?
+-  ``k`` is chosen so that ``C t1..tj (T v1...vk)`` is well-kinded. (Or,
+   in the case of a ``data instance``, so that ``C t1..tj (T s1..sk)``
+   is well kinded.)
 
-   We could try applying ``g`` to ``x``. This won't work though, as ``g``
-   expects an argument of type ``a``, and ``x :: b``. Even worse, we can't turn
-   ``x`` into something of type ``a``, since ``f`` also needs an argument of
-   type ``a``! In short, there's no good way to make this work.
+-  The type ``t`` is an arbitrary type.
 
-   On the other hand, a derived ``Functor`` instances for the ``CovFun``\ s are
-   within the realm of possibility::
+-  The type variables ``vk+1...vn`` do not occur in the types ``t``,
+   ``s1..sk``, or ``t1..tj``.
 
-       instance Functor CovFun1 where
-         fmap f (CovFun1 g) = CovFun1 (\x -> f (g x))
+-  ``C`` is not ``Read``, ``Show``, ``Typeable``, or ``Data``. These
+   classes should not "look through" the type or its constructor. You
+   can still derive these classes for a newtype, but it happens in the
+   usual way, not via this new mechanism.
 
-       instance Functor CovFun2 where
-         fmap f (CovFun2 g) = CovFun2 (\h -> f (g (\x -> h (f x))))
+-  It is safe to coerce each of the methods of ``C``. That is, the
+   missing last argument to ``C`` is not used at a nominal role in any
+   of the ``C``'s methods. (See :ref:`roles`.)
 
-       instance Functor CovFun3 where
-         fmap f (CovFun3 g) = CovFun3 (\h -> f (g (\k -> h (\x -> f (k x)))))
+Then the derived instance declaration is of the form ::
 
-There are some other scenarios in which a derived ``Functor`` instance will
-fail to compile:
+      instance C t1..tj t => C t1..tj (T v1...vk)
 
-#. A data type has no type parameters (e.g., ``data Nothing = Nothing``).
+As an example which does *not* work, consider ::
 
-#. A data type's last type variable is used in a :ghc-flag:`-XDatatypeContexts`
-   constraint (e.g., ``data Ord a => O a = O a``).
+      newtype NonMonad m s = NonMonad (State s m s) deriving Monad
 
-#. A data type's last type variable is used in an
-   :ghc-flag:`-XExistentialQuantification` constraint, or is refined in a GADT. For
-   example, ::
+Here we cannot derive the instance ::
 
-       data T a b where
-           T4 :: Ord b => b -> T a b
-           T5 :: b -> T b b
-           T6 :: T a (b,b)
+      instance Monad (State s m) => Monad (NonMonad m)
 
-       deriving instance Functor (T a)
+because the type variable ``s`` occurs in ``State s m``, and so cannot
+be "eta-converted" away. It is a good thing that this ``deriving``
+clause is rejected, because ``NonMonad m`` is not, in fact, a monad ---
+for the same reason. Try defining ``>>=`` with the correct type: you
+won't be able to.
 
-   would not compile successfully due to the way in which ``b`` is constrained.
+Notice also that the *order* of class parameters becomes important,
+since we can only derive instances for the last one. If the
+``StateMonad`` class above were instead defined as ::
 
-.. _deriving-foldable:
+      class StateMonad m s | m -> s where ...
 
-Deriving ``Foldable`` instances
--------------------------------
+then we would not have been able to derive an instance for the
+``Parser`` type above. We hypothesise that multi-parameter classes
+usually have one "main" parameter for which deriving new instances is
+most interesting.
 
-With :ghc-flag:`-XDeriveFoldable`, one can derive ``Foldable`` instances for data types
-of kind ``* -> *``. For example, this declaration::
+Lastly, all of this applies only for classes other than ``Read``,
+``Show``, ``Typeable``, and ``Data``, for which the built-in derivation
+applies (section 4.3.3. of the Haskell Report). (For the standard
+classes ``Eq``, ``Ord``, ``Ix``, and ``Bounded`` it is immaterial
+whether the standard method is used or the one described here.)
 
-    data Example a = Ex a Char (Example a) (Example Char)
-      deriving Foldable
+.. _derive-any-class:
 
-would generate the following instance::
+Deriving any other class
+------------------------
 
-    instance Foldable Example where
-      foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3)
-      foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) (foldMap f a3)
+.. ghc-flag:: -XDeriveAnyClass
 
-The algorithm for :ghc-flag:`-XDeriveFoldable` is adapted from the :ghc-flag:`-XDeriveFunctor`
-algorithm, but it generates definitions for ``foldMap`` and ``foldr`` instead
-of ``fmap``. Here are the differences between the generated code in each
-extension:
+    :since: 7.10.1
 
-#. When a bare type variable ``a`` is encountered, :ghc-flag:`-XDeriveFunctor` would
-   generate ``f a`` for an ``fmap`` definition. :ghc-flag:`-XDeriveFoldable` would
-   generate ``f a z`` for ``foldr``, and ``f a`` for ``foldMap``.
+    Allow use of any typeclass in ``deriving`` clauses.
 
-#. When a type that is not syntactically equivalent to ``a``, but which does
-   contain ``a``, is encountered, :ghc-flag:`-XDeriveFunctor` recursively calls
-   ``fmap`` on it. Similarly, :ghc-flag:`-XDeriveFoldable` would recursively call
-   ``foldr`` and ``foldMap``.
+With :ghc-flag:`-XDeriveAnyClass` you can derive any other class. The compiler
+will simply generate an instance declaration with no explicitly-defined
+methods.
+This is
+mostly useful in classes whose `minimal set <#minimal-pragma>`__ is
+empty, and especially when writing
+`generic functions <#generic-programming>`__.
 
-#. When a type that does not mention ``a`` is encountered, :ghc-flag:`-XDeriveFunctor`
-   leaves it alone. On the other hand, :ghc-flag:`-XDeriveFoldable` would generate
-   ``z`` (the state value) for ``foldr`` and ``mempty`` for ``foldMap``.
+As an example, consider a simple pretty-printer class ``SPretty``, which outputs
+pretty strings: ::
 
-#. :ghc-flag:`-XDeriveFunctor` puts everything back together again at the end by
-   invoking the constructor. :ghc-flag:`-XDeriveFoldable`, however, builds up a value
-   of some type. For ``foldr``, this is accomplished by chaining applications
-   of ``f`` and recursive ``foldr`` calls on the state value ``z``. For
-   ``foldMap``, this happens by combining all values with ``mappend``.
+    {-# LANGUAGE DefaultSignatures, DeriveAnyClass #-}
 
-There are some other differences regarding what data types can have derived
-``Foldable`` instances:
+    class SPretty a where
+      sPpr :: a -> String
+      default sPpr :: Show a => a -> String
+      sPpr = show
 
-#. Data types containing function types on the right-hand side cannot have
-   derived ``Foldable`` instances.
+If a user does not provide a manual implementation for ``sPpr``, then it will
+default to ``show``. Now we can leverage the :ghc-flag:`-XDeriveAnyClass` extension to
+easily implement a ``SPretty`` instance for a new data type: ::
 
-#. ``Foldable`` instances can be derived for data types in which the last type
-   parameter is existentially constrained or refined in a GADT. For example,
-   this data type::
+    data Foo = Foo deriving (Show, SPretty)
 
-       data E a where
-           E1 :: (a ~ Int) => a   -> E a
-           E2 ::              Int -> E Int
-           E3 :: (a ~ Int) => a   -> E Int
-           E4 :: (a ~ Int) => Int -> E a
+The above code is equivalent to: ::
 
-       deriving instance Foldable E
+    data Foo = Foo deriving Show
+    instance SPretty Foo
 
-   would have the following generated ``Foldable`` instance::
+That is, an ``SPretty Foo`` instance will be created with empty implementations
+for all methods. Since we are using :ghc-flag:`-XDefaultSignatures` in this example, a
+default implementation of ``sPpr`` is filled in automatically.
 
-       instance Foldable E where
-           foldr f z (E1 e) = f e z
-           foldr f z (E2 e) = z
-           foldr f z (E3 e) = z
-           foldr f z (E4 e) = z
+Note the following details
 
-           foldMap f (E1 e) = f e
-           foldMap f (E2 e) = mempty
-           foldMap f (E3 e) = mempty
-           foldMap f (E4 e) = mempty
+- In case you try to derive some
+  class on a newtype, and :ghc-flag:`-XGeneralizedNewtypeDeriving` is also on,
+  :ghc-flag:`-XDeriveAnyClass` takes precedence.
 
-   Notice how every constructor of ``E`` utilizes some sort of existential
-   quantification, but only the argument of ``E1`` is actually "folded over".
-   This is because we make a deliberate choice to only fold over universally
-   polymorphic types that are syntactically equivalent to the last type
-   parameter. In particular:
+- :ghc-flag:`-XDeriveAnyClass` is allowed only when the last argument of the class
+  has kind ``*`` or ``(* -> *)``.  So this is not allowed: ::
 
-  -  We don't fold over the arguments of ``E1`` or ``E4`` beacause even though
-     ``(a ~ Int)``, ``Int`` is not syntactically equivalent to ``a``.
+    data T a b = MkT a b deriving( Bifunctor )
 
-  -  We don't fold over the argument of ``E3`` because ``a`` is not universally
-     polymorphic. The ``a`` in ``E3`` is (implicitly) existentially quantified,
-     so it is not the same as the last type parameter of ``E``.
+  because the last argument of ``Bifunctor :: (* -> * -> *) -> Constraint``
+  has the wrong kind.
 
-.. _deriving-traversable:
+- The instance context will be generated according to the same rules
+  used when deriving ``Eq`` (if the kind of the type is ``*``), or
+  the rules for ``Functor`` (if the kind of the type is ``(* -> *)``).
+  For example ::
 
-Deriving ``Traversable`` instances
-----------------------------------
+    instance C a => C (a,b) where ...
 
-With :ghc-flag:`-XDeriveTraversable`, one can derive ``Traversable`` instances for data
-types of kind ``* -> *``. For example, this declaration::
+    data T a b = MkT a (a,b) deriving( C )
 
-    data Example a = Ex a Char (Example a) (Example Char)
-      deriving (Functor, Foldable, Traversable)
+  The ``deriving`` clause will generate ::
 
-would generate the following ``Traversable`` instance::
+    instance C a => C (T a b) where {}
 
-    instance Traversable Example where
-      traverse f (Ex a1 a2 a3 a4)
-        = fmap Ex (f a1) <*> traverse f a3
+  The constraints `C a` and `C (a,b)` are generated from the data
+  constructor arguments, but the latter simplifies to `C a`.
 
-The algorithm for :ghc-flag:`-XDeriveTraversable` is adapted from the
-:ghc-flag:`-XDeriveFunctor` algorithm, but it generates a definition for ``traverse``
-instead of ``fmap``. Here are the differences between the generated code in
-each extension:
+- :ghc-flag:`-XDeriveAnyClass` can be used with partially applied classes,
+  such as ::
 
-#. When a bare type variable ``a`` is encountered, both :ghc-flag:`-XDeriveFunctor` and
-   :ghc-flag:`-XDeriveTraversable` would generate ``f a`` for an ``fmap`` and
-   ``traverse`` definition, respectively.
+    data T a = MKT a deriving( D Int )
 
-#. When a type that is not syntactically equivalent to ``a``, but which does
-   contain ``a``, is encountered, :ghc-flag:`-XDeriveFunctor` recursively calls
-   ``fmap`` on it. Similarly, :ghc-flag:`-XDeriveTraversable` would recursively call
-   ``traverse``.
+  which generates ::
 
-#. When a type that does not mention ``a`` is encountered, :ghc-flag:`-XDeriveFunctor`
-   leaves it alone. On the other hand, :ghc-flag:`-XDeriveTraversable` would call
-   ``pure`` on the value of that type.
+    instance D Int a => D Int (T a) where {}
 
-#. :ghc-flag:`-XDeriveFunctor` puts everything back together again at the end by
-   invoking the constructor. :ghc-flag:`-XDeriveTraversable` does something similar,
-   but it works in an ``Applicative`` context by chaining everything together
-   with ``(<*>)``.
+- :ghc-flag:`-XDeriveAnyClass` can be used to fill in default instances for
+  associated type families: ::
 
-Unlike :ghc-flag:`-XDeriveFunctor`, :ghc-flag:`-XDeriveTraversable` cannot be used on data
-types containing a function type on the right-hand side.
+    {-# LANGUAGE DeriveAnyClass, TypeFamilies #-}
 
-For a full specification of the algorithms used in :ghc-flag:`-XDeriveFunctor`,
-:ghc-flag:`-XDeriveFoldable`, and :ghc-flag:`-XDeriveTraversable`, see
-:ghc-wiki:`this wiki page <Commentary/Compiler/DeriveFunctor>`.
+    class Sizable a where
+      type Size a
+      type Size a = Int
 
-.. _deriving-typeable:
+    data Bar = Bar deriving Sizable
 
-Deriving ``Typeable`` instances
--------------------------------
+    doubleBarSize :: Size Bar -> Size Bar
+    doubleBarSize s = 2*s
 
-.. ghc-flag:: -XDeriveDataTypeable
+  The ``deriving( Sizable )`` is equivalent to saying ::
 
-    Enable automatic deriving of instances for the ``Typeable`` typeclass
+    instance Sizeable Bar where {}
 
-The class ``Typeable`` is very special:
+  and then the normal rules for filling in associated types from the
+  default will apply, making ``Size Bar`` equal to ``Int``.
 
--  ``Typeable`` is kind-polymorphic (see :ref:`kind-polymorphism`).
+.. _pattern-synonyms:
 
--  GHC has a custom solver for discharging constraints that involve
-   class ``Typeable``, and handwritten instances are forbidden. This
-   ensures that the programmer cannot subvert the type system by writing
-   bogus instances.
+Pattern synonyms
+================
 
--  Derived instances of ``Typeable`` are ignored, and may be reported as
-   an error in a later version of the compiler.
+.. ghc-flag:: -XPatternSynonyms
 
--  The rules for solving \`Typeable\` constraints are as follows:
+    :since: 7.8.1
 
-   -  A concrete type constructor applied to some types. ::
+    Allow the definition of pattern synonyms.
 
-          instance (Typeable t1, .., Typeable t_n) =>
-            Typeable (T t1 .. t_n)
+Pattern synonyms are enabled by the flag :ghc-flag:`-XPatternSynonyms`, which is
+required for defining them, but *not* for using them. More information
+and examples of view patterns can be found on the
+`Wiki page <PatternSynonyms>`.
 
-      This rule works for any concrete type constructor, including type
-      constructors with polymorphic kinds. The only restriction is that
-      if the type constructor has a polymorphic kind, then it has to be
-      applied to all of its kinds parameters, and these kinds need to be
-      concrete (i.e., they cannot mention kind variables).
+Pattern synonyms enable giving names to parametrized pattern schemes.
+They can also be thought of as abstract constructors that don't have a
+bearing on data representation. For example, in a programming language
+implementation, we might represent types of the language as follows: ::
 
-   -  ::
+    data Type = App String [Type]
 
-          A type variable applied to some types.
-          instance (Typeable f, Typeable t1, .., Typeable t_n) =>
-            Typeable (f t1 .. t_n)
+Here are some examples of using said representation. Consider a few
+types of the ``Type`` universe encoded like this: ::
 
-   -  ::
+      App "->" [t1, t2]          -- t1 -> t2
+      App "Int" []               -- Int
+      App "Maybe" [App "Int" []] -- Maybe Int
 
-          A concrete type literal.
-          instance Typeable 0       -- Type natural literals
-          instance Typeable "Hello" -- Type-level symbols
+This representation is very generic in that no types are given special
+treatment. However, some functions might need to handle some known types
+specially, for example the following two functions collect all argument
+types of (nested) arrow types, and recognize the ``Int`` type,
+respectively: ::
 
-.. _deriving-lift:
+      collectArgs :: Type -> [Type]
+      collectArgs (App "->" [t1, t2]) = t1 : collectArgs t2
+      collectArgs _                   = []
 
-Deriving ``Lift`` instances
----------------------------
+      isInt :: Type -> Bool
+      isInt (App "Int" []) = True
+      isInt _              = False
 
-.. ghc-flag:: -XDeriveLift
+Matching on ``App`` directly is both hard to read and error prone to
+write. And the situation is even worse when the matching is nested: ::
 
-    :since: 8.0.1
+      isIntEndo :: Type -> Bool
+      isIntEndo (App "->" [App "Int" [], App "Int" []]) = True
+      isIntEndo _                                       = False
 
-    Enable automatic deriving of instances for the ``Lift`` typeclass for
-    Template Haskell.
+Pattern synonyms permit abstracting from the representation to expose
+matchers that behave in a constructor-like manner with respect to
+pattern matching. We can create pattern synonyms for the known types we
+care about, without committing the representation to them (note that
+these don't have to be defined in the same module as the ``Type`` type): ::
 
-The class ``Lift``, unlike other derivable classes, lives in
-``template-haskell`` instead of ``base``. Having a data type be an instance of
-``Lift`` permits its values to be promoted to Template Haskell expressions (of
-type ``ExpQ``), which can then be spliced into Haskell source code.
+      pattern Arrow t1 t2 = App "->"    [t1, t2]
+      pattern Int         = App "Int"   []
+      pattern Maybe t     = App "Maybe" [t]
 
-Here is an example of how one can derive ``Lift``:
+Which enables us to rewrite our functions in a much cleaner style: ::
 
-::
+      collectArgs :: Type -> [Type]
+      collectArgs (Arrow t1 t2) = t1 : collectArgs t2
+      collectArgs _             = []
 
-    {-# LANGUAGE DeriveLift #-}
-    module Bar where
+      isInt :: Type -> Bool
+      isInt Int = True
+      isInt _   = False
 
-    import Language.Haskell.TH.Syntax
+      isIntEndo :: Type -> Bool
+      isIntEndo (Arrow Int Int) = True
+      isIntEndo _               = False
 
-    data Foo a = Foo a | a :^: a deriving Lift
+In general there are three kinds of pattern synonyms. Unidirectional,
+bidirectional and explicitly bidirectional. The examples given so far are
+examples of bidirectional pattern synonyms. A bidirectional synonym
+behaves the same as an ordinary data constructor. We can use it in a pattern
+context to deconstruct values and in an expression context to construct values.
+For example, we can construct the value `intEndo` using the pattern synonyms
+`Arrow` and `Int` as defined previously. ::
 
-    {-
-    instance (Lift a) => Lift (Foo a) where
-        lift (Foo a)
-        = appE
-            (conE
-                (mkNameG_d "package-name" "Bar" "Foo"))
-            (lift a)
-        lift (u :^: v)
-        = infixApp
-            (lift u)
-            (conE
-                (mkNameG_d "package-name" "Bar" ":^:"))
-            (lift v)
-    -}
+      intEndo :: Type
+      intEndo = Arrow Int Int
 
-    -----
-    {-# LANGUAGE TemplateHaskell #-}
-    module Baz where
+This example is equivalent to the much more complicated construction if we had
+directly used the `Type` constructors. ::
 
-    import Bar
-    import Language.Haskell.TH.Lift
+      intEndo :: Type
+      intEndo = App "->" [App "Int" [], App "Int" []]
 
-    foo :: Foo String
-    foo = $(lift $ Foo "foo")
 
-    fooExp :: Lift a => Foo a -> Q Exp
-    fooExp f = [| f |]
+Unidirectional synonyms can only be used in a pattern context and are
+defined as follows:
 
-:ghc-flag:`-XDeriveLift` also works for certain unboxed types (``Addr#``, ``Char#``,
-``Double#``, ``Float#``, ``Int#``, and ``Word#``):
 
 ::
 
-    {-# LANGUAGE DeriveLift, MagicHash #-}
-    module Unboxed where
+      pattern Head x <- x:xs
 
-    import GHC.Exts
-    import Language.Haskell.TH.Syntax
+In this case, ``Head`` ⟨x⟩ cannot be used in expressions, only patterns,
+since it wouldn't specify a value for the ⟨xs⟩ on the right-hand side. However,
+we can define an explicitly bidirectional pattern synonym by separately
+specifying how to construct and deconstruct a type. The syntax for
+doing this is as follows:
 
-    data IntHash = IntHash Int# deriving Lift
+::
 
-    {-
-    instance Lift IntHash where
-        lift (IntHash i)
-        = appE
-            (conE
-                (mkNameG_d "package-name" "Unboxed" "IntHash"))
-            (litE
-                (intPrimL (toInteger (I# i))))
-    -}
+      pattern HeadC x <- x:xs where
+        HeadC x = [x]
 
+We can then use ``HeadC`` in both expression and pattern contexts. In a pattern
+context it will match the head of any list with length at least one. In an
+expression context it will construct a singleton list.
 
-.. _newtype-deriving:
+The table below summarises where each kind of pattern synonym can be used.
 
-Generalised derived instances for newtypes
-------------------------------------------
++---------------+----------------+---------------+---------------------------+
+| Context       | Unidirectional | Bidirectional | Explicitly Bidirectional  |
++===============+================+===============+===========================+
+| Pattern       | Yes            | Yes           | Yes                       |
++---------------+----------------+---------------+---------------------------+
+| Expression    | No             | Yes (Inferred)| Yes (Explicit)            |
++---------------+----------------+---------------+---------------------------+
 
-.. ghc-flag:: -XGeneralisedNewtypeDeriving
-              -XGeneralizedNewtypeDeriving
+.. _record-patsyn:
 
-    Enable GHC's cunning generalised deriving mechanism for ``newtype``\s
+Record Pattern Synonyms
+-----------------------
 
-When you define an abstract type using ``newtype``, you may want the new
-type to inherit some instances from its representation. In Haskell 98,
-you can inherit instances of ``Eq``, ``Ord``, ``Enum`` and ``Bounded``
-by deriving them, but for any other classes you have to write an
-explicit instance declaration. For example, if you define ::
+It is also possible to define pattern synonyms which behave just like record
+constructors. The syntax for doing this is as follows:
 
-      newtype Dollars = Dollars Int
+::
 
-and you want to use arithmetic on ``Dollars``, you have to explicitly
-define an instance of ``Num``: ::
+      pattern Point :: (Int, Int)
+      pattern Point{x, y} = (x, y)
 
-      instance Num Dollars where
-        Dollars a + Dollars b = Dollars (a+b)
-        ...
+The idea is that we can then use ``Point`` just as if we had defined a new
+datatype ``MyPoint`` with two fields ``x`` and ``y``.
 
-All the instance does is apply and remove the ``newtype`` constructor.
-It is particularly galling that, since the constructor doesn't appear at
-run-time, this instance declaration defines a dictionary which is
-*wholly equivalent* to the ``Int`` dictionary, only slower!
+::
 
-.. _generalized-newtype-deriving:
+    data MyPoint = Point { x :: Int, y :: Int }
 
-Generalising the deriving clause
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Whilst a normal pattern synonym can be used in two ways, there are then seven
+ways in which to use ``Point``. Precisely the ways in which a normal record
+constructor can be used.
 
-GHC now permits such instances to be derived instead, using the flag
-:ghc-flag:`-XGeneralizedNewtypeDeriving`, so one can write ::
+=======================================   ==================================
+Usage                                     Example
+=======================================   ==================================
+As a constructor                          ``zero = Point 0 0``
+As a constructor with record syntax       ``zero = Point { x = 0, y = 0}``
+In a pattern context                      ``isZero (Point 0 0) = True``
+In a pattern context with record syntax   ``isZero (Point { x = 0, y = 0 }``
+In a pattern context with field puns      ``getX (Point {x}) = x``
+In a record update                        ``(0, 0) { x = 1 } == (1,0)``
+Using record selectors                    ``x (0,0) == 0``
+=======================================   ==================================
 
-      newtype Dollars = Dollars Int deriving (Eq,Show,Num)
+For a unidirectional record pattern synonym we define record selectors but do
+not allow record updates or construction.
 
-and the implementation uses the *same* ``Num`` dictionary for
-``Dollars`` as for ``Int``. Notionally, the compiler derives an instance
-declaration of the form ::
+The syntax and semantics of pattern synonyms are elaborated in the
+following subsections. See the :ghc-wiki:`Wiki page <PatternSynonyms>` for more
+details.
 
-      instance Num Int => Num Dollars
+Syntax and scoping of pattern synonyms
+--------------------------------------
 
-which just adds or removes the ``newtype`` constructor according to the
-type.
+A pattern synonym declaration can be either unidirectional,
+bidirectional or explicitly bidirectional.
+The syntax for unidirectional pattern synonyms is: ::
 
-We can also derive instances of constructor classes in a similar way.
-For example, suppose we have implemented state and failure monad
-transformers, such that ::
+      pattern pat_lhs <- pat
 
-      instance Monad m => Monad (State s m)
-      instance Monad m => Monad (Failure m)
+the syntax for bidirectional pattern synonyms is: ::
 
-In Haskell 98, we can define a parsing monad by ::
+      pattern pat_lhs = pat
 
-      type Parser tok m a = State [tok] (Failure m) a
+and the syntax for explicitly bidirectional pattern synonyms is: ::
+
+      pattern pat_lhs <- pat where
+        pat_lhs = expr
 
-which is automatically a monad thanks to the instance declarations
-above. With the extension, we can make the parser type abstract, without
-needing to write an instance of class ``Monad``, via ::
+We can define either prefix, infix or record pattern synonyms by modifying
+the form of `pat_lhs`. The syntax for these is as follows:
 
-      newtype Parser tok m a = Parser (State [tok] (Failure m) a)
-                             deriving Monad
+======= ============================
+Prefix  ``Name args``
+------- ----------------------------
+Infix   ``arg1 `Name` arg2``
+        or ``arg1 op arg2``
+------- ----------------------------
+Record  ``Name{arg1,arg2,...,argn}``
+======= ============================
 
-In this case the derived instance declaration is of the form ::
 
-      instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
+Pattern synonym declarations can only occur in the top level of a
+module. In particular, they are not allowed as local definitions.
 
-Notice that, since ``Monad`` is a constructor class, the instance is a
-*partial application* of the new type, not the entire left hand side. We
-can imagine that the type declaration is "eta-converted" to generate the
-context of the instance declaration.
+The variables in the left-hand side of the definition are bound by the
+pattern on the right-hand side. For bidirectional pattern
+synonyms, all the variables of the right-hand side must also occur on
+the left-hand side; also, wildcard patterns and view patterns are not
+allowed. For unidirectional and explicitly bidirectional pattern
+synonyms, there is no restriction on the right-hand side pattern.
 
-We can even derive instances of multi-parameter classes, provided the
-newtype is the last class parameter. In this case, a "partial
-application" of the class appears in the ``deriving`` clause. For
-example, given the class ::
+Pattern synonyms cannot be defined recursively.
 
-      class StateMonad s m | m -> s where ...
-      instance Monad m => StateMonad s (State s m) where ...
+.. _patsyn-impexp:
 
-then we can derive an instance of ``StateMonad`` for ``Parser`` by ::
+Import and export of pattern synonyms
+-------------------------------------
 
-      newtype Parser tok m a = Parser (State [tok] (Failure m) a)
-                             deriving (Monad, StateMonad [tok])
+The name of the pattern synonym is in the same namespace as proper data
+constructors. Like normal data constructors, pattern synonyms can be imported
+and exported through association with a type constructor or independently.
 
-The derived instance is obtained by completing the application of the
-class to the new type: ::
+To export them on their own, in an export or import specification, you must
+prefix pattern names with the ``pattern`` keyword, e.g.: ::
 
-      instance StateMonad [tok] (State [tok] (Failure m)) =>
-               StateMonad [tok] (Parser tok m)
+      module Example (pattern Zero) where
 
-As a result of this extension, all derived instances in newtype
-declarations are treated uniformly (and implemented just by reusing the
-dictionary for the representation type), *except* ``Show`` and ``Read``,
-which really behave differently for the newtype and its representation.
+      data MyNum = MkNum Int
 
-A more precise specification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      pattern Zero :: MyNum
+      pattern Zero = MkNum 0
 
-A derived instance is derived only for declarations of these forms
-(after expansion of any type synonyms) ::
+Without the ``pattern`` prefix, ``Zero`` would be interpreted as a
+type constructor in the export list.
 
-      newtype T v1..vn                   = MkT (t vk+1..vn) deriving (C t1..tj)
-      newtype instance T s1..sk vk+1..vn = MkT (t vk+1..vn) deriving (C t1..tj)
+You may also use the ``pattern`` keyword in an import/export
+specification to import or export an ordinary data constructor. For
+example: ::
 
-where
+      import Data.Maybe( pattern Just )
 
--  ``v1..vn`` are type variables, and ``t``, ``s1..sk``, ``t1..tj`` are
-   types.
+would bring into scope the data constructor ``Just`` from the ``Maybe``
+type, without also bringing the type constructor ``Maybe`` into scope.
 
--  The ``(C t1..tj)`` is a partial applications of the class ``C``,
-   where the arity of ``C`` is exactly ``j+1``. That is, ``C`` lacks
-   exactly one type argument.
+To bundle a pattern synonym with a type constructor, we list the pattern
+synonym in the export list of a module which exports the type constructor.
+For example, to bundle ``Zero`` with ``MyNum`` we could write the following: ::
 
--  ``k`` is chosen so that ``C t1..tj (T v1...vk)`` is well-kinded. (Or,
-   in the case of a ``data instance``, so that ``C t1..tj (T s1..sk)``
-   is well kinded.)
+      module Example ( MyNum(Zero) ) where
 
--  The type ``t`` is an arbitrary type.
+If a module was then to import ``MyNum`` from ``Example``, it would also import
+the pattern synonym ``Zero``.
 
--  The type variables ``vk+1...vn`` do not occur in the types ``t``,
-   ``s1..sk``, or ``t1..tj``.
+It is also possible to use the special token ``..`` in an export list to mean
+all currently bundled constructors. For example, we could write: ::
 
--  ``C`` is not ``Read``, ``Show``, ``Typeable``, or ``Data``. These
-   classes should not "look through" the type or its constructor. You
-   can still derive these classes for a newtype, but it happens in the
-   usual way, not via this new mechanism.
+      module Example ( MyNum(.., Zero) ) where
 
--  It is safe to coerce each of the methods of ``C``. That is, the
-   missing last argument to ``C`` is not used at a nominal role in any
-   of the ``C``'s methods. (See :ref:`roles`.)
+in which case, ``Example`` would export the type constructor ``MyNum`` with
+the data constructor ``MkNum`` and also the pattern synonym ``Zero``.
 
-Then the derived instance declaration is of the form ::
+Bundled patterns synoyms are type checked to ensure that they are of the same
+type as the type constructor which they are bundled with. A pattern synonym
+``P`` can not be bundled with a type constructor ``T`` if ``P``\'s type is visibly
+incompatible with ``T``.
 
-      instance C t1..tj t => C t1..tj (T v1...vk)
+A module which imports ``MyNum(..)`` from ``Example`` and then re-exports
+``MyNum(..)`` will also export any pattern synonyms bundled with ``MyNum`` in
+``Example``. A more complete specification can be found on the
+:ghc-wiki:`wiki. <PatternSynonyms/AssociatingSynonyms>`
 
-As an example which does *not* work, consider ::
+Typing of pattern synonyms
+--------------------------
 
-      newtype NonMonad m s = NonMonad (State s m s) deriving Monad
+Given a pattern synonym definition of the form ::
 
-Here we cannot derive the instance ::
+      pattern P var1 var2 ... varN <- pat
 
-      instance Monad (State s m) => Monad (NonMonad m)
+it is assigned a *pattern type* of the form ::
 
-because the type variable ``s`` occurs in ``State s m``, and so cannot
-be "eta-converted" away. It is a good thing that this ``deriving``
-clause is rejected, because ``NonMonad m`` is not, in fact, a monad ---
-for the same reason. Try defining ``>>=`` with the correct type: you
-won't be able to.
+      pattern P :: CReq => CProv => t1 -> t2 -> ... -> tN -> t
 
-Notice also that the *order* of class parameters becomes important,
-since we can only derive instances for the last one. If the
-``StateMonad`` class above were instead defined as ::
+where ⟨CProv⟩ and ⟨CReq⟩ are type contexts, and ⟨t1⟩, ⟨t2⟩, ..., ⟨tN⟩
+and ⟨t⟩ are types. Notice the unusual form of the type, with two
+contexts ⟨CProv⟩ and ⟨CReq⟩:
 
-      class StateMonad m s | m -> s where ...
+-  ⟨CProv⟩ are the constraints *made available (provided)* by a
+   successful pattern match.
 
-then we would not have been able to derive an instance for the
-``Parser`` type above. We hypothesise that multi-parameter classes
-usually have one "main" parameter for which deriving new instances is
-most interesting.
+-  ⟨CReq⟩ are the constraints *required* to match the pattern.
 
-Lastly, all of this applies only for classes other than ``Read``,
-``Show``, ``Typeable``, and ``Data``, for which the built-in derivation
-applies (section 4.3.3. of the Haskell Report). (For the standard
-classes ``Eq``, ``Ord``, ``Ix``, and ``Bounded`` it is immaterial
-whether the standard method is used or the one described here.)
+For example, consider ::
 
-.. _derive-any-class:
+    data T a where
+      MkT :: (Show b) => a -> b -> T a
 
-Deriving any other class
-------------------------
+    f1 :: (Eq a, Num a) => T a -> String
+    f1 (MkT 42 x) = show x
 
-.. ghc-flag:: -XDeriveAnyClass
+    pattern ExNumPat :: (Num a, Eq a) => (Show b) => b -> T a
+    pattern ExNumPat x = MkT 42 x
 
-    :since: 7.10.1
+    f2 :: (Eq a, Num a) => T a -> String
+    f2 (ExNumPat x) = show x
 
-    Allow use of any typeclass in ``deriving`` clauses.
+Here ``f1`` does not use pattern synonyms. To match against the numeric
+pattern ``42`` *requires* the caller to satisfy the constraints
+``(Num a, Eq a)``, so they appear in ``f1``'s type. The call to ``show``
+generates a ``(Show b)`` constraint, where ``b`` is an existentially
+type variable bound by the pattern match on ``MkT``. But the same
+pattern match also *provides* the constraint ``(Show b)`` (see ``MkT``'s
+type), and so all is well.
 
-With :ghc-flag:`-XDeriveAnyClass` you can derive any other class. The compiler
-will simply generate an instance declaration with no explicitly-defined
-methods.
-This is
-mostly useful in classes whose `minimal set <#minimal-pragma>`__ is
-empty, and especially when writing
-`generic functions <#generic-programming>`__.
+Exactly the same reasoning applies to ``ExNumPat``: matching against
+``ExNumPat`` *requires* the constraints ``(Num a, Eq a)``, and
+*provides* the constraint ``(Show b)``.
 
-As an example, consider a simple pretty-printer class ``SPretty``, which outputs
-pretty strings: ::
+Note also the following points
 
-    {-# LANGUAGE DefaultSignatures, DeriveAnyClass #-}
+-  In the common case where ``Prov`` is empty, ``()``, it can be omitted
+   altogether.
 
-    class SPretty a where
-      sPpr :: a -> String
-      default sPpr :: Show a => a -> String
-      sPpr = show
+-  You may specify an explicit *pattern signature*, as we did for
+   ``ExNumPat`` above, to specify the type of a pattern, just as you can
+   for a function. As usual, the type signature can be less polymorphic
+   than the inferred type. For example
 
-If a user does not provide a manual implementation for ``sPpr``, then it will
-default to ``show``. Now we can leverage the :ghc-flag:`-XDeriveAnyClass` extension to
-easily implement a ``SPretty`` instance for a new data type: ::
+   ::
 
-    data Foo = Foo deriving (Show, SPretty)
+         -- Inferred type would be 'a -> [a]'
+         pattern SinglePair :: (a, a) -> [(a, a)]
+         pattern SinglePair x = [x]
 
-The above code is equivalent to: ::
+-  The GHCi :ghci-cmd:`:info` command shows pattern types in this format.
 
-    data Foo = Foo deriving Show
-    instance SPretty Foo
+-  For a bidirectional pattern synonym, a use of the pattern synonym as
+   an expression has the type
 
-That is, an ``SPretty Foo`` instance will be created with empty implementations
-for all methods. Since we are using :ghc-flag:`-XDefaultSignatures` in this example, a
-default implementation of ``sPpr`` is filled in automatically.
+   ::
 
-Note the following details
+         (CReq, CProv) => t1 -> t2 -> ... -> tN -> t
 
-- In case you try to derive some
-  class on a newtype, and :ghc-flag:`-XGeneralizedNewtypeDeriving` is also on,
-  :ghc-flag:`-XDeriveAnyClass` takes precedence.
+   So in the previous example, when used in an expression, ``ExNumPat``
+   has type
 
-- :ghc-flag:`-XDeriveAnyClass` is allowed only when the last argument of the class
-  has kind ``*`` or ``(* -> *)``.  So this is not allowed: ::
+   ::
 
-    data T a b = MkT a b deriving( Bifunctor )
+         ExNumPat :: (Num a, Eq a, Show b) => b -> T t
 
-  because the last argument of ``Bifunctor :: (* -> * -> *) -> Constraint``
-  has the wrong kind.
+   Notice that this is a tiny bit more restrictive than the expression
+   ``MkT 42 x`` which would not require ``(Eq a)``.
 
-- The instance context will be generated according to the same rules
-  used when deriving ``Eq`` (if the kind of the type is ``*``), or
-  the rules for ``Functor`` (if the kind of the type is ``(* -> *)``).
-  For example ::
+-  Consider these two pattern synonyms: ::
 
-    instance C a => C (a,b) where ...
+       data S a where
+          S1 :: Bool -> S Bool
 
-    data T a b = MkT a (a,b) deriving( C )
+       pattern P1 :: Bool -> Maybe Bool
+       pattern P1 b = Just b
 
-  The ``deriving`` clause will generate ::
+       pattern P2 :: () => (b ~ Bool) => Bool -> S b
+       pattern P2 b = S1 b
 
-    instance C a => C (T a b) where {}
+       f :: Maybe a -> String
+       f (P1 x) = "no no no"     -- Type-incorrect
 
-  The constraints `C a` and `C (a,b)` are generated from the data
-  constructor arguments, but the latter simplifies to `C a`.
+       g :: S a -> String
+       g (P2 b) = "yes yes yes"  -- Fine
 
-- :ghc-flag:`-XDeriveAnyClass` can be used with partially applied classes,
-  such as ::
+   Pattern ``P1`` can only match against a value of type ``Maybe Bool``,
+   so function ``f`` is rejected because the type signature is
+   ``Maybe a``. (To see this, imagine expanding the pattern synonym.)
 
-    data T a = MKT a deriving( D Int )
+   On the other hand, function ``g`` works fine, because matching
+   against ``P2`` (which wraps the GADT ``S``) provides the local
+   equality ``(a~Bool)``. If you were to give an explicit pattern
+   signature ``P2 :: Bool -> S Bool``, then ``P2`` would become less
+   polymorphic, and would behave exactly like ``P1`` so that ``g`` would
+   then be rejected.
 
-  which generates ::
+   In short, if you want GADT-like behaviour for pattern synonyms, then
+   (unlike unlike concrete data constructors like ``S1``) you must write
+   its type with explicit provided equalities. For a concrete data
+   constructor like ``S1`` you can write its type signature as either
+   ``S1 :: Bool -> S Bool`` or ``S1 :: (b~Bool) => Bool -> S b``; the
+   two are equivalent. Not so for pattern synonyms: the two forms are
+   different, in order to distinguish the two cases above. (See
+   :ghc-ticket:`9953` for discussion of this choice.)
 
-    instance D Int a => D Int (T a) where {}
+Matching of pattern synonyms
+----------------------------
 
-- :ghc-flag:`-XDeriveAnyClass` can be used to fill in default instances for
-  associated type families: ::
+A pattern synonym occurrence in a pattern is evaluated by first matching
+against the pattern synonym itself, and then on the argument patterns.
+For example, in the following program, ``f`` and ``f'`` are equivalent: ::
 
-    {-# LANGUAGE DeriveAnyClass, TypeFamilies #-}
+    pattern Pair x y <- [x, y]
 
-    class Sizable a where
-      type Size a
-      type Size a = Int
+    f (Pair True True) = True
+    f _                = False
 
-    data Bar = Bar deriving Sizable
+    f' [x, y] | True <- x, True <- y = True
+    f' _                              = False
 
-    doubleBarSize :: Size Bar -> Size Bar
-    doubleBarSize s = 2*s
+Note that the strictness of ``f`` differs from that of ``g`` defined
+below:
 
-  The ``deriving( Sizable )`` is equivalent to saying ::
+.. code-block:: none
 
-    instance Sizeable Bar where {}
+    g [True, True] = True
+    g _            = False
 
-  and then the normal rules for filling in associated types from the
-  default will apply, making ``Size Bar`` equal to ``Int``.
+    *Main> f (False:undefined)
+    *** Exception: Prelude.undefined
+    *Main> g (False:undefined)
+    False
 
 .. _type-class-extensions:
 
@@ -7544,10 +7544,13 @@ the type level:
     GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8))
     3
 
+Constraints in types
+====================
+
 .. _equality-constraints:
 
 Equality constraints
-====================
+--------------------
 
 A type context can include equality constraints of the form ``t1 ~ t2``,
 which denote that the types ``t1`` and ``t2`` need to be the same. In
@@ -7597,7 +7600,7 @@ the paper
 .. _constraint-kind:
 
 The ``Constraint`` kind
-=======================
+-----------------------
 
 .. ghc-flag:: -XConstraintKinds
 
@@ -7673,10 +7676,10 @@ contexts and superclasses, but to do so you must use
 :ghc-flag:`-XUndecidableInstances` to signal that you don't mind if the type
 checker fails to terminate.
 
-.. _other-type-extensions:
+.. _extensions-to-type-signatures:
 
-Other type system extensions
-============================
+Extensions to type signatures
+=============================
 
 .. _explicit-foralls:
 
@@ -7698,18 +7701,26 @@ means this: ::
 
     g :: forall b. (b -> b)
 
-The two are treated identically.
+The two are treated identically, except that the latter may bring type variables
+into scope (see :ref:`scoped-type-variables`).
+
+Notes:
+
+- With :ghc-flag:`-XExplicitForAll`, ``forall`` becomes a keyword; you can't use ``forall`` as a
+  type variable any more!
 
-Of course ``forall`` becomes a keyword; you can't use ``forall`` as a
-type variable any more!
+- As well in type signatures, you can also use an explicit ``forall``
+  in an instance declaration: ::
 
-If the :ghc-flag:`-Wunused-foralls` flag is enabled, a warning will be emitted
-when you write a type variable in an explicit ``forall`` statement that is
-otherwise unused. For instance: ::
+      instance forall a. Eq a => Eq [a] where ...
+
+- If the :ghc-flag:`-Wunused-foralls` flag is enabled, a warning will be emitted
+  when you write a type variable in an explicit ``forall`` statement that is
+  otherwise unused. For instance: ::
 
     g :: forall a b. (b -> b)
 
-would warn about the unused type variable `a`.
+  would warn about the unused type variable `a`.
 
 .. _flexible-contexts:
 
@@ -7763,283 +7774,83 @@ dependencies: ::
 
 The ``Int`` may well fix ``b`` at the call site, so that signature
 should not be rejected. Moreover, the dependencies might be hidden.
-Consider ::
-
-       class X a b where ...
-       class D a b | a -> b where ...
-       instance D a b => X [a] b where...
-       h :: X a b => a -> a
-
-Here ``h``\'s type looks ambiguous in ``b``, but here's a legal call: ::
-
-       ...(h [True])...
-
-That gives rise to a ``(X [Bool] beta)`` constraint, and using the
-instance means we need ``(D Bool beta)`` and that fixes ``beta`` via
-``D``\'s fundep!
-
-Behind all these special cases there is a simple guiding principle.
-Consider ::
-
-      f :: type
-      f = ...blah...
-
-      g :: type
-      g = f
-
-You would think that the definition of ``g`` would surely typecheck!
-After all ``f`` has exactly the same type, and ``g=f``. But in fact
-``f``\'s type is instantiated and the instantiated constraints are solved
-against the constraints bound by ``g``\ 's signature. So, in the case an
-ambiguous type, solving will fail. For example, consider the earlier
-definition ``f :: C a => Int``: ::
-
-      f :: C a => Int
-      f = ...blah...
-
-      g :: C a => Int
-      g = f
-
-In ``g``\'s definition, we'll instantiate to ``(C alpha)`` and try to
-deduce ``(C alpha)`` from ``(C a)``, and fail.
-
-So in fact we use this as our *definition* of ambiguity: a type ``ty``
-is ambiguous if and only if ``((undefined :: ty) :: ty)`` would fail to
-typecheck. We use a very similar test for *inferred* types, to ensure
-that they too are unambiguous.
-
-*Switching off the ambiguity check.* Even if a function is has an
-ambiguous type according the "guiding principle", it is possible that
-the function is callable. For example: ::
-
-      class D a b where ...
-      instance D Bool b where ...
-
-      strange :: D a b => a -> a
-      strange = ...blah...
-
-      foo = strange True
-
-Here ``strange``\'s type is ambiguous, but the call in ``foo`` is OK
-because it gives rise to a constraint ``(D Bool beta)``, which is
-soluble by the ``(D Bool b)`` instance. So the language extension
-:ghc-flag:`-XAllowAmbiguousTypes` allows you to switch off the ambiguity check.
-But even with ambiguity checking switched off, GHC will complain about a
-function that can *never* be called, such as this one: ::
-
-      f :: (Int ~ Bool) => a -> a
-
-.. note::
-    *A historical note.* GHC used to impose some more restrictive and less
-    principled conditions on type signatures. For type
-    ``forall tv1..tvn (c1, ...,cn) => type`` GHC used to require
-
-     a. that each universally quantified type variable ``tvi`` must be "reachable"
-        from ``type``, and
-
-     b. that every constraint ``ci`` mentions at least one of the universally
-        quantified type variables ``tvi``. These ad-hoc restrictions are
-        completely subsumed by the new ambiguity check.
-
-.. _implicit-parameters:
-
-Implicit parameters
--------------------
-
-.. ghc-flag:: -XImplicitParams
-
-    Allow definition of functions expecting implicit parameters.
-
-Implicit parameters are implemented as described in [Lewis2000]_ and enabled
-with the option :ghc-flag:`-XImplicitParams`. (Most of the following, still rather
-incomplete, documentation is due to Jeff Lewis.)
-
-.. [Lewis2000]
-    "Implicit parameters: dynamic scoping with static types",
-    J Lewis, MB Shields, E Meijer, J Launchbury,
-    *27th ACM Symposium on Principles of Programming Languages (POPL'00)*,
-    Boston, Jan 2000.
-
-A variable is called *dynamically bound* when it is bound by the calling
-context of a function and *statically bound* when bound by the callee's
-context. In Haskell, all variables are statically bound. Dynamic binding
-of variables is a notion that goes back to Lisp, but was later discarded
-in more modern incarnations, such as Scheme. Dynamic binding can be very
-confusing in an untyped language, and unfortunately, typed languages, in
-particular Hindley-Milner typed languages like Haskell, only support
-static scoping of variables.
-
-However, by a simple extension to the type class system of Haskell, we
-can support dynamic binding. Basically, we express the use of a
-dynamically bound variable as a constraint on the type. These
-constraints lead to types of the form ``(?x::t') => t``, which says
-"this function uses a dynamically-bound variable ``?x`` of type ``t'``".
-For example, the following expresses the type of a sort function,
-implicitly parameterised by a comparison function named ``cmp``. ::
-
-      sort :: (?cmp :: a -> a -> Bool) => [a] -> [a]
-
-The dynamic binding constraints are just a new form of predicate in the
-type class system.
-
-An implicit parameter occurs in an expression using the special form
-``?x``, where ``x`` is any valid identifier (e.g. ``ord ?x`` is a valid
-expression). Use of this construct also introduces a new dynamic-binding
-constraint in the type of the expression. For example, the following
-definition shows how we can define an implicitly parameterised sort
-function in terms of an explicitly parameterised ``sortBy`` function: ::
-
-      sortBy :: (a -> a -> Bool) -> [a] -> [a]
-
-      sort   :: (?cmp :: a -> a -> Bool) => [a] -> [a]
-      sort    = sortBy ?cmp
-
-Implicit-parameter type constraints
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Dynamic binding constraints behave just like other type class
-constraints in that they are automatically propagated. Thus, when a
-function is used, its implicit parameters are inherited by the function
-that called it. For example, our ``sort`` function might be used to pick
-out the least value in a list: ::
-
-      least   :: (?cmp :: a -> a -> Bool) => [a] -> a
-      least xs = head (sort xs)
-
-Without lifting a finger, the ``?cmp`` parameter is propagated to become
-a parameter of ``least`` as well. With explicit parameters, the default
-is that parameters must always be explicit propagated. With implicit
-parameters, the default is to always propagate them.
-
-An implicit-parameter type constraint differs from other type class
-constraints in the following way: All uses of a particular implicit
-parameter must have the same type. This means that the type of
-``(?x, ?x)`` is ``(?x::a) => (a,a)``, and not
-``(?x::a, ?x::b) => (a, b)``, as would be the case for type class
-constraints.
-
-You can't have an implicit parameter in the context of a class or
-instance declaration. For example, both these declarations are illegal: ::
-
-      class (?x::Int) => C a where ...
-      instance (?x::a) => Foo [a] where ...
-
-Reason: exactly which implicit parameter you pick up depends on exactly
-where you invoke a function. But the "invocation" of instance
-declarations is done behind the scenes by the compiler, so it's hard to
-figure out exactly where it is done. Easiest thing is to outlaw the
-offending types.
-
-Implicit-parameter constraints do not cause ambiguity. For example,
-consider: ::
-
-       f :: (?x :: [a]) => Int -> Int
-       f n = n + length ?x
-
-       g :: (Read a, Show a) => String -> String
-       g s = show (read s)
-
-Here, ``g`` has an ambiguous type, and is rejected, but ``f`` is fine.
-The binding for ``?x`` at ``f``\ 's call site is quite unambiguous, and
-fixes the type ``a``.
-
-Implicit-parameter bindings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-An implicit parameter is *bound* using the standard ``let`` or ``where``
-binding forms. For example, we define the ``min`` function by binding
-``cmp``. ::
-
-      min :: Ord a => [a] -> a
-      min  = let ?cmp = (<=) in least
-
-A group of implicit-parameter bindings may occur anywhere a normal group
-of Haskell bindings can occur, except at top level. That is, they can
-occur in a ``let`` (including in a list comprehension, or do-notation,
-or pattern guards), or a ``where`` clause. Note the following points:
-
--  An implicit-parameter binding group must be a collection of simple
-   bindings to implicit-style variables (no function-style bindings, and
-   no type signatures); these bindings are neither polymorphic or
-   recursive.
+Consider ::
 
--  You may not mix implicit-parameter bindings with ordinary bindings in
-   a single ``let`` expression; use two nested ``let``\ s instead. (In
-   the case of ``where`` you are stuck, since you can't nest ``where``
-   clauses.)
+       class X a b where ...
+       class D a b | a -> b where ...
+       instance D a b => X [a] b where...
+       h :: X a b => a -> a
 
--  You may put multiple implicit-parameter bindings in a single binding
-   group; but they are *not* treated as a mutually recursive group (as
-   ordinary ``let`` bindings are). Instead they are treated as a
-   non-recursive group, simultaneously binding all the implicit
-   parameter. The bindings are not nested, and may be re-ordered without
-   changing the meaning of the program. For example, consider: ::
+Here ``h``\'s type looks ambiguous in ``b``, but here's a legal call: ::
 
-         f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y
+       ...(h [True])...
 
-   The use of ``?x`` in the binding for ``?y`` does not "see" the
-   binding for ``?x``, so the type of ``f`` is ::
+That gives rise to a ``(X [Bool] beta)`` constraint, and using the
+instance means we need ``(D Bool beta)`` and that fixes ``beta`` via
+``D``\'s fundep!
 
-         f :: (?x::Int) => Int -> Int
+Behind all these special cases there is a simple guiding principle.
+Consider ::
 
-Implicit parameters and polymorphic recursion
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      f :: type
+      f = ...blah...
 
-Consider these two definitions: ::
+      g :: type
+      g = f
 
-      len1 :: [a] -> Int
-      len1 xs = let ?acc = 0 in len_acc1 xs
+You would think that the definition of ``g`` would surely typecheck!
+After all ``f`` has exactly the same type, and ``g=f``. But in fact
+``f``\'s type is instantiated and the instantiated constraints are solved
+against the constraints bound by ``g``\ 's signature. So, in the case an
+ambiguous type, solving will fail. For example, consider the earlier
+definition ``f :: C a => Int``: ::
 
-      len_acc1 [] = ?acc
-      len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs
+      f :: C a => Int
+      f = ...blah...
 
-      ------------
+      g :: C a => Int
+      g = f
 
-      len2 :: [a] -> Int
-      len2 xs = let ?acc = 0 in len_acc2 xs
+In ``g``\'s definition, we'll instantiate to ``(C alpha)`` and try to
+deduce ``(C alpha)`` from ``(C a)``, and fail.
 
-      len_acc2 :: (?acc :: Int) => [a] -> Int
-      len_acc2 [] = ?acc
-      len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs
+So in fact we use this as our *definition* of ambiguity: a type ``ty``
+is ambiguous if and only if ``((undefined :: ty) :: ty)`` would fail to
+typecheck. We use a very similar test for *inferred* types, to ensure
+that they too are unambiguous.
 
-The only difference between the two groups is that in the second group
-``len_acc`` is given a type signature. In the former case, ``len_acc1``
-is monomorphic in its own right-hand side, so the implicit parameter
-``?acc`` is not passed to the recursive call. In the latter case,
-because ``len_acc2`` has a type signature, the recursive call is made to
-the *polymorphic* version, which takes ``?acc`` as an implicit
-parameter. So we get the following results in GHCi:
+*Switching off the ambiguity check.* Even if a function is has an
+ambiguous type according the "guiding principle", it is possible that
+the function is callable. For example: ::
 
-.. code-block:: none
+      class D a b where ...
+      instance D Bool b where ...
 
-      Prog> len1 "hello"
-      0
-      Prog> len2 "hello"
-      5
+      strange :: D a b => a -> a
+      strange = ...blah...
 
-Adding a type signature dramatically changes the result! This is a
-rather counter-intuitive phenomenon, worth watching out for.
+      foo = strange True
 
-Implicit parameters and monomorphism
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Here ``strange``\'s type is ambiguous, but the call in ``foo`` is OK
+because it gives rise to a constraint ``(D Bool beta)``, which is
+soluble by the ``(D Bool b)`` instance. So the language extension
+:ghc-flag:`-XAllowAmbiguousTypes` allows you to switch off the ambiguity check.
+But even with ambiguity checking switched off, GHC will complain about a
+function that can *never* be called, such as this one: ::
 
-GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the
-Haskell Report) to implicit parameters. For example, consider: ::
+      f :: (Int ~ Bool) => a -> a
 
-     f :: Int -> Int
-     f v = let ?x = 0     in
-           let y = ?x + v in
-           let ?x = 5     in
-           y
+.. note::
+    *A historical note.* GHC used to impose some more restrictive and less
+    principled conditions on type signatures. For type
+    ``forall tv1..tvn (c1, ...,cn) => type`` GHC used to require
 
-Since the binding for ``y`` falls under the Monomorphism Restriction it
-is not generalised, so the type of ``y`` is simply ``Int``, not
-``(?x::Int) => Int``. Hence, ``(f 9)`` returns result ``9``. If you add
-a type signature for ``y``, then ``y`` will get type
-``(?x::Int) => Int``, so the occurrence of ``y`` in the body of the
-``let`` will see the inner binding of ``?x``, so ``(f 9)`` will return
-``14``.
+     a. that each universally quantified type variable ``tvi`` must be "reachable"
+        from ``type``, and
 
+     b. that every constraint ``ci`` mentions at least one of the universally
+        quantified type variables ``tvi``. These ad-hoc restrictions are
+        completely subsumed by the new ambiguity check.
 
 .. _kinding:
 
@@ -8079,702 +7890,903 @@ This flag enables kind signatures in the following places:
 
 -  ``class`` declarations: ::
 
-         class (Eq a) => C (f :: * -> *) a where ...
+         class (Eq a) => C (f :: * -> *) a where ...
+
+-  ``forall``\'s in type signatures: ::
+
+         f :: forall (cxt :: * -> *). Set cxt Int
+
+The parentheses are required. Some of the spaces are required too, to
+separate the lexemes. If you write ``(f::*->*)`` you will get a parse
+error, because ``::*->*`` is a single lexeme in Haskell.
+
+As part of the same extension, you can put kind annotations in types as
+well. Thus: ::
+
+       f :: (Int :: *) -> Int
+       g :: forall a. a -> (a :: *)
+
+The syntax is
+
+.. code-block:: none
+
+       atype ::= '(' ctype '::' kind ')
+
+The parentheses are required.
+
+.. _universal-quantification:
+
+.. _scoped-type-variables:
+
+Lexically scoped type variables
+===============================
+
+.. ghc-flag:: -XScopedTypeVariables
+
+    :implies: :ghc-flag:`-XRelaxedPolyRec`
+    :implies: :ghc-flag:`-XExplicitForAll`
+
+    Enable lexical scoping of type variables explicitly introduced with
+    ``forall``.
+
+GHC supports *lexically scoped type variables*, without which some type
+signatures are simply impossible to write. For example: ::
+
+    f :: forall a. [a] -> [a]
+    f xs = ys ++ ys
+         where
+           ys :: [a]
+           ys = reverse xs
+
+The type signature for ``f`` brings the type variable ``a`` into scope,
+because of the explicit ``forall`` (:ref:`decl-type-sigs`). The type
+variables bound by a ``forall`` scope over the entire definition of the
+accompanying value declaration. In this example, the type variable ``a``
+scopes over the whole definition of ``f``, including over the type
+signature for ``ys``. In Haskell 98 it is not possible to declare a type
+for ``ys``; a major benefit of scoped type variables is that it becomes
+possible to do so.
+
+Lexically-scoped type variables are enabled by
+:ghc-flag:`-XScopedTypeVariables`. This flag implies :ghc-flag:`-XRelaxedPolyRec`.
+
+Overview
+--------
+
+The design follows the following principles
+
+-  A scoped type variable stands for a type *variable*, and not for a
+   *type*. (This is a change from GHC's earlier design.)
+
+-  Furthermore, distinct lexical type variables stand for distinct type
+   variables. This means that every programmer-written type signature
+   (including one that contains free scoped type variables) denotes a
+   *rigid* type; that is, the type is fully known to the type checker,
+   and no inference is involved.
+
+-  Lexical type variables may be alpha-renamed freely, without changing
+   the program.
+
+A *lexically scoped type variable* can be bound by:
+
+-  A declaration type signature (:ref:`decl-type-sigs`)
+
+-  An expression type signature (:ref:`exp-type-sigs`)
+
+-  A pattern type signature (:ref:`pattern-type-sigs`)
+
+-  Class and instance declarations (:ref:`cls-inst-scoped-tyvars`)
+
+In Haskell, a programmer-written type signature is implicitly quantified
+over its free type variables (`Section
+4.1.2 <http://www.haskell.org/onlinereport/decls.html#sect4.1.2>`__ of
+the Haskell Report). Lexically scoped type variables affect this
+implicit quantification rules as follows: any type variable that is in
+scope is *not* universally quantified. For example, if type variable
+``a`` is in scope, then ::
+
+      (e :: a -> a)     means     (e :: a -> a)
+      (e :: b -> b)     means     (e :: forall b. b->b)
+      (e :: a -> b)     means     (e :: forall b. a->b)
+
+.. _decl-type-sigs:
+
+Declaration type signatures
+---------------------------
+
+A declaration type signature that has *explicit* quantification (using
+``forall``) brings into scope the explicitly-quantified type variables,
+in the definition of the named function. For example: ::
+
+      f :: forall a. [a] -> [a]
+      f (x:xs) = xs ++ [ x :: a ]
+
+The "``forall a``" brings "``a``" into scope in the definition of
+"``f``".
+
+This only happens if:
+
+-  The quantification in ``f``\'s type signature is explicit. For
+   example: ::
+
+         g :: [a] -> [a]
+         g (x:xs) = xs ++ [ x :: a ]
+
+   This program will be rejected, because "``a``" does not scope over
+   the definition of "``g``", so "``x::a``" means "``x::forall a. a``"
+   by Haskell's usual implicit quantification rules.
+
+-  The signature gives a type for a function binding or a bare variable
+   binding, not a pattern binding. For example: ::
+
+         f1 :: forall a. [a] -> [a]
+         f1 (x:xs) = xs ++ [ x :: a ]   -- OK
+
+         f2 :: forall a. [a] -> [a]
+         f2 = \(x:xs) -> xs ++ [ x :: a ]   -- OK
+
+         f3 :: forall a. [a] -> [a]
+         Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!
+
+   The binding for ``f3`` is a pattern binding, and so its type
+   signature does not bring ``a`` into scope. However ``f1`` is a
+   function binding, and ``f2`` binds a bare variable; in both cases the
+   type signature brings ``a`` into scope.
+
+.. _exp-type-sigs:
+
+Expression type signatures
+--------------------------
 
--  ``forall``\'s in type signatures: ::
+An expression type signature that has *explicit* quantification (using
+``forall``) brings into scope the explicitly-quantified type variables,
+in the annotated expression. For example: ::
 
-         f :: forall (cxt :: * -> *). Set cxt Int
+    f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
 
-The parentheses are required. Some of the spaces are required too, to
-separate the lexemes. If you write ``(f::*->*)`` you will get a parse
-error, because ``::*->*`` is a single lexeme in Haskell.
+Here, the type signature ``forall s. ST s Bool`` brings the type
+variable ``s`` into scope, in the annotated expression
+``(op >>= \(x :: STRef s Int) -> g x)``.
 
-As part of the same extension, you can put kind annotations in types as
-well. Thus: ::
+.. _pattern-type-sigs:
 
-       f :: (Int :: *) -> Int
-       g :: forall a. a -> (a :: *)
+Pattern type signatures
+-----------------------
 
-The syntax is
+A type signature may occur in any pattern; this is a *pattern type
+signature*. For example: ::
 
-.. code-block:: none
+    -- f and g assume that 'a' is already in scope
+    f = \(x::Int, y::a) -> x
 
-       atype ::= '(' ctype '::' kind ')
+    g (x::a) = x
 
-The parentheses are required.
+    h ((x,y) :: (Int,Bool)) = (y,x)
 
-.. _universal-quantification:
+In the case where all the type variables in the pattern type signature
+are already in scope (i.e. bound by the enclosing context), matters are
+simple: the signature simply constrains the type of the pattern in the
+obvious way.
 
-Arbitrary-rank polymorphism
----------------------------
+Unlike expression and declaration type signatures, pattern type
+signatures are not implicitly generalised. The pattern in a *pattern
+binding* may only mention type variables that are already in scope. For
+example: ::
 
-.. ghc-flag:: -XRankNTypes
+    f :: forall a. [a] -> (Int, [a])
+    f xs = (n, zs)
+      where
+        (ys::[a], n) = (reverse xs, length xs) -- OK
+        zs::[a] = xs ++ ys                     -- OK
 
+        Just (v::b) = ...  -- Not OK; b is not in scope
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+Here, the pattern signatures for ``ys`` and ``zs`` are fine, but the one
+for ``v`` is not because ``b`` is not in scope.
 
-    Allow types of arbitrary rank.
+However, in all patterns *other* than pattern bindings, a pattern type
+signature may mention a type variable that is not in scope; in this
+case, *the signature brings that type variable into scope*. This is
+particularly important for existential data constructors. For example: ::
 
-.. ghc-flag:: -XRank2Types
+    data T = forall a. MkT [a]
 
-    A deprecated alias of :ghc-flag:`-XRankNTypes`.
+    k :: T -> T
+    k (MkT [t::a]) =
+        MkT t3
+      where
+        t3::[a] = [t,t,t]
 
-GHC's type system supports *arbitrary-rank* explicit universal
-quantification in types. For example, all the following types are legal: ::
+Here, the pattern type signature ``(t::a)`` mentions a lexical type
+variable that is not already in scope. Indeed, it *cannot* already be in
+scope, because it is bound by the pattern match. GHC's rule is that in
+this situation (and only then), a pattern type signature can mention a
+type variable that is not already in scope; the effect is to bring it
+into scope, standing for the existentially-bound type variable.
 
-        f1 :: forall a b. a -> b -> a
-        g1 :: forall a b. (Ord a, Eq  b) => a -> b -> a
+When a pattern type signature binds a type variable in this way, GHC
+insists that the type variable is bound to a *rigid*, or fully-known,
+type variable. This means that any user-written type signature always
+stands for a completely known type.
 
-        f2 :: (forall a. a->a) -> Int -> Int
-        g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int
+If all this seems a little odd, we think so too. But we must have *some*
+way to bring such type variables into scope, else we could not name
+existentially-bound type variables in subsequent type signatures.
 
-        f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool
+This is (now) the *only* situation in which a pattern type signature is
+allowed to mention a lexical variable that is not already in scope. For
+example, both ``f`` and ``g`` would be illegal if ``a`` was not already
+in scope.
 
-        f4 :: Int -> (forall a. a -> a)
+.. _cls-inst-scoped-tyvars:
 
-Here, ``f1`` and ``g1`` are rank-1 types, and can be written in standard
-Haskell (e.g. ``f1 :: a->b->a``). The ``forall`` makes explicit the
-universal quantification that is implicitly added by Haskell.
+Class and instance declarations
+-------------------------------
 
-The functions ``f2`` and ``g2`` have rank-2 types; the ``forall`` is on
-the left of a function arrow. As ``g2`` shows, the polymorphic type on
-the left of the function arrow can be overloaded.
+The type variables in the head of a ``class`` or ``instance``
+declaration scope over the methods defined in the ``where`` part. You do
+not even need an explicit ``forall`` (although you are allowed an explicit
+``forall`` in an ``instance`` declaration; see :ref:`explicit-foralls`).
+For example: ::
 
-The function ``f3`` has a rank-3 type; it has rank-2 types on the left
-of a function arrow.
+      class C a where
+        op :: [a] -> a
 
-The language option :ghc-flag:`-XRankNTypes` (which implies
-:ghc-flag:`-XExplicitForAll`) enables higher-rank
-types. That is, you can nest ``forall``\ s arbitrarily deep in function
-arrows. For example, a forall-type (also called a "type scheme"),
-including a type-class context, is legal:
+        op xs = let ys::[a]
+                    ys = reverse xs
+                in
+                head ys
 
--  On the left or right (see ``f4``, for example) of a function arrow
+      instance C b => C [b] where
+        op xs = reverse (head (xs :: [[b]]))
 
--  As the argument of a constructor, or type of a field, in a data type
-   declaration. For example, any of the ``f1, f2, f3, g1, g2`` above would
-   be valid field type signatures.
+Bindings and generalisation
+===========================
 
--  As the type of an implicit parameter
+.. _monomorphism:
 
--  In a pattern type signature (see :ref:`scoped-type-variables`)
+Switching off the dreaded Monomorphism Restriction
+--------------------------------------------------
 
-The :ghc-flag:`-XRankNTypes` option is also required for any type with a
-``forall`` or context to the right of an arrow (e.g.
-``f :: Int -> forall a. a->a``, or ``g :: Int -> Ord a => a -> a``).
-Such types are technically rank 1, but are clearly not Haskell-98, and
-an extra flag did not seem worth the bother.
+.. ghc-flag:: -XNoMonomorphismRestriction
 
-In particular, in ``data`` and ``newtype`` declarations the constructor
-arguments may be polymorphic types of any rank; see examples in
-:ref:`univ`. Note that the declared types are nevertheless always
-monomorphic. This is important because by default GHC will not
-instantiate type variables to a polymorphic type
-(:ref:`impredicative-polymorphism`).
+    :default: on
 
-The obsolete language options :ghc-flag:`-XPolymorphicComponents` and
-:ghc-flag:`-XRank2Types` are synonyms for :ghc-flag:`-XRankNTypes`. They used to
-specify finer distinctions that GHC no longer makes. (They should really elicit
-a deprecation warning, but they don't, purely to avoid the need to library
-authors to change their old flags specifications.)
+    Prevents the compiler from applying the monomorphism restriction to
+    bindings lacking explicit type signatures.
 
-.. _univ:
+Haskell's monomorphism restriction (see `Section
+4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__ of
+the Haskell Report) can be completely switched off by
+:ghc-flag:`-XNoMonomorphismRestriction`. Since GHC 7.8.1, the monomorphism
+restriction is switched off by default in GHCi's interactive options
+(see :ref:`ghci-interactive-options`).
 
-Examples
-~~~~~~~~
+.. _typing-binds:
 
-These are examples of ``data`` and ``newtype`` declarations whose data
-constructors have polymorphic argument types: ::
+Generalised typing of mutually recursive bindings
+-------------------------------------------------
 
-    data T a = T1 (forall b. b -> b -> b) a
+.. ghc-flag:: -XRelaxedPolyRec
 
-    data MonadT m = MkMonad { return :: forall a. a -> m a,
-                              bind   :: forall a b. m a -> (a -> m b) -> m b
-                            }
+    Allow the typechecker to ignore references to bindings with
+    explicit type signatures.
 
-    newtype Swizzle = MkSwizzle (forall a. Ord a => [a] -> [a])
+The Haskell Report specifies that a group of bindings (at top level, or
+in a ``let`` or ``where``) should be sorted into strongly-connected
+components, and then type-checked in dependency order
+(`Haskell Report, Section
+4.5.1 <http://www.haskell.org/onlinereport/decls.html#sect4.5.1>`__). As
+each group is type-checked, any binders of the group that have an
+explicit type signature are put in the type environment with the
+specified polymorphic type, and all others are monomorphic until the
+group is generalised (`Haskell Report, Section
+4.5.2 <http://www.haskell.org/onlinereport/decls.html#sect4.5.2>`__).
 
-The constructors have rank-2 types: ::
+Following a suggestion of Mark Jones, in his paper `Typing Haskell in
+Haskell <http://citeseer.ist.psu.edu/424440.html>`__, GHC implements a
+more general scheme. If :ghc-flag:`-XRelaxedPolyRec` is specified: *the
+dependency analysis ignores references to variables that have an
+explicit type signature*. As a result of this refined dependency
+analysis, the dependency groups are smaller, and more bindings will
+typecheck. For example, consider: ::
 
-    T1 :: forall a. (forall b. b -> b -> b) -> a -> T a
+      f :: Eq a => a -> Bool
+      f x = (x == x) || g True || g "Yes"
 
-    MkMonad :: forall m. (forall a. a -> m a)
-                      -> (forall a b. m a -> (a -> m b) -> m b)
-                      -> MonadT m
+      g y = (y <= y) || f True
 
-    MkSwizzle :: (forall a. Ord a => [a] -> [a]) -> Swizzle
+This is rejected by Haskell 98, but under Jones's scheme the definition
+for ``g`` is typechecked first, separately from that for ``f``, because
+the reference to ``f`` in ``g``\'s right hand side is ignored by the
+dependency analysis. Then ``g``\'s type is generalised, to get ::
 
-In earlier versions of GHC, it was possible to omit the ``forall`` in
-the type of the constructor if there was an explicit context. For
-example: ::
+      g :: Ord a => a -> Bool
 
-    newtype Swizzle' = MkSwizzle' (Ord a => [a] -> [a])
+Now, the definition for ``f`` is typechecked, with this type for ``g``
+in the type environment.
 
-As of GHC 7.10, this is deprecated. The
-:ghc-flag:`-Wcontext-quantification` flag detects this situation and issues
-a warning. In GHC 8.0 this flag was deprecated and declarations such as
-``MkSwizzle'`` will cause an out-of-scope error.
+The same refined dependency analysis also allows the type signatures of
+mutually-recursive functions to have different contexts, something that
+is illegal in Haskell 98 (Section 4.5.2, last sentence). With
+:ghc-flag:`-XRelaxedPolyRec` GHC only insists that the type signatures of a
+*refined* group have identical type signatures; in practice this means
+that only variables bound by the same pattern binding must have the same
+context. For example, this is fine: ::
 
-As for type signatures, implicit quantification happens for
-non-overloaded types too. So if you write this: ::
+      f :: Eq a => a -> Bool
+      f x = (x == x) || g True
 
-      f :: (a -> a) -> a
+      g :: Ord a => a -> Bool
+      g y = (y <= y) || f True
 
-it's just as if you had written this: ::
+.. _mono-local-binds:
 
-      f :: forall a. (a -> a) -> a
+Let-generalisation
+------------------
 
-That is, since the type variable ``a`` isn't in scope, it's implicitly
-universally quantified.
+.. ghc-flag:: -XMonoLocalBinds
 
-You construct values of types ``T1, MonadT, Swizzle`` by applying the
-constructor to suitable values, just as usual. For example, ::
+    Infer less polymorphic types for local bindings by default.
 
-        a1 :: T Int
-        a1 = T1 (\xy->x) 3
+An ML-style language usually generalises the type of any ``let``\-bound or
+``where``\-bound variable, so that it is as polymorphic as possible. With the
+flag :ghc-flag:`-XMonoLocalBinds` GHC implements a slightly more conservative
+policy, using the following rules:
 
-        a2, a3 :: Swizzle
-        a2 = MkSwizzle sort
-        a3 = MkSwizzle reverse
+-  A variable is *closed* if and only if
 
-        a4 :: MonadT Maybe
-        a4 = let r x = Just x
-             b m k = case m of
-                   Just y -> k y
-                   Nothing -> Nothing
-             in
-             MkMonad r b
+   -  the variable is let-bound
 
-        mkTs :: (forall b. b -> b -> b) -> a -> [T a]
-        mkTs f x y = [T1 f x, T1 f y]
+   -  one of the following holds:
 
-The type of the argument can, as usual, be more general than the type
-required, as ``(MkSwizzle reverse)`` shows. (``reverse`` does not need
-the ``Ord`` constraint.)
+      -  the variable has an explicit type signature that has no free
+         type variables, or
 
-When you use pattern matching, the bound variables may now have
-polymorphic types. For example: ::
+      -  its binding group is fully generalised (see next bullet)
 
-        f :: T a -> a -> (a, Char)
-        f (T1 w k) x = (w k x, w 'c' 'd')
+-  A binding group is *fully generalised* if and only if
 
-        g :: (Ord a, Ord b) => Swizzle -> [a] -> (a -> b) -> [b]
-        g (MkSwizzle s) xs f = s (map f (s xs))
+   -  each of its free variables is either imported or closed, and
 
-        h :: MonadT m -> [m a] -> m [a]
-        h m [] = return m []
-        h m (x:xs) = bind m x          $ \y ->
-                     bind m (h m xs)   $ \ys ->
-                     return m (y:ys)
+   -  the binding is not affected by the monomorphism restriction
+      (`Haskell Report, Section
+      4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__)
 
-In the function ``h`` we use the record selectors ``return`` and
-``bind`` to extract the polymorphic bind and return functions from the
-``MonadT`` data structure, rather than using pattern matching.
+For example, consider ::
 
+    f x = x + 1
+    g x = let h y = f y * 2
+              k z = z+x
+          in  h x + k x
 
-.. _higher-rank-type-inference:
+Here ``f`` is generalised because it has no free variables; and its
+binding group is unaffected by the monomorphism restriction; and hence
+``f`` is closed. The same reasoning applies to ``g``, except that it has
+one closed free variable, namely ``f``. Similarly ``h`` is closed, *even
+though it is not bound at top level*, because its only free variable
+``f`` is closed. But ``k`` is not closed, because it mentions ``x``
+which is not closed (because it is not let-bound).
 
-Type inference
-~~~~~~~~~~~~~~
+Notice that a top-level binding that is affected by the monomorphism
+restriction is not closed, and hence may in turn prevent generalisation
+of bindings that mention it.
 
-In general, type inference for arbitrary-rank types is undecidable. GHC
-uses an algorithm proposed by Odersky and Laufer ("Putting type
-annotations to work", POPL'96) to get a decidable algorithm by requiring
-some help from the programmer. We do not yet have a formal specification
-of "some help" but the rule is this:
+The rationale for this more conservative strategy is given in `the
+papers <http://research.microsoft.com/~simonpj/papers/constraints/index.htm>`__
+"Let should not be generalised" and "Modular type inference with local
+assumptions", and a related `blog post <http://ghc.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7>`__.
 
-    For a lambda-bound or case-bound variable, x, either the programmer
-    provides an explicit polymorphic type for x, or GHC's type inference
-    will assume that x's type has no foralls in it.
+The flag :ghc-flag:`-XMonoLocalBinds` is implied by :ghc-flag:`-XTypeFamilies`
+and :ghc-flag:`-XGADTs`. You can switch it off again with
+:ghc-flag:`-XNoMonoLocalBinds <-XMonoLocalBinds>` but type inference becomes
+less predicatable if you do so. (Read the papers!)
 
-What does it mean to "provide" an explicit type for x? You can do that
-by giving a type signature for x directly, using a pattern type
-signature (:ref:`scoped-type-variables`), thus: ::
+.. _implicit-parameters:
 
-    \ f :: (forall a. a->a) -> (f True, f 'c')
+Implicit parameters
+===================
 
-Alternatively, you can give a type signature to the enclosing context,
-which GHC can "push down" to find the type for the variable: ::
+.. ghc-flag:: -XImplicitParams
 
-    (\ f -> (f True, f 'c')) :: (forall a. a->a) -> (Bool,Char)
+    Allow definition of functions expecting implicit parameters.
 
-Here the type signature on the expression can be pushed inwards to give
-a type signature for f. Similarly, and more commonly, one can give a
-type signature for the function itself: ::
+Implicit parameters are implemented as described in [Lewis2000]_ and enabled
+with the option :ghc-flag:`-XImplicitParams`. (Most of the following, still rather
+incomplete, documentation is due to Jeff Lewis.)
 
-    h :: (forall a. a->a) -> (Bool,Char)
-    h f = (f True, f 'c')
+.. [Lewis2000]
+    "Implicit parameters: dynamic scoping with static types",
+    J Lewis, MB Shields, E Meijer, J Launchbury,
+    *27th ACM Symposium on Principles of Programming Languages (POPL'00)*,
+    Boston, Jan 2000.
 
-You don't need to give a type signature if the lambda bound variable is
-a constructor argument. Here is an example we saw earlier: ::
+A variable is called *dynamically bound* when it is bound by the calling
+context of a function and *statically bound* when bound by the callee's
+context. In Haskell, all variables are statically bound. Dynamic binding
+of variables is a notion that goes back to Lisp, but was later discarded
+in more modern incarnations, such as Scheme. Dynamic binding can be very
+confusing in an untyped language, and unfortunately, typed languages, in
+particular Hindley-Milner typed languages like Haskell, only support
+static scoping of variables.
 
-    f :: T a -> a -> (a, Char)
-    f (T1 w k) x = (w k x, w 'c' 'd')
+However, by a simple extension to the type class system of Haskell, we
+can support dynamic binding. Basically, we express the use of a
+dynamically bound variable as a constraint on the type. These
+constraints lead to types of the form ``(?x::t') => t``, which says
+"this function uses a dynamically-bound variable ``?x`` of type ``t'``".
+For example, the following expresses the type of a sort function,
+implicitly parameterised by a comparison function named ``cmp``. ::
 
-Here we do not need to give a type signature to ``w``, because it is an
-argument of constructor ``T1`` and that tells GHC all it needs to know.
+      sort :: (?cmp :: a -> a -> Bool) => [a] -> [a]
 
+The dynamic binding constraints are just a new form of predicate in the
+type class system.
 
-.. _implicit-quant:
+An implicit parameter occurs in an expression using the special form
+``?x``, where ``x`` is any valid identifier (e.g. ``ord ?x`` is a valid
+expression). Use of this construct also introduces a new dynamic-binding
+constraint in the type of the expression. For example, the following
+definition shows how we can define an implicitly parameterised sort
+function in terms of an explicitly parameterised ``sortBy`` function: ::
 
-Implicit quantification
-~~~~~~~~~~~~~~~~~~~~~~~
+      sortBy :: (a -> a -> Bool) -> [a] -> [a]
 
-GHC performs implicit quantification as follows. At the top level
-(only) of user-written types, if and only if there is no explicit
-``forall``, GHC finds all the type variables mentioned in the type that
-are not already in scope, and universally quantifies them. For example,
-the following pairs are equivalent: ::
+      sort   :: (?cmp :: a -> a -> Bool) => [a] -> [a]
+      sort    = sortBy ?cmp
 
-      f :: a -> a
-      f :: forall a. a -> a
+Implicit-parameter type constraints
+-----------------------------------
 
-      g (x::a) = let
-                    h :: a -> b -> b
-                    h x y = y
-                 in ...
-      g (x::a) = let
-                    h :: forall b. a -> b -> b
-                    h x y = y
-                 in ...
+Dynamic binding constraints behave just like other type class
+constraints in that they are automatically propagated. Thus, when a
+function is used, its implicit parameters are inherited by the function
+that called it. For example, our ``sort`` function might be used to pick
+out the least value in a list: ::
 
-Notice that GHC does *not* find the inner-most possible quantification
-point. For example: ::
+      least   :: (?cmp :: a -> a -> Bool) => [a] -> a
+      least xs = head (sort xs)
 
-      f :: (a -> a) -> Int
-               -- MEANS
-      f :: forall a. (a -> a) -> Int
-               -- NOT
-      f :: (forall a. a -> a) -> Int
+Without lifting a finger, the ``?cmp`` parameter is propagated to become
+a parameter of ``least`` as well. With explicit parameters, the default
+is that parameters must always be explicit propagated. With implicit
+parameters, the default is to always propagate them.
 
+An implicit-parameter type constraint differs from other type class
+constraints in the following way: All uses of a particular implicit
+parameter must have the same type. This means that the type of
+``(?x, ?x)`` is ``(?x::a) => (a,a)``, and not
+``(?x::a, ?x::b) => (a, b)``, as would be the case for type class
+constraints.
 
-      g :: (Ord a => a -> a) -> Int
-               -- MEANS the illegal type
-      g :: forall a. (Ord a => a -> a) -> Int
-               -- NOT
-      g :: (forall a. Ord a => a -> a) -> Int
+You can't have an implicit parameter in the context of a class or
+instance declaration. For example, both these declarations are illegal: ::
 
-The latter produces an illegal type, which you might think is silly, but
-at least the rule is simple. If you want the latter type, you can write
-your ``forall``\s explicitly. Indeed, doing so is strongly advised for
-rank-2 types.
+      class (?x::Int) => C a where ...
+      instance (?x::a) => Foo [a] where ...
 
-.. _impredicative-polymorphism:
+Reason: exactly which implicit parameter you pick up depends on exactly
+where you invoke a function. But the "invocation" of instance
+declarations is done behind the scenes by the compiler, so it's hard to
+figure out exactly where it is done. Easiest thing is to outlaw the
+offending types.
 
-Impredicative polymorphism
---------------------------
+Implicit-parameter constraints do not cause ambiguity. For example,
+consider: ::
 
-.. ghc-flag:: -XImpredicativeTypes
+       f :: (?x :: [a]) => Int -> Int
+       f n = n + length ?x
 
-    :implies: :ghc-flag:`RankNTypes`
+       g :: (Read a, Show a) => String -> String
+       g s = show (read s)
 
-    Allow impredicative polymorphic types.
+Here, ``g`` has an ambiguous type, and is rejected, but ``f`` is fine.
+The binding for ``?x`` at ``f``\ 's call site is quite unambiguous, and
+fixes the type ``a``.
 
-In general, GHC will only instantiate a polymorphic function at a
-monomorphic type (one with no foralls). For example, ::
+Implicit-parameter bindings
+---------------------------
 
-    runST :: (forall s. ST s a) -> a
-    id :: forall b. b -> b
+An implicit parameter is *bound* using the standard ``let`` or ``where``
+binding forms. For example, we define the ``min`` function by binding
+``cmp``. ::
 
-    foo = id runST   -- Rejected
+      min :: Ord a => [a] -> a
+      min  = let ?cmp = (<=) in least
 
-The definition of ``foo`` is rejected because one would have to
-instantiate ``id``\'s type with ``b := (forall s. ST s a) -> a``, and
-that is not allowed. Instantiating polymorphic type variables with
-polymorphic types is called *impredicative polymorphism*.
+A group of implicit-parameter bindings may occur anywhere a normal group
+of Haskell bindings can occur, except at top level. That is, they can
+occur in a ``let`` (including in a list comprehension, or do-notation,
+or pattern guards), or a ``where`` clause. Note the following points:
 
-GHC has extremely flaky support for *impredicative polymorphism*,
-enabled with :ghc-flag:`-XImpredicativeTypes`. If it worked, this would mean
-that you *could* call a polymorphic function at a polymorphic type, and
-parameterise data structures over polymorphic types. For example: ::
+-  An implicit-parameter binding group must be a collection of simple
+   bindings to implicit-style variables (no function-style bindings, and
+   no type signatures); these bindings are neither polymorphic or
+   recursive.
 
-      f :: Maybe (forall a. [a] -> [a]) -> Maybe ([Int], [Char])
-      f (Just g) = Just (g [3], g "hello")
-      f Nothing  = Nothing
+-  You may not mix implicit-parameter bindings with ordinary bindings in
+   a single ``let`` expression; use two nested ``let``\ s instead. (In
+   the case of ``where`` you are stuck, since you can't nest ``where``
+   clauses.)
 
-Notice here that the ``Maybe`` type is parameterised by the
-*polymorphic* type ``(forall a. [a] -> [a])``. However *the extension
-should be considered highly experimental, and certainly un-supported*.
-You are welcome to try it, but please don't rely on it working
-consistently, or working the same in subsequent releases. See
-:ghc-wiki:`this wiki page <ImpredicativePolymorphism>` for more details.
+-  You may put multiple implicit-parameter bindings in a single binding
+   group; but they are *not* treated as a mutually recursive group (as
+   ordinary ``let`` bindings are). Instead they are treated as a
+   non-recursive group, simultaneously binding all the implicit
+   parameter. The bindings are not nested, and may be re-ordered without
+   changing the meaning of the program. For example, consider: ::
 
-If you want impredicative polymorphism, the main workaround is to use a
-newtype wrapper. The ``id runST`` example can be written using theis
-workaround like this: ::
+         f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y
 
-    runST :: (forall s. ST s a) -> a
-    id :: forall b. b -> b
+   The use of ``?x`` in the binding for ``?y`` does not "see" the
+   binding for ``?x``, so the type of ``f`` is ::
 
-    nwetype Wrap a = Wrap { unWrap :: (forall s. ST s a) -> a }
+         f :: (?x::Int) => Int -> Int
 
-    foo :: (forall s. ST s a) -> a
-    foo = unWrap (id (Wrap runST))
-          -- Here id is called at monomorphic type (Wrap a)
+Implicit parameters and polymorphic recursion
+---------------------------------------------
 
-.. _scoped-type-variables:
+Consider these two definitions: ::
 
-Lexically scoped type variables
--------------------------------
+      len1 :: [a] -> Int
+      len1 xs = let ?acc = 0 in len_acc1 xs
 
-.. ghc-flag:: -XScopedTypeVariables
+      len_acc1 [] = ?acc
+      len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs
 
-    :implies: :ghc-flag:`-XRelaxedPolyRec`
-    :implies: :ghc-flag:`-XExplicitForAll`
+      ------------
 
-    Enable lexical scoping of type variables explicitly introduced with
-    ``forall``.
+      len2 :: [a] -> Int
+      len2 xs = let ?acc = 0 in len_acc2 xs
 
-GHC supports *lexically scoped type variables*, without which some type
-signatures are simply impossible to write. For example: ::
+      len_acc2 :: (?acc :: Int) => [a] -> Int
+      len_acc2 [] = ?acc
+      len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs
 
-    f :: forall a. [a] -> [a]
-    f xs = ys ++ ys
-         where
-           ys :: [a]
-           ys = reverse xs
+The only difference between the two groups is that in the second group
+``len_acc`` is given a type signature. In the former case, ``len_acc1``
+is monomorphic in its own right-hand side, so the implicit parameter
+``?acc`` is not passed to the recursive call. In the latter case,
+because ``len_acc2`` has a type signature, the recursive call is made to
+the *polymorphic* version, which takes ``?acc`` as an implicit
+parameter. So we get the following results in GHCi:
 
-The type signature for ``f`` brings the type variable ``a`` into scope,
-because of the explicit ``forall`` (:ref:`decl-type-sigs`). The type
-variables bound by a ``forall`` scope over the entire definition of the
-accompanying value declaration. In this example, the type variable ``a``
-scopes over the whole definition of ``f``, including over the type
-signature for ``ys``. In Haskell 98 it is not possible to declare a type
-for ``ys``; a major benefit of scoped type variables is that it becomes
-possible to do so.
+.. code-block:: none
 
-Lexically-scoped type variables are enabled by
-:ghc-flag:`-XScopedTypeVariables`. This flag implies :ghc-flag:`-XRelaxedPolyRec`.
+      Prog> len1 "hello"
+      0
+      Prog> len2 "hello"
+      5
 
-Overview
-~~~~~~~~
+Adding a type signature dramatically changes the result! This is a
+rather counter-intuitive phenomenon, worth watching out for.
 
-The design follows the following principles
+Implicit parameters and monomorphism
+------------------------------------
 
--  A scoped type variable stands for a type *variable*, and not for a
-   *type*. (This is a change from GHC's earlier design.)
+GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the
+Haskell Report) to implicit parameters. For example, consider: ::
 
--  Furthermore, distinct lexical type variables stand for distinct type
-   variables. This means that every programmer-written type signature
-   (including one that contains free scoped type variables) denotes a
-   *rigid* type; that is, the type is fully known to the type checker,
-   and no inference is involved.
+     f :: Int -> Int
+     f v = let ?x = 0     in
+           let y = ?x + v in
+           let ?x = 5     in
+           y
 
--  Lexical type variables may be alpha-renamed freely, without changing
-   the program.
+Since the binding for ``y`` falls under the Monomorphism Restriction it
+is not generalised, so the type of ``y`` is simply ``Int``, not
+``(?x::Int) => Int``. Hence, ``(f 9)`` returns result ``9``. If you add
+a type signature for ``y``, then ``y`` will get type
+``(?x::Int) => Int``, so the occurrence of ``y`` in the body of the
+``let`` will see the inner binding of ``?x``, so ``(f 9)`` will return
+``14``.
 
-A *lexically scoped type variable* can be bound by:
+Arbitrary-rank polymorphism
+===========================
 
--  A declaration type signature (:ref:`decl-type-sigs`)
+.. ghc-flag:: -XRankNTypes
 
--  An expression type signature (:ref:`exp-type-sigs`)
 
--  A pattern type signature (:ref:`pattern-type-sigs`)
+    :implies: :ghc-flag:`-XExplicitForAll`
 
--  Class and instance declarations (:ref:`cls-inst-scoped-tyvars`)
+    Allow types of arbitrary rank.
 
-In Haskell, a programmer-written type signature is implicitly quantified
-over its free type variables (`Section
-4.1.2 <http://www.haskell.org/onlinereport/decls.html#sect4.1.2>`__ of
-the Haskell Report). Lexically scoped type variables affect this
-implicit quantification rules as follows: any type variable that is in
-scope is *not* universally quantified. For example, if type variable
-``a`` is in scope, then ::
+.. ghc-flag:: -XRank2Types
 
-      (e :: a -> a)     means     (e :: a -> a)
-      (e :: b -> b)     means     (e :: forall b. b->b)
-      (e :: a -> b)     means     (e :: forall b. a->b)
+    A deprecated alias of :ghc-flag:`-XRankNTypes`.
 
-.. _decl-type-sigs:
+GHC's type system supports *arbitrary-rank* explicit universal
+quantification in types. For example, all the following types are legal: ::
 
-Declaration type signatures
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        f1 :: forall a b. a -> b -> a
+        g1 :: forall a b. (Ord a, Eq  b) => a -> b -> a
 
-A declaration type signature that has *explicit* quantification (using
-``forall``) brings into scope the explicitly-quantified type variables,
-in the definition of the named function. For example: ::
+        f2 :: (forall a. a->a) -> Int -> Int
+        g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int
 
-      f :: forall a. [a] -> [a]
-      f (x:xs) = xs ++ [ x :: a ]
+        f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool
 
-The "``forall a``" brings "``a``" into scope in the definition of
-"``f``".
+        f4 :: Int -> (forall a. a -> a)
 
-This only happens if:
+Here, ``f1`` and ``g1`` are rank-1 types, and can be written in standard
+Haskell (e.g. ``f1 :: a->b->a``). The ``forall`` makes explicit the
+universal quantification that is implicitly added by Haskell.
 
--  The quantification in ``f``\'s type signature is explicit. For
-   example: ::
+The functions ``f2`` and ``g2`` have rank-2 types; the ``forall`` is on
+the left of a function arrow. As ``g2`` shows, the polymorphic type on
+the left of the function arrow can be overloaded.
 
-         g :: [a] -> [a]
-         g (x:xs) = xs ++ [ x :: a ]
+The function ``f3`` has a rank-3 type; it has rank-2 types on the left
+of a function arrow.
 
-   This program will be rejected, because "``a``" does not scope over
-   the definition of "``g``", so "``x::a``" means "``x::forall a. a``"
-   by Haskell's usual implicit quantification rules.
+The language option :ghc-flag:`-XRankNTypes` (which implies
+:ghc-flag:`-XExplicitForAll`) enables higher-rank
+types. That is, you can nest ``forall``\ s arbitrarily deep in function
+arrows. For example, a forall-type (also called a "type scheme"),
+including a type-class context, is legal:
 
--  The signature gives a type for a function binding or a bare variable
-   binding, not a pattern binding. For example: ::
+-  On the left or right (see ``f4``, for example) of a function arrow
 
-         f1 :: forall a. [a] -> [a]
-         f1 (x:xs) = xs ++ [ x :: a ]   -- OK
+-  As the argument of a constructor, or type of a field, in a data type
+   declaration. For example, any of the ``f1, f2, f3, g1, g2`` above would
+   be valid field type signatures.
 
-         f2 :: forall a. [a] -> [a]
-         f2 = \(x:xs) -> xs ++ [ x :: a ]   -- OK
+-  As the type of an implicit parameter
 
-         f3 :: forall a. [a] -> [a]
-         Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!
+-  In a pattern type signature (see :ref:`scoped-type-variables`)
 
-   The binding for ``f3`` is a pattern binding, and so its type
-   signature does not bring ``a`` into scope. However ``f1`` is a
-   function binding, and ``f2`` binds a bare variable; in both cases the
-   type signature brings ``a`` into scope.
+The :ghc-flag:`-XRankNTypes` option is also required for any type with a
+``forall`` or context to the right of an arrow (e.g.
+``f :: Int -> forall a. a->a``, or ``g :: Int -> Ord a => a -> a``).
+Such types are technically rank 1, but are clearly not Haskell-98, and
+an extra flag did not seem worth the bother.
 
-.. _exp-type-sigs:
+In particular, in ``data`` and ``newtype`` declarations the constructor
+arguments may be polymorphic types of any rank; see examples in
+:ref:`univ`. Note that the declared types are nevertheless always
+monomorphic. This is important because by default GHC will not
+instantiate type variables to a polymorphic type
+(:ref:`impredicative-polymorphism`).
 
-Expression type signatures
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+The obsolete language options :ghc-flag:`-XPolymorphicComponents` and
+:ghc-flag:`-XRank2Types` are synonyms for :ghc-flag:`-XRankNTypes`. They used to
+specify finer distinctions that GHC no longer makes. (They should really elicit
+a deprecation warning, but they don't, purely to avoid the need to library
+authors to change their old flags specifications.)
 
-An expression type signature that has *explicit* quantification (using
-``forall``) brings into scope the explicitly-quantified type variables,
-in the annotated expression. For example: ::
+.. _univ:
 
-    f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
+Examples
+--------
 
-Here, the type signature ``forall s. ST s Bool`` brings the type
-variable ``s`` into scope, in the annotated expression
-``(op >>= \(x :: STRef s Int) -> g x)``.
+These are examples of ``data`` and ``newtype`` declarations whose data
+constructors have polymorphic argument types: ::
 
-.. _pattern-type-sigs:
+    data T a = T1 (forall b. b -> b -> b) a
 
-Pattern type signatures
-~~~~~~~~~~~~~~~~~~~~~~~
+    data MonadT m = MkMonad { return :: forall a. a -> m a,
+                              bind   :: forall a b. m a -> (a -> m b) -> m b
+                            }
 
-A type signature may occur in any pattern; this is a *pattern type
-signature*. For example: ::
+    newtype Swizzle = MkSwizzle (forall a. Ord a => [a] -> [a])
 
-    -- f and g assume that 'a' is already in scope
-    f = \(x::Int, y::a) -> x
+The constructors have rank-2 types: ::
 
-    g (x::a) = x
+    T1 :: forall a. (forall b. b -> b -> b) -> a -> T a
 
-    h ((x,y) :: (Int,Bool)) = (y,x)
+    MkMonad :: forall m. (forall a. a -> m a)
+                      -> (forall a b. m a -> (a -> m b) -> m b)
+                      -> MonadT m
 
-In the case where all the type variables in the pattern type signature
-are already in scope (i.e. bound by the enclosing context), matters are
-simple: the signature simply constrains the type of the pattern in the
-obvious way.
+    MkSwizzle :: (forall a. Ord a => [a] -> [a]) -> Swizzle
 
-Unlike expression and declaration type signatures, pattern type
-signatures are not implicitly generalised. The pattern in a *pattern
-binding* may only mention type variables that are already in scope. For
+In earlier versions of GHC, it was possible to omit the ``forall`` in
+the type of the constructor if there was an explicit context. For
 example: ::
 
-    f :: forall a. [a] -> (Int, [a])
-    f xs = (n, zs)
-      where
-        (ys::[a], n) = (reverse xs, length xs) -- OK
-        zs::[a] = xs ++ ys                     -- OK
+    newtype Swizzle' = MkSwizzle' (Ord a => [a] -> [a])
 
-        Just (v::b) = ...  -- Not OK; b is not in scope
+As of GHC 7.10, this is deprecated. The
+:ghc-flag:`-Wcontext-quantification` flag detects this situation and issues
+a warning. In GHC 8.0 this flag was deprecated and declarations such as
+``MkSwizzle'`` will cause an out-of-scope error.
 
-Here, the pattern signatures for ``ys`` and ``zs`` are fine, but the one
-for ``v`` is not because ``b`` is not in scope.
+As for type signatures, implicit quantification happens for
+non-overloaded types too. So if you write this: ::
 
-However, in all patterns *other* than pattern bindings, a pattern type
-signature may mention a type variable that is not in scope; in this
-case, *the signature brings that type variable into scope*. This is
-particularly important for existential data constructors. For example: ::
+      f :: (a -> a) -> a
 
-    data T = forall a. MkT [a]
+it's just as if you had written this: ::
 
-    k :: T -> T
-    k (MkT [t::a]) =
-        MkT t3
-      where
-        t3::[a] = [t,t,t]
+      f :: forall a. (a -> a) -> a
 
-Here, the pattern type signature ``(t::a)`` mentions a lexical type
-variable that is not already in scope. Indeed, it *cannot* already be in
-scope, because it is bound by the pattern match. GHC's rule is that in
-this situation (and only then), a pattern type signature can mention a
-type variable that is not already in scope; the effect is to bring it
-into scope, standing for the existentially-bound type variable.
+That is, since the type variable ``a`` isn't in scope, it's implicitly
+universally quantified.
+
+You construct values of types ``T1, MonadT, Swizzle`` by applying the
+constructor to suitable values, just as usual. For example, ::
 
-When a pattern type signature binds a type variable in this way, GHC
-insists that the type variable is bound to a *rigid*, or fully-known,
-type variable. This means that any user-written type signature always
-stands for a completely known type.
+        a1 :: T Int
+        a1 = T1 (\xy->x) 3
 
-If all this seems a little odd, we think so too. But we must have *some*
-way to bring such type variables into scope, else we could not name
-existentially-bound type variables in subsequent type signatures.
+        a2, a3 :: Swizzle
+        a2 = MkSwizzle sort
+        a3 = MkSwizzle reverse
 
-This is (now) the *only* situation in which a pattern type signature is
-allowed to mention a lexical variable that is not already in scope. For
-example, both ``f`` and ``g`` would be illegal if ``a`` was not already
-in scope.
+        a4 :: MonadT Maybe
+        a4 = let r x = Just x
+             b m k = case m of
+                   Just y -> k y
+                   Nothing -> Nothing
+             in
+             MkMonad r b
 
-.. _cls-inst-scoped-tyvars:
+        mkTs :: (forall b. b -> b -> b) -> a -> [T a]
+        mkTs f x y = [T1 f x, T1 f y]
 
-Class and instance declarations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The type of the argument can, as usual, be more general than the type
+required, as ``(MkSwizzle reverse)`` shows. (``reverse`` does not need
+the ``Ord`` constraint.)
 
-The type variables in the head of a ``class`` or ``instance``
-declaration scope over the methods defined in the ``where`` part. You do
-not even need an explicit ``forall``. For example: ::
+When you use pattern matching, the bound variables may now have
+polymorphic types. For example: ::
 
-      class C a where
-        op :: [a] -> a
+        f :: T a -> a -> (a, Char)
+        f (T1 w k) x = (w k x, w 'c' 'd')
 
-        op xs = let ys::[a]
-                    ys = reverse xs
-                in
-                head ys
+        g :: (Ord a, Ord b) => Swizzle -> [a] -> (a -> b) -> [b]
+        g (MkSwizzle s) xs f = s (map f (s xs))
 
-      instance C b => C [b] where
-        op xs = reverse (head (xs :: [[b]]))
+        h :: MonadT m -> [m a] -> m [a]
+        h m [] = return m []
+        h m (x:xs) = bind m x          $ \y ->
+                     bind m (h m xs)   $ \ys ->
+                     return m (y:ys)
 
-Bindings and generalisation
----------------------------
+In the function ``h`` we use the record selectors ``return`` and
+``bind`` to extract the polymorphic bind and return functions from the
+``MonadT`` data structure, rather than using pattern matching.
 
-.. _monomorphism:
 
-Switching off the dreaded Monomorphism Restriction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _higher-rank-type-inference:
 
-.. ghc-flag:: -XNoMonomorphismRestriction
+Type inference
+--------------
 
-    :default: on
+In general, type inference for arbitrary-rank types is undecidable. GHC
+uses an algorithm proposed by Odersky and Laufer ("Putting type
+annotations to work", POPL'96) to get a decidable algorithm by requiring
+some help from the programmer. We do not yet have a formal specification
+of "some help" but the rule is this:
 
-    Prevents the compiler from applying the monomorphism restriction to
-    bindings lacking explicit type signatures.
+    For a lambda-bound or case-bound variable, x, either the programmer
+    provides an explicit polymorphic type for x, or GHC's type inference
+    will assume that x's type has no foralls in it.
 
-Haskell's monomorphism restriction (see `Section
-4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__ of
-the Haskell Report) can be completely switched off by
-:ghc-flag:`-XNoMonomorphismRestriction`. Since GHC 7.8.1, the monomorphism
-restriction is switched off by default in GHCi's interactive options
-(see :ref:`ghci-interactive-options`).
+What does it mean to "provide" an explicit type for x? You can do that
+by giving a type signature for x directly, using a pattern type
+signature (:ref:`scoped-type-variables`), thus: ::
 
-.. _typing-binds:
+    \ f :: (forall a. a->a) -> (f True, f 'c')
 
-Generalised typing of mutually recursive bindings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Alternatively, you can give a type signature to the enclosing context,
+which GHC can "push down" to find the type for the variable: ::
 
-.. ghc-flag:: -XRelaxedPolyRec
+    (\ f -> (f True, f 'c')) :: (forall a. a->a) -> (Bool,Char)
 
-    Allow the typechecker to ignore references to bindings with
-    explicit type signatures.
+Here the type signature on the expression can be pushed inwards to give
+a type signature for f. Similarly, and more commonly, one can give a
+type signature for the function itself: ::
 
-The Haskell Report specifies that a group of bindings (at top level, or
-in a ``let`` or ``where``) should be sorted into strongly-connected
-components, and then type-checked in dependency order
-(`Haskell Report, Section
-4.5.1 <http://www.haskell.org/onlinereport/decls.html#sect4.5.1>`__). As
-each group is type-checked, any binders of the group that have an
-explicit type signature are put in the type environment with the
-specified polymorphic type, and all others are monomorphic until the
-group is generalised (`Haskell Report, Section
-4.5.2 <http://www.haskell.org/onlinereport/decls.html#sect4.5.2>`__).
+    h :: (forall a. a->a) -> (Bool,Char)
+    h f = (f True, f 'c')
 
-Following a suggestion of Mark Jones, in his paper `Typing Haskell in
-Haskell <http://citeseer.ist.psu.edu/424440.html>`__, GHC implements a
-more general scheme. If :ghc-flag:`-XRelaxedPolyRec` is specified: *the
-dependency analysis ignores references to variables that have an
-explicit type signature*. As a result of this refined dependency
-analysis, the dependency groups are smaller, and more bindings will
-typecheck. For example, consider: ::
+You don't need to give a type signature if the lambda bound variable is
+a constructor argument. Here is an example we saw earlier: ::
 
-      f :: Eq a => a -> Bool
-      f x = (x == x) || g True || g "Yes"
+    f :: T a -> a -> (a, Char)
+    f (T1 w k) x = (w k x, w 'c' 'd')
 
-      g y = (y <= y) || f True
+Here we do not need to give a type signature to ``w``, because it is an
+argument of constructor ``T1`` and that tells GHC all it needs to know.
 
-This is rejected by Haskell 98, but under Jones's scheme the definition
-for ``g`` is typechecked first, separately from that for ``f``, because
-the reference to ``f`` in ``g``\'s right hand side is ignored by the
-dependency analysis. Then ``g``\'s type is generalised, to get ::
 
-      g :: Ord a => a -> Bool
+.. _implicit-quant:
 
-Now, the definition for ``f`` is typechecked, with this type for ``g``
-in the type environment.
+Implicit quantification
+-----------------------
 
-The same refined dependency analysis also allows the type signatures of
-mutually-recursive functions to have different contexts, something that
-is illegal in Haskell 98 (Section 4.5.2, last sentence). With
-:ghc-flag:`-XRelaxedPolyRec` GHC only insists that the type signatures of a
-*refined* group have identical type signatures; in practice this means
-that only variables bound by the same pattern binding must have the same
-context. For example, this is fine: ::
+GHC performs implicit quantification as follows. At the top level
+(only) of user-written types, if and only if there is no explicit
+``forall``, GHC finds all the type variables mentioned in the type that
+are not already in scope, and universally quantifies them. For example,
+the following pairs are equivalent: ::
 
-      f :: Eq a => a -> Bool
-      f x = (x == x) || g True
+      f :: a -> a
+      f :: forall a. a -> a
 
-      g :: Ord a => a -> Bool
-      g y = (y <= y) || f True
+      g (x::a) = let
+                    h :: a -> b -> b
+                    h x y = y
+                 in ...
+      g (x::a) = let
+                    h :: forall b. a -> b -> b
+                    h x y = y
+                 in ...
 
-.. _mono-local-binds:
+Notice that GHC does *not* find the inner-most possible quantification
+point. For example: ::
 
-Let-generalisation
-~~~~~~~~~~~~~~~~~~
+      f :: (a -> a) -> Int
+               -- MEANS
+      f :: forall a. (a -> a) -> Int
+               -- NOT
+      f :: (forall a. a -> a) -> Int
 
-.. ghc-flag:: -XMonoLocalBinds
 
-    Infer less polymorphic types for local bindings by default.
+      g :: (Ord a => a -> a) -> Int
+               -- MEANS the illegal type
+      g :: forall a. (Ord a => a -> a) -> Int
+               -- NOT
+      g :: (forall a. Ord a => a -> a) -> Int
 
-An ML-style language usually generalises the type of any ``let``\-bound or
-``where``\-bound variable, so that it is as polymorphic as possible. With the
-flag :ghc-flag:`-XMonoLocalBinds` GHC implements a slightly more conservative
-policy, using the following rules:
+The latter produces an illegal type, which you might think is silly, but
+at least the rule is simple. If you want the latter type, you can write
+your ``forall``\s explicitly. Indeed, doing so is strongly advised for
+rank-2 types.
 
--  A variable is *closed* if and only if
+.. _impredicative-polymorphism:
 
-   -  the variable is let-bound
+Impredicative polymorphism
+==========================
 
-   -  one of the following holds:
+.. ghc-flag:: -XImpredicativeTypes
 
-      -  the variable has an explicit type signature that has no free
-         type variables, or
+    :implies: :ghc-flag:`RankNTypes`
 
-      -  its binding group is fully generalised (see next bullet)
+    Allow impredicative polymorphic types.
 
--  A binding group is *fully generalised* if and only if
+In general, GHC will only instantiate a polymorphic function at a
+monomorphic type (one with no foralls). For example, ::
 
-   -  each of its free variables is either imported or closed, and
+    runST :: (forall s. ST s a) -> a
+    id :: forall b. b -> b
 
-   -  the binding is not affected by the monomorphism restriction
-      (`Haskell Report, Section
-      4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__)
+    foo = id runST   -- Rejected
 
-For example, consider ::
+The definition of ``foo`` is rejected because one would have to
+instantiate ``id``\'s type with ``b := (forall s. ST s a) -> a``, and
+that is not allowed. Instantiating polymorphic type variables with
+polymorphic types is called *impredicative polymorphism*.
 
-    f x = x + 1
-    g x = let h y = f y * 2
-              k z = z+x
-          in  h x + k x
+GHC has extremely flaky support for *impredicative polymorphism*,
+enabled with :ghc-flag:`-XImpredicativeTypes`. If it worked, this would mean
+that you *could* call a polymorphic function at a polymorphic type, and
+parameterise data structures over polymorphic types. For example: ::
 
-Here ``f`` is generalised because it has no free variables; and its
-binding group is unaffected by the monomorphism restriction; and hence
-``f`` is closed. The same reasoning applies to ``g``, except that it has
-one closed free variable, namely ``f``. Similarly ``h`` is closed, *even
-though it is not bound at top level*, because its only free variable
-``f`` is closed. But ``k`` is not closed, because it mentions ``x``
-which is not closed (because it is not let-bound).
+      f :: Maybe (forall a. [a] -> [a]) -> Maybe ([Int], [Char])
+      f (Just g) = Just (g [3], g "hello")
+      f Nothing  = Nothing
 
-Notice that a top-level binding that is affected by the monomorphism
-restriction is not closed, and hence may in turn prevent generalisation
-of bindings that mention it.
+Notice here that the ``Maybe`` type is parameterised by the
+*polymorphic* type ``(forall a. [a] -> [a])``. However *the extension
+should be considered highly experimental, and certainly un-supported*.
+You are welcome to try it, but please don't rely on it working
+consistently, or working the same in subsequent releases. See
+:ghc-wiki:`this wiki page <ImpredicativePolymorphism>` for more details.
 
-The rationale for this more conservative strategy is given in `the
-papers <http://research.microsoft.com/~simonpj/papers/constraints/index.htm>`__
-"Let should not be generalised" and "Modular type inference with local
-assumptions", and a related `blog post <http://ghc.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7>`__.
+If you want impredicative polymorphism, the main workaround is to use a
+newtype wrapper. The ``id runST`` example can be written using theis
+workaround like this: ::
 
-The flag :ghc-flag:`-XMonoLocalBinds` is implied by :ghc-flag:`-XTypeFamilies`
-and :ghc-flag:`-XGADTs`. You can switch it off again with
-:ghc-flag:`-XNoMonoLocalBinds <-XMonoLocalBinds>` but type inference becomes
-less predicatable if you do so. (Read the papers!)
+    runST :: (forall s. ST s a) -> a
+    id :: forall b. b -> b
+
+    nwetype Wrap a = Wrap { unWrap :: (forall s. ST s a) -> a }
+
+    foo :: (forall s. ST s a) -> a
+    foo = unWrap (id (Wrap runST))
+          -- Here id is called at monomorphic type (Wrap a)
 
 .. _typed-holes: