Loosen the rules for instance declarations (Part 3)

[ghc-hetmet.git] / ghc / docs / users_guide / glasgow_exts.xml

diff --git a/ghc/docs/users_guide/glasgow_exts.xml b/ghc/docs/users_guide/glasgow_exts.xml
index 3b38c1b..beaaad6 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.xml
+++ b/ghc/docs/users_guide/glasgow_exts.xml
@@ -1933,8 +1933,9 @@ In Haskell 98 the head of an instance declaration
 must be of the form <literal>C (T a1 ... an)</literal>, where
 <literal>C</literal> is the class, <literal>T</literal> is a type constructor,
 and the <literal>a1 ... an</literal> are distinct type variables.
-Furthermore, the assertions in the context of the instance declaration be of
-the form <literal>C a</literal> where <literal>a</literal> is a type variable.
+Furthermore, the assertions in the context of the instance declaration
+must be of the form <literal>C a</literal> where <literal>a</literal>
+is a type variable that occurs in the head.
 </para>
 <para>
 The <option>-fglasgow-exts</option> flag loosens these restrictions
@@ -1963,7 +1964,7 @@ corresponding type in the instance declaration.
 </para></listitem>
 </orderedlist>
 These restrictions ensure that context reduction terminates: each reduction
-step makes the problem smaller
+step makes the problem smaller by at least one
 constructor.  For example, the following would make the type checker
 loop if it wasn't excluded:
 <programlisting>
@@ -1989,34 +1990,52 @@ For example, these are OK:
 </programlisting>
 But these are not:
 <programlisting>
-  instance C a => C a where ...
       -- Context assertion no smaller than head
-  instance C b b => Foo [b] where ...
+  instance C a => C a where ...
       -- (C b b) has more more occurrences of b than the head
+  instance C b b => Foo [b] where ...
 </programlisting>
 </para>
 
 <para>
-A couple of useful idioms are these.  First, 
-if one allows overlapping instance declarations then it's quite
+The same restrictions apply to instances generated by
+<literal>deriving</literal> clauses.  Thus the following is accepted:
+<programlisting>
+  data MinHeap h a = H a (h a)
+    deriving (Show)
+</programlisting>
+because the derived instance
+<programlisting>
+  instance (Show a, Show (h a)) => Show (MinHeap h a)
+</programlisting>
+conforms to the above rules.
+</para>
+
+<para>
+A useful idiom permitted by the above rules is as follows.
+If one allows overlapping instance declarations then it's quite
 convenient to have a "default instance" declaration that applies if
 something more specific does not:
 <programlisting>
   instance C a where
     op = ... -- Default
 </programlisting>
+</para>
+</sect3>
 
-Second, sometimes you might want to use the following to get the
-effect of a "class synonym":
-
+<sect3 id="undecidable-instances">
+<title>Undecidable instances</title>
 
+<para>
+Sometimes even the rules of <xref linkend="instance-rules"/> are too onerous.
+For example, sometimes you might want to use the following to get the
+effect of a "class synonym":
 <programlisting>
   class (C1 a, C2 a, C3 a) => C a where { }
 
   instance (C1 a, C2 a, C3 a) => C a where { }
 </programlisting>
 This allows you to write shorter signatures:
-
 <programlisting>
   f :: C a => ...
 </programlisting>
@@ -2024,17 +2043,9 @@ instead of
 <programlisting>
   f :: (C1 a, C2 a, C3 a) => ...
 </programlisting>
-</para>
-</sect3>
-
-<sect3 id="undecidable-instances">
-<title>Undecidable instances</title>
-
-<para>
-Sometimes even the rules of <xref linkend="instance-rules"/> are too onerous.
-For example, with functional dependencies (<xref
-linkend="functional-dependencies"/>)
-it is tempting to introduce type variables in the context that do not appear in
+The restrictions on functional dependencies (<xref
+linkend="functional-dependencies"/>) are particularly troublesome.
+It is tempting to introduce type variables in the context that do not appear in
 the head, something that is excluded by the normal rules. For example:
 <programlisting>
   class HasConverter a b | a -> b where