Add -fghci-hist-size=N to set the number of previous steps stored by :trace
[ghc.git] / docs / users_guide / ghci.xml
index 72481eb..c59f4b3 100644 (file)
@@ -38,12 +38,11 @@ Prelude>
 
     <para>There may be a short pause while GHCi loads the prelude and
     standard libraries, after which the prompt is shown. As the banner
-    says, you can type <literal>:?</literal> to see the list of commands
-    available, and a half line description of each of them.</para>
-
-    <para>We'll explain most of these commands as we go along.  For
-    Hugs users: many things work the same as in Hugs, so you should be
-    able to get going straight away.</para>
+    says, you can type <literal>:?</literal> to see the list of
+    commands available, and a half line description of each of them.
+    We'll explain most of these commands as we go along, and there is
+    complete documentation for all the commands in
+      <xref linkend="ghci-commands" />.</para>
 
     <para>Haskell expressions can be typed at the prompt:</para>
     <indexterm><primary>prompt</primary><secondary>GHCi</secondary>
@@ -61,49 +60,12 @@ Prelude>
     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 &lt;- 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">
@@ -396,10 +358,10 @@ Prelude> 5+5
 </screen>
 </para>
 
-<sect2><title>I/O actions at the prompt</title>
+<sect2 id="actions-at-prompt"><title>I/O actions at the prompt</title>
 
 <para>GHCi does more than simple expression evaluation at the prompt.
-If you type something of type <literal>IO a</literal> for some
+If you enter an expression of type <literal>IO a</literal> for some
     <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it
     as an IO-computation.
 <screen>
@@ -408,6 +370,12 @@ Prelude> "hello"
 Prelude> putStrLn "hello"
 hello
 </screen>
+This works even if the type of the expression is more general,
+provided it can be <emphasis>instantiated</emphasis> to <literal>IO a</literal>.  For example
+<screen>
+Prelude> return True
+True
+</screen>
 Furthermore, GHCi will print the result of the I/O action if (and only
 if):
 <itemizedlist>
@@ -570,6 +538,136 @@ xs :: [Integer]
 
     </sect2>
 
+    <sect2 id="ghci-multiline">
+      <title>Multiline input</title>
+
+      <para>Apart from the <literal>:{ ... :}</literal> syntax for
+        multi-line input mentioned above, GHCi also has a multiline
+        mode, enabled by <literal>:set +m</literal>,
+        <indexterm><primary><literal>:set +m</literal></primary></indexterm>
+        in which GHCi detects automatically when the current statement
+        is unfinished and allows further lines to be added.  A
+        multi-line input is terminated with an empty line.  For example:</para>
+
+<screen>
+Prelude> :set +m
+Prelude> let x = 42
+Prelude|
+</screen>
+
+       <para>Further bindings can be added to
+       this <literal>let</literal> statement, so GHCi indicates that
+       the next line continues the previous one by changing the
+       prompt.  Note that layout is in effect, so to add more bindings
+         to this <literal>let</literal> we have to line them up:</para>
+
+<screen>
+Prelude> :set +m
+Prelude> let x = 42
+Prelude|     y = 3
+Prelude| 
+Prelude>
+</screen>
+
+       <para>Explicit braces and semicolons can be used instead of
+         layout, as usual:</para>
+
+<screen>
+Prelude> do {
+Prelude| putStrLn "hello"
+Prelude| ;putStrLn "world"
+Prelude| }
+hello
+world
+Prelude>
+</screen>
+
+       <para>Note that after the closing brace, GHCi knows that the
+         current statement is finished, so no empty line is required.</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 &lt;- 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>
+    </sect2>
+
+    <sect2 id="ghci-decls">
+      <title>Type, class and other declarations</title>
+
+      <para>At the GHCi
+      prompt you can also enter any top-level Haskell declaration,
+      including <literal>data</literal>, <literal>type</literal>, <literal>newtype</literal>, <literal>class</literal>, <literal>instance</literal>, <literal>deriving</literal>,
+      and <literal>foreign</literal> declarations.  For
+      example:</para>
+
+<screen>
+Prelude> data T = A | B | C deriving (Eq, Ord, Show, Enum)
+Prelude> [A ..]
+[A,B,C]
+Prelude> :i T
+data T = A | B | C      -- Defined at &lt;interactive>:2:6
+instance Enum T -- Defined at &lt;interactive>:2:45
+instance Eq T -- Defined at &lt;interactive>:2:30
+instance Ord T -- Defined at &lt;interactive>:2:34
+instance Show T -- Defined at &lt;interactive>:2:39
+</screen>
+
+    <para>As with ordinary variable bindings, later definitions shadow
+    earlier ones, so you can re-enter a declaration to fix a problem
+    with it or extend it.  But there's a gotcha: when a new type
+    declaration shadows an older one, there might be other
+    declarations that refer to the old type.  The thing to remember is
+    that the old type still exists, and these other declarations still
+    refer to the old type.  However, while the old and the new type
+    have the same name, GHCi will treat them as distinct.  For
+    example:</para>
+
+<screen>
+Prelude> data T = A | B
+Prelude> let f A = True; f B = False
+Prelude> data T = A | B | C
+Prelude> f A
+
+&lt;interactive>:2:3:
+    Couldn't match expected type `main::Interactive.T'
+                with actual type `T'
+    In the first argument of `f', namely `A'
+    In the expression: f A
+    In an equation for `it': it = f A
+Prelude> 
+</screen>
+
+    <para>The old, shadowed, version of <literal>T</literal> is
+      displayed as <literal>main::Interactive.T</literal> by GHCi in
+      an attempt to distinguish it from the new <literal>T</literal>,
+      which is displayed as simply <literal>T</literal>.</para>
+
+    <para>Class and type-family instance declarations are simply added to the list of available isntances, with one
+    exception. Since type-family instances are not permitted to overlap, but you might want to re-define one,
+    a type-family instance <emphasis>replaces</emphasis> any earlier type instance with an identical left hand side.
+    (See <xref linkend="type-families"/>.)</para>
+    </sect2>
+
     <sect2 id="ghci-scope">
       <title>What's really in scope at the prompt?</title>
 
@@ -582,8 +680,12 @@ xs :: [Integer]
 <screen>Prelude></screen>
 
       <para>Which indicates that everything from the module
-      <literal>Prelude</literal> is currently in scope.  If we now
-      load a file into GHCi, the prompt will change:</para>
+      <literal>Prelude</literal> is currently in scope; the visible
+      identifiers are exactly those that would be visible in a Haskell
+      source file with no <literal>import</literal>
+      declarations.</para>
+
+      <para>If we now load a file into GHCi, the prompt will change:</para>
 
 <screen>
 Prelude> :load Main.hs
@@ -620,26 +722,59 @@ Compiling Main             ( Main.hs, interpreted )
       interpreted version of a module, add the <literal>*</literal>
       when loading the module, e.g. <literal>:load *M</literal>.</para>
 
-      <para>The scope is manipulated using the
-      <literal>:module</literal> command.  For example, if the current
-      scope is <literal>Prelude</literal>, then we can bring into
-      scope the exports from the module <literal>IO</literal> like
-      so:</para>
+      <para>To add modules to the scope, use ordinary Haskell
+      <literal>import</literal> syntax:</para>
 
 <screen>
-Prelude> :module +IO
-Prelude IO> hPutStrLn stdout "hello\n"
+Prelude> import System.IO
+Prelude System.IO> hPutStrLn stdout "hello\n"
 hello
-Prelude IO>
+Prelude System.IO>
 </screen>
 
-      <para>(Note: you can use conventional
-      haskell <literal>import</literal> syntax as
-      well, but this does not support
-      <literal>*</literal> forms).
-      <literal>:module</literal> can also be shortened to
-      <literal>:m</literal>. The full syntax of the
-      <literal>:module</literal> command is:</para>
+      <para>The full Haskell import syntax is supported, including
+      <literal>hiding</literal> and <literal>as</literal> clauses.
+      The prompt shows the modules that are currently imported, but it
+      omits details about <literal>hiding</literal>,
+      <literal>as</literal>, and so on.  To see the full story, use
+      <literal>:show imports</literal>:</para>
+
+<screen>
+Prelude> import System.IO
+Prelude System.IO> import Data.Map as Map
+Prelude System.IO Map> :show imports
+import Prelude -- implicit
+import System.IO
+import Data.Map as Map
+Prelude System.IO Map>
+</screen>
+
+      <para>Note that the <literal>Prelude</literal> import is marked
+      as implicit.  It can be overriden with an explicit
+      <literal>Prelude</literal> import, just like in a Haskell
+      module.</para>
+
+      <para>Another way to manipulate the scope is to use the
+      <literal>:module</literal> command, which provides a way to do
+      two things that cannot be done with ordinary
+      <literal>import</literal> declarations:
+      <itemizedlist>
+        <listitem>
+          <para><literal>:module</literal> supports the
+          <literal>*</literal> modifier on modules, which opens the
+          full top-level scope of a module, rather than just its
+          exports.</para>
+        </listitem>
+        <listitem>
+          <para>Imports can be <emphasis>removed</emphasis> from the
+          context, using the syntax <literal>:module -M</literal>.
+          The <literal>import</literal> syntax is cumulative (as in a
+          Haskell module), so this is the only way to subtract from
+          the scope.</para>
+        </listitem>
+      </itemizedlist>
+      The full syntax of the <literal>:module</literal> command
+      is:</para>
 
 <screen>
 :module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
@@ -650,14 +785,12 @@ Prelude IO>
       scope, and <literal>-</literal> removes them.  Without either
       <literal>+</literal> or <literal>-</literal>, the current scope
       is replaced by the set of modules specified.  Note that if you
-      use this form and leave out <literal>Prelude</literal>, GHCi
-      will assume that you really wanted the
-      <literal>Prelude</literal> and add it in for you (if you don't
-      want the <literal>Prelude</literal>, then ask to remove it with
-      <literal>:m -Prelude</literal>).</para>
-
-      <para>The scope is automatically set after a
-      <literal>:load</literal> command, to the most recently loaded
+      use this form and leave out <literal>Prelude</literal>, an
+      implicit <literal>Prelude</literal> import will be added
+      automatically.</para>
+
+      <para>After a <literal>:load</literal> command, an automatic
+      import is added to the scope for the most recently loaded
       "target" module, in a <literal>*</literal>-form if possible.
       For example, if you say <literal>:load foo.hs bar.hs</literal>
       and <filename>bar.hs</filename> contains module
@@ -666,7 +799,23 @@ Prelude IO>
       interpreted, or if <literal>Bar</literal> is compiled it will be
       set to <literal>Prelude Bar</literal> (GHCi automatically adds
       <literal>Prelude</literal> if it isn't present and there aren't
-      any <literal>*</literal>-form modules).</para>
+      any <literal>*</literal>-form modules).  These
+      automatically-added imports can be seen with
+      <literal>:show imports</literal>:
+
+<screen>
+Prelude> :load hello.hs
+[1 of 1] Compiling Main             ( hello.hs, interpreted )
+Ok, modules loaded: Main.
+*Main> :show imports
+:module +*Main -- added automatically
+*Main>
+</screen>
+
+      and the automatically-added import is replaced the next time you
+      use <literal>:load</literal>, <literal>:add</literal>, or
+      <literal>:reload</literal>.  It can also be removed by
+      <literal>:module</literal> as with normal imports.</para>
 
       <para>With multiple modules in scope, especially multiple
       <literal>*</literal>-form modules, it is likely that name
@@ -692,20 +841,20 @@ Prelude IO>
 
         <itemizedlist>
           <listitem>
-            <para>The set of modules that are
-              currently <emphasis>loaded</emphasis>.  This set is
-              modified
-              by <literal>:load</literal>, <literal>:add</literal>
-              and <literal>:reload</literal>.
+            <para>The set of modules that are currently
+            <emphasis>loaded</emphasis>.  This set is modified by
+            <literal>:load</literal>, <literal>:add</literal> and
+            <literal>:reload</literal>, and can be shown with
+            <literal>:show modules</literal>.
             </para>
           </listitem>
           <listitem>
             <para>The set of modules that are currently <emphasis>in
-                scope</emphasis> at the prompt.  This set is modified
-              by <literal>:module</literal>, and it is also set
-              automatically
-                after <literal>:load</literal>, <literal>:add</literal>,
-              and <literal>:reload</literal>.</para>
+            scope</emphasis> at the prompt.  This set is modified by
+            <literal>import</literal>, <literal>:module</literal>, and
+            it is also modified automatically after
+            <literal>:load</literal>, <literal>:add</literal>, and
+            <literal>:reload</literal>, as described above.</para>
           </listitem>
         </itemizedlist>
 
@@ -950,7 +1099,66 @@ def = toEnum 0
     <literal>Integer</literal> then ghci gives an error when running a
     printf.
    </para>
+   <para>See also <xref linkend="actions-at-prompt"/> for how the monad of a computational
+   expression defaults to <literal>IO</literal> if possible.
+   </para>
     </sect2>
+
+   <sect2 id="ghci-interactive-print">
+     <title>Using a custom interactive printing function</title>
+     <para>[<emphasis role="bold">New in version 7.6.1</emphasis>]
+        By default, GHCi prints the result of expressions typed at the prompt
+        using the function <literal>System.IO.print</literal>. Its type
+        signature is <literal>Show a => a -> IO ()</literal>, and it works by
+        converting the value to <literal>String</literal> using
+        <literal>show</literal>.
+     </para>
+     <para>
+        This is not ideal in certain cases, like when the output is long, or
+        contains strings with non-ascii characters.
+     </para>
+     <para>
+       The <literal>-interactive-print</literal> flag allows to specify any
+       function of type <literal>C a => a -> IO ()</literal>, for some
+       constraint <literal>C</literal>, as the function for printing evaluated
+       expressions. The function can reside in any loaded module or any
+       registered package.
+     </para>
+     <para>
+       As an example, suppose we have following special printing module:
+       <programlisting>
+        module SpecPrinter where
+        import System.IO
+
+        sprint a = putStrLn $ show a ++ "!"
+       </programlisting>
+       The <literal>sprint</literal> function adds an exclamation mark at the
+       end of any printed value. Running GHCi with the command:
+       <programlisting>
+        ghci -interactive-print=SpecPrinter.sprinter SpecPrinter
+       </programlisting>
+       will start an interactive session where values with be printed using
+       <literal>sprint</literal>:
+       <programlisting>
+        *SpecPrinter> [1,2,3]
+        [1,2,3]!
+        *SpecPrinter> 42
+        42!
+       </programlisting>
+     </para>
+     <para>
+       A custom pretty printing function can be used, for example, to format
+       tree-like and nested structures in a more readable way.
+     </para>
+     <para>
+       The <literal>-interactive-print</literal> flag can also be used when
+       running GHC in <literal>-e mode</literal>:
+       <programlisting>
+        % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter
+        [1,2,3]!
+       </programlisting>
+     </para>
+   </sect2>
   </sect1>
 
   <sect1 id="ghci-debugger">
@@ -1507,8 +1715,7 @@ a :: a
       <para>The history is only available when
         using <literal>:trace</literal>; the reason for this is we found that
         logging each breakpoint in the history cuts performance by a factor of
-        2 or more.  GHCi remembers the last 50 steps in the history (perhaps in
-        the future we'll make this configurable).</para>
+        2 or more.  By default, GHCi remembers the last 50 steps in the history, but this can be changed with the <option>-fghci-hist-size=<replaceable>n</replaceable></option><indexterm><primary><option>&ndash;fghci-hist-size</option></primary></indexterm> option).</para>
     </sect2>
 
     <sect2 id="ghci-debugger-exceptions">
@@ -1520,7 +1727,8 @@ a :: a
         particular call to <literal>head</literal> in your program resulted in
         the error can be a painstaking process, usually involving
         <literal>Debug.Trace.trace</literal>, or compiling with
-        profiling and using <literal>+RTS -xc</literal> (see <xref
+        profiling and using <literal>Debug.Trace.traceStack</literal>
+        or <literal>+RTS -xc</literal> (see <xref
           linkend="prof-time-options" />).</para>
 
       <para>The GHCi debugger offers a way to hopefully shed some light on
@@ -1873,28 +2081,37 @@ $ ghci -lm
           <indexterm><primary><literal>:browse</literal></primary></indexterm>
         </term>
        <listitem>
-         <para>Displays the identifiers defined by the module
+         <para>Displays the identifiers exported by the module
          <replaceable>module</replaceable>, which must be either
          loaded into GHCi or be a member of a package.  If
          <replaceable>module</replaceable> is omitted, the most
          recently-loaded module is used.</para>
 
-          <para>If the <literal>*</literal> symbol is placed before
-         the module name, then <emphasis>all</emphasis> the
-         identifiers in scope in <replaceable>module</replaceable> are
-         shown; otherwise the list is limited to the exports of
-         <replaceable>module</replaceable>.  The
-         <literal>*</literal>-form is only available for modules
-         which are interpreted; for compiled modules (including
-         modules from packages) only the non-<literal>*</literal>
-    form of <literal>:browse</literal> is available.
-    If the <literal>!</literal> symbol is appended to the
-    command, data constructors and class methods will be
-    listed individually, otherwise, they will only be listed
-    in the context of their data type or class declaration.
-    The <literal>!</literal>-form also annotates the listing
-    with comments giving possible imports for each group of
-    entries.</para>
+         <para>Like all other GHCi commands, the output is always 
+          displayed in the current GHCi scope (<xref linkend="ghci-scope"/>).</para>
+
+          <para>There are two variants of the browse command:
+          <itemizedlist>
+          <listitem>  
+             <para>If the <literal>*</literal> symbol is placed before
+            the module name, then <emphasis>all</emphasis> the
+            identifiers in scope in <replaceable>module</replaceable> 
+             (rather that just its exports) are shown. </para>
+
+             <para>The <literal>*</literal>-form is only available for modules
+            which are interpreted; for compiled modules (including
+            modules from packages) only the non-<literal>*</literal>
+             form of <literal>:browse</literal> is available.</para>
+          </listitem>
+          <listitem>
+          <para>Data constructors and class methods are usually
+          displayed in the context of their data type or class declaration.
+          However, if the <literal>!</literal> symbol is appended to the
+          command, thus <literal>:browse!</literal>, 
+          they are listed individually. 
+         The <literal>!</literal>-form also annotates the listing
+         with comments giving possible imports for each group of
+         entries.  Here is an example:
 <screen>
 Prelude> :browse! Data.Maybe
 -- not currently imported
@@ -1912,15 +2129,17 @@ data Maybe a = Nothing | Just a
 Nothing :: Maybe a
 maybe :: b -> (a -> b) -> Maybe a -> b
 </screen>
-  <para>
-    This output shows that, in the context of the current session, in the scope
-    of <literal>Prelude</literal>, the first group of items from
-    <literal>Data.Maybe</literal> have not been imported (but are available in
+    This output shows that, in the context of the current session (ie in the scope
+    of <literal>Prelude</literal>), the first group of items from
+    <literal>Data.Maybe</literal> are not in scope (althought they are available in
     fully qualified form in the GHCi session - see <xref
-      linkend="ghci-scope"/>), whereas the second group of items have been
-    imported via <literal>Prelude</literal> and are therefore available either
+      linkend="ghci-scope"/>), whereas the second group of items are in scope
+    (via <literal>Prelude</literal>) and are therefore available either
     unqualified, or with a <literal>Prelude.</literal> qualifier.
   </para>
+          </listitem>
+       </itemizedlist>
+      </para>
        </listitem>
       </varlistentry>
 
@@ -2161,10 +2380,12 @@ Prelude> :. cmds.ghci
           <indexterm><primary><literal>:history</literal></primary></indexterm>
         </term>
        <listitem>
-         <para>Display the history of evaluation steps.  With a number,
-            displays that many steps (default: 20).  For use with
-            <literal>:trace</literal>; see <xref
-              linkend="tracing" />.</para>
+         <para>Display the history of evaluation steps.  With a
+         number, displays that many steps (default: 20).  For use
+         with <literal>:trace</literal>; see <xref linkend="tracing"
+         />.  To set the number of history entries stored by GHCi,
+         use
+         <option>-fghci-hist-size=<replaceable>n</replaceable></option>.</para>
        </listitem>
       </varlistentry>
 
@@ -2194,14 +2415,18 @@ Prelude> :. cmds.ghci
 
       <varlistentry>
        <term>
-          <literal>:kind</literal> <replaceable>type</replaceable>
+          <literal>:kind</literal><optional><literal>!</literal></optional> 
+                        <replaceable>type</replaceable>
           <indexterm><primary><literal>:kind</literal></primary></indexterm>
         </term>
        <listitem>
          <para>Infers and prints the kind of
          <replaceable>type</replaceable>. The latter can be an arbitrary
            type expression, including a partial application of a type constructor,
-           such as <literal>Either Int</literal>.</para>
+           such as <literal>Either Int</literal>.  If you specify the 
+            optional "<literal>!</literal>", GHC will in addition normalise the type
+            by expanding out type synonyms and evaluating type-function applications,
+            and display the normalised result.</para>
        </listitem>
       </varlistentry>
 
@@ -2494,6 +2719,28 @@ bar
 
       <varlistentry>
        <term>
+          <literal>:seti</literal> <optional><replaceable>option</replaceable>...</optional>
+          <indexterm><primary><literal>:seti</literal></primary></indexterm>
+        </term>
+       <listitem>
+          <para>
+            Like <literal>:set</literal>, but options set with
+            <literal>:seti</literal> affect only expressions and
+            commands typed at the prompt, and not modules loaded with
+            <literal>:load</literal> (in contrast, options set with
+            <literal>:set</literal> apply everywhere).  See <xref
+            linkend="ghci-interactive-options" />.
+          </para>
+          <para>
+            Without any arguments, displays the current set of options
+            that are applied to expressions and commands typed at the
+            prompt.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
           <literal>:show bindings</literal>
           <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
         </term>
@@ -2525,6 +2772,18 @@ bar
 
       <varlistentry>
        <term>
+          <literal>:show imports</literal>
+          <indexterm><primary><literal>:show imports</literal></primary></indexterm>
+        </term>
+       <listitem>
+          <para>Show the imports that are currently in force, as
+          created by <literal>import</literal> and
+          <literal>:module</literal> commands.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
           <literal>:show modules</literal>
           <indexterm><primary><literal>:show modules</literal></primary></indexterm>
         </term>
@@ -2657,8 +2916,9 @@ bar
   </sect1>
 
   <sect1 id="ghci-set">
-    <title>The <literal>:set</literal> command</title>
+    <title>The <literal>:set</literal> and <literal>:seti</literal> commands</title>
     <indexterm><primary><literal>:set</literal></primary></indexterm>
+    <indexterm><primary><literal>:seti</literal></primary></indexterm>
 
     <para>The <literal>:set</literal> command sets two types of
     options: GHCi options, which begin with
@@ -2690,7 +2950,7 @@ bar
          <listitem>
            <para>Enable parsing of multiline commands.  A multiline command
            is prompted for when the current input line contains open layout
-           contexts.</para>
+            contexts (see <xref linkend="ghci-multiline" />).</para>
          </listitem>
        </varlistentry>
 
@@ -2752,10 +3012,10 @@ bar
 
       <para>Normal GHC command-line options may also be set using
       <literal>:set</literal>.  For example, to turn on
-      <option>-fglasgow-exts</option>, you would say:</para>
+      <option>-fwarn-missing-signatures</option>, you would say:</para>
 
 <screen>
-Prelude> :set -fglasgow-exts
+Prelude> :set -fwarn-missing-signatures
 </screen>
 
       <para>Any GHC command-line option that is designated as
@@ -2766,7 +3026,7 @@ Prelude> :set -fglasgow-exts
       <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
 
 <screen>
-Prelude> :set -fno-glasgow-exts
+Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses
 </screen>
 
       <para><xref linkend="flag-reference"/> lists the reverse for each
@@ -2778,7 +3038,74 @@ Prelude> :set -fno-glasgow-exts
       not take effect until the next reload.</para>
       <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
     </sect2>
+
+    <sect2 id="ghci-interactive-options">
+      <title>Setting options for interactive evaluation only</title>
+
+      <para>
+        GHCi actually maintains two sets of options: one set that
+        applies when loading modules, and another set that applies for
+        expressions and commands typed at the prompt.  The
+        <literal>:set</literal> command modifies both, but there is
+        also a <literal>:seti</literal> command (for "set
+        interactive") that affects only the second set.
+      </para>
+
+      <para>
+        The two sets of options can be inspected using the
+        <literal>:set</literal> and <literal>:seti</literal> commands
+        respectively, with no arguments.  For example, in a clean GHCi
+        session we might see something like this:
+      </para>
+
+<screen>
+Prelude> :seti
+base language is: Haskell2010
+with the following modifiers:
+  -XNoMonomorphismRestriction
+  -XNoDatatypeContexts
+  -XNondecreasingIndentation
+  -XExtendedDefaultRules
+GHCi-specific dynamic flag settings:
+other dynamic, non-language, flag settings:
+  -fimplicit-import-qualified
+warning settings:
+</screen>
+      <para>
+        Note that the option <option>-XExtendedDefaultRules</option>
+        is on, because we apply special defaulting rules to
+        expressions typed at the prompt (see <xref
+        linkend="extended-default-rules" />).
+      </para>
+
+      <para>
+        Furthermore, the Monomorphism Restriction is disabled by default in
+        GHCi (see <xref linkend="monomorphism" />).
+      </para>
+
+      <para>
+        It is often useful to change the language options for expressions typed
+        at the prompt only, without having that option apply to loaded modules
+        too.  For example
+<screen>
+:seti -XMonoLocalBinds
+</screen>
+        It would be undesirable if <option>-XMonoLocalBinds</option> were to
+        apply to loaded modules too: that might cause a compilation error, but
+        more commonly it will cause extra recompilation, because GHC will think
+        that it needs to recompile the module because the flags have changed.
+      </para>
+
+      <para>
+        It is therefore good practice if you are setting language
+        options in your <literal>.ghci</literal> file, to use
+        <literal>:seti</literal> rather than <literal>:set</literal>
+        unless you really do want them to apply to all modules you
+        load in GHCi.
+      </para>
+    </sect2>
   </sect1>
+
   <sect1 id="ghci-dot-files">
     <title>The <filename>.ghci</filename> file</title>
     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
@@ -2809,16 +3136,24 @@ Prelude> :set -fno-glasgow-exts
 
     <para>The <filename>ghci.conf</filename> file is most useful for
     turning on favourite options (eg. <literal>:set +s</literal>), and
-    defining useful macros.  Placing a <filename>.ghci</filename> file
+    defining useful macros.  Note: when setting language options in
+    this file it is usually desirable to use <literal>:seti</literal>
+    rather than <literal>:set</literal> (see <xref
+    linkend="ghci-interactive-options" />).
+    </para>
+
+    <para>
+    Placing a <filename>.ghci</filename> file
     in a directory with a Haskell project is a useful way to set
     certain project-wide options so you don't have to type them
-    every time you start GHCi: eg. if your project uses GHC extensions
+    every time you start GHCi: eg. if your project uses multi-parameter 
+    type classes, scoped type variables,
     and CPP, and has source files in three subdirectories A, B and C,
     you might put the following lines in
     <filename>.ghci</filename>:</para>
 
 <screen>
-:set -fglasgow-exts -cpp
+:set -XMultiParamTypeClasses -XScopedTypeVariables -cpp
 :set -iA:B:C
 </screen>
 
@@ -2843,6 +3178,10 @@ Prelude> :set -fno-glasgow-exts
     wiki page: <ulink
       url="http://haskell.org/haskellwiki/GHC/GHCi">GHC/GHCi</ulink></para>
 
+       <para>Additionally, any files specified with
+    <literal>-ghci-script</literal> flags will be read after the
+    standard files, allowing the use of custom .ghci files.</para>
+
     <para>Two command-line options control whether the
     startup files files are read:</para>
 
@@ -2859,15 +3198,12 @@ Prelude> :set -fno-glasgow-exts
       </varlistentry>
       <varlistentry>
        <term>
-          <option>-read-dot-ghci</option>
-          <indexterm><primary><option>-read-dot-ghci</option></primary></indexterm>
-        </term>
+         <option>-ghci-script</option>
+         <indexterm><primary><option>-ghci-script</option></primary></indexterm>
+    </term>
        <listitem>
-         <para>Read <filename>./.ghci</filename> and the other
-          startup files (see above).  This is normally the
-         default, but the <option>-read-dot-ghci</option> option may
-         be used to override a previous
-         <option>-ignore-dot-ghci</option> option.</para>
+         <para>Read a specific file after the usual startup files.
+         Maybe be specified repeatedly for multiple inputs.</para>
        </listitem>
       </varlistentry>
     </variablelist>