Add some explanation about overlapping instances

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

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 5bcaa1b..7e88a4f 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -351,6 +351,15 @@ Indeed, the bindings can even be recursive.
              <entry>Name</entry>
            </row>
          </thead>
+
+<!--
+               to find the DocBook entities for these characters, find
+               the Unicode code point (e.g. 0x2237), and grep for it in
+               /usr/share/sgml/docbook/xml-dtd-*/ent/* (or equivalent on
+               your system.  Some of these Unicode code points don't have
+               equivalent DocBook entities.
+            -->
+
          <tbody>
            <row>
              <entry><literal>::</literal></entry>
@@ -399,6 +408,52 @@ Indeed, the bindings can even be recursive.
              <entry>MIDLINE HORIZONTAL ELLIPSIS</entry>
            </row>
           </tbody>
+
+         <tbody>
+           <row>
+             <entry>-&lt;</entry>
+             <entry>&larrtl;</entry>
+             <entry>0x2919</entry>
+             <entry>LEFTWARDS ARROW-TAIL</entry>
+           </row>
+          </tbody>
+
+         <tbody>
+           <row>
+             <entry>&gt;-</entry>
+             <entry>&rarrtl;</entry>
+             <entry>0x291A</entry>
+             <entry>RIGHTWARDS ARROW-TAIL</entry>
+           </row>
+          </tbody>
+
+         <tbody>
+           <row>
+             <entry>-&lt;&lt;</entry>
+             <entry></entry>
+             <entry>0x291B</entry>
+             <entry>LEFTWARDS DOUBLE ARROW-TAIL</entry>
+           </row>
+          </tbody>
+
+         <tbody>
+           <row>
+             <entry>&gt;&gt;-</entry>
+             <entry></entry>
+             <entry>0x291C</entry>
+             <entry>RIGHTWARDS DOUBLE ARROW-TAIL</entry>
+           </row>
+          </tbody>
+
+         <tbody>
+           <row>
+             <entry>*</entry>
+             <entry>&starf;</entry>
+             <entry>0x2605</entry>
+             <entry>BLACK STAR</entry>
+           </row>
+          </tbody>
+
         </tgroup>
       </informaltable>
     </sect2>
@@ -994,7 +1049,7 @@ It supports rebindable syntax (see <xref linkend="rebindable-syntax"/>).
 
 <sect3> <title> Mdo-notation (deprecated) </title>
 
-<para> GHC used to support the flag <option>-XREecursiveDo</option>,
+<para> GHC used to support the flag <option>-XRecursiveDo</option>,
 which enabled the keyword <literal>mdo</literal>, precisely as described in
 <ulink url="http://sites.google.com/site/leventerkok/">A recursive do for Haskell</ulink>,
 but this is now deprecated.  Instead of <literal>mdo { Q; e }</literal>, write
@@ -3950,6 +4005,51 @@ of the instance declaration, thus:
 (You need <link linkend="instance-rules"><option>-XFlexibleInstances</option></link> to do this.)
 </para>
 <para>
+Warning: overlapping instances must be used with care.  They 
+can give rise to incoherence (ie different instance choices are made
+in different parts of the program) even without <option>-XIncoherentInstances</option>. Consider:
+<programlisting>
+{-# LANGUAGE OverlappingInstances #-}
+module Help where
+
+    class MyShow a where
+      myshow :: a -> String
+
+    instance MyShow a => MyShow [a] where
+      myshow xs = concatMap myshow xs
+
+    showHelp :: MyShow a => [a] -> String
+    showHelp xs = myshow xs
+
+{-# LANGUAGE FlexibleInstances, OverlappingInstances #-}
+module Main where
+    import Help
+
+    data T = MkT
+
+    instance MyShow T where
+      myshow x = "Used generic instance"
+
+    instance MyShow [T] where
+      myshow xs = "Used more specific instance"
+
+    main = do { print (myshow [MkT]); print (showHelp [MkT]) }
+</programlisting>
+In function <literal>showHelp</literal> GHC sees no overlapping
+instances, and so uses the <literal>MyShow [a]</literal> instance
+without complaint.  In the call to <literal>myshow</literal> in <literal>main</literal>,
+GHC resolves the <literal>MyShow [T]</literal> constraint using the overlapping
+instance declaration in module <literal>Main</literal>. As a result, 
+the program prints
+<programlisting>
+  "Used more specific instance"
+  "Used generic instance"
+</programlisting>
+(An alternative possible behaviour, not currently implemented, 
+would be to reject module <literal>Help</literal>
+on the grounds that a later instance declaration might overlap the local one.)
+</para>
+<para>
 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>