Add -fghci-hist-size=N to set the number of previous steps stored by :trace
[ghc.git] / docs / users_guide / ghci.xml
index eea6f86..c59f4b3 100644 (file)
@@ -358,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>
@@ -370,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>
@@ -608,7 +614,7 @@ Prelude>
     <sect2 id="ghci-decls">
       <title>Type, class and other declarations</title>
 
-      <para>[<emphasis role="bold">New in version 7.4.1</emphasis>] At the GHCi
+      <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
@@ -656,6 +662,10 @@ Prelude>
       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">
@@ -1089,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">
@@ -1646,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">
@@ -1659,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
@@ -2311,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>
 
@@ -2648,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>
@@ -2823,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
@@ -2944,7 +3038,74 @@ Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses
       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>
@@ -2975,7 +3136,14 @@ Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses
 
     <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 multi-parameter 
@@ -3010,6 +3178,10 @@ Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses
     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>
 
@@ -3026,23 +3198,16 @@ Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses
       </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>
 
-    <para>Additional <filename>.ghci</filename> files can be added
-    through the <option>-ghci-script</option> option. These are
-    loaded after the normal <filename>.ghci</filename> files.</para>
-
   </sect1>
 
   <sect1 id="ghci-obj">