</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>
+ <sect1 id="ghci-introduction">
<title>Introduction to GHCi</title>
<para>Let's start with an example GHCi session. You can fire up
<screen>
$ ghci
- ___ ___ _
- / _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 5.04, 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.
-Loading package haskell98 ... 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>
- :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
- :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
-
- :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
enter, GHCi will attempt to evaluate it.</para>
</sect1>
- <sect1>
+ <sect1 id="loading-source-files">
<title>Loading source files</title>
<para>Suppose we have the following Haskell source code, which we
<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.
</screen>
<para>HINT: since GHCi will only use a compiled object file if it
- can sure that the compiled version is up-to-date, a good technique
+ can be sure that the compiled version is up-to-date, a good technique
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>
</sect1>
- <sect1>
+ <sect1 id="interactive-evaluation">
<title>Interactive evaluation at the prompt</title>
<para>When you type an expression at the prompt, GHCi immediately
</screen>
</para></sect2>
- <sect2>
+ <sect2 id="ghci-stmts">
<title>Using <literal>do-</literal>notation at the prompt</title>
<indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm>
<indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm>
<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>
+ <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
<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
<screen>
Prelude> :module +IO
-Prelude,IO> hPutStrLn stdout "hello\n"
+Prelude IO> hPutStrLn stdout "hello\n"
hello
-Prelude,IO>
+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>
<literal>Bar</literal>, then the scope will be set to
<literal>*Bar</literal> if <literal>Bar</literal> is
interpreted, or if <literal>Bar</literal> is compiled it will be
- set to <literal>Prelude,Bar</literal> (GHCi automatically adds
+ set to <literal>Prelude Bar</literal> (GHCi automatically adds
<literal>Prelude</literal> if it isn't present and there aren't
any <literal>*</literal>-form modules).</para>
behaves in the same way for expressions typed at the
prompt.</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>”.
+ </para>
+
<sect3>
<title>Qualified names</title>
qualified</literal> declaration for every module in every
package, and every module currently loaded into GHCi.</para>
</sect3>
+
+ <sect3>
+ <title>The <literal>:main</literal> and <literal>:run</literal> commands</title>
+
+ <para>
+ When a program is compiled and executed, it can use the
+ <literal>getArgs</literal> function to access the
+ command-line arguments.
+ 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.
+ </para>
+
+ <para>
+ Instead, we can use the <literal>:main</literal> command.
+ This runs whatever <literal>main</literal> is in scope, with
+ any arguments being treated the same as command-line arguments,
+ e.g.:
+ </para>
+
+<screen>
+Prelude> let main = System.Environment.getArgs >>= print
+Prelude> :main foo bar
+["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>
expression, and if it doesn't have an <literal>IO</literal> type,
then it transforms it as follows: an expression
<replaceable>e</replaceable> turns into
-<screen>
- let it = <replaceable>e</replaceable>;
- print it
+<screen>
+let it = <replaceable>e</replaceable>;
+print it
</screen>
which is then run as an IO-action.</para>
complain:</para>
<screen>
-Prelude> id
-No instance for `Show (a -> a)'
-arising from use of `print'
-in a `do' expression pattern binding: print it
+Prelude> id
+
+<interactive>:1:0:
+ No instance for (Show (a -> a))
+ arising from use of `print' at <interactive>:1:0-1
+ Possible fix: add an instance declaration for (Show (a -> a))
+ In the expression: print it
+ In a 'do' expression: print it
</screen>
<para>The error message contains some clues as to the
which is of type <literal>a</literal>. eg.:</para>
<screen>
Prelude> Time.getClockTime
+Wed Mar 14 12:23:13 GMT 2001
Prelude> print it
Wed Mar 14 12:23:13 GMT 2001
</screen>
<para>The corresponding translation for an IO-typed
<replaceable>e</replaceable> is
-<screen>
- it <- <replaceable>e</replaceable>
+<screen>
+it <- <replaceable>e</replaceable>
</screen>
</para>
standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
a)</literal> for each type variable <literal>a</literal>, and defaults the
type variable if
- <itemizedlist>
- <listitem><para> The type variable <literal>a</literal>
- appears in no other constraints </para></listitem>
- <listitem><para> All the classes <literal>Ci</literal> are standard.</para></listitem>
- <listitem><para> At least one of the classes <literal>Ci</literal> is
- numeric.</para></listitem>
+ <orderedlist>
+ <listitem>
+ <para>
+ The type variable <literal>a</literal> appears in no
+ other constraints
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All the classes <literal>Ci</literal> are standard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ At least one of the classes <literal>Ci</literal> is
+ numeric.
+ </para>
+ </listitem>
+ </orderedlist>
+ At the GHCi prompt, or with GHC if the
+ <literal>-XExtendedDefaultRules</literal> flag is given,
+ the following additional differences apply:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Rule 2 above is relaxed thus:
+ <emphasis>All</emphasis> of the classes
+ <literal>Ci</literal> are single-parameter type classes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rule 3 above is relaxed this:
+ At least one of the classes <literal>Ci</literal> is
+ numeric, <emphasis>or is <literal>Show</literal>,
+ <literal>Eq</literal>, or
+ <literal>Ord</literal></emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The unit type <literal>()</literal> is added to the
+ start of the standard list of types which are tried when
+ doing type defaulting.
+ </para>
+ </listitem>
+ </itemizedlist>
+ The last point means that, for example, this program:
+<programlisting>
+main :: IO ()
+main = print def
+
+instance Num ()
+
+def :: (Num a, Enum a) => a
+def = toEnum 0
+</programlisting>
+ prints <literal>()</literal> rather than <literal>0</literal> as the
+ type is defaulted to <literal>()</literal> rather than
+ <literal>Integer</literal>.
+ </para>
+ <para>
+ The motivation for the change is that it means <literal>IO a</literal>
+ actions default to <literal>IO ()</literal>, which in turn means that
+ ghci won't try to print a result when running them. This is
+ particularly important for <literal>printf</literal>, which has an
+ 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 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-debugger">
+ <title>The GHCi Debugger</title>
+ <indexterm><primary>debugger</primary><secondary>in GHCi</secondary>
+ </indexterm>
+
+ <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>
- At the GHCi prompt, the second and third rules are relaxed as follows
- (differences italicised):
- <itemizedlist>
- <listitem><para> <emphasis>All</emphasis> of the classes
- <literal>Ci</literal> are single-parameter type classes.</para></listitem>
- <listitem><para> At least one of the classes <literal>Ci</literal> is
- numeric, <emphasis>or is <literal>Show</literal>,
- <literal>Eq</literal>, or <literal>Ord</literal></emphasis>.</para></listitem>
+ </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>
+Prelude> :l qsort.hs
+[1 of 1] Compiling Main ( qsort.hs, interpreted )
+Ok, modules loaded: Main.
+*Main>
+ </screen>
+
+ <para>Now, let's set a breakpoint on the right-hand-side of the second
+ equation of qsort:</para>
+
+<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>Now, we run the program:</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>
+[qsort.hs:2:15-46] *Main> left
+
+<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>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>
+[qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show
+[qsort.hs:2:15-46] *Main> :print left
+left = (_t1::[a])
+</screen>
+
+ <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>
+
+<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>
+[qsort.hs:2:15-46] *Main> :show bindings
+_result :: [Integer]
+a :: Integer
+left :: [Integer]
+right :: [Integer]
+_t1 :: [Integer]
+</screen>
+
+ <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>
+
+<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>
+
+<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>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>Finally, we can continue the current execution:</para>
+
+<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>
+
+ <para>The execution continued at the point it previously stopped, and has
+ now stopped at the breakpoint for a second time.</para>
+
+
+ <sect3 id="setting-breakpoints">
+ <title>Setting breakpoints</title>
+
+ <para>Breakpoints can be set in various ways. Perhaps the easiest way to
+ set a breakpoint is to name a top-level function:</para>
+
+<screen>
+ :break <replaceable>identifier</replaceable>
+</screen>
+
+ <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>Breakpoints can also be set by line (and optionally column)
+ number:</para>
+
+<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>
+
+ <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>
+
+ </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>
+*Main> :show breaks
+[0] Main qsort.hs:1:11-12
+[1] Main qsort.hs:2:15-46
+</screen>
+
+ <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>
+*Main> :delete 0
+*Main> :show breaks
+[1] Main qsort.hs:2:15-46
+</screen>
+
+ <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>
+*Main> :step main
+Stopped at qsort.hs:5:7-47
+_result :: IO ()
+</screen>
+
+ <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>
- The same type-default behaviour can be enabled in an ordinary Haskell
- module, using the flag <literal>-fextended-default-rules</literal>.
- </para>
</sect2>
</sect1>
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
+ 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>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>
+ that don't make sense are mostly obvious.</para>
<sect2>
<title>Packages</title>
they will be automatically loaded the first time they are
needed.</para>
- <para>For non-auto packages, however, you need to request the
+ <para>For hidden packages, however, you need to request the
package be loaded by using the <literal>-package</literal> flag:</para>
<screen>
-$ ghci -package data
- ___ ___ _
- / _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 5.05, for Haskell 98.
-/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
-\____/\/ /_/\____/|_| Type :? for help.
-
+$ ghci -package readline
+GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
Loading package base ... linking ... done.
-Loading package haskell98 ... linking ... done.
-Loading package lang ... linking ... done.
-Loading package concurrent ... linking ... done.
-Loading package readline ... linking ... done.
-Loading package unix ... linking ... done.
-Loading package posix ... linking ... done.
-Loading package util ... linking ... done.
-Loading package data ... linking ... done.
+Loading package readline-1.0 ... linking ... done.
Prelude>
</screen>
<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, as long as the abbreviation is not ambiguous. All of
- the builtin commands, with the exception of
- <literal>:unset</literal> and <literal>:undef</literal>, may be
- abbreviated to a single letter.</para>
+ 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>
<varlistentry>
<term>
- <literal>:browse</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
+ <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 the
- <literal>*</literal> symbol is placed before the module
- name, then <emphasis>all</emphasis> the identifiers defined
- in <replaceable>module</replaceable> are shown; otherwise
- the list is limited to the exports of
+ loaded into GHCi or be a member of a package. If
+ <replaceable>module</replaceable> is omitted, the most
+ recently-loaded module is used.</para>
+
+ <para>If the <literal>*</literal> symbol is placed before
+ the module name, then <emphasis>all</emphasis> the
+ identifiers in scope in <replaceable>module</replaceable> are
+ shown; otherwise the list is limited to the exports of
<replaceable>module</replaceable>. The
<literal>*</literal>-form is only available for modules
which are interpreted; for compiled modules (including
modules from packages) only the non-<literal>*</literal>
- form of <literal>:browse</literal> is available.</para>
+ form of <literal>:browse</literal> is available.
+ If the <literal>!</literal> symbol is appended to the
+ command, data constructors and class methods will be
+ listed individually, otherwise, they will only be listed
+ in the context of their data type or class declaration.
+ The <literal>!</literal>-form also annotates the listing
+ with comments giving possible imports for each group of
+ entries.</para>
+<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>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable>
+ <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>The command <literal>:def</literal>
- <replaceable>name</replaceable>
- <replaceable>expr</replaceable> defines a new GHCi command
- <literal>:<replaceable>name</replaceable></literal>,
- implemented by the Haskell expression
- <replaceable>expr</replaceable>, which must have type
- <literal>String -> IO String</literal>. When
- <literal>:<replaceable>name</replaceable>
- <replaceable>args</replaceable></literal> is typed at the
- prompt, GHCi will run the expression
- <literal>(<replaceable>name</replaceable>
- <replaceable>args</replaceable>)</literal>, take the
- resulting <literal>String</literal>, and feed it back into
- GHCi as a new sequence of commands. Separate commands in
- the result must be separated by
- ‘<literal>\n</literal>’.</para>
+ <para><literal>:def</literal> is used to define new
+ commands, or macros, in GHCi. The command
+ <literal>:def</literal> <replaceable>name</replaceable>
+ <replaceable>expr</replaceable> defines a new GHCi command
+ <literal>:<replaceable>name</replaceable></literal>,
+ implemented by the Haskell expression
+ <replaceable>expr</replaceable>, which must have type
+ <literal>String -> IO String</literal>. When
+ <literal>:<replaceable>name</replaceable>
+ <replaceable>args</replaceable></literal> is typed at the
+ prompt, GHCi will run the expression
+ <literal>(<replaceable>name</replaceable>
+ <replaceable>args</replaceable>)</literal>, take the
+ resulting <literal>String</literal>, and feed it back into
+ GHCi as a new sequence of commands. Separate commands in
+ the result must be separated by
+ ‘<literal>\n</literal>’.</para>
<para>That's all a little confusing, so here's a few
examples. To start with, here's a new GHCi command which
<literal>:.</literal>, by analogy with the
‘<literal>.</literal>’ Unix shell command that
does the same thing.</para>
+
+ <para>Typing <literal>:def</literal> on its own lists the
+ currently-defined macros. Attempting to redefine an
+ existing command name results in an error unless the
+ <literal>:def!</literal> form is used, in which case the old
+ command with that name is silently overwritten.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:delete * | <replaceable>num</replaceable> ...</literal>
+ <indexterm><primary><literal>:delete</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Delete one or more breakpoints by number (use <literal>:show
+ breaks</literal> to see the number of each breakpoint). The
+ <literal>*</literal> form deletes all the breakpoints.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:edit <optional><replaceable>file</replaceable></optional></literal>
+ <indexterm><primary><literal>:edit</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Opens an editor to edit the file
+ <replaceable>file</replaceable>, or the most recently loaded
+ module if <replaceable>file</replaceable> is omitted. The
+ editor to invoke is taken from the <literal>EDITOR</literal>
+ environment variable, or a default editor on your system if
+ <literal>EDITOR</literal> is not set. You can change the
+ editor using <literal>:set editor</literal>.</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>
<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>
<varlistentry>
<term>
+ <literal>:main <replaceable>arg<subscript>1</subscript></replaceable> ... <replaceable>arg<subscript>n</subscript></replaceable></literal>
+ <indexterm><primary><literal>:main</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ When a program is compiled and executed, it can use the
+ <literal>getArgs</literal> function to access the
+ command-line arguments.
+ 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
+ arguments directly.
+ </para>
+
+ <para>
+ Instead, we can use the <literal>:main</literal> command.
+ This runs whatever <literal>main</literal> is in scope, with
+ any arguments being treated the same as command-line arguments,
+ e.g.:
+ </para>
+
+<screen>
+Prelude> let main = System.Environment.getArgs >>= print
+Prelude> :main foo bar
+["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>
+
+ <varlistentry>
+ <term>
<literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal>
<indexterm><primary><literal>:module</literal></primary></indexterm>
</term>
+ <term>
+ <literal>import <replaceable>mod</replaceable></literal>
+ </term>
<listitem>
<para>Sets or modifies the current context for statements
- typed at the prompt. See <xref linkend="ghci-scope"/> for
+ typed at the prompt. The form <literal>import
+ <replaceable>mod</replaceable></literal> is equivalent to
+ <literal>:module +<replaceable>mod</replaceable></literal>.
+ See <xref linkend="ghci-scope"/> for
more details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <literal>:print </literal> <replaceable>names</replaceable> ...
+ <indexterm><primary><literal>:print</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <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>
+
+ <varlistentry>
+ <term>
<literal>:quit</literal>
<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>editor</literal> <replaceable>cmd</replaceable>
+ </term>
+ <listitem>
+ <para>Sets the command used by <literal>:edit</literal> to
+ <replaceable>cmd</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:set</literal> <literal>prog</literal> <replaceable>prog</replaceable>
<indexterm><primary><literal>:set prog</literal></primary></indexterm>
</term>
<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>: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>:show packages</literal>
+ <indexterm><primary><literal>:show packages</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>Show the currently active package flags, as well as the list of
+ packages currently loaded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>:type</literal> <replaceable>expression</replaceable>
- <indexterm><primary><literal>:type</literal></primary></indexterm>
+ <literal>:show languages</literal>
+ <indexterm><primary><literal>:show languages</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>Show the currently active language flags.</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
- <literal>:kind</literal> <replaceable>type</replaceable>
- <indexterm><primary><literal>:kind</literal></primary></indexterm>
+ <literal>:show [args|prog|prompt|editor|stop]</literal>
+ <indexterm><primary><literal>:show</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>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 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>:step [<replaceable>expr</replaceable>]</literal>
+ <indexterm><primary><literal>:step</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <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>:trace [<replaceable>expr</replaceable>]</literal>
+ <indexterm><primary><literal>:trace</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <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>:type</literal> <replaceable>expression</replaceable>
+ <indexterm><primary><literal>:type</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>
</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-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>
</sect1>
- <sect1>
+ <sect1 id="ghci-obj">
+ <title>Compiling to object code inside GHCi</title>
+
+ <para>By default, GHCi compiles Haskell source code into byte-code
+ that is interpreted by the runtime system. GHCi can also compile
+ Haskell code to object code: to turn on this feature, use the
+ <option>-fobject-code</option> flag either on the command line or
+ with <literal>:set</literal> (the option
+ <option>-fbyte-code</option> restores byte-code compilation
+ again). Compiling to object code takes longer, but typically the
+ code will execute 10-20 times faster than byte-code.</para>
+
+ <para>Compiling to object code inside GHCi is particularly useful
+ if you are developing a compiled application, because the
+ <literal>:reload</literal> command typically runs much faster than
+ restarting GHC with <option>--make</option> from the command-line,
+ because all the interface files are already cached in
+ memory.</para>
+
+ <para>There are disadvantages to compiling to object-code: you
+ can't set breakpoints in object-code modules, for example. Only
+ the exports of an object-code module will be visible in GHCi,
+ rather than all top-level bindings as in interpreted
+ modules.</para>
+ </sect1>
+
+ <sect1 id="ghci-faq">
<title>FAQ and Things To Watch Out For</title>
<variablelist>
<term>Concurrent threads don't carry on running when GHCi is
waiting for input.</term>
<listitem>
- <para>No, they don't. This is because the Haskell binding
- to the GNU readline library doesn't support reading from the
- terminal in a non-blocking way, which is required to work
- properly with GHC's concurrency model.</para>
+ <para>This should work, as long as your GHCi was built with
+ the <option>-threaded</option> switch, which is the default.
+ Consult whoever supplied your GHCi installation.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>I can't use Control-C to interrupt computations in
+ GHCi on Windows.</term>
+ <listitem>
+ <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>
</sect1>
projects / ghc-hetmet.git / blobdiff