Prelude IO>
</screen>
- <para>(Note: <literal>:module</literal> can be shortened to
+ <para>(Note: you can use <literal>import M</literal> as an
+ alternative to <literal>:module +M</literal>, and
+ <literal>:module</literal> can also be shortened to
<literal>:m</literal>). The full syntax of the
<literal>:module</literal> command is:</para>
have no context information attached to them. Finding which
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>.</para>
+ <literal>Debug.Trace.trace</literal>, or compiling with
+ profiling and using <literal>+RTS -xc</literal> (see <xref
+ linkend="prof-time-options" />).</para>
<para>The GHCi debugger offers a way to hopefully shed some light on
these errors quickly and without modifying or recompiling the source
<variablelist>
<varlistentry>
<term>
+ <literal>:abandon</literal>
+ <indexterm><primary><literal>:abandon</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Abandons the current evaluation (only available when stopped at
+ a breakpoint).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:add</literal> <replaceable>module</replaceable> ...
<indexterm><primary><literal>:add</literal></primary></indexterm>
</term>
<varlistentry>
<term>
- <literal>:breakpoint</literal> <replaceable>list|add|continue|del|stop|step</replaceable> ...
- <indexterm><primary><literal>:breakpoint</literal></primary></indexterm>
+ <literal>:back</literal>
+ <indexterm><primary><literal>:back</literal></primary></indexterm>
</term>
<listitem>
- <para>Permits to add, delete or list the breakpoints in a debugging session.
- </para>
+ <para>Travel back one step in the history. See <xref
+ linkend="tracing" />. See also:
+ <literal>:trace</literal>, <literal>:history</literal>,
+ <literal>:forward</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:break [<replaceable>identifier</replaceable> |
+ [<replaceable>module</replaceable>] <replaceable>line</replaceable>
+ [<replaceable>column</replaceable>]]</literal>
+ </term>
+ <indexterm><primary><literal>:break</literal></primary></indexterm>
+ <listitem>
+ <para>Set a breakpoint on the specified function or line and
+ column. See <xref linkend="setting-breakpoints" />.</para>
</listitem>
</varlistentry>
<literal>:continue</literal>
<indexterm><primary><literal>:continue</literal></primary></indexterm>
</term>
- <listitem><para>Shortcut to <literal>:breakpoint continue</literal></para>
+ <listitem><para>Continue the current evaluation, when stopped at a
+ breakpoint.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:cmd</literal> <replaceable>expr</replaceable>
+ <indexterm><primary><literal>:cmd</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Executes <replaceable>expr</replaceable> as a computation of
+ type <literal>IO String</literal>, and then executes the resulting
+ string as a list of GHCi commands. Multiple commands are separated
+ by newlines. The <literal>:cmd</literal> command is useful with
+ <literal>:def</literal> and <literal>:set stop</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional>
+ <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional>
+ <indexterm><primary><literal>:etags</literal></primary>
+ </indexterm>
+ <indexterm><primary><literal>:etags</literal></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Generates a “tags” file for Vi-style editors
+ (<literal>:ctags</literal>) or Emacs-style editors (<literal>etags</literal>). If
+ no filename is specified, the defaulit <filename>tags</filename> or
+ <filename>TAGS</filename> is
+ used, respectively. Tags for all the functions, constructors and
+ types in the currently loaded modules are created. All modules must
+ be interpreted for these commands to work.</para>
+ <para>See also <xref linkend="hasktags" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <literal>:delete * | <replaceable>num</replaceable> ...</literal>
+ <indexterm><primary><literal>:delete</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Delete one or more breakpoints by number (use <literal>:show
+ breaks</literal> to see the number of each breakpoint). The
+ <literal>*</literal> form deletes all the breakpoints.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:edit <optional><replaceable>file</replaceable></optional></literal>
<indexterm><primary><literal>:edit</literal></primary></indexterm>
</term>
<varlistentry>
<term>
+ <literal>:force <replaceable>identifier</replaceable> ...</literal>
+ <indexterm><primary><literal>:force</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Prints the value of <replaceable>identifier</replaceable> in
+ the same way as <literal>:print</literal>. Unlike
+ <literal>:print</literal>, <literal>:force</literal> evaluates each
+ thunk that it encounters while traversing the value. This may
+ cause exceptions or infinite loops, or further breakpoints (which
+ are ignored, but displayed).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:forward</literal>
+ <indexterm><primary><literal>:forward</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Move forward in the history. See <xref
+ linkend="tracing" />. See also:
+ <literal>:trace</literal>, <literal>:history</literal>,
+ <literal>:back</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:help</literal>
<indexterm><primary><literal>:help</literal></primary></indexterm>
</term>
<varlistentry>
<term>
+ <literal>:history [<replaceable>num</replaceable>]</literal>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:info</literal> <replaceable>name</replaceable> ...
<indexterm><primary><literal>:info</literal></primary></indexterm>
</term>
<varlistentry>
<term>
+ <literal>:kind</literal> <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:load</literal> <replaceable>module</replaceable> ...
<indexterm><primary><literal>:load</literal></primary></indexterm>
</term>
<literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal>
<indexterm><primary><literal>:module</literal></primary></indexterm>
</term>
+ <term>
+ <literal>import <replaceable>mod</replaceable></literal>
+ </term>
<listitem>
<para>Sets or modifies the current context for statements
- typed at the prompt. See <xref linkend="ghci-scope"/> for
+ typed at the prompt. The form <literal>import
+ <replaceable>mod</replaceable></literal> is equivalent to
+ <literal>:module +<replaceable>mod</replaceable></literal>.
+ See <xref linkend="ghci-scope"/> for
more details.</para>
</listitem>
</varlistentry>
<indexterm><primary><literal>:print</literal></primary></indexterm>
</term>
<listitem>
- <para> Prints a semievaluated value without forcing its evaluation.
- <literal>:print </literal> works just like <literal>:sprint</literal> but additionally,
- <literal>:print</literal> binds the unevaluated parts -called
- <quote>suspensions</quote>-
- to names which you can play with. For example:
-<screen>
-Prelude> let li = map Just [1..5]
-Prelude> :sp li
-li - _
-Prelude> :p li
-li - (_t1::[Maybe Integer])
-Prelude> head li
-Just 1
-Prelude> :sp li
-li - Just 1 : _
-Prelude> :p li
-li - Just 1 : (_t2::[Maybe Integer])
-Prelude> last li
-Just 5
-Prelude> :sp li
-li - [Just 1,_,_,_,Just 5]
-Prelude> :p li
-li - [Just 1,(_t3::Maybe Integer),(_t4::Maybe Integer),(_t5::Maybe Integer),Just 4]
-Prelude> _t4
-Just 3
-Prelude> :p li
-li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4]
-</screen>
- The example uses <literal>:print</literal> and <literal>:sprint</literal>
- to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
- with it. Note for instance how <quote>last</quote> traverses all the elements of
- the list to compute its result, but without evaluating the individual elements.
- </para>
+ <para>Prints a value without forcing its evaluation.
+ <literal>:print</literal> may be used on values whose types are
+ unkonwn or partially known, which might be the case for local
+ variables with polymorphic types at a breakpoint. While inspecting
+ the runtime value, <literal>:print</literal> attempts to
+ reconstruct the type of the value, and will elaborate the type in
+ GHCi's environment if possible. If any unevaluated components
+ (thunks) are encountered, then <literal>:print</literal> binds
+ a fresh variable with a name beginning with <literal>_t</literal>
+ to each thunk. See <xref linkend="breakpoints" /> for more
+ information. See also the <literal>:sprint</literal> command,
+ which works like <literal>:print</literal> but does not bind new
+ variables.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <literal>:set</literal> <literal>stop</literal>
+ [<replaceable>num</replaceable>] <replaceable>cmd</replaceable>
+ </term>
+ <listitem>
+ <para>Set a command to be executed when a breakpoint is hit, or a new
+ item in the history is selected. The most common use of
+ <literal>:set stop</literal> is to display the source code at the
+ current location, e.g. <literal>:set stop :list</literal>.</para>
+
+ <para>If a number is given before the command, then the commands are
+ run when the specified breakpoint (only) is hit. This can be quite
+ useful: for example, <literal>:set stop 1 :continue</literal>
+ effectively disables breakpoint 1, by running
+ <literal>:continue</literal> whenever it is hit (although GHCi will
+ still emit a message to say the breakpoint was hit). What's more,
+ with cunning use of <literal>:def</literal> and
+ <literal>:cmd</literal> you can use <literal>:set stop</literal> to
+ implement conditional breakpoints:</para>
+<screen>
+*Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
+*Main> :set stop 0 :cond (x < 3)
+</screen>
+ <para>Ignoring breakpoints for a specified number of iterations is
+ also possible using similar techniques.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:show bindings</literal>
<indexterm><primary><literal>:show bindings</literal></primary></indexterm>
</term>
<varlistentry>
<term>
+ <literal>:show breaks</literal>
+ <indexterm><primary><literal>:show breaks</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>List the active breakpoints.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:show context</literal>
+ <indexterm><primary><literal>:show context</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>List the active evaluations that are stopped at breakpoints.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:show modules</literal>
<indexterm><primary><literal>:show modules</literal></primary></indexterm>
</term>
<para>Show the list of modules currently load.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:show [args|prog|prompt|editor|stop]</literal>
+ <indexterm><primary><literal>:show</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Displays the specified setting (see
+ <literal>:set</literal>).</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<literal>:sprint</literal>
<indexterm><primary><literal>:sprint</literal></primary></indexterm>
</term>
<listitem>
- <para>Prints a semievaluated value without forcing its evaluation.
- <literal>:sprint</literal> and its sibling <literal>:print</literal>
- are very useful to observe how lazy evaluation works in your code. For example:
-<screen>
-Prelude> let li = map Just [1..5]
-Prelude> :sp li
-li - _
-Prelude> head li
-Just 1
-Prelude> :sp li
-li - Just 1 : _
-Prelude> last li
-Just 5
-Prelude> :sp li
-li - [Just 1,_,_,_,Just 5]
-</screen>
- The example uses <literal>:sprint</literal> to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
- with it. Note for instance how <quote>last</quote> traverses all the elements of
- the list to compute its result, but without evaluating the individual elements.
- </para>
+ <para>Prints a value without forcing its evaluation.
+ <literal>:sprint</literal> is similar to <literal>:print</literal>,
+ with the difference that unevaluated subterms are not bound to new
+ variables, they are simply denoted by ‘_’.</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
- <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional>
- <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional>
- <indexterm><primary><literal>:etags</literal></primary>
- </indexterm>
- <indexterm><primary><literal>:etags</literal></primary>
- </indexterm>
- </term>
+ <literal>:step [<replaceable>expr</replaceable>]</literal>
+ <indexterm><primary><literal>:step</literal></primary></indexterm>
+ </term>
<listitem>
- <para>Generates a “tags” file for Vi-style editors
- (<literal>:ctags</literal>) or Emacs-style editors (<literal>etags</literal>). If
- no filename is specified, the defaulit <filename>tags</filename> or
- <filename>TAGS</filename> is
- used, respectively. Tags for all the functions, constructors and
- types in the currently loaded modules are created. All modules must
- be interpreted for these commands to work.</para>
- <para>See also <xref linkend="hasktags" />.</para>
+ <para>Single-step from the last breakpoint. With an expression
+ argument, begins evaluation of the expression with a
+ single-step.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>:type</literal> <replaceable>expression</replaceable>
- <indexterm><primary><literal>:type</literal></primary></indexterm>
+ <literal>:trace [<replaceable>expr</replaceable>]</literal>
+ <indexterm><primary><literal>:trace</literal></primary></indexterm>
</term>
<listitem>
- <para>Infers and prints the type of
- <replaceable>expression</replaceable>, including explicit
- forall quantifiers for polymorphic types. The monomorphism
- restriction is <emphasis>not</emphasis> applied to the
- expression during type inference.</para>
+ <para>Evaluates the given expression (or from the last breakpoint if
+ no expression is given), and additionally logs the evaluation
+ steps for later inspection using <literal>:history</literal>. See
+ <xref linkend="tracing" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>:kind</literal> <replaceable>type</replaceable>
- <indexterm><primary><literal>:kind</literal></primary></indexterm>
+ <literal>:type</literal> <replaceable>expression</replaceable>
+ <indexterm><primary><literal>:type</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>
+ <para>Infers and prints the type of
+ <replaceable>expression</replaceable>, including explicit
+ forall quantifiers for polymorphic types. The monomorphism
+ restriction is <emphasis>not</emphasis> applied to the
+ expression during type inference.</para>
</listitem>
</varlistentry>