<literal>IO</literal> monad.
<screen>
Prelude> x <- return 42
-42
Prelude> print x
42
Prelude>
<literal>x</literal> in future statements, for example to print
it as we did above.</para>
- <para>GHCi will print the result of a statement if and only if:
+ <para>If <option>-fprint-bind-result</option> is set then
+ GHCi will print the result of a statement if and only if:
<itemizedlist>
<listitem>
<para>The statement is not a binding, or it is a monadic binding
<literal>Show</literal></para>
</listitem>
</itemizedlist>
- The automatic printing of binding results can be supressed with
- <option>:set -fno-print-bind-result</option> (this does not
- supress 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
- them, for example.</para>
+ <indexterm><primary><option>-fprint-bind-result</option></primary></indexterm><indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm>.
+ </para>
<para>Of course, you can also bind normal non-IO expressions
using the <literal>let</literal>-statement:</para>
<para>Note that <literal>let</literal> bindings do not automatically
print the value bound, unlike monadic bindings.</para>
+ <para>Hint: you can also use <literal>let</literal>-statements
+ to define functions at the prompt:</para>
+<screen>
+Prelude> let add a b = a + b
+Prelude> add 1 2
+3
+Prelude>
+</screen>
+ <para>However, this quickly gets tedious when defining functions
+ with multiple clauses, or groups of mutually recursive functions,
+ because the complete definition has to be given on a single line,
+ using explicit braces and semicolons instead of layout:</para>
+<screen>
+Prelude> let { f op n [] = n ; f op n (h:t) = h `op` f op n t }
+Prelude> f (+) 0 [1..3]
+6
+Prelude>
+</screen>
+ <para>To alleviate this issue, GHCi commands can be split over
+ multiple lines, by wrapping them in <literal>:{</literal> and
+ <literal>:}</literal> (each on a single line of its own):</para>
+<screen>
+Prelude> :{
+Prelude| let { g op n [] = n
+Prelude| ; g op n (h:t) = h `op` g op n t
+Prelude| }
+Prelude| :}
+Prelude> g (*) 1 [1..3]
+6
+</screen>
+ <para>Such multiline commands can be used with any GHCi command,
+ and the lines between <literal>:{</literal> and
+ <literal>:}</literal> are simply merged into a single line for
+ interpretation. That implies that each such group must form a single
+ valid command when merged, and that no layout rule is used.
+ The main purpose of multiline commands is not to replace module
+ loading but to make definitions in .ghci-files (see <xref
+ linkend="ghci-dot-files"/>) more readable and maintainable.</para>
+
<para>Any exceptions raised during the evaluation or execution
of the statement are caught and printed by the GHCi command line
interface (for more information on exceptions, see the module
<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><literal>!</literal></optional> <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
modules from packages) only the non-<literal>*</literal>
- form of <literal>:browse</literal> is available.</para>
+ form of <literal>:browse</literal> is available.
+ If the <literal>!</literal> symbol is appended to the
+ command, data constructors and class methods will be
+ listed individually, otherwise, they will only be listed
+ in the context of their data type or class declaration.
+ The <literal>!</literal>-form also annotates the listing
+ with comments giving possible imports for each group of
+ entries.</para>
</listitem>
</varlistentry>
</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>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable>
+ <literal>:def<optional>!</optional> <optional><replaceable>name</replaceable> <replaceable>expr</replaceable></optional></literal>
<indexterm><primary><literal>:def</literal></primary></indexterm>
</term>
<listitem>
- <para>The command <literal>:def</literal>
- <replaceable>name</replaceable>
- <replaceable>expr</replaceable> defines a new GHCi command
- <literal>:<replaceable>name</replaceable></literal>,
- implemented by the Haskell expression
- <replaceable>expr</replaceable>, which must have type
- <literal>String -> IO String</literal>. When
- <literal>:<replaceable>name</replaceable>
- <replaceable>args</replaceable></literal> is typed at the
- prompt, GHCi will run the expression
- <literal>(<replaceable>name</replaceable>
- <replaceable>args</replaceable>)</literal>, take the
- resulting <literal>String</literal>, and feed it back into
- GHCi as a new sequence of commands. Separate commands in
- the result must be separated by
- ‘<literal>\n</literal>’.</para>
+ <para><literal>:def</literal> is used to define new
+ commands, or macros, in GHCi. The command
+ <literal>:def</literal> <replaceable>name</replaceable>
+ <replaceable>expr</replaceable> defines a new GHCi command
+ <literal>:<replaceable>name</replaceable></literal>,
+ implemented by the Haskell expression
+ <replaceable>expr</replaceable>, which must have type
+ <literal>String -> IO String</literal>. When
+ <literal>:<replaceable>name</replaceable>
+ <replaceable>args</replaceable></literal> is typed at the
+ prompt, GHCi will run the expression
+ <literal>(<replaceable>name</replaceable>
+ <replaceable>args</replaceable>)</literal>, take the
+ resulting <literal>String</literal>, and feed it back into
+ GHCi as a new sequence of commands. Separate commands in
+ the result must be separated by
+ ‘<literal>\n</literal>’.</para>
<para>That's all a little confusing, so here's a few
examples. To start with, here's a new GHCi command which
<literal>:.</literal>, by analogy with the
‘<literal>.</literal>’ Unix shell command that
does the same thing.</para>
+
+ <para>Typing <literal>:def</literal> on its own lists the
+ currently-defined macros. Attempting to redefine an
+ existing command name results in an error unless the
+ <literal>:def!</literal> form is used, in which case the old
+ command with that name is silently overwritten.</para>
</listitem>
</varlistentry>
<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>:set</literal></primary></indexterm>
</term>
<listitem>
- <para>Sets various options. See <xref linkend="ghci-set"/>
- for a list of available options. The
- <literal>:set</literal> command by itself shows which
- options are currently set.</para>
+ <para>Sets various options. See <xref linkend="ghci-set"/> for a list of
+ available options and <xref linkend="interactive-mode-options"/> for a
+ list of GHCi-specific flags. The <literal>:set</literal> command by
+ itself shows which options are currently set. It also lists the current
+ dynamic flag settings, with GHCi-specific flags listed separately.</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>
+
+ <varlistentry>
+ <term>
+ <literal>:show packages</literal>
+ <indexterm><primary><literal>:show packages</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Show the currently active package flags, as well as the list of
+ packages currently loaded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <literal>:show languages</literal>
+ <indexterm><primary><literal>:show languages</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Show the currently active language flags.</para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>
<literal>:show [args|prog|prompt|editor|stop]</literal>
<indexterm><primary><literal>:show</literal></primary></indexterm>
</term>
<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>