GHCi debugger: Added a -fprint-evld-with-show flag

[ghc-hetmet.git] / docs / users_guide / ghci.xml

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 86bfa8f..579cf23 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -929,6 +929,7 @@ right :: [a]
         <literal>left</literal>:</para>
 
 <screen>
+[qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show
 [qsort.hs:2:15-46] *Main> :print left
 left = (_t1::[a])
 </screen>
@@ -948,6 +949,13 @@ left = (_t1::[a])
         underscore, in this case
         <literal>_t1</literal>.</para>
 
+      <para>The flag <literal>-fprint-evld-with-show</literal> instructs
+      <literal>:print</literal> to reuse
+      available <literal>Show</literal> instances when possible. This happens
+      only when the contents of the variable being inspected 
+      are completely evaluated.</para>
+
+
       <para>If we aren't concerned about preserving the evaluatedness of a
         variable, we can use <literal>:force</literal> instead of
         <literal>:print</literal>.  The <literal>:force</literal> command
@@ -1017,6 +1025,7 @@ right :: [a]
       <para>The execution continued at the point it previously stopped, and has
         now stopped at the breakpoint for a second time.</para>
 
+
       <sect3 id="setting-breakpoints">
         <title>Setting breakpoints</title>
 
@@ -1106,10 +1115,14 @@ right :: [a]
 
       <para>Single-stepping is a great way to visualise the execution of your
         program, and it is also a useful tool for identifying the source of a
-        bug.  The concept is simple: single-stepping enables all the
-        breakpoints in the program and executes until the next breakpoint is
-        reached, at which point you can single-step again, or continue
-        normally.  For example:</para>
+        bug. GHCi offers two variants of stepping. Use 
+       <literal>:step</literal>  to enable all the
+        breakpoints in the program, and execute until the next breakpoint is
+        reached. Use <literal>:steplocal</literal> to limit the set
+       of enabled breakpoints to those in the current top level function.
+       Similarly, use <literal>:stepmodule</literal> to single step only on
+       breakpoints contained in the current module.
+       For example:</para>
 
 <screen>
 *Main> :step main
@@ -1118,10 +1131,11 @@ _result :: IO ()
 </screen>
 
       <para>The command <literal>:step
-          <replaceable>expr</replaceable></literal> begins the evaluation of
+        <replaceable>expr</replaceable></literal> begins the evaluation of
         <replaceable>expr</replaceable> in single-stepping mode.  If
         <replaceable>expr</replaceable> is ommitted, then it single-steps from
-        the current breakpoint.</para>
+        the current breakpoint. <literal>:stepover</literal> 
+        works similarly.</para>
 
       <para>The <literal>:list</literal> command is particularly useful when
         single-stepping, to see where you currently are:</para>
@@ -1330,9 +1344,13 @@ a :: a
         <literal>:trace</literal> and <literal>:history</literal> to establish
         the context.  However, <literal>head</literal> is in a library and
         we can't set a breakpoint on it directly.  For this reason, GHCi
-        provides the flag <literal>-fbreak-on-exception</literal> which causes
-        the evaluator to stop when an exception is thrown, just as it does when
-        a breakpoint is hit.  This is only really useful in conjunction with
+        provides the flags <literal>-fbreak-on-exception</literal> which causes
+        the evaluator to stop when an exception is thrown, and <literal>
+       -fbreak-on-error</literal>, which works similarly but stops only on 
+       uncaught exceptions. When stopping at an exception, GHCi will act 
+       just as it does when a breakpoint is hit, with the deviation that it
+       will not show you any source code location. Due to this, these 
+       commands are only really useful in conjunction with
         <literal>:trace</literal>, in order to log the steps leading up to the
         exception.  For example:</para>
 
@@ -1923,6 +1941,12 @@ Prelude> :. cmds.ghci
          will be printed.  If <replaceable>name</replaceable> has
          been loaded from a source file, then GHCi will also display
          the location of its definition in the source.</para>
+         <para>For types and classes, GHCi also summarises instances that
+         mention them.  To avoid showing irrelevant information, an instance
+         is shown only if (a) its head mentions <replaceable>name</replaceable>, 
+         and (b) all the other things mentioned in the instance
+         are in scope (either qualified or otherwise) as a result of 
+         a <literal>:load</literal> or <literal>:module</literal> commands. </para>
        </listitem>
       </varlistentry>