Add a pointer to the fundeps paper

[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 319104e..fd6e322 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -128,6 +128,45 @@ documentation</ulink> describes all the libraries that come with GHC.
 
       <varlistentry>
        <term>
+          <option>-fno-mono-pat-binds</option>:
+          <indexterm><primary><option>-fno-mono-pat-binds</option></primary></indexterm>
+          <indexterm><primary><option>-fmono-pat-binds</option></primary></indexterm>
+        </term>
+       <listitem>
+         <para> As an experimental change, we are exploring the possibility of
+         making pattern bindings monomorphic; that is, not generalised at all.  
+           A pattern binding is a binding whose LHS has no function arguments,
+           and is not a simple variable.  For example:
+<programlisting>
+  f x = x                    -- Not a pattern binding
+  f = \x -> x                -- Not a pattern binding
+  f :: Int -> Int = \x -> x  -- Not a pattern binding
+
+  (g,h) = e                  -- A pattern binding
+  (f) = e                    -- A pattern binding
+  [x] = e                    -- A pattern binding
+</programlisting>
+Experimentally, GHC now makes pattern bindings monomorphic <emphasis>by
+default</emphasis>.  Use <option>-fno-mono-pat-binds</option> to recover the
+standard behaviour.
+          </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <option>-fextended-default-rules</option>:
+          <indexterm><primary><option>-fextended-default-rules</option></primary></indexterm>
+        </term>
+       <listitem>
+         <para> Use GHCi's extended default rules in a regular module (<xref linkend="extended-default-rules"/>).
+          Independent of the <option>-fglasgow-exts</option>
+          flag. </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
           <option>-fallow-overlapping-instances</option>
           <indexterm><primary><option>-fallow-overlapping-instances</option></primary></indexterm>
         </term>
@@ -140,7 +179,7 @@ documentation</ulink> describes all the libraries that come with GHC.
           <indexterm><primary><option>-fallow-incoherent-instances</option></primary></indexterm>
         </term>
        <term>
-          <option>-fcontext-stack</option>
+          <option>-fcontext-stack=N</option>
           <indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
         </term>
        <listitem>
@@ -617,7 +656,7 @@ clunky env var1 var1 = case lookup env var1 of
     Nothing -&gt; fail
     Just val2 -&gt; val1 + val2
 where
-  fail = val1 + val2
+  fail = var1 + var2
 </programlisting>
 
 <para>
@@ -2022,6 +2061,11 @@ something more specific does not:
     op = ... -- Default
 </programlisting>
 </para>
+<para>You can find lots of background material about the reason for these
+restrictions in the paper <ulink
+url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
+Understanding functional dependencies via Constraint Handling Rules</ulink>.
+</para>
 </sect3>
 
 <sect3 id="undecidable-instances">
@@ -2090,7 +2134,7 @@ option</primary></indexterm>, you can use arbitrary
 types in both an instance context and instance head.  Termination is ensured by having a
 fixed-depth recursion stack.  If you exceed the stack depth you get a
 sort of backtrace, and the opportunity to increase the stack depth
-with <option>-fcontext-stack</option><emphasis>N</emphasis>.
+with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
 </para>
 
 </sect3>
@@ -2107,7 +2151,9 @@ can be modified by two flags: <option>-fallow-overlapping-instances</option>
 </primary></indexterm> 
 and <option>-fallow-incoherent-instances</option>
 <indexterm><primary>-fallow-incoherent-instances
-</primary></indexterm>, as this section discusses.</para>
+</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>
 <para>
 When GHC tries to resolve, say, the constraint <literal>C Int Bool</literal>,
 it tries to match every instance declaration against the
@@ -2464,7 +2510,7 @@ function that called it. For example, our <literal>sort</literal> function might
 to pick out the least value in a list:
 <programlisting>
   least   :: (?cmp :: a -> a -> Bool) => [a] -> a
-  least xs = fst (sort xs)
+  least xs = head (sort xs)
 </programlisting>
 Without lifting a finger, the <literal>?cmp</literal> parameter is
 propagated to become a parameter of <literal>least</literal> as well. With explicit
@@ -5378,7 +5424,9 @@ The programmer can specify rewrite rules as part of the source program
 (in a pragma).  GHC applies these rewrite rules wherever it can, provided (a) 
 the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on, 
 and (b) the <option>-frules-off</option> flag
-(<xref linkend="options-f"/>) is not specified.
+(<xref linkend="options-f"/>) is not specified, and (c) the
+<option>-fglasgow-exts</option> (<xref linkend="options-language"/>)
+flag is active.
 </para>
 
 <para>
@@ -6068,7 +6116,7 @@ shortcoming is something that could be fixed, with some kind of pragma.)
 </para>
 </sect2>
 
-<sect2> <title>The <literal>inline</literal> function </title>
+<sect2> <title>The <literal>lazy</literal> function </title>
 <para>
 The <literal>lazy</literal> function restrains strictness analysis a little:
 <programlisting>
@@ -6093,6 +6141,21 @@ look strict in <literal>y</literal> which would defeat the whole
 purpose of <literal>par</literal>.
 </para>
 </sect2>
+
+<sect2> <title>The <literal>unsafeCoerce#</literal> function </title>
+<para>
+The function <literal>unsafeCoerce#</literal> allows you to side-step the
+typechecker entirely.  It has type
+<programlisting>
+  unsafeCoerce# :: a -> b
+</programlisting>
+That is, it allows you to coerce any type into any other type.  If you use this
+function, you had better get it right, otherwise segmentation faults await. 
+It is generally used when you want to write a program that you know is
+well-typed, but where Haskell's type system is not expressive enough to prove
+that it is well typed.
+</para>
+</sect2>
 </sect1>