</indexterm>, then you'll be right at home with GHCi. However, GHCi
also has support for interactively loading compiled code, as well as
supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
- </footnote> the language extensions that GHC provides.</para>
+ </footnote> the language extensions that GHC provides.
<indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
- <indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
+ <indexterm><primary>Foreign Function
+ Interface</primary><secondary>GHCi support</secondary></indexterm>.
+ GHCi also includes an interactive debugger (see <xref linkend="ghci-debugger"/>).</para>
<sect1 id="ghci-introduction">
<title>Introduction to GHCi</title>
<screen>
$ ghci
- ___ ___ _
- / _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 6.6, for Haskell 98.
-/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
-\____/\/ /_/\____/|_| Type :? for help.
-
+GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
Loading package base ... linking ... done.
Prelude>
</screen>
<para>There may be a short pause while GHCi loads the prelude and
- standard libraries, after which the prompt is shown. If we follow
- the instructions and type <literal>:?</literal> for help, we
- get:</para>
-
-<screen>
- Commands available from the prompt:
-
- <stmt> evaluate/run <stmt>
- :add <filename> ... add module(s) to the current target set
- :browse [*]<module> display the names defined by <module>
- :cd <dir> change directory to <dir>
- :def <cmd> <expr> define a command :<cmd>
- :edit <file> edit file
- :edit edit last module
- :help, :? display this list of commands
- :info [<name> ...] display information about the given names
- :load <filename> ... load module(s) and their dependents
- :module [+/-] [*]<mod> ... set the context for expression evaluation
- :main [<arguments> ...] run the main function with the given arguments
- :reload reload the current module set
-
- :set <option> ... set options
- :set args <arg> ... set the arguments returned by System.getArgs
- :set prog <progname> set the value returned by System.getProgName
- :set prompt <prompt> set the prompt used in GHCi
- :set editor <cmd> set the command used for :edit
-
- :show modules show the currently loaded modules
- :show bindings show the current bindings made at the prompt
-
- :ctags [<file>] create tags file for Vi (default: "tags")
- :etags [<file>] create tags file for Emacs (default: "TAGS")
- :type <expr> show the type of <expr>
- :kind <type> show the kind of <type>
- :undef <cmd> undefine user-defined command :<cmd>
- :unset <option> ... unset options
- :quit exit GHCi
- :!<command> run the shell command <command>
-
- Options for ':set' and ':unset':
-
- +r revert top-level expressions after each evaluation
- +s print timing/memory stats after each evaluation
- +t print type after evaluation
- -<flags> most GHC command line flags can also be set here
- (eg. -v2, -fglasgow-exts, etc.)
-</screen>
+ standard libraries, after which the prompt is shown. As the banner
+ says, you can type <literal>:?</literal> to see the list of commands
+ available, and a half line description of each of them.</para>
<para>We'll explain most of these commands as we go along. For
Hugs users: many things work the same as in Hugs, so you should be
<screen>
Prelude> :! ghc -c D.hs
Prelude> :load A
-Skipping D ( D.hs, D.o )
-Compiling C ( C.hs, interpreted )
Compiling B ( B.hs, interpreted )
+Compiling C ( C.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
*Main>
</screen>
- <para>In the messages from the compiler, we see that it skipped D,
- and used the object file <filename>D.o</filename>. The message
- <literal>Skipping</literal> <replaceable>module</replaceable>
- indicates that compilation for <replaceable>module</replaceable>
- isn't necessary, because the source and everything it depends on
+ <para>In the messages from the compiler, we see that there is no line
+ for <literal>D</literal>. This is because
+ it isn't necessary to compile <literal>D</literal>,
+ because the source and everything it depends on
is unchanged since the last compilation.</para>
<para>At any time you can use the command
A ( A.hs, interpreted )
*Main></screen>
- <para>If we now modify the source of D (or pretend to: using Unix
+ <para>If we now modify the source of D (or pretend to: using the Unix
command <literal>touch</literal> on the source file is handy for
this), the compiler will no longer be able to use the object file,
because it might be out of date:</para>
*Main> :! touch D.hs
*Main> :reload
Compiling D ( D.hs, interpreted )
-Skipping C ( C.hs, interpreted )
-Skipping B ( B.hs, interpreted )
-Skipping A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
*Main>
</screen>
*Main> :! ghc -c C.hs
*Main> :load A
Compiling D ( D.hs, interpreted )
-Compiling C ( C.hs, interpreted )
Compiling B ( B.hs, interpreted )
+Compiling C ( C.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
</screen>
<screen>
*Main> :load A
-Skipping D ( D.hs, D.o )
-Skipping C ( C.hs, C.o )
Compiling B ( B.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
when working on a large program is to occasionally run
<literal>ghc ––make</literal> to compile the whole project (say
before you go for lunch :-), then continue working in the
- interpreter. As you modify code, the new modules will be
+ interpreter. As you modify code, the changed modules will be
interpreted, but the rest of the project will remain
compiled.</para>
<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
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>
<para>
Hint: GHCi will tab-complete names that are in scope; for
example, if you run GHCi and type <literal>J<tab></literal>
- then GHCi will expand it to <literal>Just </literal>.
+ then GHCi will expand it to “<literal>Just </literal>”.
</para>
<sect3>
</sect3>
<sect3>
- <title>The <literal>:main</literal> command</title>
+ <title>The <literal>:main</literal> and <literal>:run</literal> commands</title>
<para>
When a program is compiled and executed, it can use the
["foo","bar"]
</screen>
+ <para>
+ We can also quote arguments which contains characters like
+ spaces, and they are treated like Haskell strings, or we can
+ just use Haskell list syntax:
+ </para>
+
+<screen>
+Prelude> :main foo "bar baz"
+["foo","bar baz"]
+Prelude> :main ["foo", "bar baz"]
+["foo","bar baz"]
+</screen>
+
+ <para>
+ Finally, other functions can be called, either with the
+ <literal>-main-is</literal> flag or the <literal>:run</literal>
+ command:
+ </para>
+
+<screen>
+Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
+Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
+Prelude> :set -main-is foo
+Prelude> :main foo "bar baz"
+foo
+["foo","bar baz"]
+Prelude> :run bar ["foo", "bar baz"]
+bar
+["foo","bar baz"]
+</screen>
+
</sect3>
</sect2>
</listitem>
</orderedlist>
At the GHCi prompt, or with GHC if the
- <literal>-fextended-default-rules</literal> flag is given,
+ <literal>-XExtendedDefaultRules</literal> flag is given,
the following additional differences apply:
<itemizedlist>
<listitem>
instance that returns <literal>IO a</literal>.
However, it is only able to return
<literal>undefined</literal>
- (the reason for the instance having this type is to not require
- extensions to the class system), so if the type defaults to
+ (the reason for the instance having this type is so that printf
+ doesn't require extensions to the class system), so if the type defaults to
<literal>Integer</literal> then ghci gives an error when running a
printf.
</para>
</sect2>
</sect1>
- <sect1 id="ghci-invocation">
- <title>Invoking GHCi</title>
- <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
- <indexterm><primary><option>––interactive</option></primary></indexterm>
+ <sect1 id="ghci-debugger">
+ <title>The GHCi Debugger</title>
+ <indexterm><primary>debugger</primary><secondary>in GHCi</secondary>
+ </indexterm>
- <para>GHCi is invoked with the command <literal>ghci</literal> or
- <literal>ghc ––interactive</literal>. One or more modules or
- filenames can also be specified on the command line; this
- instructs GHCi to load the specified modules or filenames (and all
- the modules they depend on), just as if you had said
- <literal>:load <replaceable>modules</replaceable></literal> at the
- GHCi prompt (see <xref linkend="ghci-commands"/>). For example, to
- start GHCi and load the program whose topmost module is in the
- file <literal>Main.hs</literal>, we could say:</para>
+ <para>GHCi contains a simple imperative-style debugger in which you can
+ stop a running computation in order to examine the values of
+ variables. The debugger is integrated into GHCi, and is turned on by
+ default: no flags are required to enable the debugging
+ facilities. There is one major restriction: breakpoints and
+ single-stepping are only available in interpreted modules;
+ compiled code is invisible to the debugger<footnote><para>Note that packages
+ only contain compiled code, so debugging a package requires
+ finding its source and loading that directly.</para></footnote>.</para>
+
+ <para>The debugger provides the following:
+ <itemizedlist>
+ <listitem>
+ <para>The ability to set a <firstterm>breakpoint</firstterm> on a
+ function definition or expression in the program. When the function
+ is called, or the expression evaluated, GHCi suspends
+ execution and returns to the prompt, where you can inspect the
+ values of local variables before continuing with the
+ execution.</para>
+ </listitem>
+ <listitem>
+ <para>Execution can be <firstterm>single-stepped</firstterm>: the
+ evaluator will suspend execution approximately after every
+ reduction, allowing local variables to be inspected. This is
+ equivalent to setting a breakpoint at every point in the
+ program.</para>
+ </listitem>
+ <listitem>
+ <para>Execution can take place in <firstterm>tracing
+ mode</firstterm>, in which the evaluator remembers each
+ evaluation step as it happens, but doesn't suspend execution until
+ an actual breakpoint is reached. When this happens, the history of
+ evaluation steps can be inspected.</para>
+ </listitem>
+ <listitem>
+ <para>Exceptions (e.g. pattern matching failure and
+ <literal>error</literal>) can be treated as breakpoints, to help
+ locate the source of an exception in the program.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>There is currently no support for obtaining a “stack
+ trace”, but the tracing and history features provide a
+ useful second-best, which will often be enough to establish the
+ context of an error. For instance, it is possible to break
+ automatically when an exception is thrown, even if it is thrown
+ from within compiled code (see <xref
+ linkend="ghci-debugger-exceptions" />).</para>
+
+ <sect2 id="breakpoints">
+ <title>Breakpoints and inspecting variables</title>
+
+ <para>Let's use quicksort as a running example. Here's the code:</para>
+
+<programlisting>
+qsort [] = []
+qsort (a:as) = qsort left ++ [a] ++ qsort right
+ where (left,right) = (filter (<=a) as, filter (>a) as)
+
+main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+</programlisting>
+
+ <para>First, load the module into GHCi:</para>
<screen>
-$ ghci Main.hs
-</screen>
+Prelude> :l qsort.hs
+[1 of 1] Compiling Main ( qsort.hs, interpreted )
+Ok, modules loaded: Main.
+*Main>
+ </screen>
- <para>Most of the command-line options accepted by GHC (see <xref
- linkend="using-ghc"/>) also make sense in interactive mode. The ones
- that don't make sense are mostly obvious; for example, GHCi
- doesn't generate interface files, so options related to interface
- file generation won't have any effect.</para>
+ <para>Now, let's set a breakpoint on the right-hand-side of the second
+ equation of qsort:</para>
- <sect2>
- <title>Packages</title>
- <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
+<programlisting>
+*Main> :break 2
+Breakpoint 0 activated at qsort.hs:2:15-46
+*Main>
+</programlisting>
+
+ <para>The command <literal>:break 2</literal> sets a breakpoint on line
+ 2 of the most recently-loaded module, in this case
+ <literal>qsort.hs</literal>. Specifically, it picks the
+ leftmost complete subexpression on that line on which to set the
+ breakpoint, which in this case is the expression
+ <literal>(qsort left ++ [a] ++ qsort right)</literal>.</para>
- <para>Most packages (see <xref linkend="using-packages"/>) are
- available without needing to specify any extra flags at all:
- they will be automatically loaded the first time they are
- needed.</para>
+ <para>Now, we run the program:</para>
- <para>For non-auto packages, however, you need to request the
- package be loaded by using the <literal>-package</literal> flag:</para>
+<programlisting>
+*Main> main
+Stopped at qsort.hs:2:15-46
+_result :: [a]
+a :: a
+left :: [a]
+right :: [a]
+[qsort.hs:2:15-46] *Main>
+</programlisting>
+
+ <para>Execution has stopped at the breakpoint. The prompt has changed to
+ indicate that we are currently stopped at a breakpoint, and the location:
+ <literal>[qsort.hs:2:15-46]</literal>. To further clarify the
+ location, we can use the <literal>:list</literal> command:</para>
+
+<programlisting>
+[qsort.hs:2:15-46] *Main> :list
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+</programlisting>
+
+ <para>The <literal>:list</literal> command lists the source code around
+ the current breakpoint. If your output device supports it, then GHCi
+ will highlight the active subexpression in bold.</para>
+
+ <para>GHCi has provided bindings for the free variables<footnote><para>We
+ originally provided bindings for all variables in scope, rather
+ than just
+ the free variables of the expression, but found that this affected
+ performance considerably, hence the current restriction to just the
+ free variables.</para>
+ </footnote> of the expression
+ on which the
+ breakpoint was placed (<literal>a</literal>, <literal>left</literal>,
+ <literal>right</literal>), and additionally a binding for the result of
+ the expression (<literal>_result</literal>). These variables are just
+ like other variables that you might define in GHCi; you
+ can use them in expressions that you type at the prompt, you can ask
+ for their types with <literal>:type</literal>, and so on. There is one
+ important difference though: these variables may only have partial
+ types. For example, if we try to display the value of
+ <literal>left</literal>:</para>
<screen>
-$ ghci -package readline
- ___ ___ _
- / _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 6.6, for Haskell 98.
-/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
-\____/\/ /_/\____/|_| Type :? for help.
+[qsort.hs:2:15-46] *Main> left
-Loading package base ... linking ... done.
-Loading package readline-1.0 ... linking ... done.
-Prelude>
+<interactive>:1:0:
+ Ambiguous type variable `a' in the constraint:
+ `Show a' arising from a use of `print' at <interactive>:1:0-3
+ Cannot resolve unknown runtime types: a
+ Use :print or :force to determine these types
</screen>
- <para>The following command works to load new packages into a
- running GHCi:</para>
+ <para>This is because <literal>qsort</literal> is a polymorphic function,
+ and because GHCi does not carry type information at runtime, it cannot
+ determine the runtime types of free variables that involve type
+ variables. Hence, when you ask to display <literal>left</literal> at
+ the prompt, GHCi can't figure out which instance of
+ <literal>Show</literal> to use, so it emits the type error above.</para>
+
+ <para>Fortunately, the debugger includes a generic printing command,
+ <literal>:print</literal>, which can inspect the actual runtime value of a
+ variable and attempt to reconstruct its type. If we try it on
+ <literal>left</literal>:</para>
<screen>
-Prelude> :set -package <replaceable>name</replaceable>
+[qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show
+[qsort.hs:2:15-46] *Main> :print left
+left = (_t1::[a])
</screen>
- <para>But note that doing this will cause all currently loaded
- modules to be unloaded, and you'll be dumped back into the
- <literal>Prelude</literal>.</para>
- </sect2>
+ <para>This isn't particularly enlightening. What happened is that
+ <literal>left</literal> is bound to an unevaluated computation (a
+ suspension, or <firstterm>thunk</firstterm>), and
+ <literal>:print</literal> does not force any evaluation. The idea is
+ that <literal>:print</literal> can be used to inspect values at a
+ breakpoint without any unfortunate side effects. It won't force any
+ evaluation, which could cause the program to give a different answer
+ than it would normally, and hence it won't cause any exceptions to be
+ raised, infinite loops, or further breakpoints to be triggered (see
+ <xref linkend="nested-breakpoints" />).
+ Rather than forcing thunks, <literal>:print</literal>
+ binds each thunk to a fresh variable beginning with an
+ 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
+ behaves exactly like <literal>:print</literal>, except that it forces
+ the evaluation of any thunks it encounters:</para>
- <sect2>
- <title>Extra libraries</title>
- <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
-
- <para>Extra libraries may be specified on the command line using
- the normal <literal>-l<replaceable>lib</replaceable></literal>
- option. (The term <emphasis>library</emphasis> here refers to
- libraries of foreign object code; for using libraries of Haskell
- source code, see <xref linkend="ghci-modules-filenames"/>.) For
- example, to load the “m” library:</para>
+<screen>
+[qsort.hs:2:15-46] *Main> :force left
+left = [4,0,3,1]
+</screen>
+
+ <para>Now, since <literal>:force</literal> has inspected the runtime
+ value of <literal>left</literal>, it has reconstructed its type. We
+ can see the results of this type reconstruction:</para>
<screen>
-$ ghci -lm
+[qsort.hs:2:15-46] *Main> :show bindings
+_result :: [Integer]
+a :: Integer
+left :: [Integer]
+right :: [Integer]
+_t1 :: [Integer]
</screen>
- <para>On systems with <literal>.so</literal>-style shared
- libraries, the actual library loaded will the
- <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi
- searches the following places for libraries, in this order:</para>
+ <para>Not only do we now know the type of <literal>left</literal>, but
+ all the other partial types have also been resolved. So we can ask
+ for the value of <literal>a</literal>, for example:</para>
- <itemizedlist>
- <listitem>
- <para>Paths specified using the
- <literal>-L<replaceable>path</replaceable></literal>
- command-line option,</para>
- </listitem>
- <listitem>
- <para>the standard library search path for your system,
- which on some systems may be overridden by setting the
- <literal>LD_LIBRARY_PATH</literal> environment
- variable.</para>
- </listitem>
- </itemizedlist>
+<screen>
+[qsort.hs:2:15-46] *Main> a
+8
+</screen>
+
+ <para>You might find it useful to use Haskell's
+ <literal>seq</literal> function to evaluate individual thunks rather
+ than evaluating the whole expression with <literal>:force</literal>.
+ For example:</para>
- <para>On systems with <literal>.dll</literal>-style shared
- libraries, the actual library loaded will be
- <filename><replaceable>lib</replaceable>.dll</filename>. Again,
- GHCi will signal an error if it can't find the library.</para>
+<screen>
+[qsort.hs:2:15-46] *Main> :print right
+right = (_t1::[Integer])
+[qsort.hs:2:15-46] *Main> seq _t1 ()
+()
+[qsort.hs:2:15-46] *Main> :print right
+right = 23 : (_t2::[Integer])
+</screen>
- <para>GHCi can also load plain object files
- (<literal>.o</literal> or <literal>.obj</literal> depending on
- your platform) from the command-line. Just add the name the
- object file to the command line.</para>
+ <para>We evaluated only the <literal>_t1</literal> thunk, revealing the
+ head of the list, and the tail is another thunk now bound to
+ <literal>_t2</literal>. The <literal>seq</literal> function is a
+ little inconvenient to use here, so you might want to use
+ <literal>:def</literal> to make a nicer interface (left as an exercise
+ for the reader!).</para>
- <para>Ordering of <option>-l</option> options matters: a library
- should be mentioned <emphasis>before</emphasis> the libraries it
- depends on (see <xref linkend="options-linker"/>).</para>
- </sect2>
+ <para>Finally, we can continue the current execution:</para>
- </sect1>
+<screen>
+[qsort.hs:2:15-46] *Main> :continue
+Stopped at qsort.hs:2:15-46
+_result :: [a]
+a :: a
+left :: [a]
+right :: [a]
+[qsort.hs:2:15-46] *Main>
+</screen>
- <sect1 id="ghci-commands">
- <title>GHCi commands</title>
+ <para>The execution continued at the point it previously stopped, and has
+ now stopped at the breakpoint for a second time.</para>
- <para>GHCi commands all begin with
- ‘<literal>:</literal>’ and consist of a single command
- name followed by zero or more parameters. The command name may be
- abbreviated, with ambiguities being resolved in favour of the more
- commonly used commands.</para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>:add</literal> <replaceable>module</replaceable> ...
- <indexterm><primary><literal>:add</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Add <replaceable>module</replaceable>(s) to the
- current <firstterm>target set</firstterm>, and perform a
- reload.</para>
- </listitem>
- </varlistentry>
+ <sect3 id="setting-breakpoints">
+ <title>Setting breakpoints</title>
- <varlistentry>
- <term>
- <literal>:breakpoint</literal> <replaceable>list|add|continue|del|stop|step</replaceable> ...
- <indexterm><primary><literal>:breakpoint</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Permits to add, delete or list the breakpoints in a debugging session.
- In order to make this command available, the
- <literal>-fdebugging</literal> flag must be active. The easiest way is to launch
- GHCi with the <literal>-fdebugging</literal> option. For more
- details on how the debugger works, see <xref linkend="ghci-debugger"/>.
- </para>
- </listitem>
- </varlistentry>
+ <para>Breakpoints can be set in various ways. Perhaps the easiest way to
+ set a breakpoint is to name a top-level function:</para>
- <varlistentry>
- <term>
- <literal>:browse</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
- <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
- <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>
- </listitem>
- </varlistentry>
+<screen>
+ :break <replaceable>identifier</replaceable>
+</screen>
- <varlistentry>
- <term>
- <literal>:cd</literal> <replaceable>dir</replaceable>
- <indexterm><primary><literal>:cd</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Changes the current working directory to
- <replaceable>dir</replaceable>. A
- ‘<literal>˜</literal>’ symbol at the
- beginning of <replaceable>dir</replaceable> will be replaced
- by the contents of the environment variable
- <literal>HOME</literal>.</para>
+ <para>Where <replaceable>identifier</replaceable> names any top-level
+ function in an interpreted module currently loaded into GHCi (qualified
+ names may be used). The breakpoint will be set on the body of the
+ function, when it is fully applied but before any pattern matching has
+ taken place.</para>
- <para>NOTE: changing directories causes all currently loaded
- modules to be unloaded. This is because the search path is
- usually expressed using relative directories, and changing
- the search path in the middle of a session is not
- supported.</para>
- </listitem>
- </varlistentry>
+ <para>Breakpoints can also be set by line (and optionally column)
+ number:</para>
- <varlistentry>
- <term>
- <literal>:continue</literal>
- <indexterm><primary><literal>:continue</literal></primary></indexterm>
- </term>
- <listitem><para>Shortcut to <literal>:breakpoint continue</literal></para>
- </listitem>
- </varlistentry>
+<screen>
+ :break <replaceable>line</replaceable>
+ :break <replaceable>line</replaceable> <replaceable>column</replaceable>
+ :break <replaceable>module</replaceable> <replaceable>line</replaceable>
+ :break <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable>
+</screen>
- <varlistentry>
- <term>
- <literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable>
- <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>When a breakpoint is set on a particular line, GHCi sets the
+ breakpoint on the
+ leftmost subexpression that begins and ends on that line. If two
+ complete subexpressions start at the same
+ column, the longest one is picked. If there is no complete
+ subexpression on the line, then the leftmost expression starting on
+ the line is picked, and failing that the rightmost expression that
+ partially or completely covers the line.</para>
+
+ <para>When a breakpoint is set on a particular line and column, GHCi
+ picks the smallest subexpression that encloses that location on which
+ to set the breakpoint. Note: GHC considers the TAB character to have a
+ width of 1, wherever it occurs; in other words it counts
+ characters, rather than columns. This matches what some editors do,
+ and doesn't match others. The best advice is to avoid tab
+ characters in your source code altogether (see
+ <option>-fwarn-tabs</option> in <xref linkend="options-sanity"
+ />).</para>
+
+ <para>If the module is omitted, then the most recently-loaded module is
+ used.</para>
+
+ <para>Not all subexpressions are potential breakpoint locations. Single
+ variables are typically not considered to be breakpoint locations
+ (unless the variable is the right-hand-side of a function definition,
+ lambda, or case alternative). The rule of thumb is that all redexes
+ are breakpoint locations, together with the bodies of functions,
+ lambdas, case alternatives and binding statements. There is normally
+ no breakpoint on a let expression, but there will always be a
+ breakpoint on its body, because we are usually interested in inspecting
+ the values of the variables bound by the let.</para>
- <para>That's all a little confusing, so here's a few
- examples. To start with, here's a new GHCi command which
- doesn't take any arguments or produce any results, it just
- outputs the current date & time:</para>
+ </sect3>
+ <sect3>
+ <title>Listing and deleting breakpoints</title>
+ <para>The list of breakpoints currently enabled can be displayed using
+ <literal>:show breaks</literal>:</para>
<screen>
-Prelude> let date _ = Time.getClockTime >>= print >> return ""
-Prelude> :def date date
-Prelude> :date
-Fri Mar 23 15:16:40 GMT 2001
+*Main> :show breaks
+[0] Main qsort.hs:1:11-12
+[1] Main qsort.hs:2:15-46
</screen>
- <para>Here's an example of a command that takes an argument.
- It's a re-implementation of <literal>:cd</literal>:</para>
+ <para>To delete a breakpoint, use the <literal>:delete</literal>
+ command with the number given in the output from <literal>:show breaks</literal>:</para>
<screen>
-Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
-Prelude> :def mycd mycd
-Prelude> :mycd ..
-</screen>
+*Main> :delete 0
+*Main> :show breaks
+[1] Main qsort.hs:2:15-46
+</screen>
- <para>Or I could define a simple way to invoke
- “<literal>ghc ––make Main</literal>” in the
- current directory:</para>
+ <para>To delete all breakpoints at once, use <literal>:delete *</literal>.</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="single-stepping">
+ <title>Single-stepping</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. 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>
-Prelude> :def make (\_ -> return ":! ghc ––make Main")
+*Main> :step main
+Stopped at qsort.hs:5:7-47
+_result :: IO ()
</screen>
- <para>We can define a command that reads GHCi input from a
- file. This might be useful for creating a set of bindings
- that we want to repeatedly load into the GHCi session:</para>
+ <para>The command <literal>:step
+ <replaceable>expr</replaceable></literal> begins the evaluation of
+ <replaceable>expr</replaceable> in single-stepping mode. If
+ <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>
+
+<screen>
+[qsort.hs:5:7-47] *Main> :list
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:7-47] *Main>
+</screen>
+
+ <para>In fact, GHCi provides a way to run a command when a breakpoint is
+ hit, so we can make it automatically do
+ <literal>:list</literal>:</para>
+
+<screen>
+[qsort.hs:5:7-47] *Main> :set stop :list
+[qsort.hs:5:7-47] *Main> :step
+Stopped at qsort.hs:5:14-46
+_result :: [Integer]
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:14-46] *Main>
+</screen>
+ </sect2>
+
+ <sect2 id="nested-breakpoints">
+ <title>Nested breakpoints</title>
+ <para>When GHCi is stopped at a breakpoint, and an expression entered at
+ the prompt triggers a
+ second breakpoint, the new breakpoint becomes the “current”
+ one, and the old one is saved on a stack. An arbitrary number of
+ breakpoint contexts can be built up in this way. For example:</para>
+
+<screen>
+[qsort.hs:2:15-46] *Main> :st qsort [1,3]
+Stopped at qsort.hs:(1,0)-(3,55)
+_result :: [a]
+... [qsort.hs:(1,0)-(3,55)] *Main>
+</screen>
+
+ <para>While stopped at the breakpoint on line 2 that we set earlier, we
+ started a new evaluation with <literal>:step qsort [1,3]</literal>.
+ This new evaluation stopped after one step (at the definition of
+ <literal>qsort</literal>). The prompt has changed, now prefixed with
+ <literal>...</literal>, to indicate that there are saved breakpoints
+ beyond the current one. To see the stack of contexts, use
+ <literal>:show context</literal>:</para>
+
+<screen>
+... [qsort.hs:(1,0)-(3,55)] *Main> :show context
+--> main
+ Stopped at qsort.hs:2:15-46
+--> qsort [1,3]
+ Stopped at qsort.hs:(1,0)-(3,55)
+... [qsort.hs:(1,0)-(3,55)] *Main>
+</screen>
+
+ <para>To abandon the current evaluation, use
+ <literal>:abandon</literal>:</para>
+
+<screen>
+... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
+[qsort.hs:2:15-46] *Main> :abandon
+*Main>
+</screen>
+ </sect2>
+
+ <sect2 id="ghci-debugger-result">
+ <title>The <literal>_result</literal> variable</title>
+ <para>When stopped at a breakpoint or single-step, GHCi binds the
+ variable <literal>_result</literal> to the value of the currently
+ active expression. The value of <literal>_result</literal> is
+ presumably not available yet, because we stopped its evaluation, but it
+ can be forced: if the type is known and showable, then just entering
+ <literal>_result</literal> at the prompt will show it. However,
+ there's one caveat to doing this: evaluating <literal>_result</literal>
+ will be likely to trigger further breakpoints, starting with the
+ breakpoint we are currently stopped at (if we stopped at a real
+ breakpoint, rather than due to <literal>:step</literal>). So it will
+ probably be necessary to issue a <literal>:continue</literal>
+ immediately when evaluating <literal>_result</literal>. Alternatively,
+ you can use <literal>:force</literal> which ignores breakpoints.</para>
+ </sect2>
+
+ <sect2 id="tracing">
+ <title>Tracing and history</title>
+
+ <para>A question that we often want to ask when debugging a program is
+ “how did I get here?”. Traditional imperative debuggers
+ usually provide some kind of stack-tracing feature that lets you see
+ the stack of active function calls (sometimes called the “lexical
+ call stack”), describing a path through the code
+ to the current location. Unfortunately this is hard to provide in
+ Haskell, because execution proceeds on a demand-driven basis, rather
+ than a depth-first basis as in strict languages. The
+ “stack“ in GHC's execution engine bears little
+ resemblance to the lexical call stack. Ideally GHCi would maintain a
+ separate lexical call stack in addition to the dynamic call stack, and
+ in fact this is exactly
+ what our profiling system does (<xref linkend="profiling" />), and what
+ some other Haskell debuggers do. For the time being, however, GHCi
+ doesn't maintain a lexical call stack (there are some technical
+ challenges to be overcome). Instead, we provide a way to backtrack from a
+ breakpoint to previous evaluation steps: essentially this is like
+ single-stepping backwards, and should in many cases provide enough
+ information to answer the “how did I get here?”
+ question.</para>
+
+ <para>To use tracing, evaluate an expression with the
+ <literal>:trace</literal> command. For example, if we set a breakpoint
+ on the base case of <literal>qsort</literal>:</para>
+
+<screen>
+*Main> :list qsort
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+4
+*Main> :b 1
+Breakpoint 1 activated at qsort.hs:1:11-12
+*Main>
+</screen>
+
+ <para>and then run a small <literal>qsort</literal> with
+ tracing:</para>
+
+<screen>
+*Main> :trace qsort [3,2,1]
+Stopped at qsort.hs:1:11-12
+_result :: [a]
+[qsort.hs:1:11-12] *Main>
+</screen>
+
+ <para>We can now inspect the history of evaluation steps:</para>
+
+<screen>
+[qsort.hs:1:11-12] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:3:24-38
+-7 : qsort.hs:3:23-55
+-8 : qsort.hs:(1,0)-(3,55)
+-9 : qsort.hs:2:15-24
+-10 : qsort.hs:2:15-46
+-11 : qsort.hs:3:24-38
+-12 : qsort.hs:3:23-55
+-13 : qsort.hs:(1,0)-(3,55)
+-14 : qsort.hs:2:15-24
+-15 : qsort.hs:2:15-46
+-16 : qsort.hs:(1,0)-(3,55)
+<end of history>
+</screen>
+
+ <para>To examine one of the steps in the history, use
+ <literal>:back</literal>:</para>
+
+<screen>
+[qsort.hs:1:11-12] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main>
+</screen>
+
+ <para>Note that the local variables at each step in the history have been
+ preserved, and can be examined as usual. Also note that the prompt has
+ changed to indicate that we're currently examining the first step in
+ the history: <literal>-1</literal>. The command
+ <literal>:forward</literal> can be used to traverse forward in the
+ history.</para>
+
+ <para>The <literal>:trace</literal> command can be used with or without
+ an expression. When used without an expression, tracing begins from
+ the current breakpoint, just like <literal>:step</literal>.</para>
+
+ <para>The history is only available when
+ using <literal>:trace</literal>; the reason for this is we found that
+ logging each breakpoint in the history cuts performance by a factor of
+ 2 or more. GHCi remembers the last 50 steps in the history (perhaps in
+ the future we'll make this configurable).</para>
+ </sect2>
+
+ <sect2 id="ghci-debugger-exceptions">
+ <title>Debugging exceptions</title>
+ <para>Another common question that comes up when debugging is
+ “where did this exception come from?”. Exceptions such as
+ those raised by <literal>error</literal> or <literal>head []</literal>
+ 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>, 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
+ code. One way would be to set a breakpoint on the location in the
+ source code that throws the exception, and then use
+ <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 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>
+
+<screen>
+*Main> :set -fbreak-on-exception
+*Main> :trace qsort ("abc" ++ undefined)
+"Stopped at <exception thrown>
+_exception :: e
+[<exception thrown>] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:(1,0)-(3,55)
+<end of history>
+[<exception thrown>] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main> :force as
+*** Exception: Prelude.undefined
+[-1: qsort.hs:3:24-38] *Main> :print as
+as = 'b' : 'c' : (_t1::[Char])
+</screen>
+
+ <para>The exception itself is bound to a new variable,
+ <literal>_exception</literal>.</para>
+
+ <para>Breaking on exceptions is particularly useful for finding out what
+ your program was doing when it was in an infinite loop. Just hit
+ Control-C, and examine the history to find out what was going
+ on.</para>
+ </sect2>
+
+ <sect2><title>Example: inspecting functions</title>
+ <para>
+ It is possible to use the debugger to examine function values.
+ When we are at a breakpoint and a function is in scope, the debugger
+ cannot show
+ you the source code for it; however, it is possible to get some
+ information by applying it to some arguments and observing the result.
+ </para>
+
+ <para>
+ The process is slightly complicated when the binding is polymorphic.
+ We show the process by means of an example.
+ To keep things simple, we will use the well known <literal>map</literal> function:
+<programlisting>
+import Prelude hiding (map)
+
+map :: (a->b) -> [a] -> [b]
+map f [] = []
+map f (x:xs) = f x : map f xs
+</programlisting>
+ </para>
+
+ <para>
+ We set a breakpoint on <literal>map</literal>, and call it.
+<screen>
+*Main> :break 5
+Breakpoint 0 activated at map.hs:5:15-28
+*Main> map Just [1..5]
+Stopped at map.hs:(4,0)-(5,12)
+_result :: [b]
+x :: a
+f :: a -> b
+xs :: [a]
+</screen>
+ GHCi tells us that, among other bindings, <literal>f</literal> is in scope.
+ However, its type is not fully known yet,
+ and thus it is not possible to apply it to any
+ arguments. Nevertheless, observe that the type of its first argument is the
+ same as the type of <literal>x</literal>, and its result type is shared
+ with <literal>_result</literal>.
+ </para>
+
+ <para>
+ As we demonstrated earlier (<xref linkend="breakpoints" />), the
+ debugger has some intelligence built-in to update the type of
+ <literal>f</literal> whenever the types of <literal>x</literal> or
+ <literal>_result</literal> are discovered. So what we do in this
+ scenario is
+ force <literal>x</literal> a bit, in order to recover both its type
+ and the argument part of <literal>f</literal>.
+<screen>
+*Main> seq x ()
+*Main> :print x
+x = 1
+</screen>
+ </para>
+ <para>
+ We can check now that as expected, the type of <literal>x</literal>
+ has been reconstructed, and with it the
+ type of <literal>f</literal> has been too:</para>
+<screen>
+*Main> :t x
+x :: Integer
+*Main> :t f
+f :: Integer -> b
+</screen>
+ <para>
+ From here, we can apply f to any argument of type Integer and observe
+ the results.
+<screen><![CDATA[
+*Main> let b = f 10
+*Main> :t b
+b :: b
+*Main> b
+<interactive>:1:0:
+ Ambiguous type variable `b' in the constraint:
+ `Show b' arising from a use of `print' at <interactive>:1:0
+*Main> :p b
+b = (_t2::a)
+*Main> seq b ()
+()
+*Main> :t b
+b :: a
+*Main> :p b
+b = Just 10
+*Main> :t b
+b :: Maybe Integer
+*Main> :t f
+f :: Integer -> Maybe Integer
+*Main> f 20
+Just 20
+*Main> map f [1..5]
+[Just 1, Just 2, Just 3, Just 4, Just 5]
+]]></screen>
+ In the first application of <literal>f</literal>, we had to do
+ some more type reconstruction
+ in order to recover the result type of <literal>f</literal>.
+ But after that, we are free to use
+ <literal>f</literal> normally.
+ </para>
+ </sect2>
+
+ <sect2><title>Limitations</title>
+ <itemizedlist>
+ <listitem>
+ <para>When stopped at a breakpoint, if you try to evaluate a variable
+ that is already under evaluation, the second evaluation will hang.
+ The reason is
+ that GHC knows the variable is under evaluation, so the new
+ evaluation just waits for the result before continuing, but of
+ course this isn't going to happen because the first evaluation is
+ stopped at a breakpoint. Control-C can interrupt the hung
+ evaluation and return to the prompt.</para>
+ <para>The most common way this can happen is when you're evaluating a
+ CAF (e.g. main), stop at a breakpoint, and ask for the value of the
+ CAF at the prompt again.</para>
+ </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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="ghci-invocation">
+ <title>Invoking GHCi</title>
+ <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
+ <indexterm><primary><option>––interactive</option></primary></indexterm>
+
+ <para>GHCi is invoked with the command <literal>ghci</literal> or
+ <literal>ghc ––interactive</literal>. One or more modules or
+ filenames can also be specified on the command line; this
+ instructs GHCi to load the specified modules or filenames (and all
+ the modules they depend on), just as if you had said
+ <literal>:load <replaceable>modules</replaceable></literal> at the
+ GHCi prompt (see <xref linkend="ghci-commands" />). For example, to
+ start GHCi and load the program whose topmost module is in the
+ file <literal>Main.hs</literal>, we could say:</para>
+
+<screen>
+$ ghci Main.hs
+</screen>
+
+ <para>Most of the command-line options accepted by GHC (see <xref
+ linkend="using-ghc"/>) also make sense in interactive mode. The ones
+ that don't make sense are mostly obvious.</para>
+
+ <sect2>
+ <title>Packages</title>
+ <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
+
+ <para>Most packages (see <xref linkend="using-packages"/>) are
+ available without needing to specify any extra flags at all:
+ they will be automatically loaded the first time they are
+ needed.</para>
+
+ <para>For hidden packages, however, you need to request the
+ package be loaded by using the <literal>-package</literal> flag:</para>
+
+<screen>
+$ ghci -package readline
+GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
+Loading package base ... linking ... done.
+Loading package readline-1.0 ... linking ... done.
+Prelude>
+</screen>
+
+ <para>The following command works to load new packages into a
+ running GHCi:</para>
+
+<screen>
+Prelude> :set -package <replaceable>name</replaceable>
+</screen>
+
+ <para>But note that doing this will cause all currently loaded
+ modules to be unloaded, and you'll be dumped back into the
+ <literal>Prelude</literal>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Extra libraries</title>
+ <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
+
+ <para>Extra libraries may be specified on the command line using
+ the normal <literal>-l<replaceable>lib</replaceable></literal>
+ option. (The term <emphasis>library</emphasis> here refers to
+ libraries of foreign object code; for using libraries of Haskell
+ source code, see <xref linkend="ghci-modules-filenames"/>.) For
+ example, to load the “m” library:</para>
+
+<screen>
+$ ghci -lm
+</screen>
+
+ <para>On systems with <literal>.so</literal>-style shared
+ libraries, the actual library loaded will the
+ <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi
+ searches the following places for libraries, in this order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Paths specified using the
+ <literal>-L<replaceable>path</replaceable></literal>
+ command-line option,</para>
+ </listitem>
+ <listitem>
+ <para>the standard library search path for your system,
+ which on some systems may be overridden by setting the
+ <literal>LD_LIBRARY_PATH</literal> environment
+ variable.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>On systems with <literal>.dll</literal>-style shared
+ libraries, the actual library loaded will be
+ <filename><replaceable>lib</replaceable>.dll</filename>. Again,
+ GHCi will signal an error if it can't find the library.</para>
+
+ <para>GHCi can also load plain object files
+ (<literal>.o</literal> or <literal>.obj</literal> depending on
+ your platform) from the command-line. Just add the name the
+ object file to the command line.</para>
+
+ <para>Ordering of <option>-l</option> options matters: a library
+ should be mentioned <emphasis>before</emphasis> the libraries it
+ depends on (see <xref linkend="options-linker"/>).</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="ghci-commands">
+ <title>GHCi commands</title>
+
+ <para>GHCi commands all begin with
+ ‘<literal>:</literal>’ and consist of a single command
+ name followed by zero or more parameters. The command name may be
+ abbreviated, with ambiguities being resolved in favour of the more
+ commonly used commands.</para>
+
+ <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>
+ <listitem>
+ <para>Add <replaceable>module</replaceable>(s) to the
+ current <firstterm>target set</firstterm>, and perform a
+ reload.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:back</literal>
+ <indexterm><primary><literal>:back</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <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>
+
+ <varlistentry>
+ <term>
+ <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
+ <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.
+ 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>
+<screen>
+Prelude> :browse! Data.Maybe
+-- not currently imported
+Data.Maybe.catMaybes :: [Maybe a] -> [a]
+Data.Maybe.fromJust :: Maybe a -> a
+Data.Maybe.fromMaybe :: a -> Maybe a -> a
+Data.Maybe.isJust :: Maybe a -> Bool
+Data.Maybe.isNothing :: Maybe a -> Bool
+Data.Maybe.listToMaybe :: [a] -> Maybe a
+Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
+Data.Maybe.maybeToList :: Maybe a -> [a]
+-- imported via Prelude
+Just :: a -> Maybe a
+data Maybe a = Nothing | Just a
+Nothing :: Maybe a
+maybe :: b -> (a -> b) -> Maybe a -> b
+</screen>
+ <para>
+ This output shows that, in the context of the current session, in the scope
+ of <literal>Prelude</literal>, the first group of items from
+ <literal>Data.Maybe</literal> have not been imported (but are available in
+ fully qualified form in the GHCi session - see <xref
+ linkend="ghci-scope"/>), whereas the second group of items have been
+ imported via <literal>Prelude</literal> and are therefore available either
+ unqualified, or with a <literal>Prelude.</literal> qualifier.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:cd</literal> <replaceable>dir</replaceable>
+ <indexterm><primary><literal>:cd</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Changes the current working directory to
+ <replaceable>dir</replaceable>. A
+ ‘<literal>˜</literal>’ symbol at the
+ beginning of <replaceable>dir</replaceable> will be replaced
+ by the contents of the environment variable
+ <literal>HOME</literal>.</para>
+
+ <para>NOTE: changing directories causes all currently loaded
+ modules to be unloaded. This is because the search path is
+ usually expressed using relative directories, and changing
+ the search path in the middle of a session is not
+ supported.</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>:continue</literal>
+ <indexterm><primary><literal>:continue</literal></primary></indexterm>
+ </term>
+ <listitem><para>Continue the current evaluation, when stopped at a
+ breakpoint.</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 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
+ be interpreted for these commands to work.</para>
+ <para>See also <xref linkend="hasktags" />.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:def<optional>!</optional> <optional><replaceable>name</replaceable> <replaceable>expr</replaceable></optional></literal>
+ <indexterm><primary><literal>:def</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <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
+ doesn't take any arguments or produce any results, it just
+ outputs the current date & time:</para>
+
+<screen>
+Prelude> let date _ = Time.getClockTime >>= print >> return ""
+Prelude> :def date date
+Prelude> :date
+Fri Mar 23 15:16:40 GMT 2001
+</screen>
+
+ <para>Here's an example of a command that takes an argument.
+ It's a re-implementation of <literal>:cd</literal>:</para>
+
+<screen>
+Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
+Prelude> :def mycd mycd
+Prelude> :mycd ..
+</screen>
+
+ <para>Or I could define a simple way to invoke
+ “<literal>ghc ––make Main</literal>” in the
+ current directory:</para>
+
+<screen>
+Prelude> :def make (\_ -> return ":! ghc ––make Main")
+</screen>
+
+ <para>We can define a command that reads GHCi input from a
+ file. This might be useful for creating a set of bindings
+ that we want to repeatedly load into the GHCi session:</para>
<screen>
Prelude> :def . readFile
<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>: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>: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>
+ <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>
<varlistentry>
+ <term>
+ <literal>:</literal>
+ <indexterm><primary><literal>:</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Repeat the previous command.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
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>
+
+ <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>
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>
["foo","bar"]
</screen>
+ <para>
+ We can also quote arguments which contains characters like
+ spaces, and they are treated like Haskell strings, or we can
+ just use Haskell list syntax:
+ </para>
+
+<screen>
+Prelude> :main foo "bar baz"
+["foo","bar baz"]
+Prelude> :main ["foo", "bar baz"]
+["foo","bar baz"]
+</screen>
+
+ <para>
+ Finally, other functions can be called, either with the
+ <literal>-main-is</literal> flag or the <literal>:run</literal>
+ command:
+ </para>
+
+<screen>
+Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
+Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
+Prelude> :set -main-is foo
+Prelude> :main foo "bar baz"
+foo
+["foo","bar baz"]
+Prelude> :run bar ["foo", "bar baz"]
+bar
+["foo","bar baz"]
+</screen>
+
</listitem>
</varlistentry>
<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
+ 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
+ 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>
<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>
<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>
<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>
+ <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>
<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>static</primary><secondary>options</secondary></indexterm>
</sect2>
</sect1>
- <sect1 id="ghci-debugger">
- <title>The GHCi debugger</title>
- <indexterm><primary>debugger</primary></indexterm>
- <para>GHCi embeds an utility debugger with a very basic set of operations. The debugger
- is always available in ghci, you do not need to do anything to activate it. </para>
- <para>The following conditions must hold before a module can be debugged in GHCi:
- <itemizedlist>
- <listitem>
- <para>The module must have been loaded interpreted, i.e. not loaded from an <filename>.o</filename> file compiled by ghc </para>
- </listitem>
- <listitem>
- <para>The module must have been loaded with the <literal>-fdebugging</literal> flag
- </para></listitem>
- </itemizedlist></para>
- <sect2><title>Using the debugger</title>
- <para>The debugger allows the insertion of breakpoints at specific locations in the source code. These locations are governed by event sites, and not by line as in traditional debuggers such as gdb. </para> <para>
- Once a breakpointed event is hit, the debugger stops the execution and you can examine the local variables in scope
- in the context of the event, as well as evaluate arbitrary Haskell expressions in
- a special interactive prompt. </para><para>
-
- When you are done you issue the <literal>:continue</literal>
- command to leave the breakpoint and let the execution go on.
- Note that not all the GHCi commands are supported in a breakpoint.
-
- </para>
- <sidebar><title>Events</title><?dbfo float-type="left"?>
- <para> Events are the places in source code where you can set a breakpoint.
-<programlisting>
-qsort [] = <co id="name-binding-co"/> []
-qsort (x:xs) =
- <coref linkend="name-binding-co"/> let left = <coref linkend="name-binding-co"/> filter (\y -> <co id="lambda-co"/> y < x) xs
- right = <coref linkend="name-binding-co"/> case filter (\y -> <coref linkend="lambda-co"/> y > x) xs of
- right_val -> <co id="case-co"/> right_val
- in <co id="let-co"/> qsort left ++ [x] ++ qsort right
-main = <coref linkend="name-binding-co"/> do {
- arg <- <coref linkend="name-binding-co"/> getLine ;
- let num = <coref linkend="name-binding-co"/> read arg :: [Int] ;
- <co id="stmts-co"/> print (qsort num) ;
- <coref linkend="stmts-co"/> putStrLn "GoodBye!" }
-</programlisting>
- The GHCi debugger recognizes the following event types:
- <calloutlist>
- <callout arearefs="name-binding-co" id="name-binding">
- <para>Function definition and local bindings in let/where</para>
- </callout>
- <callout arearefs="lambda-co" id="lambda">
- <para>Lambda expression entry point</para>
- </callout>
- <callout arearefs="let-co" id="let">
- <para>Let expression body</para>
- </callout>
- <callout arearefs="case-co" id="case">
- <para>Case alternative body</para>
- </callout>
- <callout arearefs="stmts-co" id="stmts">
- <para>do notation statements</para>
- </callout>
- </calloutlist></para>
- <para>In reality however, ghci eliminates some redundant event sites.
- For instance, sites with two co-located breakpoint events are coalesced into a single one,
- and sites with no bindings in scope are assumed to be uninteresting and no breakpoint can be set in them.</para>
- </sidebar>
-
-<para>
- You don't need to do anything special in order to start the debugging session.
- Simply use ghci to evaluate your Haskell expressions and whenever a breakpoint
- is hit, the debugger will enter the stage:
-<programlisting>
-*main:Main> :break add Main 2
-Breakpoint set at (2,15)
-
-*main:Main> qsort [10,9..1]
-Local bindings in scope:
- x :: a, xs :: [a], left :: [a], right :: [a]
-
-qsort2.hs:2:15-46>
-</programlisting>
- What is happening here is that GHCi has interrupted the evaluation of
- <literal>qsort</literal> at the breakpoint set in line 2, as the prompt indicates.
- At this point you can freely explore the contents of the bindings in scope,
- but with two catches. </para><para>
- First, take into account that due to the lazy nature of Haskell, some of
- these bindings may be unevaluated, and that exploring their contents may
- trigger a computation. </para><para>
- Second: look at the types of the things in scope.
- GHCi has left its types parameterised by a variable!
- Look at the type of <literal>qsort</literal>, which is
- polymorphic on the type of its argument. It does not
- tell us really what the types of <literal>x</literal> and <literal>xs</literal> can be.
- In general, polymorphic programs deal with polymorphic values,
- and this means that some of the bindings available in a breakpoint site
- will be parametrically typed.
- </para><para>
- So, what can we do with a value without concrete type? Very few interesting
- things. The <literal>:print</literal> command in ghci allows you to
- explore its contents and see if it is evaluated or not.
- This is useful because you cannot just type <literal>x</literal> in the
- prompt and expect GHCi to return you its value. Perhaps you know for
- sure that
- <literal>x</literal> is of type <literal>Int</literal>, which is an instance of
- <literal>Show</literal>, but GHCi does not have this information.
- <literal>:print</literal> however is fine, because it does not need to know the
- type to do its work. </para>
- <para> Let's go on with the debugging session of the <literal>qsort</literal>
- example:
-<example id="debuggingEx"><title>A short debugging session</title>
-<programlisting>
-qsort2.hs:2:15-46> x
-This is an untyped, unevaluated computation. You can use seq to
-force its evaluation and then :print to recover its type <co id="seq1"/>
-qsort2.hs:2:15-46> seq x () <co id="seq2"/>
-()
-qsort2.hs:2:15-46> x <co id="seq3"/>
-This is an untyped, unevaluated computation. You can use seq to
-force its evaluation and then :print to recover its type
-
-qsort2.hs:2:15-46> :t x
-x :: GHC.Base.Unknown
-qsort2.hs:2:15-46> :p x <co id="seq4"/>
-x - 10
-qsort2.hs:2:15-46> :t x <co id="seq5"/>
-x :: Int
-</programlisting>
-</example>
- <calloutlist>
- <callout arearefs="seq1">
- <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
- </callout>
- <callout arearefs="seq2">
- <para>This line forces the evaluation of <literal>x</literal> </para>
- </callout>
- <callout arearefs="seq3">
- <para>Even though x has been evaluated, we cannot simply use its name to see its value!
- This is a bit counterintuitive, but currently in GHCi the type of a binding
- cannot be a type variable <literal>a</literal>.
- Thus, the binding <literal>x</literal> gets assigned the concrete type Unknown.</para>
- </callout>
- <callout arearefs="seq4">
- <para>We can explore <literal>x</literal> using the <literal>:print</literal>
- command, which does find out that <literal>x</literal> is of type Int and prints
- its value accordingly.</para>
- </callout>
- <callout arearefs="seq5">
- <para><literal>:print</literal> also updates the type of <literal>x</literal> with
- the most concrete type information available.</para>
- </callout>
- </calloutlist>
- The example shows the standard way to proceeed with polymorphic values in a breakpoint.
- </para>
- </sect2>
- <sect2><title>Commands</title>
- <para>Breakpoints can be set in several ways using the <literal>:breakpoint</literal> command. Note that you can take advantage of the command abbreviation feature of GHCi and use simply <literal>:bre</literal> to save quite a few keystrokes.
-<variablelist>
-<varlistentry>
- <term>
- <literal>:breakpoint add <replaceable>module</replaceable> <replaceable>line</replaceable></literal>
- </term>
- <listitem><para>
- Adds a breakpoint at the first event found at line <literal>line</literal> in <literal>module</literal>, if any.
- </para></listitem>
-</varlistentry>
-<varlistentry>
- <term>
- <literal>:breakpoint add <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable></literal>
- </term>
- <listitem><para>
- Adds a breakpoint at the first event found after column <literal>column</literal>
- at line <literal>line</literal> in <literal>module</literal>, if any.
- </para></listitem>
-</varlistentry>
-
-<varlistentry>
- <term>
- <literal>:breakpoint continue</literal>
- </term>
- <listitem><para>
- When at a breakpoint, continue execution up to the next breakpoint
- or end of evaluation.
- </para></listitem>
-</varlistentry>
-
-<varlistentry>
- <term>
- <literal>:continue</literal>
- </term>
- <listitem><para>
- Shortcut for <literal>:breakpoint continue</literal>
- </para></listitem>
-</varlistentry>
-
-<varlistentry>
- <term>
- <literal>:breakpoint list</literal>
- </term>
- <listitem><para>
- Lists the currently set up breakpoints.
- </para></listitem>
-</varlistentry>
-<varlistentry>
- <term>
- <literal>:breakpoint del <replaceable>num</replaceable></literal>
- </term>
- <listitem><para>
- Deletes the breakpoint at position <literal>num</literal> in the list of
- breakpoints shown by <literal>:breakpoint list</literal>.
- </para></listitem>
-</varlistentry>
-<varlistentry>
- <term>
- <literal>:breakpoint del <replaceable>module</replaceable> <replaceable>line</replaceable></literal>
- </term>
- <listitem><para>
- Dels the breakpoint at line <literal>line</literal> in <literal>module</literal>, if any.
- </para></listitem>
-</varlistentry>
-<varlistentry>
- <term>
- <literal>:breakpoint del <replaceable>module</replaceable> <replaceable>line</replaceable><replaceable>col</replaceable> </literal>
- </term>
- <listitem><para>
- Deletes the first breakpoint found after column <literal>column</literal>
- at line <literal>line</literal> in <literal>module</literal>, if any.
- </para></listitem>
-</varlistentry>
-<varlistentry>
- <term>
- <literal>:breakpoint stop </literal>
- </term>
- <listitem><para>
- Stop the program being executed. This interrupts a debugging session
- and returns to the top level.
- </para></listitem>
-</varlistentry>
-</variablelist></para>
- </sect2>
- <sect2><title>Debugging Higher-Order functions</title>
- It is possible to use the debugger to examine lambdas.
- When we are at a breakpoint and a lambda is in scope, the debugger cannot show
- you the source code that constitutes it; however, it is possible to get some
- information by applying it to some arguments and observing the result.
-
- The process is slightly complicated when the binding is polymorphic.
- We will use a example to show the process.
- To keep it simple, we will use the well known <literal>map</literal> function:
- <programlisting>
-import Prelude hiding (map)
-
-map :: (a->b) -> a -> b
-map f [] = []
-map f (x:xs) = f x : map f xs
- </programlisting>
- We set a breakpoint on <literal>map</literal>, and call it.
- <programlisting>
-*Main> :break map
-Breakpoint 0 activated at map.hs:(4,0)-(5,12)
-*Main> map Just [1..5]
-Stopped at map.hs:(4,0)-(5,12)
-_result :: [b]
-x :: a
-f :: a -> b
-xs :: [a]
- </programlisting>
- GHCi tells us that, among other bindings, <literal>f</literal> is in scope.
- However, its type is not fully known yet,
- and thus it is not possible to apply it yet to any
- arguments. Nevertheless, observe that the type of its first argument is the
- same as the type of <literal>x</literal>, and its result type is the
- same as the type of <literal>_result</literal>.
- The debugger has some intelligence built-in to update the type of
- <literal>f</literal> whenever the types of <literal>x</literal> or
- <literal>_result</literal> are reconstructed. So what we do in this scenario is
- force <literal>x</literal> a bit, in order to recover both its type
- and the argument part of <literal>f</literal>.
- <programlisting>
-*Main> seq x ()
-*Main> :print x
-x = 1
- </programlisting>
- We can check now that as expected, the type of <literal>x</literal>
- has been reconstructed, and with it the
- type of <literal>f</literal> has been too:
- <programlisting>
-*Main> :t x
-x :: Integer
-*Main> :t f
-f :: Integer -> b
- </programlisting>
- From here, we can apply f to any argument of type Integer and observe the
- results.
- <programlisting><![CDATA[
-*Main> let b = f 10
-*Main> :t b
-b :: b
-*Main> b
-<interactive>:1:0:
- Ambiguous type variable `b' in the constraint:
- `Show b' arising from a use of `print' at <interactive>:1:0
-*Main> :p b
-b = (_t2::a)
-*Main> seq b ()
-()
-*Main> :t b
-b :: a
-*Main> :p b
-b = Just 10
-*Main> :t b
-b :: Maybe Integer
-*Main> :t f
-f :: Integer -> Maybe Integer
-*Main> f 20
-Just 20
-*Main> map f [1..5]
-[Just 1, Just 2, Just 3, Just 4, Just 5]
- ]]></programlisting>
- In the first application of <literal>f</literal>, we had to do
- some more type reconstruction
- in order to recover the result type of <literal>f</literal>.
- But after that, we are free to use
- <literal>f</literal> normally.
- </sect2>
- <sect2><title>Tips</title>
- <variablelist>
- <varlistentry><term>* Use PRAGMAs to fine tune which modules are loaded under debugging mode</term>
- <listitem>
- <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry> <term>* Repeated use of <literal>seq</literal> and
- <literal>:print</literal> may be necessary to observe unevaluated
- untyped bindings</term>
- <listitem><para>see <xref linkend="debuggingEx"/>
- </para></listitem>
- </varlistentry>
- <varlistentry> <term> * <literal>GHC.Exts.unsafeCoerce</literal> can help if you are positive about the type of a binding</term>
- <listitem><para><programlisting>
-type MyLongType a = [Maybe [Maybe a]]
-
-*Main> :m +GHC.Exts
-*Main> main
-Local bindings in scope:
- x :: a
-Main.hs:15> let x' = unsafeCoerce x :: MyLongType Bool
-Main.hs:15> x'
-[Just [Just False, Just True]]
- </programlisting>
- Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault
- </para></listitem>
- </varlistentry>
- <varlistentry> <term> * The <literal>:force</literal> command </term>
- <listitem><para>
- equivalent to <literal> :print</literal> with automatic
- <literal>seq</literal> forcing,
- may prove useful to replace sequences of <literal>seq</literal> and
- <literal>:print</literal> in some situations.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- <sect2><title>Limitations</title>
- <para>
- <itemizedlist>
- <listitem><para>
- Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available
- at the scope of a breakpoint if there is a explicit type signature.
- </para></listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem><para>
- Modules compiled by GHCi under the <literal>-fdebugging
- </literal> flag will perform slower: the debugging mode introduces some overhead.
- Modules compiled to object code by ghc are not affected.
- </para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
<sect1 id="ghci-dot-files">
<title>The <filename>.ghci</filename> file</title>
<indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
<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>The <filename>.ghci</filename> in your home directory is
- most useful for turning on favourite options (eg. <literal>:set
- +s</literal>), and defining useful macros. Placing a
- <filename>.ghci</filename> file in a directory with a Haskell
- 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
+ <para>When it starts, unless the <literal>-ignore-dot-ghci</literal>
+ flag is given, GHCi reads and executes commands from the following
+ files, in this order, if they exist:</para>
+
+ <orderedlist>
+ <listitem>
+ <para><filename>./.ghci</filename></para>
+ </listitem>
+ <listitem>
+ <para><literal><replaceable>appdata</replaceable>/ghc/ghci.conf</literal>,
+ where <replaceable>appdata</replaceable> depends on your system,
+ but is usually something like <literal>C:/Documents and Settings/<replaceable>user</replaceable>/Application Data</literal></para>
+ </listitem>
+ <listitem>
+ <para>On Unix: <literal>$HOME/.ghc/ghci.conf</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>$HOME/.ghci</literal></para>
+ </listitem>
+ </orderedlist>
+
+ <para>The <filename>ghci.conf</filename> file is most useful for
+ turning on favourite options (eg. <literal>:set +s</literal>), and
+ defining useful macros. Placing a <filename>.ghci</filename> file
+ in a directory with a Haskell 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
<filename>.ghci</filename>:</para>
<screen>
until the next <literal>:load</literal>, though.)</para>
<para>Two command-line options control whether the
- <filename>.ghci</filename> files are read:</para>
+ startup files files are read:</para>
<variablelist>
<varlistentry>
<indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm>
</term>
<listitem>
- <para>Don't read either <filename>./.ghci</filename> or
- <filename>$HOME/.ghci</filename> when starting up.</para>
+ <para>Don't read either <filename>./.ghci</filename> or the
+ other startup files when starting up.</para>
</listitem>
</varlistentry>
<varlistentry>
<indexterm><primary><option>-read-dot-ghci</option></primary></indexterm>
</term>
<listitem>
- <para>Read <filename>.ghci</filename> and
- <filename>$HOME/.ghci</filename>. This is normally the
+ <para>Read <filename>./.ghci</filename> and the other
+ startup files (see above). This is normally the
default, but the <option>-read-dot-ghci</option> option may
be used to override a previous
<option>-ignore-dot-ghci</option> option.</para>
<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