[project @ 2002-09-30 13:42:01 by simonpj]

Move mdo section

diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index b98d10b..6001ed9 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -2628,6 +2628,84 @@ qualifier list has just one element, a boolean expression.
 </para>
 </sect2>
 
+<!-- ===================== Recursive do-notation ===================  -->
+
+<sect2 id="mdo-notation">
+<title>The recursive do-notation
+</title>
+
+<para> The recursive do-notation (also known as mdo-notation) is implemented as described in
+"A recursive do for Haskell",
+Levent Erkok, John Launchbury",
+Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania. 
+</para>
+<para>
+The do-notation of Haskell does not allow <emphasis>recursive bindings</emphasis>,
+that is, the variables bound in a do-expression are visible only in the textually following 
+code block. Compare this to a let-expression, where bound variables are visible in the entire binding
+group. It turns out that several applications can benefit from recursive bindings in
+the do-notation, and this extension provides the necessary syntactic support.
+</para>
+<para>
+Here is a simple (yet contrived) example:
+</para>
+<programlisting>
+justOnes = mdo xs <- Just (1:xs)
+               return xs
+</programlisting>
+<para>
+As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [1,1,1,...</literal>.
+</para>
+
+<para>
+The MonadRec library introduces the <literal>MonadRec</literal> class. It's definition is:
+</para>
+<programlisting>
+class Monad m => MonadRec m where
+   mfix :: (a -> m a) -> m a
+</programlisting>
+<para>
+The function <literal>mfix</literal>
+dictates how the required recursion operation should be performed. If recursive bindings are required for a monad,
+then that monad must be declared an instance of the <literal>MonadRec</literal> class.
+For details, see the above mentioned reference.
+</para>
+<para>
+The <literal>MonadRec</literal> library automatically declares List, Maybe, IO, and
+state monads (both lazy and strict) as instances of the <literal>MonadRec</literal> class.
+</para>
+<para>
+There are three 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
+than <literal>do</literal>).
+</para></listitem>
+
+<listitem><para>
+If you want to declare an instance of the <literal>MonadRec</literal> class for one of 
+your own monads, or you need to refer to the class name <literal>MonadRec</literal> in any other way (for instance in
+writing a type constraint), then your program should <literal>import Control.Monad.MonadRec</literal>.
+Otherwise, you don't need to import any special libraries to use the mdo-notation. That is,
+as long as you only use the predefined instances mentioned above, the mdo-notation will
+be automatically available. (Note: This differs from the Hugs implementation, where
+<literal>MonadRec</literal> should always be imported.)
+</para></listitem>
+
+<listitem><para>
+As with other extensions, ghc should be given the flag <literal>-fglasgow-exts</literal>
+</para></listitem>
+</itemizedlist>
+</para>
+
+
+<para>
+The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb">http://www.cse.ogi.edu/PacSoft/projects/rmb</ulink>
+contains up to date information on recursive monadic bindings.
+</para>
+
+</sect2>
+
 <!-- ===================== PARALLEL LIST COMPREHENSIONS ===================  -->
 
   <sect2 id="parallel-list-comprehensions">
@@ -4025,81 +4103,6 @@ instances is most interesting.
 </para>
 </sect2>
 
-<sect2 id="mdo-notation">
-<title>The recursive do-notation
-</title>
-
-<para> The recursive do-notation (a.k.a. mdo-notation) is implemented as described in
-"A recursive do for Haskell",
-Levent Erkok, John Launchbury",
-Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania. 
-</para>
-<para>
-The do-notation of Haskell does not allow <emphasis>recursive bindings</emphasis>,
-that is, the variables bound in a do-expression are visible only in the textually following 
-code block. Compare this to a let-expression, where bound variables are visible in the entire binding
-group. It turns out that several applications can benefit from recursive bindings in
-the do-notation, and this extension provides the necessary syntactic support.
-</para>
-<para>
-Here is a simple (yet contrived) example:
-</para>
-<programlisting>
-justOnes = mdo xs <- Just (1:xs)
-               return xs
-</programlisting>
-<para>
-As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [1,1,1,...</literal>.
-</para>
-
-<para>
-The MonadRec library introduces the <literal>MonadRec</literal> class. It's definition is:
-</para>
-<programlisting>
-class Monad m => MonadRec m where
-   mfix :: (a -> m a) -> m a
-</programlisting>
-<para>
-The function <literal>mfix</literal>
-dictates how the required recursion operation should be performed. If recursive bindings are required for a monad,
-then that monad must be declared an instance of the <literal>MonadRec</literal> class.
-For details, see the above mentioned reference.
-</para>
-<para>
-The <literal>MonadRec</literal> library automatically declares List, Maybe, IO, and
-state monads (both lazy and strict) as instances of the <literal>MonadRec</literal> class.
-</para>
-<para>
-There are three 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
-than <literal>do</literal>).
-</para></listitem>
-
-<listitem><para>
-If you want to declare an instance of the <literal>MonadRec</literal> class for one of 
-your own monads, or you need to refer to the class name <literal>MonadRec</literal> in any other way (for instance in
-writing a type constraint), then your program should <literal>import Control.Monad.MonadRec</literal>.
-Otherwise, you don't need to import any special libraries to use the mdo-notation. That is,
-as long as you only use the predefined instances mentioned above, the mdo-notation will
-be automatically available. (Note: This differs from the Hugs implementation, where
-<literal>MonadRec</literal> should always be imported.)
-</para></listitem>
-
-<listitem><para>
-As with other extensions, ghc should be given the flag <literal>-fglasgow-exts</literal>
-</para></listitem>
-</itemizedlist>
-</para>
-
-
-<para>
-The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb">http://www.cse.ogi.edu/PacSoft/projects/rmb</ulink>
-contains up to date information on recursive monadic bindings.
-</para>
-
-</sect2>
 </sect1>