for Haskell's internal state monad (strict and lazy, respectively).
</para>
<para>
-There are three important points in using the recursive-do notation:
+Here are some important points in using the recursive-do notation:
<itemizedlist>
<listitem><para>
The recursive version of the do-notation uses the keyword <literal>mdo</literal> (rather
</para></listitem>
<listitem><para>
-As with other extensions, ghc should be given the flag <literal>-fglasgow-exts</literal>
+It is enabled with the flag <literal>-XRecursiveDo</literal>, which is in turn implied by
+<literal>-fglasgow-exts</literal>.
+</para></listitem>
+
+<listitem><para>
+Unlike ordinary do-notation, but like <literal>let</literal> and <literal>where</literal> bindings,
+name shadowing is not allowed; that is, all the names bound in a single <literal>mdo</literal> must
+be distinct (Section 3.3 of the paper).
+</para></listitem>
+
+<listitem><para>
+Variables bound by a <literal>let</literal> statement in an <literal>mdo</literal>
+are monomorphic in the <literal>mdo</literal> (Section 3.1 of the paper). However
+GHC breaks the <literal>mdo</literal> into segments to enhance polymorphism,
+and improve termination (Section 3.2 of the paper).
</para></listitem>
</itemizedlist>
</para>
</para>
</sect2>
+</sect1>
<!-- ====================== End of Generalised algebraic data types ======================= -->
+<sect1 id="deriving">
+<title>Extensions to the "deriving" mechanism</title>
+
+<sect2 id="deriving-inferred">
+<title>Inferred context for deriving clauses</title>
+
+<para>
+The Haskell Report is vague about exactly when a <literal>deriving</literal> clause is
+legal. For example:
+<programlisting>
+ data T0 f a = MkT0 a deriving( Eq )
+ data T1 f a = MkT1 (f a) deriving( Eq )
+ data T2 f a = MkT2 (f (f a)) deriving( Eq )
+</programlisting>
+The natural generated <literal>Eq</literal> code would result in these instance declarations:
+<programlisting>
+ instance Eq a => Eq (T0 f a) where ...
+ instance Eq (f a) => Eq (T1 f a) where ...
+ instance Eq (f (f a)) => Eq (T2 f a) where ...
+</programlisting>
+The first of these is obviously fine. The second is still fine, although less obviously.
+The third is not Haskell 98, and risks losing termination of instances.
+</para>
+<para>
+GHC takes a conservative position: it accepts the first two, but not the third. The rule is this:
+each constraint in the inferred instance context must consist only of type variables,
+with no repititions.
+</para>
+<para>
+This rule is applied regardless of flags. If you want a more exotic context, you can write
+it yourself, using the <link linkend="stand-alone-deriving">standalone deriving mechanism</link>.
+</para>
+</sect2>
+
+<sect2 id="stand-alone-deriving">
+<title>Stand-alone deriving declarations</title>
+
+<para>
+GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-XStandaloneDeriving</literal>:
+<programlisting>
+ data Foo a = Bar a | Baz String
+
+ deriving instance Eq a => Eq (Foo a)
+</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.
+You must supply a context (in the example the context is <literal>(Eq a)</literal>),
+exactly as you would in an ordinary instance declaration.
+(In contrast the context is inferred in a <literal>deriving</literal> clause
+attached to a data type declaration.) These <literal>deriving instance</literal>
+rules obey the same rules concerning form and termination as ordinary instance declarations,
+controlled by the same flags; see <link linkend="instance-decls"/>. </para>
+
+<para>The stand-alone syntax is generalised for newtypes in exactly the same
+way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
+For example:
+<programlisting>
+ newtype Foo a = MkFoo (State Int a)
+
+ deriving instance MonadState Int Foo
+</programlisting>
+GHC always treats the <emphasis>last</emphasis> parameter of the instance
+(<literal>Foo</literal> in this exmample) as the type whose instance is being derived.
+</para>
+
+</sect2>
+
<sect2 id="deriving-typeable">
<title>Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal></title>
</para>
<para>
GHC extends this list with two more classes that may be automatically derived
-(provided the <option>-fglasgow-exts</option> flag is specified):
+(provided the <option>-XDeriveDataTypeable</option> flag is specified):
<literal>Typeable</literal>, and <literal>Data</literal>. These classes are defined in the library
modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively, and the
appropriate class must be in scope before it can be mentioned in the <literal>deriving</literal> clause.
<sect3> <title> Generalising the deriving clause </title>
<para>
-GHC now permits such instances to be derived instead, so one can write
+GHC now permits such instances to be derived instead,
+using the flag <option>-XGeneralizedNewtypeDeriving</option>,
+so one can write
<programlisting>
newtype Dollars = Dollars Int deriving (Eq,Show,Num)
</programlisting>
Notice that, since <literal>Monad</literal> is a constructor class, the
instance is a <emphasis>partial application</emphasis> of the new type, not the
entire left hand side. We can imagine that the type declaration is
-``eta-converted'' to generate the context of the instance
+"eta-converted" to generate the context of the instance
declaration.
</para>
<para>
the standard method is used or the one described here.)
</para>
</sect3>
-
</sect2>
-
-<sect2 id="stand-alone-deriving">
-<title>Stand-alone deriving declarations</title>
-
-<para>
-GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-fglasgow-exts</literal>:
-<programlisting>
- data Foo a = Bar a | Baz String
-
- derive instance Eq (Foo a)
-</programlisting>
-The token "<literal>derive</literal>" is a keyword only when followed by "<literal>instance</literal>";
-you can use it as a variable name elsewhere.</para>
-<para>The stand-alone syntax is generalised for newtypes in exactly the same
-way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
-For example:
-<programlisting>
- newtype Foo a = MkFoo (State Int a)
-
- derive instance MonadState Int Foo
-</programlisting>
-GHC always treats the <emphasis>last</emphasis> parameter of the instance
-(<literal>Foo</literal> in this exmample) as the type whose instance is being derived.
-</para>
-
-</sect2>
-
</sect1>
<!-- TYPE SYSTEM EXTENSIONS -->
-<sect1 id="other-type-extensions">
-<title>Other type system extensions</title>
+<sect1 id="type-class-extensions">
+<title>Class and instances declarations</title>
<sect2 id="multi-param-type-classes">
<title>Class declarations</title>
</sect2>
+<sect2 id="overloaded-strings">
+<title>Overloaded string literals
+</title>
+
+<para>
+GHC supports <emphasis>overloaded string literals</emphasis>. Normally a
+string literal has type <literal>String</literal>, but with overloaded string
+literals enabled (with <literal>-XOverloadedStrings</literal>)
+ a string literal has type <literal>(IsString a) => a</literal>.
+</para>
+<para>
+This means that the usual string syntax can be used, e.g., for packed strings
+and other variations of string like types. String literals behave very much
+like integer literals, i.e., they can be used in both expressions and patterns.
+If used in a pattern the literal with be replaced by an equality test, in the same
+way as an integer literal is.
+</para>
+<para>
+The class <literal>IsString</literal> is defined as:
+<programlisting>
+class IsString a where
+ fromString :: String -> a
+</programlisting>
+The only predefined instance is the obvious one to make strings work as usual:
+<programlisting>
+instance IsString [Char] where
+ fromString cs = cs
+</programlisting>
+The class <literal>IsString</literal> is not in scope by default. If you want to mention
+it explicitly (for exmaple, to give an instance declaration for it), you can import it
+from module <literal>GHC.Exts</literal>.
+</para>
+<para>
+Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
+Specifically:
+<itemizedlist>
+<listitem><para>
+Each type in a default declaration must be an
+instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
+</para></listitem>
+
+<listitem><para>
+The standard defaulting rule (<ulink url="http://haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
+is extended thus: defaulting applies when all the unresolved constraints involve standard classes
+<emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
+<emphasis>or</emphasis> <literal>IsString</literal>.
+</para></listitem>
+</itemizedlist>
+</para>
+<para>
+A small example:
+<programlisting>
+module Main where
+
+import GHC.Exts( IsString(..) )
+
+newtype MyString = MyString String deriving (Eq, Show)
+instance IsString MyString where
+ fromString = MyString
+
+greet :: MyString -> MyString
+greet "hello" = "world"
+greet other = other
+
+main = do
+ print $ greet "hello"
+ print $ greet "fool"
+</programlisting>
+</para>
+<para>
+Note that deriving <literal>Eq</literal> is necessary for the pattern matching
+to work since it gets translated into an equality comparison.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="other-type-extensions">
+<title>Other type system extensions</title>
+
<sect2 id="type-restrictions">
<title>Type signatures</title>
</para>
</sect2>
-<sect2 id="overloaded-strings">
-<title>Overloaded string literals
-</title>
-
-<para>
-GHC supports <emphasis>overloaded string literals</emphasis>. Normally a
-string literal has type <literal>String</literal>, but with overloaded string
-literals enabled (with <literal>-XOverloadedStrings</literal>)
- a string literal has type <literal>(IsString a) => a</literal>.
-</para>
-<para>
-This means that the usual string syntax can be used, e.g., for packed strings
-and other variations of string like types. String literals behave very much
-like integer literals, i.e., they can be used in both expressions and patterns.
-If used in a pattern the literal with be replaced by an equality test, in the same
-way as an integer literal is.
-</para>
-<para>
-The class <literal>IsString</literal> is defined as:
-<programlisting>
-class IsString a where
- fromString :: String -> a
-</programlisting>
-The only predefined instance is the obvious one to make strings work as usual:
-<programlisting>
-instance IsString [Char] where
- fromString cs = cs
-</programlisting>
-The class <literal>IsString</literal> is not in scope by default. If you want to mention
-it explicitly (for exmaple, to give an instance declaration for it), you can import it
-from module <literal>GHC.Exts</literal>.
-</para>
-<para>
-Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
-Specifically:
-<itemizedlist>
-<listitem><para>
-Each type in a default declaration must be an
-instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
-</para></listitem>
-
-<listitem><para>
-The standard defaulting rule (<ulink url="http://haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
-is extended thus: defaulting applies when all the unresolved constraints involve standard classes
-<emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
-<emphasis>or</emphasis> <literal>IsString</literal>.
-</para></listitem>
-</itemizedlist>
-</para>
-<para>
-A small example:
-<programlisting>
-module Main where
-
-import GHC.Exts( IsString(..) )
-
-newtype MyString = MyString String deriving (Eq, Show)
-instance IsString MyString where
- fromString = MyString
-
-greet :: MyString -> MyString
-greet "hello" = "world"
-greet other = other
-
-main = do
- print $ greet "hello"
- print $ greet "fool"
-</programlisting>
-</para>
-<para>
-Note that deriving <literal>Eq</literal> is necessary for the pattern matching
-to work since it gets translated into an equality comparison.
-</para>
-</sect2>
-
<sect2 id="type-families">
<title>Type families
</title>
<sect1 id="special-ids">
<title>Special built-in functions</title>
-<para>GHC has a few built-in funcions with special behaviour,
-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.
-<programlisting>
- inline :: a -> a
-</programlisting>
-The call <literal>(inline f)</literal> arranges that <literal>f</literal>
-is inlined, regardless of its size. More precisely, the call
-<literal>(inline f)</literal> rewrites to the right-hand side of <literal>f</literal>'s
-definition.
-This allows the programmer to control inlining from
-a particular <emphasis>call site</emphasis>
-rather than the <emphasis>definition site</emphasis> of the function
-(c.f. <literal>INLINE</literal> pragmas <xref linkend="inline-noinline-pragma"/>).
-</para>
-<para>
-This inlining occurs regardless of the argument to the call
-or the size of <literal>f</literal>'s definition; it is unconditional.
-The main caveat is that <literal>f</literal>'s definition must be
-visible to the compiler. That is, <literal>f</literal> must be
-let-bound in the current scope.
-If no inlining takes place, the <literal>inline</literal> function
-expands to the identity function in Phase zero; so its use imposes
-no overhead.</para>
-
-<para> If the function is defined in another
-module, GHC only exposes its inlining in the interface file if the
-function is sufficiently small that it <emphasis>might</emphasis> be
-inlined by the automatic mechanism. There is currently no way to tell
-GHC to expose arbitrarily-large functions in the interface file. (This
-shortcoming is something that could be fixed, with some kind of pragma.)
-</para>
-</sect2>
-
-<sect2> <title>The <literal>lazy</literal> function </title>
-<para>
-The <literal>lazy</literal> function restrains strictness analysis a little:
-<programlisting>
- lazy :: a -> a
-</programlisting>
-The call <literal>(lazy e)</literal> means the same as <literal>e</literal>,
-but <literal>lazy</literal> has a magical property so far as strictness
-analysis is concerned: it is lazy in its first argument,
-even though its semantics is strict. After strictness analysis has run,
-calls to <literal>lazy</literal> are inlined to be the identity function.
-</para>
-<para>
-This behaviour is occasionally useful when controlling evaluation order.
-Notably, <literal>lazy</literal> is used in the library definition of
-<literal>Control.Parallel.par</literal>:
-<programlisting>
- par :: a -> b -> b
- par x y = case (par# x) of { _ -> lazy y }
-</programlisting>
-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>
-<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>
-<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>
-
+<para>GHC has a few built-in funcions with special behaviour. These
+are now described in the module <ulink
+url="../libraries/base/GHC-Prim.html"><literal>GHC.Prim</literal></ulink>
+in the library documentation.</para>
</sect1>