<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
</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 (<=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
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.
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>
<indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
</indexterm>
- <para>When it starts, GHCi always reads and executes commands from
- <filename>$HOME/.ghci</filename>, followed by
- <filename>./.ghci</filename>.</para>
+ <para>When it starts, unless the <literal>-ignore-dot-ghci</literal>
+ flag is given, GHCi reads and executes commands from
+ <filename>./.ghci</filename>, followed by
+ <filename>$HOME/.ghci</filename>.</para>
<para>The <filename>.ghci</filename> in your home directory is
most useful for turning on favourite options (eg. <literal>:set
project is a useful way to set certain project-wide options so you
don't have to type them everytime you start GHCi: eg. if your
project uses GHC extensions and CPP, and has source files in three
- subdirectories A B and C, you might put the following lines in
+ subdirectories A, B and C, you might put the following lines in
<filename>.ghci</filename>:</para>
<screen>
<term>I can't use Control-C to interrupt computations in
GHCi on Windows.</term>
<listitem>
- <para>See <xref linkend="ghci-windows"/></para>
+ <para>See <xref linkend="ghci-windows"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>The default buffering mode is different in GHCi to GHC.</term>
+ <listitem>
+ <para>
+ In GHC, the stdout handle is line-buffered by default.
+ However, in GHCi we turn off the buffering on stdout,
+ because this is normally what you want in an interpreter:
+ output appears as it is generated.
+ </para>
</listitem>
</varlistentry>
</variablelist>