Add documentation for seq

[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 09fd3f5..052c9c3 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -106,9 +106,7 @@ documentation</ulink> describes all the libraries that come with GHC.
         </term>
        <listitem>
          <para>This option enables the language extension defined in the
-         Haskell 98 Foreign Function Interface Addendum plus deprecated
-         syntax of previous versions of the FFI for backwards
-         compatibility.</para> 
+         Haskell 98 Foreign Function Interface Addendum.</para>
 
          <para>New reserved words: <literal>foreign</literal>.</para>
        </listitem>
@@ -116,7 +114,7 @@ documentation</ulink> describes all the libraries that come with GHC.
 
       <varlistentry>
        <term>
-          <option>-fno-monomorphism-restriction</option>,<option>-fno-monomorphism-restriction</option>:
+          <option>-fno-monomorphism-restriction</option>,<option>-fno-mono-pat-binds</option>:
         </term>
        <listitem>
          <para> These two flags control how generalisation is done.
@@ -3301,6 +3299,7 @@ changing the program.</para></listitem>
 A <emphasis>lexically scoped type variable</emphasis> can be bound by:
 <itemizedlist>
 <listitem><para>A declaration type signature (<xref linkend="decl-type-sigs"/>)</para></listitem>
+<listitem><para>An expression type signature (<xref linkend="exp-type-sigs"/>)</para></listitem>
 <listitem><para>A pattern type signature (<xref linkend="pattern-type-sigs"/>)</para></listitem>
 <listitem><para>Class and instance declarations (<xref linkend="cls-inst-scoped-tyvars"/>)</para></listitem>
 </itemizedlist>
@@ -3352,6 +3351,23 @@ quantification rules.
 </para>
 </sect3>
 
+<sect3 id="exp-type-sigs">
+<title>Expression type signatures</title>
+
+<para>An expression type signature that has <emphasis>explicit</emphasis>
+quantification (using <literal>forall</literal>) brings into scope the
+explicitly-quantified
+type variables, in the annotated expression.  For example:
+<programlisting>
+  f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
+</programlisting>
+Here, the type signature <literal>forall a. ST s Bool</literal> brings the 
+type variable <literal>s</literal> into scope, in the annotated expression 
+<literal>(op >>= \(x :: STRef s Int) -> g x)</literal>.
+</para>
+
+</sect3>
+
 <sect3 id="pattern-type-sigs">
 <title>Pattern type signatures</title>
 <para>
@@ -3709,6 +3725,33 @@ the standard method is used or the one described here.)
 
 </sect2>
 
+<sect2 id="stand-alone-deriving">
+<title>Stand-alone deriving declarations</title>
+
+<para>
+GHC now allows stand-alone <literal>deriving</literal> declarations:
+</para>
+
+<programlisting>
+  data Foo = Bar Int | Baz String
+
+  deriving Eq for Foo
+</programlisting>
+
+<para>Deriving instances of multi-parameter type classes for newtypes is
+also allowed:</para>
+
+<programlisting>
+  newtype Foo a = MkFoo (State Int a)
+
+  deriving (MonadState Int) for Foo
+</programlisting>
+
+<para>
+</para>
+
+</sect2>
+
 <sect2 id="typing-binds">
 <title>Generalised typing of mutually recursive bindings</title>
 
@@ -6087,6 +6130,22 @@ r) ->
 described in this section.  All are exported by
 <literal>GHC.Exts</literal>.</para>
 
+<sect2> <title>The <literal>seq</literal> function </title>
+<para>
+The function <literal>seq</literal> is as described in the Haskell98 Report.
+<programlisting>
+  seq :: a -> b -> b
+</programlisting>
+It evaluates its first argument to head normal form, and then returns its
+second argument as the result.  The reason that it is documented here is 
+that, despite <literal>seq</literal>'s polymorphism, its 
+second argument can have an unboxed type, or
+can be an unboxed tuple; for example <literal>(seq x 4#)</literal>
+or <literal>(seq x (# p,q #))</literal>.  This requires <literal>b</literal>
+to be instantiated to an unboxed type, which is not usually allowed.
+</para>
+</sect2>
+
 <sect2> <title>The <literal>inline</literal> function </title>
 <para>
 The <literal>inline</literal> function is somewhat experimental.
@@ -6145,6 +6204,11 @@ If <literal>lazy</literal> were not lazy, <literal>par</literal> would
 look strict in <literal>y</literal> which would defeat the whole 
 purpose of <literal>par</literal>.
 </para>
+<para>
+Like <literal>seq</literal>, the argument of <literal>lazy</literal> can have
+an unboxed type.
+</para>
+
 </sect2>
 
 <sect2> <title>The <literal>unsafeCoerce#</literal> function </title>
@@ -6160,7 +6224,14 @@ 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>
+<para>
+The argument to <literal>unsafeCoerce#</literal> can have unboxed types,
+although extremely bad things will happen if you coerce a boxed type 
+to an unboxed type.
+</para>
+
 </sect2>
+
 </sect1>