multiline commands in GHCi #4316

This patch adds support for multiline commands in GHCi.

The first line of input is lexed.  If there is an active
layout context once the lexer reaches the end of file, the
user is prompted for more input.

Multiline input is exited by an empty line and can be escaped 
with a user interrupt.

Multiline mode is toggled with `:set +m`

1 files changed, 58 insertions, 2 deletions

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 80205954e5..ebf195b2a6 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -58,8 +58,52 @@ Prelude>
 </screen>
 
     <para>GHCi interprets the whole line as an expression to evaluate.
-    The expression may not span several lines - as soon as you press
-    enter, GHCi will attempt to evaluate it.</para>
+    The expression may not span several lines - as soon as you press enter, 
+    GHCi will attempt to evaluate it.</para>
+
+    <para>GHCi also has a multiline mode, 
+    <indexterm><primary><literal>:set +m</literal></primary></indexterm>,
+    which is terminated by an empty line:</para>
+
+<screen>
+Prelude> :set +m
+Prelude> let x = 42 in x / 9
+Prelude| 
+4.666666666666667
+Prelude> 
+</screen>
+    
+    <para>In Haskell, a <literal>let</literal> expression is followed
+    by <literal>in</literal>.  However, in GHCi, since the expression 
+    can also be interpreted in the <literal>IO</literal> monad, 
+    a <literal>let</literal> binding with no accompanying 
+    <literal>in</literal> statement can be signalled by an empty line, 
+    as in the above example.</para>
+
+    <para>Multiline mode is useful when entering monadic 
+    <literal>do<literal> statements:</para>
+
+<screen>
+Control.Monad.State> flip evalStateT 0 $ do
+Control.Monad.State| i <- get
+Control.Monad.State| lift $ do
+Control.Monad.State|   putStrLn "Hello World!"
+Control.Monad.State|   print i
+Control.Monad.State|
+"Hello World!"
+0
+Control.Monad.State>
+</screen>
+  
+   <para>During a multiline interaction, the user can interrupt and
+   return to the top-level prompt.</para>
+
+<screen>
+Prelude> do
+Prelude| putStrLn "Hello, World!"
+Prelude| ^C
+Prelude>
+</screen>
   </sect1>
 
   <sect1 id="loading-source-files">
@@ -2627,6 +2671,18 @@ bar
       <variablelist>
 	<varlistentry>
 	  <term>
+            <literal>+m</literal>
+            <indexterm><primary><literal>+m</literal></primary></indexterm>
+          </term>
+	  <listitem>
+	    <para>Enable parsing of multiline commands.  A multiline command
+	    is prompted for when the current input line contains open layout
+	    contexts.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>
             <literal>+r</literal>
             <indexterm><primary><literal>+r</literal></primary></indexterm>
             <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>