Better document :stepover and its limitations

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

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 7a3c77a..82ee330 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1106,10 +1106,12 @@ 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>:stepover</literal> to step over function
+       applications, which of course are executed all the same. 
+       For example:</para>
 
 <screen>
 *Main> :step main
@@ -1118,13 +1120,53 @@ _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>In the current version of the debugger, <literal>:stepover</literal>
+       is limited to work locally in the lexical sense, that is in the context
+       of the current expression body.
+       When you run to the end of the expression, <literal>:stepover</literal>
+       stops working and switches to behave like regular <literal>:step</literal>. 
+       This means 
+       that it will fail to step over the last function application. As a result,
+       currently <literal>:stepover</literal> works great for monadic code, but 
+       interacts less perfectly with pure code. For example, if stopped at the 
+       line 2, on the entire expression 
+       <literal>qsort left ++ [a] ++ qsort right</literal>:</para>
+<screen>
+... [qsort2.hs:2:15-46] *Main> :step
+Stopped at qsort2.hs:2:15-46
+
+... [qsort2.hs:2:15-46] *Main> :list
+2  qsort (a:as) = qsort left ++ [a] ++ qsort right
+</screen>
+       
+      <para> The first <literal>:stepover</literal> will step over the first
+           <literal>qsort</literal> recursive call, as expected. The second one 
+           will step over the evaluation of <literal>[a]</literal>, again as
+           expected. However, the third one has lexically <quote>run out</quote>
+           of the current expression, and will behave like regular 
+           <literal>:step</literal>, performing one step of lazy evaluation and
+           stopping at the next breakpoint. In this case it is indeed the second
+           recursive application of <literal>qsort</literal>.</para>
+<screen>
+[qsort2.hs:2:36-46] *Main> :stepover
+Warning: no more breakpoints in this function body, switching to :step
+Stopped at qsort2.hs:(1,0)-(3,55)
+
+[qsort2.hs:2:36-46] *Main> :list
+_result :: [a]
+1  qsort [] = []
+2  qsort (a:as) = qsort left ++ [a] ++ qsort right
+3    where (left,right) = (filter (&lt;=a) as, filter (>a) as)
+</screen>
       <para>The <literal>:list</literal> command is particularly useful when
-        single-stepping, to see where you currently are:</para>
+        single-stepping, to see where you currently are, as just shown
+       in the above example.</para>
 
 <screen>
 [qsort.hs:5:7-47] *Main> :list
@@ -1486,6 +1528,10 @@ Just 20
             CAF (e.g. main), stop at a breakpoint, and ask for the value of the
             CAF at the prompt again.</para>
         </listitem>
+       <listitem> <literal>:stepover</literal> only works lexically locally, in the
+         body of the current expression. As a result, it can be rather impredictable
+         when used in pure functional code, as opposed to monadic code.
+       </listitem>
        <listitem><para>
          Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available 
          at the scope of a breakpoint if there is an explicit type signature.
@@ -1925,7 +1971,7 @@ Prelude> :. cmds.ghci
          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 <relaceable>name</replaceable>, 
+         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>