Make DeriveTraversable imply DeriveFunctor/Foldable
[ghc.git] / docs / users_guide / glasgow_exts.xml
index b398597..ac8004f 100644 (file)
@@ -272,7 +272,7 @@ If the types of <literal>p</literal> and <literal>q</literal> are not unboxed,
 the resulting binding is lazy like any other Haskell pattern binding.  The
 above example desugars like this:
 <programlisting>
-  f x = let t = case h x o f{ (# p,q #) -> (p,q)
+  f x = let t = case h x of { (# p,q #) -> (p,q) }
             p = fst t
             q = snd t
         in ..body..
@@ -423,14 +423,18 @@ Indeed, the bindings can even be recursive.
        import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>);
        the <option>-XMagicHash</option> extension
        then allows you to <emphasis>refer</emphasis> to the <literal>Int&num;</literal>
-       that is now in scope.</para>
+       that is now in scope. Note that with this option, the meaning of <literal>x&num;y = 0</literal>
+       is changed: it defines a function <literal>x&num;</literal> taking a single argument <literal>y</literal>;
+        to define the operator <literal>&num;</literal>, put a space: <literal>x &num; y = 0</literal>.
+
+</para>
       <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>):
        <itemizedlist>
          <listitem><para> <literal>'x'&num;</literal> has type <literal>Char&num;</literal></para> </listitem>
          <listitem><para> <literal>&quot;foo&quot;&num;</literal> has type <literal>Addr&num;</literal></para> </listitem>
          <listitem><para> <literal>3&num;</literal> has type <literal>Int&num;</literal>. In general,
          any Haskell integer lexeme followed by a <literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
-            <literal>-0x3A&num;</literal> as well as <literal>32&num;</literal></para>.</listitem>
+            <literal>-0x3A&num;</literal> as well as <literal>32&num;</literal>.</para></listitem>
          <listitem><para> <literal>3&num;&num;</literal> has type <literal>Word&num;</literal>. In general,
          any non-negative Haskell integer lexeme followed by <literal>&num;&num;</literal>
              is a <literal>Word&num;</literal>. </para> </listitem>
@@ -440,6 +444,43 @@ Indeed, the bindings can even be recursive.
       </para>
    </sect2>
 
+    <sect2 id="negative-literals">
+      <title>Negative literals</title>
+      <para>
+          The literal <literal>-123</literal> is, according to
+          Haskell98 and Haskell 2010, desugared as
+          <literal>negate (fromInteger 123)</literal>.
+         The language extension <option>-XNegativeLiterals</option>
+         means that it is instead desugared as
+         <literal>fromInteger (-123)</literal>.
+      </para>
+
+      <para>
+      This can make a difference when the positive and negative range of 
+      a numeric data type don't match up.  For example, 
+      in 8-bit arithmetic -128 is representable, but +128 is not.
+      So <literal>negate (fromInteger 128)</literal> will elicit an 
+      unexpected integer-literal-overflow message.
+      </para>
+   </sect2>
+
+    <sect2 id="num-decimals">
+      <title>Fractional looking integer literals</title>
+      <para>
+          Haskell 2010 and Haskell 98 define floating literals with
+          the syntax <literal>1.2e6</literal>. These literals have the
+          type <literal>Fractional a => a</literal>.
+      </para>
+
+      <para>
+         The language extension <option>-XNumDecimals</option> allows
+         you to also use the floating literal syntax for instances of
+         <literal>Integral</literal>, and have values like
+         <literal>(1.2e6 :: Num a => a)</literal>
+      </para>
+   </sect2>
+
+
     <!-- ====================== HIERARCHICAL MODULES =======================  -->
 
 
@@ -623,7 +664,7 @@ qualifier list has just one element, a boolean expression.
 <para>
 View patterns are enabled by the flag <literal>-XViewPatterns</literal>.
 More information and examples of view patterns can be found on the
-<ulink url="http://hackage.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki
+<ulink url="http://ghc.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki
 page</ulink>.
 </para>
 
@@ -741,7 +782,7 @@ let {(x -> y) = e1 ;
 </programlisting>
 
 (For some amplification on this design choice see
-<ulink url="http://hackage.haskell.org/trac/ghc/ticket/4061">Trac #4061</ulink>.)
+<ulink url="http://ghc.haskell.org/trac/ghc/ticket/4061">Trac #4061</ulink>.)
 
 </para>
 </listitem>
@@ -808,6 +849,299 @@ y)</literal> will not be coalesced.
 
 </sect2>
 
+    <!-- ===================== Pattern synonyms ===================  -->
+
+<sect2 id="pattern-synonyms">
+<title>Pattern synonyms
+</title>
+
+<para>
+Pattern synonyms are enabled by the flag
+<literal>-XPatternSynonyms</literal>, which is required for both
+defining them <emphasis>and</emphasis> using them.  More information
+and examples of view patterns can be found on the <ulink
+url="http://ghc.haskell.org/trac/ghc/wiki/PatternSynonyms">Wiki
+page</ulink>.
+</para>
+
+<para>
+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:
+</para>
+
+<programlisting>
+data Type = App String [Type]
+</programlisting>
+
+<para>
+Here are some examples of using said representation.
+Consider a few types of the <literal>Type</literal> universe encoded
+like this:
+</para>
+
+<programlisting>
+  App "->" [t1, t2]          -- t1 -> t2
+  App "Int" []               -- Int
+  App "Maybe" [App "Int" []] -- Maybe Int
+</programlisting>
+
+<para>
+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
+<literal>Int</literal> type, respectively:
+</para>
+
+<programlisting>
+  collectArgs :: Type -> [Type]
+  collectArgs (App "->" [t1, t2]) = t1 : collectArgs t2
+  collectArgs _                   = []
+
+  isInt :: Type -> Bool
+  isInt (App "Int" []) = True
+  isInt _              = False
+</programlisting>
+
+<para>
+Matching on <literal>App</literal> directly is both hard to read and
+error prone to write. And the situation is even worse when the
+matching is nested:
+</para>
+
+<programlisting>
+  isIntEndo :: Type -> Bool
+  isIntEndo (App "->" [App "Int" [], App "Int" []]) = True
+  isIntEndo _                                       = False
+</programlisting>
+
+<para>
+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
+<literal>Type</literal> type):
+</para>
+
+<programlisting>
+  pattern Arrow t1 t2 = App "->"    [t1, t2]
+  pattern Int         = App "Int"   []
+  pattern Maybe t     = App "Maybe" [t]
+</programlisting>
+
+<para>
+Which enables us to rewrite our functions in a much cleaner style:
+</para>
+
+<programlisting>
+  collectArgs :: Type -> [Type]
+  collectArgs (Arrow t1 t2) = t1 : collectArgs t2
+  collectArgs _             = []
+
+  isInt :: Type -> Bool
+  isInt Int = True
+  isInt _   = False
+
+  isIntEndo :: Type -> Bool
+  isIntEndo (Arrow Int Int) = True
+  isIntEndo _               = False
+</programlisting>
+
+<para>
+  Note that in this example, the pattern synonyms
+  <literal>Int</literal> and <literal>Arrow</literal> can also be used
+  as expressions (they are <emphasis>bidirectional</emphasis>). This
+  is not necessarily the case: <emphasis>unidirectional</emphasis>
+  pattern synonyms can also be declared with the following syntax:
+</para>
+
+<programlisting>
+  pattern Head x &lt;- x:xs
+</programlisting>
+
+<para>
+In this case, <literal>Head</literal> <replaceable>x</replaceable>
+cannot be used in expressions, only patterns, since it wouldn't
+specify a value for the <replaceable>xs</replaceable> on the
+right-hand side.
+</para>
+
+<para>
+The semantics of a unidirectional pattern synonym declaration and
+usage are as follows:
+
+<itemizedlist>
+
+<listitem> Syntax:
+<para>
+A pattern synonym declaration can be either unidirectional or
+bidirectional. The syntax for unidirectional pattern synonyms is:
+</para>
+<programlisting>
+  pattern Name args &lt;- pat
+</programlisting>
+<para>
+  and the syntax for bidirectional pattern synonyms is:
+</para>
+<programlisting>
+  pattern Name args = pat
+</programlisting>
+<para>
+  Pattern synonym declarations can only occur in the top level of a
+  module. In particular, they are not allowed as local
+  definitions. Currently, they also don't work in GHCi, but that is a
+  technical restriction that will be lifted in later versions.
+</para>
+<para>
+  The name of the pattern synonym itself is in the same namespace as
+  proper data constructors. Either prefix or infix syntax can be
+  used. In export/import specifications, you have to prefix pattern
+  names with the <literal>pattern</literal> keyword, e.g.:
+</para>
+<programlisting>
+  module Example (pattern Single) where
+  pattern Single x = [x]
+</programlisting>
+</listitem>
+
+<listitem> Scoping:
+
+<para>
+  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 pattern synonyms, there is no
+  restriction on the right-hand side pattern.
+</para>
+
+<para>
+  Pattern synonyms cannot be defined recursively.
+</para>
+
+</listitem>
+
+<listitem> Typing:
+
+<para>
+  Given a pattern synonym definition of the form
+</para>
+<programlisting>
+  pattern P var1 var2 ... varN &lt;- pat
+</programlisting>
+<para>
+  it is assigned a <emphasis>pattern type</emphasis> of the form
+</para>
+<programlisting>
+  pattern CProv => P t1 t2 ... tN :: CReq => t
+</programlisting>
+<para>
+  where <replaceable>CProv</replaceable> and
+  <replaceable>CReq</replaceable> are type contexts, and
+  <replaceable>t1</replaceable>, <replaceable>t2</replaceable>, ...,
+  <replaceable>tN</replaceable> and <replaceable>t</replaceable> are
+  types.
+</para>
+
+<para>
+A pattern synonym of this type can be used in a pattern if the
+instatiated (monomorphic) type satisfies the constraints of
+<replaceable>CReq</replaceable>. In this case, it extends the context
+available in the right-hand side of the match with
+<replaceable>CProv</replaceable>, just like how an existentially-typed
+data constructor can extend the context.
+</para>
+
+<para>
+For example, in the following program:
+</para>
+<programlisting>
+{-# LANGUAGE PatternSynonyms, GADTs #-}
+module ShouldCompile where
+
+data T a where
+       MkT :: (Show b) => a -> b -> T a
+
+pattern ExNumPat x = MkT 42 x
+</programlisting>
+
+<para>
+the pattern type of <literal>ExNumPat</literal> is
+</para>
+
+<programlisting>
+pattern (Show b) => ExNumPat b :: (Num a, Eq a) => T a
+</programlisting>
+
+<para>
+  and so can be used in a function definition like the following:
+</para>
+
+<programlisting>
+  f :: (Num t, Eq t) => T t -> String
+  f (ExNumPat x) = show x
+</programlisting>
+
+<para>
+  For bidirectional pattern synonyms, uses as expressions have the type
+</para>
+<programlisting>
+  (CProv, CReq) => t1 -> t2 -> ... -> tN -> t
+</programlisting>
+
+<para>
+  So in the previous example, <literal>ExNumPat</literal>,
+  when used in an expression, has type
+</para>
+<programlisting>
+  ExNumPat :: (Show b, Num a, Eq a) => b -> T t
+</programlisting>
+
+</listitem>
+
+<listitem> Matching:
+
+<para>
+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, <literal>f</literal>
+and <literal>f'</literal> are equivalent:
+</para>
+
+<programlisting>
+pattern Pair x y &lt;- [x, y]
+
+f (Pair True True) = True
+f _                = False
+
+f' [x, y] | True &lt;- x, True &lt;- y = True
+f' _                                   = False
+</programlisting>
+
+<para>
+  Note that the strictness of <literal>f</literal> differs from that
+  of <literal>g</literal> defined below:
+</para>
+
+<programlisting>
+g [True, True] = True
+g _            = False
+
+*Main> f (False:undefined)
+*** Exception: Prelude.undefined
+*Main> g (False:undefined)
+False
+</programlisting>
+</listitem>
+</itemizedlist>
+</para>
+
+</sect2>
+
     <!-- ===================== n+k patterns ===================  -->
 
 <sect2 id="n-k-patterns">
@@ -1693,7 +2027,7 @@ has no non-bottom values.  For example:
   f x = case x of { }
 </programlisting>
 With dependently-typed features it is more useful
-(see <ulink url="http://hackage.haskell.org/trac/ghc/ticket/2431">Trac</ulink>).
+(see <ulink url="http://ghc.haskell.org/trac/ghc/ticket/2431">Trac</ulink>).
 For example, consider these two candidate definitions of <literal>absurd</literal>:
 <programlisting>
 data a :==: b where
@@ -1706,7 +2040,7 @@ absurd x = case x of {}      -- (B)
 We much prefer (B). Why? Because GHC can figure out that <literal>(True :~: False)</literal>
 is an empty type. So (B) has no partiality and GHC should be able to compile with
 <option>-fwarn-incomplete-patterns</option>.  (Though the pattern match checking is not
-yet clever enough to do that.
+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.
 </para>
@@ -1729,7 +2063,35 @@ which is roughly equivalent to
     ...
     _ | guardN -> exprN
 </programlisting>
-except that multi-way if-expressions do not alter the layout.
+</para>
+
+<para>Multi-way if expressions introduce a new layout context.  So the
+example above is equivalent to:
+<programlisting>
+  if { | guard1 -> expr1
+     ; | ...
+     ; | guardN -> exprN
+     }
+</programlisting>
+The following behaves as expected:
+<programlisting>
+  if | guard1 -> if | guard2 -> expr2
+                    | guard3 -> expr3
+     | guard4 -> expr4
+</programlisting>
+because layout translates it as
+<programlisting>
+  if { | guard1 -> if { | guard2 -> expr2
+                      ; | guard3 -> expr3
+                      }
+     ; | guard4 -> expr4
+     }
+</programlisting>
+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.
 </para>
 </sect2>
 
@@ -2075,6 +2437,36 @@ import safe qualified Network.Socket as NS
 
 </sect2>
 
+<sect2 id="explicit-namespaces">
+<title>Explicit namespaces in import/export</title>
+
+<para> In an import or export list, such as 
+<programlisting>
+  module M( f, (++) ) where ...
+    import N( f, (++) ) 
+    ...
+</programlisting>
+the entities <literal>f</literal> and <literal>(++)</literal> are <emphasis>values</emphasis>.
+However, with type operators (<xref linkend="type-operators"/>) it becomes possible
+to declare <literal>(++)</literal> as a <emphasis>type constructor</emphasis>.  In that
+case, how would you export or import it?
+</para>
+<para>
+The <option>-XExplicitNamespaces</option> extension allows you to prefix the name of 
+a type constructor in an import or export list with "<literal>type</literal>" to 
+disambiguate this case, thus:
+<programlisting>
+  module M( f, type (++) ) where ...
+    import N( f, type (++) ) 
+    ...
+  module N( f, type (++) ) where
+    data family a ++ b = L a | R b
+</programlisting>
+The extension <option>-XExplicitNamespaces</option>
+is implied by <option>-XTypeOperators</option> and (for some reason) by <option>-XTypeFamilies</option>.
+</para>
+</sect2>
+
 <sect2 id="syntax-stolen">
 <title>Summary of stolen syntax</title>
 
@@ -2161,8 +2553,7 @@ The following syntax is stolen:
 
       <varlistentry>
        <term>
-         <literal>?<replaceable>varid</replaceable></literal>,
-         <literal>%<replaceable>varid</replaceable></literal>
+         <literal>?<replaceable>varid</replaceable></literal>
           <indexterm><primary>implicit parameters</primary></indexterm>
        </term>
        <listitem><para>
@@ -2176,7 +2567,11 @@ The following syntax is stolen:
          <literal>[e|</literal>, <literal>[p|</literal>,
          <literal>[d|</literal>, <literal>[t|</literal>,
          <literal>$(</literal>,
-         <literal>$<replaceable>varid</replaceable></literal>
+         <literal>$$(</literal>,
+         <literal>[||</literal>,
+         <literal>[e||</literal>,
+         <literal>$<replaceable>varid</replaceable></literal>,
+         <literal>$$<replaceable>varid</replaceable></literal>
           <indexterm><primary>Template Haskell</primary></indexterm>
        </term>
        <listitem><para>
@@ -2186,7 +2581,7 @@ The following syntax is stolen:
 
       <varlistentry>
        <term>
-         <literal>[:<replaceable>varid</replaceable>|</literal>
+         <literal>[<replaceable>varid</replaceable>|</literal>
           <indexterm><primary>quasi-quotation</primary></indexterm>
        </term>
        <listitem><para>
@@ -2201,13 +2596,39 @@ The following syntax is stolen:
              <replaceable>string</replaceable><literal>&num;</literal>,
              <replaceable>integer</replaceable><literal>&num;</literal>,
              <replaceable>float</replaceable><literal>&num;</literal>,
-             <replaceable>float</replaceable><literal>&num;&num;</literal>,
-             <literal>(&num;</literal>, <literal>&num;)</literal>
+             <replaceable>float</replaceable><literal>&num;&num;</literal>
        </term>
        <listitem><para>
        Stolen by: <option>-XMagicHash</option>
          </para></listitem>
       </varlistentry>
+
+      <varlistentry>
+       <term>
+             <literal>(&num;</literal>, <literal>&num;)</literal>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XUnboxedTuples</option>
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+             <replaceable>varid</replaceable><literal>!</literal><replaceable>varid</replaceable>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XBangPatterns</option>
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>pattern</literal>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XPatternSynonyms</option>
+         </para></listitem>
+      </varlistentry>
     </variablelist>
 </para>
 </sect2>
@@ -2284,10 +2705,10 @@ to be written infix, very much like expressions.  More specifically:
   </para></listitem>
 <listitem><para>
   Types, and class constraints, can be written infix.  For example
-  <screen>
-       x :: Int :*: Bool
-        f :: (a :=: b) => a -> b
-  </screen>
+<screen>
+  x :: Int :*: Bool
+  f :: (a :=: b) => a -> b
+</screen>
   </para></listitem>
 <listitem><para>
   Back-quotes work
@@ -2313,6 +2734,58 @@ to be written infix, very much like expressions.  More specifically:
 </para>
 </sect2>
 
+<sect2 id="type-operators">
+<title>Type operators</title>
+<para>
+In types, an operator symbol like <literal>(+)</literal> is normally treated as a type
+<emphasis>variable</emphasis>, just like <literal>a</literal>.  Thus in Haskell 98 you can say
+<programlisting>
+type T (+) = ((+), (+))
+-- Just like: type T a = (a,a)
+
+f :: T Int -> Int
+f (x,y)= x
+</programlisting>
+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.
+</para>
+<para>
+The language <option>-XTypeOperators</option> changes this behaviour:
+<itemizedlist>
+<listitem><para>
+Operator symbols become type <emphasis>constructors</emphasis> rather than 
+type <emphasis>variables</emphasis>.
+</para></listitem>
+<listitem><para>
+Operator symbols in types can be written infix, both in definitions and uses. 
+for example:
+<programlisting>
+data a + b = Plus a b
+type Foo = Int + Bool
+</programlisting>
+</para></listitem>
+<listitem><para>
+There is now some potential ambiguity in import and export lists; for example
+if you write <literal>import M( (+) )</literal> do you mean the 
+<emphasis>function</emphasis> <literal>(+)</literal> or the 
+<emphasis>type constructor</emphasis> <literal>(+)</literal>?
+The default is the former, but with <option>-XExplicitNamespaces</option> (which is implied
+by <option>-XExplicitTypeOperators</option>) GHC allows you to specify the latter
+by preceding it with the keyword <literal>type</literal>, thus:
+<programlisting>
+import M( type (+) )
+</programlisting>
+See <xref linkend="explicit-namespaces"/>.
+</para></listitem>
+<listitem><para>
+The fixity of a type operator may be set using the usual fixity declarations
+but, as in <xref linkend="infix-tycons"/>, the function and type constructor share
+a single fixity.
+</para></listitem>
+</itemizedlist>
+</para>
+</sect2>
+
 <sect2 id="type-synonyms">
 <title>Liberalised type synonyms</title>
 
@@ -2388,24 +2861,21 @@ After expanding type synonyms, GHC does validity checking on types, looking for
 the following mal-formedness which isn't detected simply by kind checking:
 <itemizedlist>
 <listitem><para>
-Type constructor applied to a type involving for-alls.
-</para></listitem>
-<listitem><para>
-Unboxed tuple on left of an arrow.
+Type constructor applied to a type involving for-alls (if <literal>XImpredicativeTypes</literal>
+is off)
 </para></listitem>
 <listitem><para>
 Partially-applied type synonym.
 </para></listitem>
 </itemizedlist>
-So, for example,
-this will be rejected:
+So, for example, this will be rejected:
 <programlisting>
-  type Pr = (# Int, Int #)
+  type Pr = forall a. a
 
-  h :: Pr -> Int
-  h = ...
+  h :: [Pr]
+  h = ...
 </programlisting>
-because GHC does not allow  unboxed tuples on the left of a function arrow.
+because GHC does not allow type constructors applied to for-all types.
 </para>
 </sect2>
 
@@ -3284,8 +3754,16 @@ GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by
 </programlisting>
 The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
 <literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
-Note the following points:
+</para>
+<para>
+However, standalone deriving differs from a <literal>deriving</literal> clause in a number
+of important ways:
 <itemizedlist>
+<listitem><para>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 (<xref linkend="orphan-modules"/>).
+</para></listitem>
+
 <listitem><para>
 You must supply an explicit context (in the example the context is <literal>(Eq a)</literal>),
 exactly as you would in an ordinary instance declaration.
@@ -3294,12 +3772,6 @@ attached to a data type declaration, the context is inferred.)
 </para></listitem>
 
 <listitem><para>
-A <literal>deriving instance</literal> declaration
-must obey the same rules concerning form and termination as ordinary instance declarations,
-controlled by the same flags; see <xref linkend="instance-decls"/>.
-</para></listitem>
-
-<listitem><para>
 Unlike a <literal>deriving</literal>
 declaration attached to a <literal>data</literal> declaration, the instance can be more specific
 than the data type (assuming you also use
@@ -3321,6 +3793,8 @@ declaration attached to a <literal>data</literal> 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.)
+</para>
+<para>
 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:
 <programlisting>
@@ -3335,7 +3809,24 @@ data type declaration for <literal>T</literal>,
 because <literal>T</literal> is a GADT, but you <emphasis>can</emphasis> generate
 the instance declaration using stand-alone deriving.
 </para>
+<para>
+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 <literal>deriving</literal> clause
+the side-conditions are necessarily more conservative, but any error message
+may be more comprehensible.
+</para>
 </listitem>
+</itemizedlist></para>
+
+<para>
+In other ways, however, a standalone deriving obeys the same rules as ordinary deriving:
+<itemizedlist>
+<listitem><para>
+A <literal>deriving instance</literal> declaration
+must obey the same rules concerning form and termination as ordinary instance declarations,
+controlled by the same flags; see <xref linkend="instance-decls"/>.
+</para></listitem>
 
 <listitem>
 <para>The stand-alone syntax is generalised for newtypes in exactly the same
@@ -3353,9 +3844,8 @@ GHC always treats the <emphasis>last</emphasis> parameter of the instance
 
 </sect2>
 
-
-<sect2 id="deriving-typeable">
-<title>Deriving clause for extra classes (<literal>Typeable</literal>, <literal>Data</literal>, etc)</title>
+<sect2 id="deriving-extra">
+<title>Deriving instances of extra classes (<literal>Data</literal>, etc)</title>
 
 <para>
 Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type
@@ -3367,27 +3857,6 @@ classes <literal>Eq</literal>, <literal>Ord</literal>,
 <para>
 GHC extends this list with several more classes that may be automatically derived:
 <itemizedlist>
-<listitem><para> With <option>-XDeriveDataTypeable</option>, you can derive instances of the classes
-<literal>Typeable</literal>, and <literal>Data</literal>, defined in the library
-modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively.
-</para>
-<para>Since GHC 7.8.1, <literal>Typeable</literal> is kind-polymorphic (see
-<xref linkend="kind-polymorphism"/>) and can be derived for any datatype and
-type class. Instances for datatypes can be derived by attaching a
-<literal>deriving Typeable</literal> clause to the datatype declaration, or by
-using standalone deriving (see <xref linkend="stand-alone-deriving"/>).
-Instances for type classes can only be derived using standalone deriving.
-For data families, <literal>Typeable</literal> should only be derived for the
-uninstantiated family type; each instance will then automatically have a
-<literal>Typeable</literal> instance too.
-See also <xref linkend="auto-derive-typeable"/>.
-</para>
-<para>
-Also since GHC 7.8.1, handwritten (ie. not derived) instances of
-<literal>Typeable</literal> are forbidden, and will be ignored with a warning.
-</para>
-</listitem>
-
 <listitem><para> With <option>-XDeriveGeneric</option>, you can derive
 instances of the classes <literal>Generic</literal> and
 <literal>Generic1</literal>, defined in <literal>GHC.Generics</literal>.
@@ -3400,6 +3869,12 @@ the class <literal>Functor</literal>,
 defined in <literal>GHC.Base</literal>.
 </para></listitem>
 
+<listitem><para> With <option>-XDeriveDataTypeable</option>, you can derive instances of
+the class <literal>Data</literal>,
+defined in <literal>Data.Data</literal>.  See <xref linkend="deriving-typeable"/> for 
+deriving <literal>Typeable</literal>.
+</para></listitem>
+
 <listitem><para> With <option>-XDeriveFoldable</option>, you can derive instances of
 the class <literal>Foldable</literal>,
 defined in <literal>Data.Foldable</literal>.
@@ -3407,24 +3882,73 @@ defined in <literal>Data.Foldable</literal>.
 
 <listitem><para> With <option>-XDeriveTraversable</option>, you can derive instances of
 the class <literal>Traversable</literal>,
-defined in <literal>Data.Traversable</literal>.
+defined in <literal>Data.Traversable</literal>. Since the <literal>Traversable</literal>
+instance dictates the instances of <literal>Functor</literal> and 
+<literal>Foldable</literal>, you'll probably want to derive them too, so
+<option>-XDeriveTraversable</option> implies
+<option>-XDeriveFunctor</option> and <option>-XDeriveFoldable</option>.
 </para></listitem>
 </itemizedlist>
+You can also use a standalone deriving declaration instead
+(see <xref linkend="stand-alone-deriving"/>).
+</para>
+<para>
 In each case the appropriate class must be in scope before it
 can be mentioned in the <literal>deriving</literal> clause.
 </para>
 </sect2>
 
-<sect2 id="auto-derive-typeable">
-<title>Automatically deriving <literal>Typeable</literal> instances</title>
+<sect2 id="deriving-typeable">
+<title>Deriving <literal>Typeable</literal> instances</title>
 
-<para>
+<para>The class <literal>Typeable</literal> is very special:
+<itemizedlist>
+<listitem><para>
+<literal>Typeable</literal> is kind-polymorphic (see
+<xref linkend="kind-polymorphism"/>).
+</para></listitem>
+
+<listitem><para>
+Only derived instances of <literal>Typeable</literal> are allowed;
+i.e. handwritten instances are forbidden.  This ensures that the
+programmer cannot subert the type system by writing bogus instances.
+</para></listitem>
+
+<listitem><para>
+With <option>-XDeriveDataTypeable</option> 
+GHC allows you to derive instances of <literal>Typeable</literal> for data types or newtypes,
+using a <literal>deriving</literal> clause, or using 
+a standalone deriving declaration (<xref linkend="stand-alone-deriving"/>).
+</para></listitem>
+
+<listitem><para>
+With <option>-XDataKinds</option>, deriving <literal>Typeable</literal> for a data
+type (whether via a deriving clause or standalone deriving)
+also derives <literal>Typeable</literal> for the promoted data constructors (<xref linkend="promotion"/>).
+</para></listitem>
+
+<listitem><para>
+However, using standalone deriving, you can <emphasis>also</emphasis> derive
+a <literal>Typeable</literal> instance for a data family.
+You may not add a <literal>deriving(Typeable)</literal> clause to a
+<literal>data instance</literal> declaration; instead you must use a
+standalone deriving declaration for the data family.
+</para></listitem>
+
+<listitem><para>
+Using standalone deriving, you can <emphasis>also</emphasis> derive
+a <literal>Typeable</literal> instance for a type class.
+</para></listitem>
+
+<listitem><para>
 The flag <option>-XAutoDeriveTypeable</option> triggers the generation
-of derived <literal>Typeable</literal> instances for every datatype and type
-class declaration in the module it is used. It will also generate
-<literal>Typeable</literal> instances for any promoted data constructors
-(<xref linkend="promotion"/>). This flag implies
-<option>-XDeriveDataTypeable</option> (<xref linkend="deriving-typeable"/>).
+of derived <literal>Typeable</literal> instances for every datatype, data family, 
+and type class declaration in the module it is used, unless a manually-specified one is
+already provided.
+This flag implies <option>-XDeriveDataTypeable</option>.
+</para></listitem>
+</itemizedlist>
+
 </para>
 
 </sect2>
@@ -3460,7 +3984,7 @@ dictionary, only slower!
 </para>
 
 
-<sect3> <title> Generalising the deriving clause </title>
+<sect3 id="generalized-newtype-deriving"> <title> Generalising the deriving clause </title>
 <para>
 GHC now permits such instances to be derived instead,
 using the flag <option>-XGeneralizedNewtypeDeriving</option>,
@@ -3550,42 +4074,52 @@ the newtype and its representation.
 
 <sect3> <title> A more precise specification </title>
 <para>
-Derived instance declarations are constructed as follows. Consider the
-declaration (after expansion of any type synonyms)
+A derived instance is derived only for declarations of these forms (after expansion of any type synonyms)
 
 <programlisting>
-  newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
+  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)
 </programlisting>
-
 where
  <itemizedlist>
 <listitem><para>
-  The <literal>ci</literal> are partial applications of
-  classes of the form <literal>C t1'...tj'</literal>, where the arity of <literal>C</literal>
+<literal>v1..vn</literal> are type variables, and <literal>t</literal>, 
+<literal>s1..sk</literal>, <literal>t1..tj</literal> are types.
+</para></listitem>
+<listitem><para>
+  The <literal>(C t1..tj)</literal> is a partial applications of the class <literal>C</literal>,
+  where the arity of <literal>C</literal>
   is exactly <literal>j+1</literal>.  That is, <literal>C</literal> lacks exactly one type argument.
 </para></listitem>
 <listitem><para>
-  The <literal>k</literal> is chosen so that <literal>ci (T v1...vk)</literal> is well-kinded.
+  <literal>k</literal> is chosen so that <literal>C t1..tj (T v1...vk)</literal> is well-kinded.
+(Or, in the case of a <literal>data instance</literal>, so that <literal>C t1..tj (T s1..sk)</literal> is
+well kinded.)
 </para></listitem>
 <listitem><para>
   The type <literal>t</literal> is an arbitrary type.
 </para></listitem>
 <listitem><para>
-  The type variables <literal>vk+1...vn</literal> do not occur in <literal>t</literal>,
-  nor in the <literal>ci</literal>, and
+  The type variables <literal>vk+1...vn</literal> do not occur in the types <literal>t</literal>,
+  <literal>s1..sk</literal>, or <literal>t1..tj</literal>.
 </para></listitem>
 <listitem><para>
-  None of the <literal>ci</literal> is <literal>Read</literal>, <literal>Show</literal>,
+  <literal>C</literal> is not <literal>Read</literal>, <literal>Show</literal>,
                <literal>Typeable</literal>, or <literal>Data</literal>.  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.
 </para></listitem>
+<listitem><para>
+  It is safe to coerce each of the methods of <literal>C</literal>. That is,
+  the missing last argument to <literal>C</literal> is not used
+  at a nominal role in any of the <literal>C</literal>'s methods.
+  (See <xref linkend="roles"/>.)</para></listitem>
 </itemizedlist>
-Then, for each <literal>ci</literal>, the derived instance
+Then the derived instance is of form
 declaration is:
 <programlisting>
-  instance ci t => ci (T v1...vk)
+  instance C t1..tj t => C t1..tj (T v1...vk)
 </programlisting>
 As an example which does <emphasis>not</emphasis> work, consider
 <programlisting>
@@ -3787,7 +4321,9 @@ We use default signatures to simplify generic programming in GHC
 
 <sect3 id="nullary-type-classes">
 <title>Nullary type classes</title>
-Nullary (no parameter) type classes are enabled with <option>-XNullaryTypeClasses</option>.
+Nullary (no parameter) type classes are enabled with
+<option>-XMultiTypeClasses</option>; historically, they were enabled with the
+(now deprecated) <option>-XNullaryTypeClasses</option>.
 Since there are no available parameters, there can be at most one instance
 of a nullary class. A nullary type class might be used to document some assumption
 in a type signature (such as reliance on the Riemann hypothesis) or add some
@@ -4416,21 +4952,33 @@ and <option>-XIncoherentInstances</option>
 <indexterm><primary>-XIncoherentInstances
 </primary></indexterm>, as this section discusses.  Both these
 flags are dynamic flags, and can be set on a per-module basis, using
-an <literal>OPTIONS_GHC</literal> pragma if desired (<xref linkend="source-file-options"/>).</para>
+an <literal>LANGUAGE</literal> pragma if desired (<xref linkend="language-pragma"/>).</para>
 <para>
 The <option>-XOverlappingInstances</option> flag instructs GHC to loosen
 the instance resolution described in <xref linkend="instance-resolution"/>, by
-allowing more than one instance to match, <emphasis>provided there is a most specific one</emphasis>.
+allowing more than one instance to match, <emphasis>provided there is a most
+specific one</emphasis>. The <option>-XIncoherentInstances</option> flag
+further loosens the resolution, by allowing more than one instance to match,
+irespective of whether there is a most specific one.
+</para>
+
+<para>
 For example, consider
 <programlisting>
-  instance context1 => C Int a     where ...  -- (A)
+  instance context1 => C Int b     where ...  -- (A)
   instance context2 => C a   Bool  where ...  -- (B)
-  instance context3 => C Int [a]   where ...  -- (C)
+  instance context3 => C a   [b]   where ...  -- (C)
   instance context4 => C Int [Int] where ...  -- (D)
 </programlisting>
-The constraint <literal>C Int [Int]</literal> matches instances (A),
-(C) and (D), but the last is more specific, and hence is chosen.  If there is no
-most-specific match, the program is rejected.
+compiled with <option>-XOverlappingInstances</option> enabled. The constraint
+<literal>C Int [Int]</literal> matches instances (A), (C) and (D), but the last
+is more specific, and hence is chosen.
+</para>
+<para>If (D) did not exist then (A) and (C) would still be matched, but neither is
+most specific. In that case, the program would be rejected even with
+<option>-XOverlappingInstances</option>. With
+<option>-XIncoherentInstances</option> enabled, it would be accepted and (A) or
+(C) would be chosen arbitrarily.
 </para>
 <para>
 An instance declaration is <emphasis>more specific</emphasis> than another iff
@@ -4445,15 +4993,15 @@ However, GHC is conservative about committing to an overlapping instance.  For e
   f x = ...
 </programlisting>
 Suppose that from the RHS of <literal>f</literal> we get the constraint
-<literal>C Int [b]</literal>.  But
+<literal>C b [b]</literal>.  But
 GHC does not commit to instance (C), because in a particular
 call of <literal>f</literal>, <literal>b</literal> might be instantiate
 to <literal>Int</literal>, in which case instance (D) would be more specific still.
 So GHC rejects the program.</para>
 <para>
-If, however, you add the flag <option>-XIncoherentInstances</option>,
-GHC will instead pick (C), without complaining about
-the problem of subsequent instantiations.
+If, however, you add the flag <option>-XIncoherentInstances</option> when
+compiling the module that contians (D), GHC will instead pick (C), without
+complaining about the problem of subsequent instantiations.
 </para>
 <para>
 Notice that we gave a type signature to <literal>f</literal>, so GHC had to
@@ -4463,7 +5011,7 @@ it instead.  In this case, GHC will refrain from
 simplifying the constraint <literal>C Int [b]</literal> (for the same reason
 as before) but, rather than rejecting the program, it will infer the type
 <programlisting>
-  f :: C Int [b] => [b] -> [b]
+  f :: C b [b] => [b] -> [b]
 </programlisting>
 That postpones the question of which instance to pick to the
 call site for <literal>f</literal>
@@ -4541,26 +5089,44 @@ The willingness to be overlapped or incoherent is a property of
 the <emphasis>instance declaration</emphasis> itself, controlled by the
 presence or otherwise of the <option>-XOverlappingInstances</option>
 and <option>-XIncoherentInstances</option> flags when that module is
-being defined.  Specifically, during the lookup process:
+being defined.  Suppose we are searching for an instance of the 
+<emphasis>target constraint</emphasis> <literal>(C ty1 .. tyn)</literal>.
+The search works like this.
 <itemizedlist>
 <listitem><para>
-If the constraint being looked up matches two instance declarations IA and IB,
-and
+Find all instances I that <emphasis>match</emphasis> the target constraint;
+that is, the target constraint is a substitution instance of I.  These
+instance declarations are the <emphasis>candidates</emphasis>.
+</para></listitem>
+
+<listitem><para>
+Find all <emphasis>non-candidate</emphasis> instances 
+that <emphasis>unify</emphasis> with the target constraint.
+Such non-candidates instances might match when the target constraint is further
+instantiated.  If all of them were compiled with
+<option>-XIncoherentInstances</option>, proceed; if not, the search fails.
+</para></listitem>
+
+<listitem><para>
+Eliminate any candidate IX for which both of the following hold:
+
 <itemizedlist>
-<listitem><para>IB is a substitution instance of IA (but not vice versa);
-that is, IB is strictly more specific than IA</para></listitem>
-<listitem><para>either IA or IB was compiled with <option>-XOverlappingInstances</option></para></listitem>
+<listitem><para>There is another candidate IY that is strictly more specific;
+that is, IY is a substitution instance of IX but not vice versa.
+</para></listitem>
+<listitem><para>Either IX or IY was compiled with 
+<option>-XOverlappingInstances</option>.
+</para></listitem>
 </itemizedlist>
-then the less-specific instance IA is ignored.
+
 </para></listitem>
+
 <listitem><para>
-Suppose an instance declaration does not match the constraint being looked up, but
-does <emphasis>unify</emphasis> with it, so that it might match when the constraint is further
-instantiated.  Usually GHC will regard this as a reason for not committing to
-some other constraint.  But if the instance declaration was compiled with
-<option>-XIncoherentInstances</option>, GHC will skip the "does-it-unify?"
-check for that declaration.
+If only one candidate remains, pick it.
+Otherwise if all remaining candidates were compiled with
+<option>-XInccoherentInstances</option>, pick an arbitrary candidate.
 </para></listitem>
+
 </itemizedlist>
 These rules make it possible for a library author to design a library that relies on
 overlapping instances without the library client having to know.
@@ -4757,7 +5323,7 @@ class IsList l where
   fromListN _ = fromList
 </programlisting>
 
-<para>The <literal>FromList</literal> class and its methods are intended to be
+<para>The <literal>IsList</literal> class and its methods are intended to be
 used in conjunction with the <option>OverloadedLists</option> extension.
 <itemizedlist>
 <listitem> <para> The type function
@@ -4789,32 +5355,32 @@ of <literal>IsList</literal>, so that list notation becomes
 useful for completely new data types.
 Here are several example instances:
 <programlisting>
-instance FromList [a] where
+instance IsList [a] where
   type Item [a] = a
   fromList = id
   toList = id
 
-instance (Ord a) => FromList (Set a) where
+instance (Ord a) => IsList (Set a) where
   type Item (Set a) = a
   fromList = Set.fromList
   toList = Set.toList
 
-instance (Ord k) => FromList (Map k v) where
+instance (Ord k) => IsList (Map k v) where
   type Item (Map k v) = (k,v)
   fromList = Map.fromList
   toList = Map.toList
 
-instance FromList (IntMap v) where
+instance IsList (IntMap v) where
   type Item (IntMap v) = (Int,v)
   fromList = IntMap.fromList
   toList = IntMap.toList
 
-instance FromList Text where
+instance IsList Text where
   type Item Text = Char
   fromList = Text.pack
   toList = Text.unpack
 
-instance FromList (Vector a) where
+instance IsList (Vector a) where
   type Item (Vector a) = a
   fromList  = Vector.fromList
   fromListN = Vector.fromListN
@@ -5354,7 +5920,7 @@ class Collects ce where
   type Elem ce :: *
   ...
 </programlisting>
-When doing so, we drop the "<literal>family</literal>" keyword.
+When doing so, we (optionally) may drop the "<literal>family</literal>" keyword.
 </para>
 <para>
        The type parameters must all be type variables, of course,
@@ -5375,7 +5941,7 @@ When doing so, we drop the "<literal>family</literal>" keyword.
       <title>Associated instances</title>
       <para>
        When an associated data or type synonym family instance is declared within a type
-       class instance, we drop the <literal>instance</literal> keyword in the
+       class instance, we (optionally) may drop the <literal>instance</literal> keyword in the
        family instance:
 <programlisting>
 instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
@@ -5429,14 +5995,16 @@ instance GMapKey Flob where
 <programlisting>
 class IsBoolMap v where
   type Key v
-  type Key v = Int
+  type instance Key v = Int
 
   lookupKey :: Key v -> v -> Maybe Bool
 
 instance IsBoolMap [(Int, Bool)] where
   lookupKey = lookup
 </programlisting>
-
+The <literal>instance</literal> keyword is optional.
+      </para>
+<para>
 There can also be multiple defaults for a single type, as long as they do not
 overlap:
 <programlisting>
@@ -5474,6 +6042,23 @@ instance C [c] d where
         type safety.
       </para>
     </sect3>
+
+    <sect3><title>Instance contexts and associated type and data instances</title>
+    <para>Associated type and data instance declarations do not inherit any
+          context specified on the enclosing instance. For type instance declarations,
+         it is unclear what the context would mean. For data instance declarations,
+         it is unlikely a user would want the context repeated for every data constructor.
+         The only place where the context might likely be useful is in a
+         <literal>deriving</literal> clause of an associated data instance. However,
+         even here, the role of the outer instance context is murky. So, for
+         clarity, we just stick to the rule above: the enclosing instance context
+         is ignored. If you need to use
+         a non-trivial context on a derived instance,
+         use a <link linkend="stand-alone-deriving">standalone
+         deriving</link> clause (at the top level).
+    </para>
+    </sect3>
+
   </sect2>
 
   <sect2 id="data-family-import-export">
@@ -5763,7 +6348,7 @@ very convenient, and it is not clear what the syntax for explicit quantification
 </para>
 </sect2>
 
-<sect2> <title>Polymorphic kind recursion and complete kind signatures</title>
+<sect2 id="complete-kind-signatures"> <title>Polymorphic kind recursion and complete kind signatures</title>
 
 <para>
 Just as in type inference, kind inference for recursive types can only use <emphasis>monomorphic</emphasis> recursion.
@@ -5808,14 +6393,21 @@ you must use GADT syntax.
 </para></listitem>
 
 <listitem><para>
-A type or data family declaration <emphasis>always</emphasis> have a
+An open type or data family declaration <emphasis>always</emphasis> has a
 complete user-specified kind signature; no "<literal>::</literal>" is required:
 <programlisting>
 data family D1 a               -- D1 :: * -> *
 data family D2 (a :: k)        -- D2 :: forall k. k -> *
 data family D3 (a :: k) :: *    -- D3 :: forall k. k -> *
 type family S1 a :: k -> *      -- S1 :: forall k. * -> k -> *
+
+class C a where                 -- C  :: k -> Constraint
+  type AT a b                   -- AT :: k -> * -> *
 </programlisting>
+In the last example, the variable <literal>a</literal> has an implicit kind
+variable annotation from the class declaration. It keeps its polymorphic kind
+in the associated type declaration. The variable <literal>b</literal>, however,
+gets defaulted to <literal>*</literal>.
 </para></listitem>
 </itemizedlist>
 In a complete user-specified kind signature, any un-decorated type variable to the
@@ -5824,6 +6416,68 @@ If you want kind polymorphism, specify a kind variable.
 </para>
 
 </sect2>
+
+<sect2><title>Kind inference in closed type families</title>
+
+<para>Although all open type families are considered to have a complete
+user-specified kind signature, we can relax this condition for closed type
+families, where we have equations on which to perform kind inference. GHC will
+infer a kind for any type variable in a closed type family when that kind is
+never used in pattern-matching. If you want a kind variable to be used in
+pattern-matching, you must declare it explicitly.
+</para>
+
+<para>
+Here are some examples (assuming <literal>-XDataKinds</literal> is enabled):
+<programlisting>
+type family Not a where      -- Not :: Bool -> Bool
+  Not False = True
+  Not True  = False
+
+type family F a where        -- ERROR: requires pattern-matching on a kind variable
+  F Int   = Bool
+  F Maybe = Char
+
+type family G (a :: k) where -- G :: k -> *
+  G Int   = Bool
+  G Maybe = Char
+
+type family SafeHead where   -- SafeHead :: [k] -> Maybe k
+  SafeHead '[] = Nothing     -- note that k is not required for pattern-matching
+  SafeHead (h ': t) = Just h
+</programlisting>
+</para>
+
+</sect2>
+
+<sect2><title>Kind inference in class instance declarations</title>
+
+<para>Consider the following example of a poly-kinded class and an instance for it:</para>
+
+<programlisting>
+class C a where
+  type F a
+
+instance C b where
+  type F b = b -> b
+</programlisting>
+
+<para>In the class declaration, nothing constrains the kind of the type
+<literal>a</literal>, so it becomes a poly-kinded type variable <literal>(a :: k)</literal>.
+Yet, in the instance declaration, the right-hand side of the associated type instance
+<literal>b -> b</literal> says that <literal>b</literal> must be of kind <literal>*</literal>. GHC could theoretically propagate this information back into the instance head, and
+make that instance declaration apply only to type of kind <literal>*</literal>, as opposed
+to types of any kind. However, GHC does <emphasis>not</emphasis> do this.</para>
+
+<para>In short: GHC does <emphasis>not</emphasis> propagate kind information from
+the members of a class instance declaration into the instance declaration head.</para>
+
+<para>This lack of kind inference is simply an engineering problem within GHC, but
+getting it to work would make a substantial change to the inference infrastructure,
+and it's not clear the payoff is worth it. If you want to restrict <literal>b</literal>'s
+kind in the instance above, just use a kind signature in the instance head.</para>
+
+</sect2>
 </sect1>
 
 <sect1 id="promotion">
@@ -5978,14 +6632,78 @@ Note that this requires <option>-XTypeOperators</option>.
 </para>
 </sect2>
 
-<sect2 id="promoted-literals">
-<title>Promoted Literals</title>
+<sect2 id="promotion-existentials">
+<title>Promoting existential data constructors</title>
 <para>
-Numeric and string literals are promoted to the type level, giving convenient
-access to a large number of predefined type-level constants.  Numeric literals
-are of kind <literal>Nat</literal>, while string literals are of kind
-<literal>Symbol</literal>.  These kinds are defined in the module
-<literal>GHC.TypeLits</literal>.
+Note that we do promote existential data constructors that are otherwise suitable.
+For example, consider the following:
+<programlisting>
+data Ex :: * where
+  MkEx :: forall a. a -> Ex
+</programlisting>
+Both the type <literal>Ex</literal> and the data constructor <literal>MkEx</literal>
+get promoted, with the polymorphic kind <literal>'MkEx :: forall k. k -> Ex</literal>.
+Somewhat surprisingly, you can write a type family to extract the member
+of a type-level existential:
+<programlisting>
+type family UnEx (ex :: Ex) :: k
+type instance UnEx (MkEx x) = x
+</programlisting>
+At first blush, <literal>UnEx</literal> seems poorly-kinded. The return kind
+<literal>k</literal> is not mentioned in the arguments, and thus it would seem
+that an instance would have to return a member of <literal>k</literal>
+<emphasis>for any</emphasis> <literal>k</literal>. However, this is not the
+case. The type family <literal>UnEx</literal> is a kind-indexed type family.
+The return kind <literal>k</literal> is an implicit parameter to <literal>UnEx</literal>.
+The elaborated definitions are as follows:
+<programlisting>
+type family UnEx (k :: BOX) (ex :: Ex) :: k
+type instance UnEx k (MkEx k x) = x
+</programlisting>
+Thus, the instance triggers only when the implicit parameter to <literal>UnEx</literal>
+matches the implicit parameter to <literal>MkEx</literal>. Because <literal>k</literal>
+is actually a parameter to <literal>UnEx</literal>, the kind is not escaping the
+existential, and the above code is valid.
+</para>
+
+<para>
+See also <ulink url="http://ghc.haskell.org/trac/ghc/ticket/7347">Trac #7347</ulink>.
+</para>
+</sect2>
+
+<sect2>
+<title>Promoting type operators</title>
+<para>
+Type operators are <emphasis>not</emphasis> promoted to the kind level. Why not? Because
+<literal>*</literal> is a kind, parsed the way identifiers are. Thus, if a programmer
+tried to write <literal>Either * Bool</literal>, would it be <literal>Either</literal>
+applied to <literal>*</literal> and <literal>Bool</literal>? Or would it be
+<literal>*</literal> applied to <literal>Either</literal> and <literal>Bool</literal>.
+To avoid this quagmire, we simply forbid promoting type operators to the kind level.
+</para>
+</sect2>
+
+
+</sect1>
+
+<sect1 id="type-level-literals">
+<title>Type-Level Literals</title>
+<para>
+GHC supports numeric and string literals at the type level, giving convenient
+access to a large number of predefined type-level constants.
+Numeric literals are of kind <literal>Nat</literal>, while string literals
+are of kind <literal>Symbol</literal>.
+This feature is enabled by the <literal>XDataKinds</literal>
+language extension.
+</para>
+
+<para>
+The kinds of the literals and all other low-level operations for this feature
+are defined in module <literal>GHC.TypeLits</literal>. Note that the module
+defines some type-level operators that clash with their value-level
+counterparts (e.g. <literal>(+)</literal>).  Import and export declarations
+referring to these operators require an explicit namespace
+annotation (see <xref linkend="explicit-namespaces"/>).
 </para>
 
 <para>
@@ -6020,44 +6738,84 @@ instance Has Point "y" Int where from (Point _ y) _ = y
 example = from (Point 1 2) (Get :: Label "x")
 </programlisting>
 </para>
-</sect2>
 
-<sect2 id="promotion-existentials">
-<title>Promoting existential data constructors</title>
+<sect2 id="typelit-runtime">
+<title>Runtime Values for Type-Level Literals</title>
 <para>
-Note that we do promote existential data constructors that are otherwise suitable.
-For example, consider the following:
+Sometimes it is useful to access the value-level literal assocaited with
+a type-level literal.  This is done with the functions
+<literal>natVal</literal> and <literal>symbolVal</literal>. For example:
 <programlisting>
-data Ex :: * where
-  MkEx :: forall a. a -> Ex
+GHC.TypeLits> natVal (Proxy :: Proxy 2)
+2
 </programlisting>
-Both the type <literal>Ex</literal> and the data constructor <literal>MkEx</literal>
-get promoted, with the polymorphic kind <literal>'MkEx :: forall k. k -> Ex</literal>.
-Somewhat surprisingly, you can write a type family to extract the member
-of a type-level existential:
+These functions are overloaded because they need to return a different
+result, depending on the type at which they are instantiated.
 <programlisting>
-type family UnEx (ex :: Ex) :: k
-type instance UnEx (MkEx x) = x
+natVal :: KnownNat n => proxy n -> Integer
+
+-- instance KnownNat 0
+-- instance KnownNat 1
+-- instance KnownNat 2
+-- ...
 </programlisting>
-At first blush, <literal>UnEx</literal> seems poorly-kinded. The return kind
-<literal>k</literal> is not mentioned in the arguments, and thus it would seem
-that an instance would have to return a member of <literal>k</literal>
-<emphasis>for any</emphasis> <literal>k</literal>. However, this is not the
-case. The type family <literal>UnEx</literal> is a kind-indexed type family.
-The return kind <literal>k</literal> is an implicit parameter to <literal>UnEx</literal>.
-The elaborated definitions are as follows:
+GHC discharges the constraint as soon as it knows what concrete
+type-level literal is being used in the program.  Note that this works
+only for <emphasis>literals</emphasis> and not arbitrary type expressions.
+For example, a constraint of the form <literal>KnownNat (a + b)</literal>
+will <emphasis>not</emphasis> be simplified to
+<literal>(KnownNat a, KnownNat b)</literal>; instead, GHC will keep the
+constraint as is, until it can simplify <literal>a + b</literal> to
+a constant value.
+</para>
+</sect2>
+
+<para>
+It is also possible to convert a run-time integer or string value to
+the corresponding type-level literal.  Of course, the resulting type
+literal will be unknown at compile-time, so it is hidden in an existential
+type.   The conversion may be performed using <literal>someNatVal</literal>
+for integers and <literal>someSymbolVal</literal> for strings:
 <programlisting>
-type family UnEx (k :: BOX) (ex :: Ex) :: k
-type instance UnEx k (MkEx k x) = x
+someNatVal :: Integer -> Maybe SomeNat
+SomeNat    :: KnownNat n => Proxy n -> SomeNat
+</programlisting>
+The operations on strings are similar.
+</para>
+
+<sect2 id="typelit-tyfuns">
+<title>Computing With Type-Level Naturals</title>
+<para>
+GHC 7.8 can evaluate arithmetic expressions involving type-level natural
+numbers.  Such expressions may be constructed using the type-families
+<literal>(+), (*), (^)</literal> for addition, multiplication,
+and exponentiation.  Numbers may be compared using <literal>(&lt;=?)</literal>,
+which returns a promoted boolean value, or <literal>(&lt;=)</literal>, which
+compares numbers as a constraint.  For example:
+<programlisting>
+GHC.TypeLits> natVal (Proxy :: Proxy (2 + 3))
+5
 </programlisting>
-Thus, the instance triggers only when the implicit parameter to <literal>UnEx</literal>
-matches the implicit parameter to <literal>MkEx</literal>. Because <literal>k</literal>
-is actually a parameter to <literal>UnEx</literal>, the kind is not escaping the
-existential, and the above code is valid.
+</para>
+<para>
+At present, GHC is quite limited in its reasoning about arithmetic:
+it will only evalute the arithmetic type functions and compare the results---
+in the same way that it does for any other type function.  In particular,
+it does not know more general facts about arithmetic, such as the commutativity
+and associativity of <literal>(+)</literal>, for example.
 </para>
 
 <para>
-See also <ulink url="http://hackage.haskell.org/trac/ghc/ticket/7347">Trac #7347</ulink>.
+However, it is possible to perform a bit of "backwards" evaluation.
+For example, here is how we could get GHC to compute arbitrary logarithms
+at the type level:
+<programlisting>
+lg :: Proxy base -> Proxy (base ^ pow) -> Proxy pow
+lg _ _ = Proxy
+
+GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8))
+3
+</programlisting>
 </para>
 </sect2>
 
@@ -6105,6 +6863,21 @@ class (F a ~ b) => C a b where
       with the class head.  Method signatures are not affected by that
       process.
     </para>
+
+  <sect2 id="coercible">
+  <title>The <literal>Coercible</literal> constraint</title>
+  <para>
+  The constraint <literal>Coercible t1 t2</literal> is similar to <literal>t1 ~
+  t2</literal>, but denotes representational equality between
+  <literal>t1</literal> and <literal>t2</literal> in the sense of Roles
+  (<xref linkend="roles"/>). It is exported by
+  <ulink url="&libraryBaseLocation;/Data-Coerce.html"><literal>Data.Coerce</literal></ulink>,
+  which also contains the documentation. More details and discussion can be found in
+  the paper
+  <ulink href="http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf">Safe Coercions"</ulink>.
+  </para>
+  </sect2>
+
   </sect1>
 
 <sect1 id="constraint-kind">
@@ -6145,9 +6918,10 @@ class (F a ~ b) => C a b where
                        type <literal>(Show a, Ord a)</literal> is of kind <literal>Constraint</literal>.
                </listitem>
                <listitem>
-                       Anything whose form is not yet know, but the user has declared to have kind <literal>Constraint</literal>.
-                       So for example <literal>type Foo (f :: * -> Constraint) = forall b. f b => b -> b</literal> is allowed, as
-                       well as examples involving type families:
+                       Anything whose form is not yet know, but the user has declared to have kind <literal>Constraint</literal>
+                       (for which they need to import it from <literal>GHC.Exts</literal>).  So for example
+                       <literal>type Foo (f :: * -> Constraint) = forall b. f b => b -> b</literal> is allowed, as well as
+                       examples involving type families:
 <programlisting>
 type family Typ a b :: Constraint
 type instance Typ Int  b = Show b
@@ -6230,7 +7004,7 @@ a type variable any more!
 The <option>-XFlexibleContexts</option> flag lifts the Haskell 98 restriction
 that the type-class constraints in a type signature must have the
 form <emphasis>(class type-variable)</emphasis> or
-<emphasis>(class (type-variable type-variable ...))</emphasis>.
+<emphasis>(class (type-variable type1 type2 ... typen))</emphasis>.
 With <option>-XFlexibleContexts</option>
 these type signatures are perfectly OK
 <programlisting>
@@ -6241,106 +7015,119 @@ The flag <option>-XFlexibleContexts</option> also lifts the corresponding
 restriction on class declarations (<xref linkend="superclass-rules"/>) and instance declarations
 (<xref linkend="instance-rules"/>).
 </para>
+</sect2>
 
-<para>
-GHC imposes the following restrictions on the constraints in a type signature.
-Consider the type:
+<sect2 id="ambiguity"><title>Ambiguous types and the ambiguity check</title>
 
+<para>
+Each user-written type signature is subjected to an
+<emphasis>ambiguity check</emphasis>.  
+The ambiguity check rejects functions that can never be called; for example:
 <programlisting>
-  forall tv1..tvn (c1, ...,cn) => type
+   f :: C a => Int
 </programlisting>
-
-(Here, we write the "foralls" explicitly, although the Haskell source
-language omits them; in Haskell 98, all the free type variables of an
-explicit source-language type signature are universally quantified,
-except for the class type variables in a class declaration.  However,
-in GHC, you can give the foralls if you want.  See <xref linkend="explicit-foralls"/>).
+The idea is there can be no legal calls to <literal>f</literal> because every call will
+give rise to an ambiguous constraint.  
+Indeed, the <emphasis>only</emphasis> purpose of the
+ambiguity check is to report functions that cannot possibly be called.
+We could soundly omit the
+ambiguity check on type signatures entirely, at the expense of
+delaying ambiguity errors to call sites.  Indeed, the language extension
+<option>-XAllowAmbiguousTypes</option> switches off the ambiguity check.
 </para>
-
-<para>
-
-<orderedlist>
-<listitem>
-
 <para>
- <emphasis>Each universally quantified type variable
-<literal>tvi</literal> must be reachable from <literal>type</literal></emphasis>.
-
-A type variable <literal>a</literal> is "reachable" if it appears
-in the same constraint as either a type variable free in
-<literal>type</literal>, or another reachable type variable.
-A value with a type that does not obey
-this reachability restriction cannot be used without introducing
-ambiguity; that is why the type is rejected.
-Here, for example, is an illegal type:
-
-
+Ambiguity can be subtle.  Consider this example which uses functional dependencies:
 <programlisting>
-  forall a. Eq a => Int
+   class D a b | a -> b where ..
+   h :: D Int b => Int 
 </programlisting>
-
-
-When a value with this type was used, the constraint <literal>Eq tv</literal>
-would be introduced where <literal>tv</literal> is a fresh type variable, and
-(in the dictionary-translation implementation) the value would be
-applied to a dictionary for <literal>Eq tv</literal>.  The difficulty is that we
-can never know which instance of <literal>Eq</literal> to use because we never
-get any more information about <literal>tv</literal>.
-</para>
-<para>
-Note
-that the reachability condition is weaker than saying that <literal>a</literal> is
-functionally dependent on a type variable free in
-<literal>type</literal> (see <xref
-linkend="functional-dependencies"/>).  The reason for this is there
-might be a "hidden" dependency, in a superclass perhaps.  So
-"reachable" is a conservative approximation to "functionally dependent".
-For example, consider:
+The <literal>Int</literal> may well fix <literal>b</literal> at the call site, so that signature should
+not be rejected.  Moreover, the dependencies might be hidden. Consider
+<programlisting>
+   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
+</programlisting>
+Here <literal>h</literal>'s type looks ambiguous in <literal>b</literal>, but here's a legal call:
 <programlisting>
-  class C a b | a -> b where ...
-  class C a b => D a b where ...
-  f :: forall a b. D a b => a -> a
+   ...(h [True])...
 </programlisting>
-This is fine, because in fact <literal>a</literal> does functionally determine <literal>b</literal>
-but that is not immediately apparent from <literal>f</literal>'s type.
+That gives rise to a <literal>(X [Bool] beta)</literal> constraint, and using the
+instance means we need <literal>(D Bool beta)</literal> and that 
+fixes <literal>beta</literal> via <literal>D</literal>'s
+fundep!
 </para>
-</listitem>
-<listitem>
-
 <para>
- <emphasis>Every constraint <literal>ci</literal> must mention at least one of the
-universally quantified type variables <literal>tvi</literal></emphasis>.
-
-For example, this type is OK because <literal>C a b</literal> mentions the
-universally quantified type variable <literal>b</literal>:
-
-
+Behind all these special cases there is a simple guiding principle. 
+Consider
 <programlisting>
-  forall a. C a b => burble
-</programlisting>
+  f :: <replaceable>type</replaceable>
+  f = ...blah...
 
+  g :: <replaceable>type</replaceable>
+  g = f
+</programlisting>
+You would think that the definition of <literal>g</literal> would surely typecheck!
+After all <literal>f</literal> has exactly the same type, and <literal>g=f</literal>. 
+But in fact <literal>f</literal>'s type
+is instantiated and the instantiated constraints are solved against
+the constraints bound by <literal>g</literal>'s signature.  So, in the case an ambiguous type, solving will fail.
+For example, consider the earlier definition <literal>f :: C a => Int</literal>:
+<programlisting>
+  f :: C a => Int
+  f = ...blah...
 
-The next type is illegal because the constraint <literal>Eq b</literal> does not
-mention <literal>a</literal>:
+  g :: C a => Int
+  g = f
+</programlisting>
+In <literal>g</literal>'s definition,
+we'll instantiate to <literal>(C alpha)</literal> and try to
+deduce <literal>(C alpha)</literal> from <literal>(C a)</literal>,
+and fail.
+</para>
+<para>
+So in fact we use this as our <emphasis>definition</emphasis> of ambiguity: a type
+<literal><replaceable>ty</replaceable></literal> is
+ambiguious if and only if <literal>((undefined :: <replaceable>ty</replaceable>)
+:: <replaceable>ty</replaceable>)</literal> would fail to typecheck.  We use a
+very similar test for <emphasis>inferred</emphasis> types, to ensure that they too are
+unambiguous.
+</para>
+<para><emphasis>Switching off the ambiguity check.</emphasis>
+Even if a function is has an ambiguous type according the "guiding principle",
+it is possible that the function is callable.  For example:
+<programlisting>
+  class D a b where ...
+  instance D Bool b where ...
 
+  strange :: D a b => a -> a
+  strange = ...blah...
 
+  foo = strange True
+</programlisting>
+Here <literal>strange</literal>'s type is ambiguous, but the call in <literal>foo</literal>
+is OK because it gives rise to a constraint <literal>(D Bool beta)</literal>, which is
+soluble by the <literal>(D Bool b)</literal> instance.  So the language extension
+<option>-XAllowAmbiguousTypes</option> allows you to switch off the ambiguity check.
+But even with ambiguity checking switched off, GHC will complain about a function
+that can <emphasis>never</emphasis> be called, such as this one:
 <programlisting>
-  forall a. Eq b => burble
+  f :: (Int ~ Bool) => a -> a
 </programlisting>
-
-
-The reason for this restriction is milder than the other one.  The
-excluded types are never useful or necessary (because the offending
-context doesn't need to be witnessed at this point; it can be floated
-out).  Furthermore, floating them out increases sharing. Lastly,
-excluding them is a conservative choice; it leaves a patch of
-territory free in case we need it later.
-
 </para>
-</listitem>
-
-</orderedlist>
 
+<para>
+<emphasis>A historical note.</emphasis>
+GHC used to impose some more restrictive and less principled conditions
+on type signatures. For type type
+<literal>forall tv1..tvn (c1, ...,cn) => type</literal>
+GHC used to require (a) that each universally quantified type variable
+<literal>tvi</literal> must be "reachable" from <literal>type</literal>, 
+and (b) that every constraint <literal>ci</literal> mentions at least one of the
+universally quantified type variables <literal>tvi</literal>.
+These ad-hoc restrictions are completely subsumed by the new ambiguity check.
+<emphasis>End of historical note.</emphasis>
 </para>
 
 </sect2>
@@ -6353,9 +7140,7 @@ territory free in case we need it later.
 J Lewis, MB Shields, E Meijer, J Launchbury,
 27th ACM Symposium on Principles of Programming Languages (POPL'00),
 Boston, Jan 2000.
-</para>
-
-<para>(Most of the following, still rather incomplete, documentation is
+(Most of the following, still rather incomplete, documentation is
 due to Jeff Lewis.)</para>
 
 <para>Implicit parameter support is enabled with the option
@@ -6746,7 +7531,11 @@ explicit context.  For example in the first argument of the
 constructor <function>MkSwizzle</function>, an implicit "<literal>forall a.</literal>" is
 prefixed to the argument type.  The implicit <literal>forall</literal>
 quantifies all type variables that are not already in scope, and are
-mentioned in the type quantified over.
+mentioned in the type quantified over. (Arguably, it would be better
+to <emphasis>require</emphasis> explicit quantification on constructor arguments
+where that is what is wanted.
+See <ulink url="http://ghc.haskell.org/trac/ghc/ticket/4426">Trac #4426</ulink>.)
+
 </para>
 
 <para>
@@ -6754,19 +7543,17 @@ As for type signatures, implicit quantification happens for non-overloaded
 types too.  So if you write this:
 
 <programlisting>
-  data T a = MkT (Either a b) (b -> b)
+  f :: (a -> a) -> a
 </programlisting>
 
 it's just as if you had written this:
 
 <programlisting>
-  data T a = MkT (forall b. Either a b) (forall b. b -> b)
+  f :: forall a. (a -> a) -> a
 </programlisting>
 
-That is, since the type variable <literal>b</literal> isn't in scope, it's
-implicitly universally quantified.  (Arguably, it would be better
-to <emphasis>require</emphasis> explicit quantification on constructor arguments
-where that is what is wanted.  Feedback welcomed.)
+That is, since the type variable <literal>a</literal> isn't in scope, it's
+implicitly universally quantified.
 </para>
 
 <para>
@@ -7257,7 +8044,8 @@ scope over the methods defined in the <literal>where</literal> part.  For exampl
 4.5.5</ulink>
 of the Haskell Report)
 can be completely switched off by
-<option>-XNoMonomorphismRestriction</option>.
+<option>-XNoMonomorphismRestriction</option>. Since GHC 7.8.1, the monomorphism
+restriction is switched off by default in GHCi.
 </para>
 </sect3>
 
@@ -7330,12 +8118,30 @@ pattern binding must have the same context.  For example, this is fine:
 <para>
 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 <option>-XMonoLocalBinds</option> GHC implements a slightly more conservative policy:
-<emphasis>it generalises only "closed" bindings</emphasis>.
-A binding is considered "closed" if either
+With the flag <option>-XMonoLocalBinds</option> GHC implements a slightly more conservative policy,
+using the following rules:
 <itemizedlist>
-<listitem><para>It is one of the top-level bindings of a module, or </para></listitem>
-<listitem><para>Its free variables are all themselves closed</para></listitem>
+  <listitem><para>
+  A variable is <emphasis>closed</emphasis> if and only if
+    <itemizedlist>
+    <listitem><para> the variable is let-bound</para></listitem>
+    <listitem><para> one of the following holds:
+          <itemizedlist>
+          <listitem><para>the variable has an explicit type signature that has no free type variables, or</para></listitem>
+          <listitem><para>its binding group is fully generalised (see next bullet) </para></listitem>
+         </itemizedlist>
+    </para></listitem>
+    </itemizedlist>
+  </para></listitem>
+
+  <listitem><para>
+  A binding group is <emphasis>fully generalised</emphasis> if and only if
+    <itemizedlist> 
+    <listitem><para>each of its free variables is either imported or closed, and</para></listitem>
+    <listitem><para>the binding is not affected by the monomorphism restriction 
+        (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Haskell Report, Section 4.5.5</ulink>)</para></listitem>
+    </itemizedlist>
+  </para></listitem>
 </itemizedlist>
 For example, consider
 <programlisting>
@@ -7344,18 +8150,21 @@ g x = let h y = f y * 2
           k z = z+x
       in  h x + k x
 </programlisting>
-Here <literal>f</literal> and <literal>g</literal> are closed because they are bound at top level.
-Also <literal>h</literal> is closed because its only free variable <literal>f</literal> is closed.
-But <literal>k</literal> is not closed because it mentions <literal>x</literal> which is locally bound.
-Another way to think of it is this: all closed bindings <literal>could</literal> be defined at top level.
-(In the example, we could move <literal>h</literal> to top level.)
-</para><para>
-All of this applies only to bindings that lack an explicit type signature, so that GHC has to
-infer its type.  If you supply a type signature, then that fixes type of the binding, end of story.
-</para><para>
+Here <literal>f</literal> is generalised because it has no free variables; and its binding group
+is unaffected by the monomorphism restriction; and hence <literal>f</literal> is closed.
+The same reasoning applies to <literal>g</literal>, except that it has one closed free variable, namely <literal>f</literal>.
+Similarly <literal>h</literal> is closed, <emphasis>even though it is not bound at top level</emphasis>,
+because its only free variable <literal>f</literal> is closed.
+But <literal>k</literal> is not closed, because it mentions <literal>x</literal> which is not closed (because it is not let-bound).
+</para>
+<para>
+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.
+</para>
+<para>
 The rationale for this more conservative strategy is given in
 <ulink url="http://research.microsoft.com/~simonpj/papers/constraints/index.htm">the papers</ulink> "Let should not be generalised" and "Modular type inference with local assumptions", and
-a related <ulink url="http://hackage.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7">blog post</ulink>.
+a related <ulink url="http://ghc.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7">blog post</ulink>.
 </para><para>
 The flag <option>-XMonoLocalBinds</option> is implied by <option>-XTypeFamilies</option> and <option>-XGADTs</option>.  You can switch it off again
 with <option>-XNoMonoLocalBinds</option> but type inference becomes less predicatable if you do so. (Read the papers!)
@@ -7363,24 +8172,17 @@ with <option>-XNoMonoLocalBinds</option> but type inference becomes less predica
 </sect3>
 </sect2>
 
-<sect2 id="type-holes">
-<title>Type Holes</title>
+</sect1>
+<!-- ==================== End of type system extensions =================  -->
 
-<para>Type hole support is enabled with the option
-<option>-XTypeHoles</option>.</para>
+<sect1 id="typed-holes">
+<title>Typed Holes</title>
 
-<para>
-The goal of the type holes extension is not to change the type system, but to help with writing Haskell
-code. Type holes can be used to obtain extra information from the type checker, which might otherwise be hard
-to get.
-Normally, the type checker is used to decide if a module is well typed or not. Using GHCi,
-users can inspect the (inferred) type signatures of all top-level bindings. However, determining the
-type of a single term is still hard. Yet while writing code, it could be helpful to know the type of
-the term you're about to write.
-</para>
+<para>Typed hole support is enabled with the option
+<option>-fwarn-typed-holes</option>, which is enabled by default.</para>
 
 <para>
-This extension allows special placeholders, written with a leading underscore (e.g. "<literal>_</literal>",
+This option allows special placeholders, written with a leading underscore (e.g. "<literal>_</literal>",
 "<literal>_foo</literal>", "<literal>_bar</literal>"), to be used as an expression.
 During compilation these holes will generate an error message describing what type is expected there,
 information about the origin of any free type variables, and a list of local bindings
@@ -7388,6 +8190,15 @@ that might help fill the hole with actual code.
 </para>
 
 <para>
+The goal of the typed holes warning is not to change the type system, but to help with writing Haskell
+code. Typed holes can be used to obtain extra information from the type checker, which might otherwise be hard
+to get.
+Normally, using GHCi, users can inspect the (inferred) type signatures of all top-level bindings.
+However, this method is less convenient with terms which are not defined on top-level or
+inside complex expressions. Holes allow to check the type of the term you're about to write.
+</para>
+
+<para>
 Holes work together well with <link linkend="defer-type-errors">deferring type errors to runtime</link>:
 with <literal>-fdefer-type-errors</literal>, the error from a hole is also deferred, effctively making the hole
 typecheck just like <literal>undefined</literal>, but with the added benefit that it will show its warning message
@@ -7415,15 +8226,15 @@ hole.hs:2:7:
 </para>
 
 <para>
-Multiple type holes can be used to find common type variables between expressions. For example:
+Multiple typed holes can be used to find common type variables between expressions. For example:
 <programlisting>
 sum :: [Int] -> Int
-sum xx = foldr _f _z xs
+sum xs = foldr _f _z xs
 </programlisting>
 Shows:
 <programlisting>
 holes.hs:2:15:
-    Found hole `_f' with type: Int-> Int -> Int
+    Found hole `_f' with type: Int -> Int -> Int
     In the first argument of `foldr', namely `_'
     In the expression: foldr _a _b _c
     In an equation for `sum': sum x = foldr _a _b _c
@@ -7462,15 +8273,13 @@ unbound.hs:1:13:
     In the second argument of `(:)', namely `_x'
     In the expression: _x : _x
     In an equation for `cons': cons = _x : _x
-Failed, modules loaded: none.
 </programlisting>
 This ensures that an unbound identifier is never reported with a too polymorphic type, like
 <literal>forall a. a</literal>, when used multiple times for types that can not be unified.
 </para>
 
-</sect2>
 </sect1>
-<!-- ==================== End of type system extensions =================  -->
+<!-- ==================== Deferring type errors =================  -->
 
 <sect1 id="defer-type-errors">
 <title>Deferring type errors to runtime</title>
@@ -7491,7 +8300,7 @@ main = print "b"
   </para>
   <para>
     For more motivation and details please refer to the <ulink
-      url="http://hackage.haskell.org/trac/ghc/wiki/DeferErrorsToRuntime">HaskellWiki</ulink>
+      url="http://ghc.haskell.org/trac/ghc/wiki/DeferErrorsToRuntime">HaskellWiki</ulink>
     page or the <ulink
       url="http://research.microsoft.com/en-us/um/people/simonpj/papers/ext-f/">original
       paper</ulink>.
@@ -7605,9 +8414,7 @@ Wiki page</ulink>.
       constructions.  You need to use the flag
       <option>-XTemplateHaskell</option>
        <indexterm><primary><option>-XTemplateHaskell</option></primary>
-      </indexterm>to switch these syntactic extensions on
-      (<option>-XTemplateHaskell</option> is no longer implied by
-      <option>-fglasgow-exts</option>).</para>
+      </indexterm>to switch these syntactic extensions on.</para>
 
        <itemizedlist>
              <listitem><para>
@@ -7621,12 +8428,13 @@ Wiki page</ulink>.
                  <itemizedlist>
                    <listitem><para> an expression; the spliced expression must
                    have type <literal>Q Exp</literal></para></listitem>
-                   <listitem><para> an type; the spliced expression must
-                   have type <literal>Q Typ</literal></para></listitem>
-                   <listitem><para> a list of top-level declarations; the spliced expression
+                   <listitem><para> a pattern; the spliced pattern must
+                   have type <literal>Q Pat</literal></para></listitem>
+                   <listitem><para> a type; the spliced expression must
+                   have type <literal>Q Type</literal></para></listitem>
+                   <listitem><para> a list of declarations; the spliced expression
                     must have type <literal>Q [Dec]</literal></para></listitem>
                    </itemizedlist>
-            Note that pattern splices are not supported.
             Inside a splice you can only call functions defined in imported modules,
            not functions defined elsewhere in the same module.</para></listitem>
 
@@ -7644,6 +8452,36 @@ Wiki page</ulink>.
                              the quotation has type <literal>Q Pat</literal>.</para></listitem>
                  </itemizedlist></para></listitem>
 
+             <listitem>
+               <para>
+                 A <emphasis>typed</emphasis> expression splice is written
+                 <literal>$$x</literal>, where <literal>x</literal> is an
+                 identifier, or <literal>$$(...)</literal>, where the "..." is
+                 an arbitrary expression.
+               </para>
+               <para>
+                 A typed expression splice can occur in place of an
+                 expression; the spliced expression must have type <literal>Q
+                 (TExp a)</literal>
+               </para>
+             </listitem>
+
+             <listitem>
+               <para>
+                 A <emphasis>typed</emphasis> expression quotation is written
+                 as <literal>[|| ... ||]</literal>, or <literal>[e||
+                 ... ||]</literal>, where the "..." is an expression; if the
+                 "..." expression has type <literal>a</literal>, then the
+                 quotation has type <literal>Q (TExp a)</literal>.
+               </para>
+
+               <para>
+                 Values of type <literal>TExp a</literal> may be converted to
+                 values of type <literal>Exp</literal> using the function
+                 <literal>unType :: TExp a -> Exp</literal>.
+               </para>
+             </listitem>
+
              <listitem><para>
                  A quasi-quotation can appear in either a pattern context or an
                  expression context and is also written in Oxford brackets:
@@ -7699,13 +8537,117 @@ h z = z-1
 </programlisting>
             This abbreviation makes top-level declaration slices quieter and less intimidating.
            </para></listitem>
+           
+           <listitem>
+             <para>
+               Binders are lexically scoped. For example, consider the
+               following code, where a value <literal>g</literal> of type
+               <literal>Bool -> Q Pat</literal> is in scope, having been
+               imported from another module
+<programlisting>
+y :: Int
+y = 7
+
+f :: Int -> Int -> Int
+f n = \ $(g True) -> y+n
+</programlisting>
+                The <literal>y</literal> in the right-hand side of
+                <literal>f</literal> refers to the top-level <literal>y =
+                7</literal>, even if the pattern splice <literal>$(g
+                n)</literal> also generates a binder <literal>y</literal>.
+             </para>
+
+             <para>
+               Note that a pattern quasiquoter <emphasis>may</emphasis>
+               generate binders that scope over the right-hand side of a
+               definition because these binders are in scope lexically. For
+               example, given a quasiquoter <literal>haskell</literal> that
+               parses Haskell, in the following code, the <literal>y</literal>
+               in the right-hand side of <literal>f</literal> refers to the
+               <literal>y</literal> bound by the <literal>haskell</literal>
+               pattern quasiquoter, <emphasis>not</emphasis> the top-level
+               <literal>y = 7</literal>.
+<programlisting>
+y :: Int
+y = 7
+
+f :: Int -> Int -> Int
+f n = \ [haskell|y|] -> y+n
+</programlisting>
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               The type environment seen by <literal>reify</literal> includes
+               all the top-level declaration up to the end of the immediately
+               preceding <emphasis>declaration group</emphasis>, but no more.
+             </para>
+
+             <para>
+               A <emphasis>declaration group</emphasis> is the group of
+               declarations created by a top-level declaration splice, plus
+               those following it, down to but not including the next top-level
+               declaration splice. The first declaration group in a module
+               includes all top-level definitions down to but not including the
+               first top-level declaration splice.
+             </para>
+
+
+             <para>
+               Concretely, consider the following code
+<programlisting>
+module M where
+   import ...
+   f x = x
+   $(th1 4)
+   h y = k y y $(blah1)
+   $(th2 10)
+   w z = $(blah2)
+</programlisting>
+
+              In this example
+              <orderedlist>
+               <listitem>
+                 <para>
+                   A <literal>reify</literal> inside the splice <literal>$(th1
+                   ..)</literal> would see the definition of
+                   <literal>f</literal>.
+                 </para>
+               </listitem>
+               <listitem>
+                 <para>
+                   A <literal>reify</literal> inside the splice
+                   <literal>$(blah1)</literal> would see the definition of
+                   <literal>f</literal>, but would not see the definition of
+                   <literal>h</literal>.
+                 </para>
+               </listitem>
+               <listitem>
+                 <para>
+                   A <literal>reify</literal> inside the splice
+                   <literal>$(th2..)</literal> would see the definition of
+                   <literal>f</literal>, all the bindings created by
+                   <literal>$(th1..)</literal>, and the definition of
+                   <literal>h</literal>.
+                 </para>
+               </listitem>
+               <listitem>
+                 <para>
+                   A <literal>reify</literal> inside the splice
+                   <literal>$(blah2)</literal> would see the same definitions
+                   as the splice <literal>$(th2...)</literal>.
+                 </para>
+               </listitem>
+              </orderedlist>
+             </para>
+           </listitem>
 
 
        </itemizedlist>
 (Compared to the original paper, there are many differences of detail.
 The syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>".
 The type of the enclosed expression must be  <literal>Q [Dec]</literal>, not  <literal>[Q Dec]</literal>.
-Pattern splices and quotations are not implemented.)
+Typed expression splices and quotations are supported.)
 
 </sect2>
 
@@ -7899,7 +8841,7 @@ as, say, using the string <literal>"|~]"</literal> instead), and make your
 quoter function interpret <literal>"|~]"</literal> as <literal>"|]"</literal>.
 One way to implement this is to compose your quoter with a pre-processing pass to
 perform your escape conversion.  See the
-<ulink url="http://hackage.haskell.org/trac/ghc/ticket/5348">
+<ulink url="http://ghc.haskell.org/trac/ghc/ticket/5348">
 discussion in Trac</ulink> for details.
 </para></listitem>
 </itemizedlist>
@@ -8284,7 +9226,7 @@ proc (x,y) ->
 which is translated to
 <screen>
 arr (\ (x,y) -> if f x y then Left x else Right y) >>>
-        (arr (\x -> x+1) >>> f) ||| (arr (\y -> y+2) >>> g)
+        (arr (\x -> x+1) >>> g) ||| (arr (\y -> y+2) >>> h)
 </screen>
 Since the translation uses <function>|||</function>,
 the arrow concerned must belong to the <literal>ArrowChoice</literal> class.
@@ -8577,7 +9519,7 @@ Because the preprocessor targets Haskell (rather than Core),
 patterns</emphasis>, written <literal>!<replaceable>pat</replaceable></literal>.
 Bang patterns are under consideration for Haskell Prime.
 The <ulink
-url="http://hackage.haskell.org/trac/haskell-prime/wiki/BangPatterns">Haskell
+url="http://ghc.haskell.org/trac/haskell-prime/wiki/BangPatterns">Haskell
 prime feature description</ulink> contains more discussion and examples
 than the material below.
 </para>
@@ -8825,7 +9767,9 @@ GHC ignores assertions when optimisation is turned on with the
 <literal>e</literal>.  You can also disable assertions using the
       <option>-fignore-asserts</option>
       option<indexterm><primary><option>-fignore-asserts</option></primary>
-      </indexterm>.</para>
+      </indexterm>.  The option <option>-fno-ignore-asserts</option> allows
+enabling assertions even when optimisation is turned on.
+</para>
 
 <para>
 Assertion failures can be caught, see the documentation for the
@@ -8905,7 +9849,7 @@ Assertion failures can be caught, see the documentation for the
 
       <para>Every language extension can also be turned into a command-line flag
        by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>.
-       (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.
+       (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.)
       </para>
 
       <para>A list of all supported language extensions can be obtained by invoking
@@ -9006,6 +9950,43 @@ Assertion failures can be caught, see the documentation for the
       <option>-fno-warn-warnings-deprecations</option>.</para>
     </sect2>
 
+    <sect2 id="minimal-pragma">
+      <title>MINIMAL pragma</title>
+      <indexterm><primary>MINIMAL</primary></indexterm>
+      <para>The MINIMAL pragma is used to specify the minimal complete definition of a class. I.e. specify which methods must be implemented by all instances. If an instance does not satisfy the minimal complete definition, then a warning is generated.
+      This can be useful when a class has methods with circular defaults. For example
+      </para>
+<programlisting>
+class Eq a where
+    (==) :: a -> a -> Bool
+    (/=) :: a -> a -> Bool
+    x == y = not (x /= y)
+    x /= y = not (x == y)
+    {-# MINIMAL (==) | (/=) #-}
+</programlisting>
+      <para>Without the MINIMAL pragma no warning would be generated for an instance that implements neither method.
+      </para>
+      <para>The syntax for minimal complete definition is:</para>
+<screen>
+mindef ::= name
+        |  '(' mindef ')'
+        |  mindef '|' mindef
+        |  mindef ',' mindef
+</screen>
+      <para>A vertical bar denotes disjunction, i.e. one of the two sides is required.
+      A comma denotes conjunction, i.e. both sides are required.
+      Conjunction binds stronger than disjunction.</para>
+      <para>
+      If no MINIMAL pragma is given in the class declaration, it is just as if 
+      a pragma <literal>{-# MINIMAL op1, op2, ..., opn #-}</literal> was given, where
+      the <literal>opi</literal> are the methods 
+      (a) that lack a default method in the class declaration, and 
+      (b) whose name that does not start with an underscore  
+      (c.f. <option>-fwarn-missing-methods</option>, <xref linkend="options-sanity"/>).
+      </para>
+      <para>This warning can be turned off with the flag <option>-fno-warn-missing-methods</option>.</para>
+    </sect2>
+
     <sect2 id="inline-noinline-pragma">
       <title>INLINE and NOINLINE pragmas</title>
 
@@ -9016,13 +9997,32 @@ Assertion failures can be caught, see the documentation for the
        <title>INLINE pragma</title>
        <indexterm><primary>INLINE</primary></indexterm>
 
-       <para>GHC (with <option>-O</option>, as always) tries to
-        inline (or &ldquo;unfold&rdquo;) functions/values that are
-        &ldquo;small enough,&rdquo; thus avoiding the call overhead
-        and possibly exposing other more-wonderful optimisations.
-        Normally, if GHC decides a function is &ldquo;too
-        expensive&rdquo; to inline, it will not do so, nor will it
-        export that unfolding for other modules to use.</para>
+        <para>
+          GHC (with <option>-O</option>, as always) tries to inline
+          (or &ldquo;unfold&rdquo;) functions/values that are
+          &ldquo;small enough,&rdquo; thus avoiding the call overhead
+          and possibly exposing other more-wonderful optimisations.
+          GHC has a set of heuristics, tuned over a long period of
+          time using many benchmarks, that decide when it is
+          beneficial to inline a function at its call site.  The
+          heuristics are designed to inline functions when it appears
+          to be beneficial to do so, but without incurring excessive
+          code bloat.  If a function looks too big, it won't be
+          inlined, and functions larger than a certain size will not
+          even have their definition exported in the interface file.
+          Some of the thresholds that govern these heuristic decisions
+          can be changed using flags, see <xref linkend="options-f"
+          />.
+        </para>
+
+        <para>
+          Normally GHC will do a reasonable job of deciding by itself
+          when it is a good idea to inline a function.  However,
+          sometimes you might want to override the default behaviour.
+          For example, if you have a key function that is important to
+          inline because it leads to further optimisations, but GHC
+          judges it to be too big to inline.
+        </para>
 
         <para>The sledgehammer you can bring to bear is the
         <literal>INLINE</literal><indexterm><primary>INLINE
@@ -9133,11 +10133,6 @@ itself, so an INLINE pragma is always ignored.</para>
         and <literal>INLINABLE</literal> (<xref linkend="inlinable-pragma"/>)
         pragmas.</para>
 
-       <para>Note: the HBC compiler doesn't like <literal>INLINE</literal> pragmas,
-         so if you want your code to be HBC-compatible you'll have to surround
-         the pragma with C pre-processor directives
-         <literal>#ifdef __GLASGOW_HASKELL__</literal>...<literal>#endif</literal>.</para>
-
       </sect3>
 
       <sect3 id="inlinable-pragma">
@@ -9543,10 +10538,6 @@ instance (Eq a) => Eq (Foo a) where {
 The pragma must occur inside the <literal>where</literal> part
 of the instance declaration.
 </para>
-<para>
-Compatible with HBC, by the way, except perhaps in the placement
-of the pragma.
-</para>
 
 </sect2>
 
@@ -9576,7 +10567,7 @@ data T = T {-# UNPACK #-} !Float
       conjunction with <option>-O</option><footnote>in fact, UNPACK
           has no effect without <option>-O</option>, for technical
           reasons
-      (see <ulink url="http://hackage.haskell.org/trac/ghc/ticket/5252">tick
+      (see <ulink url="http://ghc.haskell.org/trac/ghc/ticket/5252">tick
             5252</ulink>)</footnote>, in order to expose
       unfoldings to the compiler so the reboxing can be removed as
       often as possible.  For example:</para>
@@ -10293,69 +11284,6 @@ program even if fusion doesn't happen.  More rules in <filename>GHC/List.lhs</fi
 
 </sect2>
 
-<sect2 id="core-pragma">
-  <title>CORE pragma</title>
-
-  <indexterm><primary>CORE pragma</primary></indexterm>
-  <indexterm><primary>pragma, CORE</primary></indexterm>
-  <indexterm><primary>core, annotation</primary></indexterm>
-
-<para>
-  The external core format supports <quote>Note</quote> annotations;
-  the <literal>CORE</literal> pragma gives a way to specify what these
-  should be in your Haskell source code.  Syntactically, core
-  annotations are attached to expressions and take a Haskell string
-  literal as an argument.  The following function definition shows an
-  example:
-
-<programlisting>
-f x = ({-# CORE "foo" #-} show) ({-# CORE "bar" #-} x)
-</programlisting>
-
-  Semantically, this is equivalent to:
-
-<programlisting>
-g x = show x
-</programlisting>
-</para>
-
-<para>
-  However, when external core is generated (via
-  <option>-fext-core</option>), there will be Notes attached to the
-  expressions <function>show</function> and <varname>x</varname>.
-  The core function declaration for <function>f</function> is:
-</para>
-
-<programlisting>
-  f :: %forall a . GHCziShow.ZCTShow a ->
-                   a -> GHCziBase.ZMZN GHCziBase.Char =
-    \ @ a (zddShow::GHCziShow.ZCTShow a) (eta::a) ->
-        (%note "foo"
-         %case zddShow %of (tpl::GHCziShow.ZCTShow a)
-           {GHCziShow.ZCDShow
-            (tpl1::GHCziBase.Int ->
-                   a ->
-                   GHCziBase.ZMZN GHCziBase.Char -> GHCziBase.ZMZN GHCziBase.Cha
-r)
-            (tpl2::a -> GHCziBase.ZMZN GHCziBase.Char)
-            (tpl3::GHCziBase.ZMZN a ->
-                   GHCziBase.ZMZN GHCziBase.Char -> GHCziBase.ZMZN GHCziBase.Cha
-r) ->
-              tpl2})
-        (%note "bar"
-         eta);
-</programlisting>
-
-<para>
-  Here, we can see that the function <function>show</function> (which
-  has been expanded out to a case expression over the Show dictionary)
-  has a <literal>%note</literal> attached to it, as does the
-  expression <varname>eta</varname> (which used to be called
-  <varname>x</varname>).
-</para>
-
-</sect2>
-
 </sect1>
 
 <sect1 id="special-ids">
@@ -10364,11 +11292,11 @@ r) ->
 In particular:
 <itemizedlist>
 <listitem><para>
-<ulink url="&libraryGhcPrimLocation;/GHC-Exts.html#v%3Ainline"><literal>inline</literal></ulink>
+<ulink url="&libraryBaseLocation;/GHC-Exts.html#v%3Ainline"><literal>inline</literal></ulink>
 allows control over inlining on a per-call-site basis.
 </para></listitem>
 <listitem><para>
-<ulink url="&libraryGhcPrimLocation;/GHC-Exts.html#v%3Alazy"><literal>lazy</literal></ulink>
+<ulink url="&libraryBaseLocation;/GHC-Exts.html#v%3Alazy"><literal>lazy</literal></ulink>
 restrains the strictness analyser.
 </para></listitem>
 </itemizedlist>
@@ -10602,7 +11530,264 @@ Jose Pedro Magalhaes, Atze Dijkstra, Johan Jeuring, and Andres Loeh.
 
 </sect1>
 
+<sect1 id="roles">
+<title>Roles
+<indexterm><primary>roles</primary></indexterm>
+</title>
+
+<para>
+Using <option>-XGeneralizedNewtypeDeriving</option> (<xref
+linkend="generalized-newtype-deriving" />), a programmer can take existing
+instances of classes and "lift" these into instances of that class for a
+newtype. However, this is not always safe. For example, consider the following:
+</para>
+
+<programlisting>
+  newtype Age = MkAge { unAge :: Int }
+
+  type family Inspect x
+  type instance Inspect Age = Int
+  type instance Inspect Int = Bool
+
+  class BadIdea a where
+    bad :: a -> Inspect a
+
+  instance BadIdea Int where
+    bad = (> 0)
+
+  deriving instance BadIdea Age    -- not allowed!
+</programlisting>
+
+<para>
+If the derived instance were allowed, what would the type of its method
+<literal>bad</literal> be? It would seem to be <literal>Age -> Inspect
+Age</literal>, which is equivalent to <literal>Age -> Int</literal>, according
+to the type family <literal>Inspect</literal>. Yet, if we simply adapt the
+implementation from the instance for <literal>Int</literal>, the implementation
+for <literal>bad</literal> produces a <literal>Bool</literal>, and we have trouble.
+</para>
+
+<para>
+The way to identify such situations is to have <emphasis>roles</emphasis> assigned
+to type variables of datatypes, classes, and type synonyms.</para>
+
+<para>
+Roles as implemented in GHC are a from a simplified version of the work
+described in <ulink
+url="http://www.seas.upenn.edu/~sweirich/papers/popl163af-weirich.pdf">Generative
+type abstraction and type-level computation</ulink>, published at POPL 2011.</para>
+
+<sect2 id="nominal-representational-and-phantom">
+<title>Nominal, Representational, and Phantom</title>
+
+<para>The goal of the roles system is to track when two types have the same
+underlying representation. In the example above, <literal>Age</literal> and
+<literal>Int</literal> have the same representation. But, the corresponding
+instances of <literal>BadIdea</literal> would <emphasis>not</emphasis> have
+the same representation, because the types of the implementations of
+<literal>bad</literal> would be different.</para>
+
+<para>Suppose we have two uses of a type constructor, each applied to the same
+parameters except for one difference. (For example, <literal>T Age Bool
+c</literal> and <literal>T Int Bool c</literal> for some type
+<literal>T</literal>.) The role of a type parameter says what we need to
+know about the two differing type arguments in order to know that the two
+outer types have the same representation (in the example, what must be true
+about <literal>Age</literal> and <literal>Int</literal> in order to show that
+<literal>T Age Bool c</literal> has the same representation as <literal>
+T Int Bool c</literal>).</para>
 
+<para>GHC supports three different roles for type parameters: nominal,
+representational, and phantom. If a type parameter has a nominal role, then
+the two types that differ must not actually differ at all: they must be
+identical (after type family reduction). If a type parameter has a
+representational role, then the two types must have the same representation.
+(If <literal>T</literal>'s first parameter's role is representational, then
+<literal>T Age Bool c</literal> and <literal>T Int Bool c</literal> would have
+the same representation, because <literal>Age</literal> and
+<literal>Int</literal> have the same representation.) If a type parameter has
+a phantom role, then we need no further information.</para>
+
+<para>Here are some examples:</para>
+
+<programlisting>
+  data Simple a = MkSimple a          -- a has role representational
+
+  type family F
+  type instance F Int = Bool
+  type instance F Age = Char
+
+  data Complex a = MkComplex (F a)    -- a has role nominal
+
+  data Phant a = MkPhant Bool         -- a has role phantom
+</programlisting>
+
+<para>The type <literal>Simple</literal> has its parameter at role
+representational, which is generally the most common case. <literal>Simple
+Age</literal> would have the same representation as <literal>Simple
+Int</literal>. The type <literal>Complex</literal>, on the other hand, has its
+parameter at role nominal, because <literal>Simple Age</literal> and
+<literal>Simple Int</literal> are <emphasis>not</emphasis> the same. Lastly,
+<literal>Phant Age</literal> and <literal>Phant Bool</literal> have the same
+representation, even though <literal>Age</literal> and <literal>Bool</literal>
+are unrelated.</para>
+
+</sect2>
+
+<sect2 id="role-inference">
+<title>Role inference</title>
+
+<para>
+What role should a given type parameter should have? GHC performs role
+inference to determine the correct role for every parameter. It starts with a
+few base facts: <literal>(->)</literal> has two representational parameters;
+<literal>(~)</literal> has two nominal parameters; all type families'
+parameters are nominal; and all GADT-like parameters are nominal. Then, these
+facts are propagated to all places where these types are used. The default
+role for datatypes and synonyms is phantom; the default role for classes is
+nominal. Thus, for datatypes and synonyms, any parameters unused in the
+right-hand side (or used only in other types in phantom positions) will be
+phantom. Whenever a parameter is used in a representational position (that is,
+used as a type argument to a constructor whose corresponding variable is at
+role representational), we raise its role from phantom to representational.
+Similarly, when a parameter is used in a nominal position, its role is
+upgraded to nominal. We never downgrade a role from nominal to phantom or
+representational, or from representational to phantom. In this way, we infer
+the most-general role for each parameter.
+</para>
+
+<para>
+Classes have their roles default to nominal to promote coherence of class
+instances. If a <literal>C Int</literal> were stored in a datatype, it would
+be quite bad if that were somehow changed into a <literal>C Age</literal>
+somewhere, especially if another <literal>C Age</literal> had been declared!
+</para>
+
+<para>There is one particularly tricky case that should be explained:</para>
+
+<programlisting>
+  data Tricky a b = MkTricky (a b)
+</programlisting>
+
+<para>What should <literal>Tricky</literal>'s roles be? At first blush, it
+would seem that both <literal>a</literal> and <literal>b</literal> should be
+at role representational, since both are used in the right-hand side and
+neither is involved in a type family. However, this would be wrong, as the
+following example shows:</para>
+
+<programlisting>
+  data Nom a = MkNom (F a)   -- type family F from example above
+</programlisting>
+
+<para>Is <literal>Tricky Nom Age</literal> representationally equal to
+<literal>Tricky Nom Int</literal>? No! The former stores a
+<literal>Char</literal> and the latter stores a <literal>Bool</literal>. The
+solution to this is to require all parameters to type variables to have role
+nominal. Thus, GHC would infer role representational for <literal>a</literal>
+but role nominal for <literal>b</literal>.</para>
+
+</sect2>
+
+<sect2 id="role-annotations">
+<title>Role annotations
+<indexterm><primary>-XRoleAnnotations</primary></indexterm>
+</title>
+
+<para>
+Sometimes the programmer wants to constrain the inference process. For
+example, the base library contains the following definition:
+</para>
+
+<programlisting>
+  data Ptr a = Ptr Addr#
+</programlisting>
+
+<para>
+The idea is that <literal>a</literal> should really be a representational
+parameter, but role inference assigns it to phantom. This makes some level of
+sense: a pointer to an <literal>Int</literal> really is representationally the
+same as a pointer to a <literal>Bool</literal>. But, that's not at all how we
+want to use <literal>Ptr</literal>s! So, we want to be able to say</para>
+
+<programlisting>
+  type role Ptr representational
+  data Ptr a = Ptr Addr#
+</programlisting>
+
+<para>
+The <literal>type role</literal> (enabled with
+<option>-XRoleAnnotations</option>) declaration forces the parameter
+<literal>a</literal> to be at role representational, not role phantom. GHC
+then checks the user-supplied roles to make sure they don't break any
+promises. It would be bad, for example, if the user could make
+<literal>BadIdea</literal>'s role be representational.
+</para>
+
+<para>As another example, we can consider a type <literal>Set a</literal> that
+represents a set of data, ordered according to <literal>a</literal>'s
+<literal>Ord</literal> instance. While it would generally be type-safe to
+consider <literal>a</literal> to be at role representational, it is possible
+that a <literal>newtype</literal> and its base type have
+<emphasis>different</emphasis> orderings encoded in their respective
+<literal>Ord</literal> instances. This would lead to misbehavior at runtime.
+So, the author of the <literal>Set</literal> datatype would like its parameter
+to be at role nominal. This would be done with a declaration</para>
+
+<programlisting>
+  type role Set nominal
+</programlisting>
+
+<para>Role annotations can also be used should a programmer wish to write
+a class with a representational (or phantom) role. However, as a class
+with non-nominal roles can quickly lead to class instance incoherence,
+it is necessary to also specify <option>-XIncoherentInstances</option>
+to allow non-nominal roles for classes.</para>
+
+<para>The other place where role annotations may be necessary are in
+<literal>hs-boot</literal> files (<xref linkend="mutual-recursion"/>), where
+the right-hand sides of definitions can be omitted. As usual, the
+types/classes declared in an <literal>hs-boot</literal> file must match up
+with the definitions in the <literal>hs</literal> file, including down to the
+roles. The default role for datatypes
+is representational in <literal>hs-boot</literal> files,
+corresponding to the common use case.</para>
+
+<para>
+Role annotations are allowed on data, newtype, and class declarations. A role
+annotation declaration starts with <literal>type role</literal> and is
+followed by one role listing for each parameter of the type. (This parameter
+count includes parameters implicitly specified by a kind signature in a
+GADT-style data or newtype declaration.) Each role listing is a role
+(<literal>nominal</literal>, <literal>representational</literal>, or
+<literal>phantom</literal>) or a <literal>_</literal>. Using a
+<literal>_</literal> says that GHC should infer that role. The role annotation
+may go anywhere in the same module as the datatype or class definition
+(much like a value-level type signature).
+Here are some examples:</para>
+
+<programlisting>
+  type role T1 _ phantom
+  data T1 a b = MkT1 a     -- b is not used; annotation is fine but unnecessary
+
+  type role T2 _ phantom
+  data T2 a b = MkT2 b     -- ERROR: b is used and cannot be phantom
+
+  type role T3 _ nominal
+  data T3 a b = MkT3 a     -- OK: nominal is higher than necessary, but safe
+
+  type role T4 nominal
+  data T4 a = MkT4 (a Int) -- OK, but nominal is higher than necessary
+
+  type role C representational _   -- OK, with -XIncoherentInstances
+  class C a b where ...    -- OK, b will get a nominal role
+
+  type role X nominal
+  type X a = ...           -- ERROR: role annotations not allowed for type synonyms
+</programlisting>
+
+</sect2>
+
+</sect1>
 
 <!-- Emacs stuff:
      ;;; Local Variables: ***