<literal>Show</literal></para>
</listitem>
</itemizedlist>
- The automatic printing of binding results can be supressed with
+ The automatic printing of binding results can be suppressed with
<option>:set -fno-print-bind-result</option> (this does not
- supress printing the result of non-binding statements).
+ suppress printing the result of non-binding statements).
<indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm><indexterm><primary><option>-fprint-bind-result</option></primary></indexterm>.
You might want to do this to prevent the result of binding
statements from being fully evaluated by the act of printing
<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>
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
<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>
<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
</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>
+ <replaceable>expr</replaceable> is omitted, then it single-steps from
+ 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>
<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>
<varlistentry>
<term>
- <literal>:browse</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
+ <literal>:browse</literal> <optional><optional><literal>*</literal></optional><replaceable>module</replaceable></optional> ...
<indexterm><primary><literal>:browse</literal></primary></indexterm>
</term>
<listitem>
<para>Displays the identifiers defined by the module
<replaceable>module</replaceable>, which must be either
- loaded into GHCi or be a member of a package. If the
- <literal>*</literal> symbol is placed before the module
- name, then <emphasis>all</emphasis> the identifiers defined
- in <replaceable>module</replaceable> are shown; otherwise
- the list is limited to the exports of
+ loaded into GHCi or be a member of a package. If
+ <replaceable>module</replaceable> is omitted, the most
+ recently-loaded module is used.</para>
+
+ <para>If the <literal>*</literal> symbol is placed before
+ the module name, then <emphasis>all</emphasis> the
+ identifiers in scope in <replaceable>module</replaceable> are
+ shown; otherwise the list is limited to the exports of
<replaceable>module</replaceable>. The
<literal>*</literal>-form is only available for modules
which are interpreted; for compiled modules (including
</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
+ (<literal>:ctags</literal>) or
+ Emacs-style editors (<literal>:etags</literal>). If
+ no filename is specified, the default <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
<varlistentry>
<term>
+ <literal>:etags</literal>
+ </term>
+ <listitem>
+ <para>See <literal>:ctags</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:force <replaceable>identifier</replaceable> ...</literal>
<indexterm><primary><literal>:force</literal></primary></indexterm>
</term>
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>
However, we cannot simply pass the arguments to the
<literal>main</literal> function while we are testing in ghci,
as the <literal>main</literal> function doesn't take its
- directly.
+ arguments directly.
</para>
<para>
<listitem>
<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
+ unknown 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
<indexterm><primary><literal>:quit</literal></primary></indexterm>
</term>
<listitem>
- <para>Quits GHCi. You can also quit by typing a control-D
+ <para>Quits GHCi. You can also quit by typing control-D
at the prompt.</para>
</listitem>
</varlistentry>
<indexterm><primary><literal>:show modules</literal></primary></indexterm>
</term>
<listitem>
- <para>Show the list of modules currently load.</para>
+ <para>Show the list of modules currently loaded.</para>
</listitem>
</varlistentry>
<para>The <literal>:set</literal> command sets two types of
options: GHCi options, which begin with
- ‘<literal>+</literal>” and “command-line”
+ ‘<literal>+</literal>’, and “command-line”
options, which begin with ‘-’. </para>
<para>NOTE: at the moment, the <literal>:set</literal> command
<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>
projects / ghc-hetmet.git / blobdiff