docs/users_guide/ghci.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <chapter id="ghci">
   3   <title>Using GHCi</title>
   4   <indexterm><primary>GHCi</primary></indexterm>
   5   <indexterm><primary>interpreter</primary><see>GHCi</see></indexterm>
   6   <indexterm><primary>interactive</primary><see>GHCi</see></indexterm>
   7
   8   <para>GHCi<footnote>
   9       <para>The &lsquo;i&rsquo; stands for &ldquo;Interactive&rdquo;</para>
  10     </footnote>
  11   is GHC's interactive environment, in which Haskell expressions can
  12   be interactively evaluated and programs can be interpreted.  If
  13   you're familiar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary>
  14   </indexterm>, then you'll be right at home with GHCi.  However, GHCi
  15   also has support for interactively loading compiled code, as well as
  16   supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
  17   </footnote> the language extensions that GHC provides.
  18   <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
  19   <indexterm><primary>Foreign Function
  20   Interface</primary><secondary>GHCi support</secondary></indexterm>.
  21   GHCi also includes an interactive debugger (see <xref linkend="ghci-debugger"/>).</para>
  22
  23   <sect1 id="ghci-introduction">
  24     <title>Introduction to GHCi</title>
  25
  26     <para>Let's start with an example GHCi session.  You can fire up
  27     GHCi with the command <literal>ghci</literal>:</para>
  28
  29 <screen>
  30 $ ghci
  31 GHCi, version 6.8.1: http://www.haskell.org/ghc/  :? for help
  32 Loading package base ... linking ... done.
  33 Prelude>
  34 </screen>
  35
  36     <para>There may be a short pause while GHCi loads the prelude and
  37     standard libraries, after which the prompt is shown.  If we follow
  38     the instructions and type <literal>:?</literal> for help, we
  39     get:</para>
  40
  41 <screen>
  42  Commands available from the prompt:
  43
  44    &lt;stmt&gt;                      evaluate/run &lt;stmt&gt;
  45    :add &lt;filename&gt; ...         add module(s) to the current target set
  46    :browse [*]&lt;module&gt;         display the names defined by &lt;module&gt;
  47    :cd &lt;dir&gt;                   change directory to &lt;dir&gt;
  48    :def &lt;cmd&gt; &lt;expr&gt;           define a command :&lt;cmd&gt;
  49    :edit &lt;file&gt;                edit file
  50    :edit                       edit last module
  51    :help, :?                   display this list of commands
  52    :info [&lt;name&gt; ...]          display information about the given names
  53    :load &lt;filename&gt; ...        load module(s) and their dependents
  54    :module [+/-] [*]&lt;mod&gt; ...  set the context for expression evaluation
  55    :main [&lt;arguments&gt; ...]     run the main function with the given arguments
  56    :reload                     reload the current module set
  57
  58    :set &lt;option&gt; ...           set options
  59    :set args &lt;arg&gt; ...         set the arguments returned by System.getArgs
  60    :set prog &lt;progname&gt;        set the value returned by System.getProgName
  61    :set prompt &lt;prompt&gt;        set the prompt used in GHCi
  62    :set editor &lt;cmd&gt;        set the command used for :edit
  63
  64    :show modules               show the currently loaded modules
  65    :show bindings              show the current bindings made at the prompt
  66
  67    :ctags [&lt;file&gt;]             create tags file for Vi (default: "tags")
  68    :etags [&lt;file&gt;]             create tags file for Emacs (default: "TAGS")
  69    :type &lt;expr&gt;                show the type of &lt;expr&gt;
  70    :kind &lt;type&gt;                show the kind of &lt;type&gt;
  71    :undef &lt;cmd&gt;                undefine user-defined command :&lt;cmd&gt;
  72    :unset &lt;option&gt; ...         unset options
  73    :quit                       exit GHCi
  74    :!&lt;command&gt;                 run the shell command &lt;command&gt;
  75
  76  Options for ':set' and ':unset':
  77
  78     +r            revert top-level expressions after each evaluation
  79     +s            print timing/memory stats after each evaluation
  80     +t            print type after evaluation
  81     -&lt;flags&gt;      most GHC command line flags can also be set here
  82                          (eg. -v2, -fglasgow-exts, etc.)
  83 </screen>
  84
  85     <para>We'll explain most of these commands as we go along.  For
  86     Hugs users: many things work the same as in Hugs, so you should be
  87     able to get going straight away.</para>
  88
  89     <para>Haskell expressions can be typed at the prompt:</para>
  90     <indexterm><primary>prompt</primary><secondary>GHCi</secondary>
  91   </indexterm>
  92
  93 <screen>
  94 Prelude> 1+2
  95 3
  96 Prelude> let x = 42 in x / 9
  97 4.666666666666667
  98 Prelude>
  99 </screen>
 100
 101     <para>GHCi interprets the whole line as an expression to evaluate.
 102     The expression may not span several lines - as soon as you press
 103     enter, GHCi will attempt to evaluate it.</para>
 104   </sect1>
 105
 106   <sect1 id="loading-source-files">
 107     <title>Loading source files</title>
 108
 109     <para>Suppose we have the following Haskell source code, which we
 110     place in a file <filename>Main.hs</filename>:</para>
 111
 112 <programlisting>
 113 main = print (fac 20)
 114
 115 fac 0 = 1
 116 fac n = n * fac (n-1)
 117 </programlisting>
 118
 119     <para>You can save <filename>Main.hs</filename> anywhere you like,
 120     but if you save it somewhere other than the current
 121     directory<footnote><para>If you started up GHCi from the command
 122     line then GHCi's current directory is the same as the current
 123     directory of the shell from which it was started.  If you started
 124     GHCi from the &ldquo;Start&rdquo; menu in Windows, then the
 125     current directory is probably something like
 126     <filename>C:\Documents and Settings\<replaceable>user
 127     name</replaceable></filename>.</para> </footnote> then we will
 128     need to change to the right directory in GHCi:</para>
 129
 130 <screen>
 131 Prelude> :cd <replaceable>dir</replaceable>
 132 </screen>
 133
 134     <para>where <replaceable>dir</replaceable> is the directory (or
 135     folder) in which you saved <filename>Main.hs</filename>.</para>
 136
 137     <para>To load a Haskell source file into GHCi, use the
 138     <literal>:load</literal> command:</para>
 139     <indexterm><primary><literal>:load</literal></primary></indexterm>
 140
 141 <screen>
 142 Prelude> :load Main
 143 Compiling Main             ( Main.hs, interpreted )
 144 Ok, modules loaded: Main.
 145 *Main>
 146 </screen>
 147
 148     <para>GHCi has loaded the <literal>Main</literal> module, and the
 149     prompt has changed to &ldquo;<literal>*Main></literal>&rdquo; to
 150     indicate that the current context for expressions typed at the
 151     prompt is the <literal>Main</literal> module we just loaded (we'll
 152     explain what the <literal>*</literal> means later in <xref
 153     linkend="ghci-scope"/>).  So we can now type expressions involving
 154     the functions from <filename>Main.hs</filename>:</para>
 155
 156 <screen>
 157 *Main> fac 17
 158 355687428096000
 159 </screen>
 160
 161     <para>Loading a multi-module program is just as straightforward;
 162     just give the name of the &ldquo;topmost&rdquo; module to the
 163     <literal>:load</literal> command (hint: <literal>:load</literal>
 164     can be abbreviated to <literal>:l</literal>).  The topmost module
 165     will normally be <literal>Main</literal>, but it doesn't have to
 166     be.  GHCi will discover which modules are required, directly or
 167     indirectly, by the topmost module, and load them all in dependency
 168     order.</para>
 169
 170     <sect2 id="ghci-modules-filenames">
 171       <title>Modules vs. filenames</title>
 172       <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
 173       <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>
 174
 175       <para>Question: How does GHC find the filename which contains
 176       module <replaceable>M</replaceable>?  Answer: it looks for the
 177       file <literal><replaceable>M</replaceable>.hs</literal>, or
 178       <literal><replaceable>M</replaceable>.lhs</literal>.  This means
 179       that for most modules, the module name must match the filename.
 180       If it doesn't, GHCi won't be able to find it.</para>
 181
 182       <para>There is one exception to this general rule: when you load
 183       a program with <literal>:load</literal>, or specify it when you
 184       invoke <literal>ghci</literal>, you can give a filename rather
 185       than a module name.  This filename is loaded if it exists, and
 186       it may contain any module you like.  This is particularly
 187       convenient if you have several <literal>Main</literal> modules
 188       in the same directory and you can't call them all
 189       <filename>Main.hs</filename>.</para>
 190
 191       <para>The search path for finding source files is specified with
 192       the <option>-i</option> option on the GHCi command line, like
 193       so:</para>
 194 <screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen>
 195
 196       <para>or it can be set using the <literal>:set</literal> command
 197       from within GHCi (see <xref
 198       linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in
 199       GHCi, and <option>&ndash;&ndash;make</option> mode, the <option>-i</option>
 200       option is used to specify the search path for
 201       <emphasis>source</emphasis> files, whereas in standard
 202       batch-compilation mode the <option>-i</option> option is used to
 203       specify the search path for interface files, see <xref
 204       linkend="search-path"/>.</para> </footnote></para>
 205
 206       <para>One consequence of the way that GHCi follows dependencies
 207       to find modules to load is that every module must have a source
 208       file.  The only exception to the rule is modules that come from
 209       a package, including the <literal>Prelude</literal> and standard
 210       libraries such as <literal>IO</literal> and
 211       <literal>Complex</literal>.  If you attempt to load a module for
 212       which GHCi can't find a source file, even if there are object
 213       and interface files for the module, you'll get an error
 214       message.</para>
 215     </sect2>
 216
 217     <sect2>
 218       <title>Making changes and recompilation</title>
 219       <indexterm><primary><literal>:reload</literal></primary></indexterm>
 220
 221       <para>If you make some changes to the source code and want GHCi
 222       to recompile the program, give the <literal>:reload</literal>
 223       command.  The program will be recompiled as necessary, with GHCi
 224       doing its best to avoid actually recompiling modules if their
 225       external dependencies haven't changed.  This is the same
 226       mechanism we use to avoid re-compiling modules in the batch
 227       compilation setting (see <xref linkend="recomp"/>).</para>
 228     </sect2>
 229   </sect1>
 230
 231   <sect1 id="ghci-compiled">
 232     <title>Loading compiled code</title>
 233     <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm>
 234
 235     <para>When you load a Haskell source module into GHCi, it is
 236     normally converted to byte-code and run using the interpreter.
 237     However, interpreted code can also run alongside compiled code in
 238     GHCi; indeed, normally when GHCi starts, it loads up a compiled
 239     copy of the <literal>base</literal> package, which contains the
 240     <literal>Prelude</literal>.</para>
 241
 242     <para>Why should we want to run compiled code?  Well, compiled
 243     code is roughly 10x faster than interpreted code, but takes about
 244     2x longer to produce (perhaps longer if optimisation is on).  So
 245     it pays to compile the parts of a program that aren't changing
 246     very often, and use the interpreter for the code being actively
 247     developed.</para>
 248
 249     <para>When loading up source files with <literal>:load</literal>,
 250     GHCi looks for any corresponding compiled object files, and will
 251     use one in preference to interpreting the source if possible.  For
 252     example, suppose we have a 4-module program consisting of modules
 253     A, B, C, and D.  Modules B and C both import D only,
 254     and A imports both B &amp; C:</para>
 255 <screen>
 256       A
 257      / \
 258     B   C
 259      \ /
 260       D
 261 </screen>
 262     <para>We can compile D, then load the whole program, like this:</para>
 263 <screen>
 264 Prelude> :! ghc -c D.hs
 265 Prelude> :load A
 266 Skipping  D                ( D.hs, D.o )
 267 Compiling C                ( C.hs, interpreted )
 268 Compiling B                ( B.hs, interpreted )
 269 Compiling A                ( A.hs, interpreted )
 270 Ok, modules loaded: A, B, C, D.
 271 *Main>
 272 </screen>
 273
 274     <para>In the messages from the compiler, we see that it skipped D,
 275     and used the object file <filename>D.o</filename>.  The message
 276     <literal>Skipping</literal> <replaceable>module</replaceable>
 277     indicates that compilation for <replaceable>module</replaceable>
 278     isn't necessary, because the source and everything it depends on
 279     is unchanged since the last compilation.</para>
 280
 281     <para>At any time you can use the command
 282     <literal>:show modules</literal>
 283     to get a list of the modules currently loaded
 284     into GHCi:</para>
 285
 286 <screen>
 287 *Main> :show modules
 288 D                ( D.hs, D.o )
 289 C                ( C.hs, interpreted )
 290 B                ( B.hs, interpreted )
 291 A                ( A.hs, interpreted )
 292 *Main></screen>
 293
 294     <para>If we now modify the source of D (or pretend to: using Unix
 295     command <literal>touch</literal> on the source file is handy for
 296     this), the compiler will no longer be able to use the object file,
 297     because it might be out of date:</para>
 298
 299 <screen>
 300 *Main> :! touch D.hs
 301 *Main> :reload
 302 Compiling D                ( D.hs, interpreted )
 303 Skipping  C                ( C.hs, interpreted )
 304 Skipping  B                ( B.hs, interpreted )
 305 Skipping  A                ( A.hs, interpreted )
 306 Ok, modules loaded: A, B, C, D.
 307 *Main>
 308 </screen>
 309
 310     <para>Note that module D was compiled, but in this instance
 311     because its source hadn't really changed, its interface remained
 312     the same, and the recompilation checker determined that A, B and C
 313     didn't need to be recompiled.</para>
 314
 315     <para>So let's try compiling one of the other modules:</para>
 316
 317 <screen>
 318 *Main> :! ghc -c C.hs
 319 *Main> :load A
 320 Compiling D                ( D.hs, interpreted )
 321 Compiling C                ( C.hs, interpreted )
 322 Compiling B                ( B.hs, interpreted )
 323 Compiling A                ( A.hs, interpreted )
 324 Ok, modules loaded: A, B, C, D.
 325 </screen>
 326
 327     <para>We didn't get the compiled version of C!  What happened?
 328     Well, in GHCi a compiled module may only depend on other compiled
 329     modules, and in this case C depends on D, which doesn't have an
 330     object file, so GHCi also rejected C's object file.  Ok, so let's
 331     also compile D:</para>
 332
 333 <screen>
 334 *Main> :! ghc -c D.hs
 335 *Main> :reload
 336 Ok, modules loaded: A, B, C, D.
 337 </screen>
 338
 339     <para>Nothing happened!  Here's another lesson: newly compiled
 340     modules aren't picked up by <literal>:reload</literal>, only
 341     <literal>:load</literal>:</para>
 342
 343 <screen>
 344 *Main> :load A
 345 Skipping  D                ( D.hs, D.o )
 346 Skipping  C                ( C.hs, C.o )
 347 Compiling B                ( B.hs, interpreted )
 348 Compiling A                ( A.hs, interpreted )
 349 Ok, modules loaded: A, B, C, D.
 350 </screen>
 351
 352     <para>HINT: since GHCi will only use a compiled object file if it
 353     can be sure that the compiled version is up-to-date, a good technique
 354     when working on a large program is to occasionally run
 355     <literal>ghc &ndash;&ndash;make</literal> to compile the whole project (say
 356     before you go for lunch :-), then continue working in the
 357     interpreter.  As you modify code, the new modules will be
 358     interpreted, but the rest of the project will remain
 359     compiled.</para>
 360
 361   </sect1>
 362
 363   <sect1 id="interactive-evaluation">
 364     <title>Interactive evaluation at the prompt</title>
 365
 366     <para>When you type an expression at the prompt, GHCi immediately
 367     evaluates and prints the result:
 368 <screen>
 369 Prelude> reverse "hello"
 370 "olleh"
 371 Prelude> 5+5
 372 10
 373 </screen>
 374 </para>
 375
 376 <sect2><title>I/O actions at the prompt</title>
 377
 378 <para>GHCi does more than simple expression evaluation at the prompt.
 379 If you type something of type <literal>IO a</literal> for some
 380     <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it
 381     as an IO-computation.
 382 <screen>
 383 Prelude> "hello"
 384 "hello"
 385 Prelude> putStrLn "hello"
 386 hello
 387 </screen>
 388 Furthermore, GHCi will print the result of the I/O action if (and only
 389 if):
 390 <itemizedlist>
 391   <listitem><para>The result type is an instance of <literal>Show</literal>.</para></listitem>
 392   <listitem><para>The result type is not
 393   <literal>()</literal>.</para></listitem>
 394 </itemizedlist>
 395 For example, remembering that <literal>putStrLn :: String -> IO ()</literal>:
 396 <screen>
 397 Prelude> putStrLn "hello"
 398 hello
 399 Prelude> do { putStrLn "hello"; return "yes" }
 400 hello
 401 "yes"
 402 </screen>
 403 </para></sect2>
 404
 405     <sect2 id="ghci-stmts">
 406       <title>Using <literal>do-</literal>notation at the prompt</title>
 407       <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm>
 408       <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm>
 409
 410       <para>GHCi actually accepts <firstterm>statements</firstterm>
 411       rather than just expressions at the prompt.  This means you can
 412       bind values and functions to names, and use them in future
 413       expressions or statements.</para>
 414
 415       <para>The syntax of a statement accepted at the GHCi prompt is
 416       exactly the same as the syntax of a statement in a Haskell
 417       <literal>do</literal> expression.  However, there's no monad
 418       overloading here: statements typed at the prompt must be in the
 419       <literal>IO</literal> monad.
 420 <screen>
 421 Prelude> x &lt;- return 42
 422 42
 423 Prelude> print x
 424 42
 425 Prelude>
 426 </screen>
 427       The statement <literal>x &lt;- return 42</literal> means
 428       &ldquo;execute <literal>return 42</literal> in the
 429       <literal>IO</literal> monad, and bind the result to
 430       <literal>x</literal>&rdquo;.  We can then use
 431       <literal>x</literal> in future statements, for example to print
 432       it as we did above.</para>
 433
 434       <para>GHCi will print the result of a statement if and only if:
 435         <itemizedlist>
 436           <listitem>
 437             <para>The statement is not a binding, or it is a monadic binding
 438               (<literal>p &lt;- e</literal>) that binds exactly one
 439               variable.</para>
 440           </listitem>
 441           <listitem>
 442             <para>The variable's type is not polymorphic, is not
 443               <literal>()</literal>, and is an instance of
 444               <literal>Show</literal></para>
 445           </listitem>
 446         </itemizedlist>
 447       The automatic printing of binding results can be supressed with
 448       <option>:set -fno-print-bind-result</option> (this does not
 449       supress printing the result of non-binding statements).
 450       <indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm><indexterm><primary><option>-fprint-bind-result</option></primary></indexterm>.
 451       You might want to do this to prevent the result of binding
 452       statements from being fully evaluated by the act of printing
 453       them, for example.</para>
 454
 455       <para>Of course, you can also bind normal non-IO expressions
 456       using the <literal>let</literal>-statement:</para>
 457 <screen>
 458 Prelude> let x = 42
 459 Prelude> x
 460 42
 461 Prelude>
 462 </screen>
 463       <para>Another important difference between the two types of binding
 464       is that the monadic bind (<literal>p &lt;- e</literal>) is
 465       <emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
 466       whereas with the <literal>let</literal> form, the expression
 467       isn't evaluated immediately:</para>
 468 <screen>
 469 Prelude> let x = error "help!"
 470 Prelude> print x
 471 *** Exception: help!
 472 Prelude>
 473 </screen>
 474
 475       <para>Note that <literal>let</literal> bindings do not automatically
 476         print the value bound, unlike monadic bindings.</para>
 477
 478       <para>Any exceptions raised during the evaluation or execution
 479       of the statement are caught and printed by the GHCi command line
 480       interface (for more information on exceptions, see the module
 481       <literal>Control.Exception</literal> in the libraries
 482       documentation).</para>
 483
 484       <para>Every new binding shadows any existing bindings of the
 485       same name, including entities that are in scope in the current
 486       module context.</para>
 487
 488       <para>WARNING: temporary bindings introduced at the prompt only
 489       last until the next <literal>:load</literal> or
 490       <literal>:reload</literal> command, at which time they will be
 491       simply lost.  However, they do survive a change of context with
 492       <literal>:module</literal>: the temporary bindings just move to
 493       the new location.</para>
 494
 495       <para>HINT: To get a list of the bindings currently in scope, use the
 496       <literal>:show bindings</literal> command:</para>
 497
 498 <screen>
 499 Prelude> :show bindings
 500 x :: Int
 501 Prelude></screen>
 502
 503       <para>HINT: if you turn on the <literal>+t</literal> option,
 504       GHCi will show the type of each variable bound by a statement.
 505       For example:</para>
 506       <indexterm><primary><literal>+t</literal></primary></indexterm>
 507 <screen>
 508 Prelude> :set +t
 509 Prelude> let (x:xs) = [1..]
 510 x :: Integer
 511 xs :: [Integer]
 512 </screen>
 513
 514     </sect2>
 515
 516     <sect2 id="ghci-scope">
 517       <title>What's really in scope at the prompt?</title>
 518
 519       <para>When you type an expression at the prompt, what
 520       identifiers and types are in scope?  GHCi provides a flexible
 521       way to control exactly how the context for an expression is
 522       constructed.  Let's start with the simple cases; when you start
 523       GHCi the prompt looks like this:</para>
 524
 525 <screen>Prelude></screen>
 526
 527       <para>Which indicates that everything from the module
 528       <literal>Prelude</literal> is currently in scope.  If we now
 529       load a file into GHCi, the prompt will change:</para>
 530
 531 <screen>
 532 Prelude> :load Main.hs
 533 Compiling Main             ( Main.hs, interpreted )
 534 *Main>
 535 </screen>
 536
 537       <para>The new prompt is <literal>*Main</literal>, which
 538       indicates that we are typing expressions in the context of the
 539       top-level of the <literal>Main</literal> module.  Everything
 540       that is in scope at the top-level in the module
 541       <literal>Main</literal> we just loaded is also in scope at the
 542       prompt (probably including <literal>Prelude</literal>, as long
 543       as <literal>Main</literal> doesn't explicitly hide it).</para>
 544
 545       <para>The syntax
 546       <literal>*<replaceable>module</replaceable></literal> indicates
 547       that it is the full top-level scope of
 548       <replaceable>module</replaceable> that is contributing to the
 549       scope for expressions typed at the prompt.  Without the
 550       <literal>*</literal>, just the exports of the module are
 551       visible.</para>
 552
 553       <para>We're not limited to a single module: GHCi can combine
 554       scopes from multiple modules, in any mixture of
 555       <literal>*</literal> and non-<literal>*</literal> forms.  GHCi
 556       combines the scopes from all of these modules to form the scope
 557       that is in effect at the prompt.  For technical reasons, GHCi
 558       can only support the <literal>*</literal>-form for modules which
 559       are interpreted, so compiled modules and package modules can
 560       only contribute their exports to the current scope.</para>
 561
 562       <para>The scope is manipulated using the
 563       <literal>:module</literal> command.  For example, if the current
 564       scope is <literal>Prelude</literal>, then we can bring into
 565       scope the exports from the module <literal>IO</literal> like
 566       so:</para>
 567
 568 <screen>
 569 Prelude> :module +IO
 570 Prelude IO> hPutStrLn stdout "hello\n"
 571 hello
 572 Prelude IO>
 573 </screen>
 574
 575       <para>(Note: you can use <literal>import M</literal> as an
 576       alternative to <literal>:module +M</literal>, and
 577       <literal>:module</literal> can also be shortened to
 578       <literal>:m</literal>). The full syntax of the
 579       <literal>:module</literal> command is:</para>
 580
 581 <screen>
 582 :module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
 583 </screen>
 584
 585       <para>Using the <literal>+</literal> form of the
 586       <literal>module</literal> commands adds modules to the current
 587       scope, and <literal>-</literal> removes them.  Without either
 588       <literal>+</literal> or <literal>-</literal>, the current scope
 589       is replaced by the set of modules specified.  Note that if you
 590       use this form and leave out <literal>Prelude</literal>, GHCi
 591       will assume that you really wanted the
 592       <literal>Prelude</literal> and add it in for you (if you don't
 593       want the <literal>Prelude</literal>, then ask to remove it with
 594       <literal>:m -Prelude</literal>).</para>
 595
 596       <para>The scope is automatically set after a
 597       <literal>:load</literal> command, to the most recently loaded
 598       "target" module, in a <literal>*</literal>-form if possible.
 599       For example, if you say <literal>:load foo.hs bar.hs</literal>
 600       and <filename>bar.hs</filename> contains module
 601       <literal>Bar</literal>, then the scope will be set to
 602       <literal>*Bar</literal> if <literal>Bar</literal> is
 603       interpreted, or if <literal>Bar</literal> is compiled it will be
 604       set to <literal>Prelude Bar</literal> (GHCi automatically adds
 605       <literal>Prelude</literal> if it isn't present and there aren't
 606       any <literal>*</literal>-form modules).</para>
 607
 608       <para>With multiple modules in scope, especially multiple
 609       <literal>*</literal>-form modules, it is likely that name
 610       clashes will occur.  Haskell specifies that name clashes are
 611       only reported when an ambiguous identifier is used, and GHCi
 612       behaves in the same way for expressions typed at the
 613       prompt.</para>
 614
 615       <para>
 616         Hint: GHCi will tab-complete names that are in scope; for
 617         example, if you run GHCi and type <literal>J&lt;tab&gt;</literal>
 618         then GHCi will expand it to <literal>Just </literal>.
 619       </para>
 620
 621       <sect3>
 622         <title>Qualified names</title>
 623
 624         <para>To make life slightly easier, the GHCi prompt also
 625         behaves as if there is an implicit <literal>import
 626         qualified</literal> declaration for every module in every
 627         package, and every module currently loaded into GHCi.</para>
 628       </sect3>
 629
 630       <sect3>
 631         <title>The <literal>:main</literal> command</title>
 632
 633         <para>
 634           When a program is compiled and executed, it can use the
 635           <literal>getArgs</literal> function to access the
 636           command-line arguments.
 637           However, we cannot simply pass the arguments to the
 638           <literal>main</literal> function while we are testing in ghci,
 639           as the <literal>main</literal> function doesn't take its
 640           directly.
 641         </para>
 642
 643         <para>
 644           Instead, we can use the <literal>:main</literal> command.
 645           This runs whatever <literal>main</literal> is in scope, with
 646           any arguments being treated the same as command-line arguments,
 647           e.g.:
 648         </para>
 649
 650 <screen>
 651 Prelude> let main = System.Environment.getArgs >>= print
 652 Prelude> :main foo bar
 653 ["foo","bar"]
 654 </screen>
 655
 656       </sect3>
 657     </sect2>
 658
 659
 660     <sect2>
 661       <title>The <literal>it</literal> variable</title>
 662       <indexterm><primary><literal>it</literal></primary>
 663       </indexterm>
 664
 665       <para>Whenever an expression (or a non-binding statement, to be
 666       precise) is typed at the prompt, GHCi implicitly binds its value
 667       to the variable <literal>it</literal>.  For example:</para>
 668 <screen>
 669 Prelude> 1+2
 670 3
 671 Prelude> it * 2
 672 6
 673 </screen>
 674     <para>What actually happens is that GHCi typechecks the
 675     expression, and if it doesn't have an <literal>IO</literal> type,
 676     then it transforms it as follows: an expression
 677     <replaceable>e</replaceable> turns into
 678 <screen>
 679 let it = <replaceable>e</replaceable>;
 680 print it
 681 </screen>
 682     which is then run as an IO-action.</para>
 683
 684     <para>Hence, the original expression must have a type which is an
 685     instance of the <literal>Show</literal> class, or GHCi will
 686     complain:</para>
 687
 688 <screen>
 689 Prelude&gt; id
 690
 691 &lt;interactive&gt;:1:0:
 692     No instance for (Show (a -&gt; a))
 693       arising from use of `print' at &lt;interactive&gt;:1:0-1
 694     Possible fix: add an instance declaration for (Show (a -> a))
 695     In the expression: print it
 696     In a 'do' expression: print it
 697 </screen>
 698
 699     <para>The error message contains some clues as to the
 700     transformation happening internally.</para>
 701
 702       <para>If the expression was instead of type <literal>IO a</literal> for
 703       some <literal>a</literal>, then <literal>it</literal> will be
 704       bound to the result of the <literal>IO</literal> computation,
 705       which is of type <literal>a</literal>.  eg.:</para>
 706 <screen>
 707 Prelude> Time.getClockTime
 708 Wed Mar 14 12:23:13 GMT 2001
 709 Prelude> print it
 710 Wed Mar 14 12:23:13 GMT 2001
 711 </screen>
 712
 713       <para>The corresponding translation for an IO-typed
 714       <replaceable>e</replaceable> is
 715 <screen>
 716 it &lt;- <replaceable>e</replaceable>
 717 </screen>
 718       </para>
 719
 720       <para>Note that <literal>it</literal> is shadowed by the new
 721       value each time you evaluate a new expression, and the old value
 722       of <literal>it</literal> is lost.</para>
 723
 724     </sect2>
 725
 726     <sect2 id="extended-default-rules">
 727       <title>Type defaulting in GHCi</title>
 728     <indexterm><primary>Type default</primary></indexterm>
 729     <indexterm><primary><literal>Show</literal> class</primary></indexterm>
 730       <para>
 731       Consider this GHCi session:
 732 <programlisting>
 733   ghci> reverse []
 734 </programlisting>
 735       What should GHCi do?  Strictly speaking, the program is ambiguous.  <literal>show (reverse [])</literal>
 736       (which is what GHCi computes here) has type <literal>Show a => a</literal> and how that displays depends
 737       on the type <literal>a</literal>.  For example:
 738 <programlisting>
 739   ghci> (reverse []) :: String
 740   ""
 741   ghci> (reverse []) :: [Int]
 742   []
 743 </programlisting>
 744     However, it is tiresome for the user to have to specify the type, so GHCi extends Haskell's type-defaulting
 745     rules (Section 4.3.4 of the Haskell 98 Report (Revised)) as follows.  The
 746     standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
 747     a)</literal> for each type variable <literal>a</literal>, and defaults the
 748     type variable if
 749     <orderedlist>
 750         <listitem>
 751             <para>
 752                 The type variable <literal>a</literal> appears in no
 753                 other constraints
 754             </para>
 755         </listitem>
 756         <listitem>
 757             <para>
 758                 All the classes <literal>Ci</literal> are standard.
 759             </para>
 760         </listitem>
 761         <listitem>
 762             <para>
 763                 At least one of the classes <literal>Ci</literal> is
 764                 numeric.
 765             </para>
 766         </listitem>
 767     </orderedlist>
 768     At the GHCi prompt, or with GHC if the
 769     <literal>-fextended-default-rules</literal> flag is given,
 770     the following additional differences apply:
 771     <itemizedlist>
 772         <listitem>
 773             <para>
 774                 Rule 2 above is relaxed thus:
 775                 <emphasis>All</emphasis> of the classes
 776                 <literal>Ci</literal> are single-parameter type classes.
 777             </para>
 778         </listitem>
 779         <listitem>
 780             <para>
 781                 Rule 3 above is relaxed this:
 782                 At least one of the classes <literal>Ci</literal> is
 783                 numeric, <emphasis>or is <literal>Show</literal>,
 784                 <literal>Eq</literal>, or
 785                 <literal>Ord</literal></emphasis>.
 786             </para>
 787         </listitem>
 788         <listitem>
 789             <para>
 790                 The unit type <literal>()</literal> is added to the
 791                 start of the standard list of types which are tried when
 792                 doing type defaulting.
 793             </para>
 794         </listitem>
 795     </itemizedlist>
 796     The last point means that, for example, this program:
 797 <programlisting>
 798 main :: IO ()
 799 main = print def
 800
 801 instance Num ()
 802
 803 def :: (Num a, Enum a) => a
 804 def = toEnum 0
 805 </programlisting>
 806     prints <literal>()</literal> rather than <literal>0</literal> as the
 807     type is defaulted to <literal>()</literal> rather than
 808     <literal>Integer</literal>.
 809    </para>
 810    <para>
 811     The motivation for the change is that it means <literal>IO a</literal>
 812     actions default to <literal>IO ()</literal>, which in turn means that
 813     ghci won't try to print a result when running them. This is
 814     particularly important for <literal>printf</literal>, which has an
 815     instance that returns <literal>IO a</literal>.
 816     However, it is only able to return
 817     <literal>undefined</literal>
 818     (the reason for the instance having this type is to not require
 819     extensions to the class system), so if the type defaults to
 820     <literal>Integer</literal> then ghci gives an error when running a
 821     printf.
 822    </para>
 823     </sect2>
 824   </sect1>
 825
 826   <sect1 id="ghci-debugger">
 827     <title>The GHCi Debugger</title>
 828     <indexterm><primary>debugger</primary><secondary>in GHCi</secondary>
 829     </indexterm>
 830
 831     <para>GHCi contains a simple imperative-style debugger in which you can
 832       stop a running computation in order to examine the values of
 833       variables.  The debugger is integrated into GHCi, and is turned on by
 834       default: no flags are required to enable the debugging facilities.  There
 835       is one major restriction: breakpoints and single-stepping are only
 836       available in <emphasis>interpreted</emphasis> modules; compiled code is
 837       invisible to the debugger.</para>
 838
 839     <para>The debugger provides the following:
 840     <itemizedlist>
 841         <listitem>
 842           <para>The abilty to set a <firstterm>breakpoint</firstterm> on a
 843             function definition or expression in the program.  When the function
 844             is called, or the expression evaluated, GHCi suspends
 845             execution and returns to the prompt, where you can inspect the
 846             values of local variables before continuing with the
 847             execution.</para>
 848         </listitem>
 849         <listitem>
 850           <para>Execution can be <firstterm>single-stepped</firstterm>: the
 851             evaluator will suspend execution approximately after every
 852             reduction, allowing local variables to be inspected.  This is
 853             equivalent to setting a breakpoint at every point in the
 854             program.</para>
 855         </listitem>
 856         <listitem>
 857           <para>Execution can take place in <firstterm>tracing
 858               mode</firstterm>, in which the evaluator remembers each
 859             evaluation step as it happens, but doesn't suspend execution until
 860             an actual breakpoint is reached.  When this happens, the history of
 861             evaluation steps can be inspected.</para>
 862         </listitem>
 863         <listitem>
 864           <para>Exceptions (e.g. pattern matching failure and
 865             <literal>error</literal>) can be treated as breakpoints, to help
 866             locate the source of an exception in the program.</para>
 867         </listitem>
 868       </itemizedlist>
 869     </para>
 870
 871     <para>There is currently no support for obtaining a &ldquo;stack
 872       trace&rdquo;, but the tracing and history features provide a useful
 873       second-best, which will often be enough to establish the context of an
 874       error.</para>
 875
 876     <sect2 id="breakpoints">
 877       <title>Breakpoints and inspecting variables</title>
 878
 879       <para>Let's use quicksort as a running example.  Here's the code:</para>
 880
 881 <programlisting>
 882 qsort [] = []
 883 qsort (a:as) = qsort left ++ [a] ++ qsort right
 884   where (left,right) = (filter (&lt;=a) as, filter (&gt;a) as)
 885
 886 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
 887 </programlisting>
 888
 889       <para>First, load the module into GHCi:</para>
 890
 891 <screen>
 892 Prelude> :l qsort.hs
 893 [1 of 1] Compiling Main             ( qsort.hs, interpreted )
 894 Ok, modules loaded: Main.
 895 *Main>
 896       </screen>
 897
 898       <para>Now, let's set a breakpoint on the right-hand-side of the second
 899         equation of qsort:</para>
 900
 901 <programlisting>
 902 *Main> :break 2
 903 Breakpoint 0 activated at qsort.hs:2:15-46
 904 *Main>
 905 </programlisting>
 906
 907       <para>The command <literal>:break 2</literal> sets a breakpoint on line
 908         2 of the most recently-loaded module, in this case
 909         <literal>qsort.hs</literal>.   Specifically, it picks the
 910         leftmost complete subexpression on that line on which to set the
 911         breakpoint, which in this case is the expression
 912         <literal>(qsort left ++ [a] ++ qsort right)</literal>.</para>
 913
 914       <para>Now, we run the program:</para>
 915
 916 <programlisting>
 917 *Main> main
 918 Stopped at qsort.hs:2:15-46
 919 _result :: [a]
 920 a :: a
 921 left :: [a]
 922 right :: [a]
 923 [qsort.hs:2:15-46] *Main>
 924 </programlisting>
 925
 926       <para>Execution has stopped at the breakpoint.  The prompt has changed to
 927         indicate that we are currently stopped at a breakpoint, and the location:
 928         <literal>[qsort.hs:2:15-46]</literal>.  To further clarify the
 929         location, we can use the <literal>:list</literal> command:</para>
 930
 931 <programlisting>
 932 [qsort.hs:2:15-46] *Main> :list
 933 1  qsort [] = []
 934 2  qsort (a:as) = qsort left ++ [a] ++ qsort right
 935 3    where (left,right) = (filter (&lt;=a) as, filter (&gt;a) as)
 936 </programlisting>
 937
 938       <para>The <literal>:list</literal> command lists the source code around
 939         the current breakpoint.  If your output device supports it, then GHCi
 940         will highlight the active subexpression in bold.</para>
 941
 942       <para>GHCi has provided bindings for the free variables<footnote><para>We
 943             originally provided bindings for all variables in scope, rather
 944             than just
 945             the free variables of the expression, but found that this affected
 946             performance considerably, hence the current restriction to just the
 947             free variables.</para>
 948         </footnote> of the expression
 949         on which the
 950         breakpoint was placed (<literal>a</literal>, <literal>left</literal>,
 951         <literal>right</literal>), and additionally a binding for the result of
 952         the expression (<literal>_result</literal>).  These variables are just
 953         like other variables that you might define in GHCi; you
 954         can use them in expressions that you type at the prompt, you can ask
 955         for their types with <literal>:type</literal>, and so on.  There is one
 956         important difference though: these variables may only have partial
 957         types.  For example, if we try to display the value of
 958         <literal>left</literal>:</para>
 959
 960 <screen>
 961 [qsort.hs:2:15-46] *Main> left
 962
 963 &lt;interactive&gt;:1:0:
 964     Ambiguous type variable `a' in the constraint:
 965       `Show a' arising from a use of `print' at &lt;interactive&gt;:1:0-3
 966     Cannot resolve unknown runtime types: a
 967     Use :print or :force to determine these types
 968 </screen>
 969
 970       <para>This is because <literal>qsort</literal> is a polymorphic function,
 971         and because GHCi does not carry type information at runtime, it cannot
 972         determine the runtime types of free variables that involve type
 973         variables.  Hence, when you ask to display <literal>left</literal> at
 974         the prompt, GHCi can't figure out which instance of
 975         <literal>Show</literal> to use, so it emits the type error above.</para>
 976
 977       <para>Fortunately, the debugger includes a generic printing command,
 978         <literal>:print</literal>, which can inspect the actual runtime value of a
 979         variable and attempt to reconstruct its type.  If we try it on
 980         <literal>left</literal>:</para>
 981
 982 <screen>
 983 [qsort.hs:2:15-46] *Main> :print left
 984 left = (_t1::[a])
 985 </screen>
 986
 987       <para>This isn't particularly enlightening.  What happened is that
 988         <literal>left</literal> is bound to an unevaluated computation (a
 989         suspension, or <firstterm>thunk</firstterm>), and
 990         <literal>:print</literal> does not force any evaluation.  The idea is
 991         that <literal>:print</literal> can be used to inspect values at a
 992         breakpoint without any unfortunate side effects.  It won't force any
 993         evaluation, which could cause the program to give a different answer
 994         than it would normally, and hence it won't cause any exceptions to be
 995         raised, infinite loops, or further breakpoints to be triggered (see
 996         <xref linkend="nested-breakpoints" />).
 997         Rather than forcing thunks, <literal>:print</literal>
 998         binds each thunk to a fresh variable beginning with an
 999         underscore, in this case
1000         <literal>_t1</literal>.</para>
1001
1002       <para>If we aren't concerned about preserving the evaluatedness of a
1003         variable, we can use <literal>:force</literal> instead of
1004         <literal>:print</literal>.  The <literal>:force</literal> command
1005         behaves exactly like <literal>:print</literal>, except that it forces
1006         the evaluation of any thunks it encounters:</para>
1007
1008 <screen>
1009 [qsort.hs:2:15-46] *Main> :force left
1010 left = [4,0,3,1]
1011 </screen>
1012
1013       <para>Now, since <literal>:force</literal> has inspected the runtime
1014         value of <literal>left</literal>, it has reconstructed its type.  We
1015         can see the results of this type reconstruction:</para>
1016
1017 <screen>
1018 [qsort.hs:2:15-46] *Main> :show bindings
1019 _result :: [Integer]
1020 a :: Integer
1021 left :: [Integer]
1022 right :: [Integer]
1023 _t1 :: [Integer]
1024 </screen>
1025
1026       <para>Not only do we now know the type of <literal>left</literal>, but
1027         all the other partial types have also been resolved.  So we can ask
1028         for the value of <literal>a</literal>, for example:</para>
1029
1030 <screen>
1031 [qsort.hs:2:15-46] *Main> a
1032 8
1033 </screen>
1034
1035       <para>You might find it useful to use Haskell's
1036         <literal>seq</literal> function to evaluate individual thunks rather
1037         than evaluating the whole expression with <literal>:force</literal>.
1038         For example:</para>
1039
1040 <screen>
1041 [qsort.hs:2:15-46] *Main> :print right
1042 right = (_t1::[Integer])
1043 [qsort.hs:2:15-46] *Main> seq _t1 ()
1044 ()
1045 [qsort.hs:2:15-46] *Main> :print right
1046 right = 23 : (_t2::[Integer])
1047 </screen>
1048
1049       <para>We evaluated only the <literal>_t1</literal> thunk, revealing the
1050         head of the list, and the tail is another thunk now bound to
1051         <literal>_t2</literal>.  The <literal>seq</literal> function is a
1052         little inconvenient to use here, so you might want to use
1053         <literal>:def</literal> to make a nicer interface (left as an exercise
1054         for the reader!).</para>
1055
1056       <para>Finally, we can continue the current execution:</para>
1057
1058 <screen>
1059 [qsort.hs:2:15-46] *Main> :continue
1060 Stopped at qsort.hs:2:15-46
1061 _result :: [a]
1062 a :: a
1063 left :: [a]
1064 right :: [a]
1065 [qsort.hs:2:15-46] *Main>
1066 </screen>
1067
1068       <para>The execution continued at the point it previously stopped, and has
1069         now stopped at the breakpoint for a second time.</para>
1070
1071       <sect3 id="setting-breakpoings">
1072         <title>Setting breakpoints</title>
1073
1074         <para>Breakpoints can be set in various ways.  Perhaps the easiest way to
1075           set a breakpoint is to name a top-level function:</para>
1076
1077 <screen>
1078    :break <replaceable>identifier</replaceable>
1079 </screen>
1080
1081       <para>Where <replaceable>identifier</replaceable> names any top-level
1082         function in an interpreted module currently loaded into GHCi (qualified
1083         names may be used).  The breakpoint will be set on the body of the
1084         function, when it is fully applied but before any pattern matching has
1085         taken place.</para>
1086
1087       <para>Breakpoints can also be set by line (and optionally column)
1088         number:</para>
1089
1090 <screen>
1091    :break <replaceable>line</replaceable>
1092    :break <replaceable>line</replaceable> <replaceable>column</replaceable>
1093    :break <replaceable>module</replaceable> <replaceable>line</replaceable>
1094    :break <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable>
1095 </screen>
1096
1097       <para>When a breakpoint is set on a particular line, GHCi sets the
1098         breakpoint on the
1099         leftmost subexpression that begins and ends on that line.  If two
1100         complete subexpressions start at the same
1101         column, the longest one is picked.  If there is no complete
1102         subexpression on the line, then the leftmost expression starting on
1103         the line is picked, and failing that the rightmost expression that
1104         partially or completely covers the line.</para>
1105
1106       <para>When a breakpoint is set on a particular line and column, GHCi
1107         picks the smallest subexpression that encloses that location on which
1108         to set the breakpoint.  Note: GHC considers the TAB character to have a
1109         width of 1, wherever it occurs; in other words it counts
1110           characters, rather than columns.  This matches what some editors do,
1111           and doesn't match others.  The best advice is to avoid tab
1112           characters in your source code altogether (see
1113           <option>-fwarn-tabs</option> in <xref linkend="options-sanity"
1114             />).</para>
1115
1116       <para>If the module is omitted, then the most recently-loaded module is
1117         used.</para>
1118
1119       <para>Not all subexpressions are potential breakpoint locations.  Single
1120         variables are typically not considered to be breakpoint locations
1121         (unless the variable is the right-hand-side of a function definition,
1122         lambda, or case alternative).  The rule of thumb is that all redexes
1123         are breakpoint locations, together with the bodies of functions,
1124         lambdas, case alternatives and binding statements.  There is normally
1125         no breakpoint on a let expression, but there will always be a
1126         breakpoint on its body, because we are usually interested in inspecting
1127         the values of the variables bound by the let.</para>
1128
1129       </sect3>
1130       <sect3>
1131         <title>Listing and deleting breakpoints</title>
1132
1133         <para>The list of breakpoints currently enabled can be displayed using
1134           <literal>:show&nbsp;breaks</literal></para>:
1135 <screen>
1136 *Main> :show breaks
1137 [0] Main qsort.hs:1:11-12
1138 [1] Main qsort.hs:2:15-46
1139 </screen>
1140
1141         <para>To delete a breakpoint, use the <literal>:delete</literal>
1142           command with the number given in the output from <literal>:show&nbsp;breaks</literal>:</para>
1143
1144 <screen>
1145 *Main> :delete 0
1146 *Main> :show breaks
1147 [1] Main qsort.hs:2:15-46
1148 </screen>
1149
1150         <para>To delete all breakpoints at once, use <literal>:delete *</literal>.</para>
1151
1152     </sect3>
1153     </sect2>
1154
1155     <sect2 id="single-stepping">
1156       <title>Single-stepping</title>
1157
1158       <para>Single-stepping is a great way to visualise the execution of your
1159         program, and it is also a useful tool for identifying the source of a
1160         bug.  The concept is simple: single-stepping enables all the
1161         breakpoints in the program and executes until the next breakpoint is
1162         reached, at which point you can single-step again, or continue
1163         normally.  For example:</para>
1164
1165 <screen>
1166 *Main> :step main
1167 Stopped at qsort.hs:5:7-47
1168 _result :: IO ()
1169 </screen>
1170
1171       <para>The command <literal>:step
1172           <replaceable>expr</replaceable></literal> begins the evaluation of
1173         <replaceable>expr</replaceable> in single-stepping mode.  If
1174         <replaceable>expr</replaceable> is ommitted, then it single-steps from
1175         the current breakpoint.</para>
1176
1177       <para>The <literal>:list</literal> command is particularly useful when
1178         single-stepping, to see where you currently are:</para>
1179
1180 <screen>
1181 [qsort.hs:5:7-47] *Main> :list
1182 4
1183 5  main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1184 6
1185 [qsort.hs:5:7-47] *Main>
1186 </screen>
1187
1188       <para>In fact, GHCi provides a way to run a command when a breakpoint is
1189         hit, so we can make it automatically do
1190         <literal>:list</literal>:</para>
1191
1192 <screen>
1193 [qsort.hs:5:7-47] *Main> :set stop :list
1194 [qsort.hs:5:7-47] *Main> :step
1195 Stopped at qsort.hs:5:14-46
1196 _result :: [Integer]
1197 4
1198 5  main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1199 6
1200 [qsort.hs:5:14-46] *Main>
1201 </screen>
1202     </sect2>
1203
1204     <sect2 id="nested-breakpoints">
1205       <title>Nested breakpoints</title>
1206       <para>When GHCi is stopped at a breakpoint, and an expression entered at
1207         the prompt triggers a
1208         second breakpoint, the new breakpoint becomes the &ldquo;current&rdquo;
1209       one, and the old one is saved on a stack.  An arbitrary number of
1210         breakpoint contexts can be built up in this way.  For example:</para>
1211
1212 <screen>
1213 [qsort.hs:2:15-46] *Main> :st qsort [1,3]
1214 Stopped at qsort.hs:(1,0)-(3,55)
1215 _result :: [a]
1216 ... [qsort.hs:(1,0)-(3,55)] *Main>
1217 </screen>
1218
1219       <para>While stopped at the breakpoint on line 2 that we set earlier, we
1220         started a new evaluation with <literal>:step qsort [1,3]</literal>.
1221         This new evaluation stopped after one step (at the definition of
1222         <literal>qsort</literal>).  The prompt has changed, now prefixed with
1223         <literal>...</literal>, to indicate that there are saved breakpoints
1224         beyond the current one.  To see the stack of contexts, use
1225         <literal>:show context</literal>:</para>
1226
1227 <screen>
1228 ... [qsort.hs:(1,0)-(3,55)] *Main> :show context
1229 --> main
1230   Stopped at qsort.hs:2:15-46
1231 --> qsort [1,3]
1232   Stopped at qsort.hs:(1,0)-(3,55)
1233 ... [qsort.hs:(1,0)-(3,55)] *Main>
1234 </screen>
1235
1236         <para>To abandon the current evaluation, use
1237         <literal>:abandon</literal>:</para>
1238
1239 <screen>
1240 ... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
1241 [qsort.hs:2:15-46] *Main> :abandon
1242 *Main>
1243 </screen>
1244     </sect2>
1245
1246     <sect2 id="ghci-debugger-result">
1247       <title>The <literal>_result</literal> variable</title>
1248       <para>When stopped at a breakpoint or single-step, GHCi binds the
1249         variable <literal>_result</literal> to the value of the currently
1250         active expression.  The value of <literal>_result</literal> is
1251         presumably not available yet, because we stopped its evaluation, but it
1252         can be forced: if the type is known and showable, then just entering
1253         <literal>_result</literal> at the prompt will show it.  However,
1254         there's one caveat to doing this: evaluating <literal>_result</literal>
1255         will be likely to trigger further breakpoints, starting with the
1256         breakpoint we are currently stopped at (if we stopped at a real
1257         breakpoint, rather than due to <literal>:step</literal>).  So it will
1258         probably be necessary to issue a <literal>:continue</literal>
1259         immediately when evaluating <literal>_result</literal>.  Alternatively,
1260         you can use <literal>:force</literal> which ignores breakpoints.</para>
1261     </sect2>
1262
1263     <sect2 id="tracing">
1264       <title>Tracing and history</title>
1265
1266       <para>A question that we often want to ask when debugging a program is
1267         &ldquo;how did I get here?&rdquo;.  Traditional imperative debuggers
1268         usually provide some kind of stack-tracing feature that lets you see
1269         the stack of active function calls (sometimes called the &ldquo;lexical
1270         call stack&rdquo;), describing a path through the code
1271         to the current location.  Unfortunately this is hard to provide in
1272         Haskell, because execution proceeds on a demand-driven basis, rather
1273         than a depth-first basis as in strict languages.  The
1274         &ldquo;stack&ldquo; in GHC's execution engine bears little
1275         resemblance to the lexical call stack.  Ideally GHCi would maintain a
1276         separate lexical call stack in addition to the dynamic call stack, and
1277         in fact this is exactly
1278         what our profiling system does (<xref linkend="profiling" />), and what
1279         some other Haskell debuggers do.  For the time being, however, GHCi
1280         doesn't maintain a lexical call stack (there are some technical
1281         challenges to be overcome).  Instead, we provide a way to backtrack from a
1282         breakpoint to previous evaluation steps: essentially this is like
1283         single-stepping backwards, and should in many cases provide enough
1284         information to answer the &ldquo;how did I get here?&rdquo;
1285         question.</para>
1286
1287       <para>To use tracing, evaluate an expression with the
1288         <literal>:trace</literal> command.  For example, if we set a breakpoint
1289         on the base case of <literal>qsort</literal>:</para>
1290
1291 <screen>
1292 *Main&gt; :list qsort
1293 1  qsort [] = []
1294 2  qsort (a:as) = qsort left ++ [a] ++ qsort right
1295 3    where (left,right) = (filter (&lt;=a) as, filter (&gt;a) as)
1296 4
1297 *Main&gt; :b 1
1298 Breakpoint 1 activated at qsort.hs:1:11-12
1299 *Main&gt;
1300 </screen>
1301
1302       <para>and then run a small <literal>qsort</literal> with
1303         tracing:</para>
1304
1305 <screen>
1306 *Main> :trace qsort [3,2,1]
1307 Stopped at qsort.hs:1:11-12
1308 _result :: [a]
1309 [qsort.hs:1:11-12] *Main>
1310 </screen>
1311
1312       <para>We can now inspect the history of evaluation steps:</para>
1313
1314 <screen>
1315 [qsort.hs:1:11-12] *Main> :hist
1316 -1  : qsort.hs:3:24-38
1317 -2  : qsort.hs:3:23-55
1318 -3  : qsort.hs:(1,0)-(3,55)
1319 -4  : qsort.hs:2:15-24
1320 -5  : qsort.hs:2:15-46
1321 -6  : qsort.hs:3:24-38
1322 -7  : qsort.hs:3:23-55
1323 -8  : qsort.hs:(1,0)-(3,55)
1324 -9  : qsort.hs:2:15-24
1325 -10 : qsort.hs:2:15-46
1326 -11 : qsort.hs:3:24-38
1327 -12 : qsort.hs:3:23-55
1328 -13 : qsort.hs:(1,0)-(3,55)
1329 -14 : qsort.hs:2:15-24
1330 -15 : qsort.hs:2:15-46
1331 -16 : qsort.hs:(1,0)-(3,55)
1332 &lt;end of history&gt;
1333 </screen>
1334
1335       <para>To examine one of the steps in the history, use
1336         <literal>:back</literal>:</para>
1337
1338 <screen>
1339 [qsort.hs:1:11-12] *Main> :back
1340 Logged breakpoint at qsort.hs:3:24-38
1341 _result :: [a]
1342 as :: [a]
1343 a :: a
1344 [-1: qsort.hs:3:24-38] *Main>
1345 </screen>
1346
1347       <para>Note that the local variables at each step in the history have been
1348         preserved, and can be examined as usual.  Also note that the prompt has
1349         changed to indicate that we're currently examining the first step in
1350         the history: <literal>-1</literal>.  The command
1351         <literal>:forward</literal> can be used to traverse forward in the
1352         history.</para>
1353
1354       <para>The <literal>:trace</literal> command can be used with or without
1355         an expression.  When used without an expression, tracing begins from
1356         the current breakpoint, just like <literal>:step</literal>.</para>
1357
1358       <para>The history is only available when
1359         using <literal>:trace</literal>; the reason for this is we found that
1360         logging each breakpoint in the history cuts performance by a factor of
1361         2 or more.  GHCi remembers the last 50 steps in the history (perhaps in
1362         the future we'll make this configurable).</para>
1363     </sect2>
1364
1365     <sect2 id="ghci-debugger-exceptions">
1366       <title>Debugging exceptions</title>
1367       <para>Another common question that comes up when debugging is
1368         &ldquo;where did this exception come from?&rdquo;.  Exceptions such as
1369         those raised by <literal>error</literal> or <literal>head []</literal>
1370         have no context information attached to them.  Finding which
1371         particular call to <literal>head</literal> in your program resulted in
1372         the error can be a painstaking process, usually involving
1373         <literal>Debug.Trace.trace</literal>, or compiling with
1374         profiling and using <literal>+RTS -xc</literal> (see <xref
1375           linkend="prof-time-options" />).</para>
1376
1377       <para>The GHCi debugger offers a way to hopefully shed some light on
1378         these errors quickly and without modifying or recompiling the source
1379         code.  One way would be to set a breakpoint on the location in the
1380         source code that throws the exception, and then use
1381         <literal>:trace</literal> and <literal>:history</literal> to establish
1382         the context.  However, <literal>head</literal> is in a library and
1383         we can't set a breakpoint on it directly.  For this reason, GHCi
1384         provides the flag <literal>-fbreak-on-exception</literal> which causes
1385         the evaluator to stop when an exception is thrown, just as it does when
1386         a breakpoint is hit.  This is only really useful in conjunction with
1387         <literal>:trace</literal>, in order to log the steps leading up to the
1388         exception.  For example:</para>
1389
1390 <screen>
1391 *Main> :set -fbreak-on-exception
1392 *Main> :trace qsort ("abc" ++ undefined)
1393 "Stopped at &lt;exception thrown&gt;
1394 _exception :: e
1395 [&lt;exception thrown&gt;] *Main&gt; :hist
1396 -1  : qsort.hs:3:24-38
1397 -2  : qsort.hs:3:23-55
1398 -3  : qsort.hs:(1,0)-(3,55)
1399 -4  : qsort.hs:2:15-24
1400 -5  : qsort.hs:2:15-46
1401 -6  : qsort.hs:(1,0)-(3,55)
1402 &lt;end of history&gt;
1403 [&lt;exception thrown&gt;] *Main&gt; :back
1404 Logged breakpoint at qsort.hs:3:24-38
1405 _result :: [a]
1406 as :: [a]
1407 a :: a
1408 [-1: qsort.hs:3:24-38] *Main&gt; :force as
1409 *** Exception: Prelude.undefined
1410 [-1: qsort.hs:3:24-38] *Main&gt; :print as
1411 as = 'b' : 'c' : (_t1::[Char])
1412 </screen>
1413
1414       <para>The exception itself is bound to a new variable,
1415         <literal>_exception</literal>.</para>
1416
1417       <para>Breaking on exceptions is particularly useful for finding out what
1418         your program was doing when it was in an infinite loop.  Just hit
1419         Control-C, and examine the history to find out what was going
1420         on.</para>
1421     </sect2>
1422
1423     <sect2><title>Example: inspecting functions</title>
1424       <para>
1425         It is possible to use the debugger to examine function values.
1426         When we are at a breakpoint and a function is in scope, the debugger
1427         cannot show
1428         you the source code for it; however, it is possible to get some
1429         information by applying it to some arguments and  observing the result.
1430       </para>
1431
1432       <para>
1433         The process is slightly complicated when the binding is polymorphic.
1434         We show the process by means of an example.
1435         To keep things simple, we will use the well known <literal>map</literal> function:
1436 <programlisting>
1437 import Prelude hiding (map)
1438
1439 map :: (a->b) -> a -> b
1440 map f [] = []
1441 map f (x:xs) = f x : map f xs
1442 </programlisting>
1443       </para>
1444
1445       <para>
1446         We set a breakpoint on <literal>map</literal>, and call it.
1447 <screen>
1448 *Main> :break 5
1449 Breakpoint 0 activated at  map.hs:5:15-28
1450 *Main> map Just [1..5]
1451 Stopped at map.hs:(4,0)-(5,12)
1452 _result :: [b]
1453 x :: a
1454 f :: a -> b
1455 xs :: [a]
1456 </screen>
1457       GHCi tells us that, among other bindings, <literal>f</literal> is in scope.
1458       However, its type is not fully known yet,
1459       and thus it is not possible to apply it to any
1460       arguments. Nevertheless, observe that the type of its first argument is the
1461       same as the type of <literal>x</literal>, and its result type is shared
1462         with <literal>_result</literal>.
1463       </para>
1464
1465       <para>
1466         As we demonstrated earlier (<xref linkend="breakpoints" />),  the
1467         debugger has some intelligence built-in to update the type of
1468         <literal>f</literal> whenever the types of <literal>x</literal> or
1469         <literal>_result</literal> are discovered.  So what we do in this
1470         scenario is
1471         force <literal>x</literal> a bit, in order to recover both its type
1472       and the argument part of <literal>f</literal>.
1473 <screen>
1474 *Main> seq x ()
1475 *Main> :print x
1476 x = 1
1477 </screen>
1478       </para>
1479       <para>
1480         We can check now that as expected, the type of <literal>x</literal>
1481         has been reconstructed, and with it the
1482         type of <literal>f</literal> has been too:</para>
1483 <screen>
1484 *Main> :t x
1485 x :: Integer
1486 *Main> :t f
1487 f :: Integer -> b
1488 </screen>
1489       <para>
1490         From here, we can apply f to any argument of type Integer and observe
1491         the results.
1492 <screen><![CDATA[
1493 *Main> let b = f 10
1494 *Main> :t b
1495 b :: b
1496 *Main> b
1497 <interactive>:1:0:
1498     Ambiguous type variable `b' in the constraint:
1499       `Show b' arising from a use of `print' at <interactive>:1:0
1500 *Main> :p b
1501 b = (_t2::a)
1502 *Main> seq b ()
1503 ()
1504 *Main> :t b
1505 b :: a
1506 *Main> :p b
1507 b = Just 10
1508 *Main> :t b
1509 b :: Maybe Integer
1510 *Main> :t f
1511 f :: Integer -> Maybe Integer
1512 *Main> f 20
1513 Just 20
1514 *Main> map f [1..5]
1515 [Just 1, Just 2, Just 3, Just 4, Just 5]
1516 ]]></screen>
1517       In the first application of <literal>f</literal>, we had to do
1518       some more type reconstruction
1519       in order to recover the result type of <literal>f</literal>.
1520       But after that, we are free to use
1521       <literal>f</literal> normally.
1522      </para>
1523     </sect2>
1524
1525     <sect2><title>Limitations</title>
1526       <itemizedlist>
1527         <listitem>
1528           <para>When stopped at a breakpoint, if you try to evaluate a variable
1529             that is already under evaluation, the second evaluation will hang.
1530             The reason is
1531             that GHC knows the variable is under evaluation, so the new
1532             evaluation just waits for the result before continuing, but of
1533             course this isn't going to happen because the first evaluation is
1534             stopped at a breakpoint. Control-C can interrupt the hung
1535             evaluation and return to the prompt.</para>
1536           <para>The most common way this can happen is when you're evaluating a
1537             CAF (e.g. main), stop at a breakpoint, and ask for the value of the
1538             CAF at the prompt again.</para>
1539         </listitem>
1540         <listitem><para>
1541           Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available
1542           at the scope of a breakpoint if there is a explicit type signature.
1543         </para>
1544         </listitem>
1545       </itemizedlist>
1546     </sect2>
1547   </sect1>
1548
1549   <sect1 id="ghci-invocation">
1550     <title>Invoking GHCi</title>
1551     <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
1552     <indexterm><primary><option>&ndash;&ndash;interactive</option></primary></indexterm>
1553
1554     <para>GHCi is invoked with the command <literal>ghci</literal> or
1555     <literal>ghc &ndash;&ndash;interactive</literal>.  One or more modules or
1556     filenames can also be specified on the command line; this
1557     instructs GHCi to load the specified modules or filenames (and all
1558     the modules they depend on), just as if you had said
1559     <literal>:load <replaceable>modules</replaceable></literal> at the
1560     GHCi prompt (see <xref linkend="ghci-commands" />).  For example, to
1561     start GHCi and load the program whose topmost module is in the
1562     file <literal>Main.hs</literal>, we could say:</para>
1563
1564 <screen>
1565 $ ghci Main.hs
1566 </screen>
1567
1568     <para>Most of the command-line options accepted by GHC (see <xref
1569     linkend="using-ghc"/>) also make sense in interactive mode.  The ones
1570     that don't make sense are mostly obvious; for example, GHCi
1571     doesn't generate interface files, so options related to interface
1572     file generation won't have any effect.</para>
1573
1574     <sect2>
1575       <title>Packages</title>
1576       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
1577
1578       <para>Most packages (see <xref linkend="using-packages"/>) are
1579       available without needing to specify any extra flags at all:
1580       they will be automatically loaded the first time they are
1581       needed.</para>
1582
1583       <para>For hidden packages, however, you need to request the
1584       package be loaded by using the <literal>-package</literal> flag:</para>
1585
1586 <screen>
1587 $ ghci -package readline
1588    ___         ___ _
1589   / _ \ /\  /\/ __(_)
1590  / /_\// /_/ / /  | |      GHC Interactive, version 6.6, for Haskell 98.
1591 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
1592 \____/\/ /_/\____/|_|      Type :? for help.
1593
1594 Loading package base ... linking ... done.
1595 Loading package readline-1.0 ... linking ... done.
1596 Prelude>
1597 </screen>
1598
1599       <para>The following command works to load new packages into a
1600       running GHCi:</para>
1601
1602 <screen>
1603 Prelude> :set -package <replaceable>name</replaceable>
1604 </screen>
1605
1606       <para>But note that doing this will cause all currently loaded
1607       modules to be unloaded, and you'll be dumped back into the
1608       <literal>Prelude</literal>.</para>
1609     </sect2>
1610
1611     <sect2>
1612       <title>Extra libraries</title>
1613       <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
1614
1615       <para>Extra libraries may be specified on the command line using
1616       the normal <literal>-l<replaceable>lib</replaceable></literal>
1617       option.  (The term <emphasis>library</emphasis> here refers to
1618       libraries of foreign object code; for using libraries of Haskell
1619       source code, see <xref linkend="ghci-modules-filenames"/>.) For
1620       example, to load the &ldquo;m&rdquo; library:</para>
1621
1622 <screen>
1623 $ ghci -lm
1624 </screen>
1625
1626       <para>On systems with <literal>.so</literal>-style shared
1627       libraries, the actual library loaded will the
1628       <filename>lib<replaceable>lib</replaceable>.so</filename>.  GHCi
1629       searches the following places for libraries, in this order:</para>
1630
1631       <itemizedlist>
1632         <listitem>
1633           <para>Paths specified using the
1634           <literal>-L<replaceable>path</replaceable></literal>
1635           command-line option,</para>
1636         </listitem>
1637         <listitem>
1638           <para>the standard library search path for your system,
1639           which on some systems may be overridden by setting the
1640           <literal>LD_LIBRARY_PATH</literal> environment
1641           variable.</para>
1642         </listitem>
1643       </itemizedlist>
1644
1645       <para>On systems with <literal>.dll</literal>-style shared
1646       libraries, the actual library loaded will be
1647       <filename><replaceable>lib</replaceable>.dll</filename>.  Again,
1648       GHCi will signal an error if it can't find the library.</para>
1649
1650       <para>GHCi can also load plain object files
1651       (<literal>.o</literal> or <literal>.obj</literal> depending on
1652       your platform) from the command-line.  Just add the name the
1653       object file to the command line.</para>
1654
1655       <para>Ordering of <option>-l</option> options matters: a library
1656       should be mentioned <emphasis>before</emphasis> the libraries it
1657       depends on (see <xref linkend="options-linker"/>).</para>
1658     </sect2>
1659
1660   </sect1>
1661
1662   <sect1 id="ghci-commands">
1663     <title>GHCi commands</title>
1664
1665     <para>GHCi commands all begin with
1666     &lsquo;<literal>:</literal>&rsquo; and consist of a single command
1667     name followed by zero or more parameters.  The command name may be
1668     abbreviated, with ambiguities being resolved in favour of the more
1669     commonly used commands.</para>
1670
1671     <variablelist>
1672       <varlistentry>
1673         <term>
1674           <literal>:abandon</literal>
1675           <indexterm><primary><literal>:abandon</literal></primary></indexterm>
1676         </term>
1677         <listitem>
1678           <para>Abandons the current evaluation (only available when stopped at
1679           a breakpoint).</para>
1680         </listitem>
1681       </varlistentry>
1682
1683       <varlistentry>
1684         <term>
1685           <literal>:add</literal> <replaceable>module</replaceable> ...
1686           <indexterm><primary><literal>:add</literal></primary></indexterm>
1687         </term>
1688         <listitem>
1689           <para>Add <replaceable>module</replaceable>(s) to the
1690           current <firstterm>target set</firstterm>, and perform a
1691           reload.</para>
1692         </listitem>
1693       </varlistentry>
1694
1695       <varlistentry>
1696         <term>
1697           <literal>:back</literal>
1698           <indexterm><primary><literal>:back</literal></primary></indexterm>
1699         </term>
1700         <listitem>
1701           <para>Travel back one step in the history.  See <xref
1702               linkend="tracing" />.  See also:
1703             <literal>:trace</literal>, <literal>:history</literal>,
1704             <literal>:forward</literal>.</para>
1705         </listitem>
1706       </varlistentry>
1707
1708       <varlistentry>
1709         <term>
1710           <literal>:break [<replaceable>identifier</replaceable> |
1711             [<replaceable>module</replaceable>] <replaceable>line</replaceable>
1712             [<replaceable>column</replaceable>]]</literal>
1713         </term>
1714           <indexterm><primary><literal>:break</literal></primary></indexterm>
1715         <listitem>
1716           <para>Set a breakpoint on the specified function or line and
1717               column.  See <xref linkend="setting-breakpoints" />.</para>
1718         </listitem>
1719       </varlistentry>
1720
1721       <varlistentry>
1722         <term>
1723           <literal>:browse</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
1724           <indexterm><primary><literal>:browse</literal></primary></indexterm>
1725         </term>
1726         <listitem>
1727           <para>Displays the identifiers defined by the module
1728           <replaceable>module</replaceable>, which must be either
1729           loaded into GHCi or be a member of a package.  If the
1730           <literal>*</literal> symbol is placed before the module
1731           name, then <emphasis>all</emphasis> the identifiers defined
1732           in <replaceable>module</replaceable> are shown; otherwise
1733           the list is limited to the exports of
1734           <replaceable>module</replaceable>.  The
1735           <literal>*</literal>-form is only available for modules
1736           which are interpreted; for compiled modules (including
1737           modules from packages) only the non-<literal>*</literal>
1738           form of <literal>:browse</literal> is available.</para>
1739         </listitem>
1740       </varlistentry>
1741
1742       <varlistentry>
1743         <term>
1744           <literal>:cd</literal> <replaceable>dir</replaceable>
1745           <indexterm><primary><literal>:cd</literal></primary></indexterm>
1746         </term>
1747         <listitem>
1748           <para>Changes the current working directory to
1749           <replaceable>dir</replaceable>.  A
1750           &lsquo;<literal>&tilde;</literal>&rsquo; symbol at the
1751           beginning of <replaceable>dir</replaceable> will be replaced
1752           by the contents of the environment variable
1753           <literal>HOME</literal>.</para>
1754
1755           <para>NOTE: changing directories causes all currently loaded
1756           modules to be unloaded.  This is because the search path is
1757           usually expressed using relative directories, and changing
1758           the search path in the middle of a session is not
1759           supported.</para>
1760         </listitem>
1761       </varlistentry>
1762
1763       <varlistentry>
1764         <term>
1765           <literal>:continue</literal>
1766           <indexterm><primary><literal>:continue</literal></primary></indexterm>
1767         </term>
1768         <listitem><para>Continue the current evaluation, when stopped at a
1769             breakpoint.</para>
1770         </listitem>
1771       </varlistentry>
1772
1773       <varlistentry>
1774         <term>
1775           <literal>:cmd</literal> <replaceable>expr</replaceable>
1776           <indexterm><primary><literal>:cmd</literal></primary></indexterm>
1777         </term>
1778         <listitem>
1779           <para>Executes <replaceable>expr</replaceable> as a computation of
1780             type <literal>IO String</literal>, and then executes the resulting
1781             string as a list of GHCi commands.  Multiple commands are separated
1782             by newlines.  The <literal>:cmd</literal> command is useful with
1783             <literal>:def</literal> and <literal>:set stop</literal>.</para>
1784         </listitem>
1785       </varlistentry>
1786
1787       <varlistentry>
1788         <term>
1789           <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional>
1790           <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional>
1791           <indexterm><primary><literal>:etags</literal></primary>
1792           </indexterm>
1793           <indexterm><primary><literal>:etags</literal></primary>
1794           </indexterm>
1795         </term>
1796         <listitem>
1797           <para>Generates a &ldquo;tags&rdquo; file for Vi-style editors
1798             (<literal>:ctags</literal>) or Emacs-style editors (<literal>etags</literal>).  If
1799             no filename is specified, the defaulit <filename>tags</filename> or
1800             <filename>TAGS</filename> is
1801             used, respectively.  Tags for all the functions, constructors and
1802             types in the currently loaded modules are created.  All modules must
1803             be interpreted for these commands to work.</para>
1804           <para>See also <xref linkend="hasktags" />.</para>
1805         </listitem>
1806       </varlistentry>
1807
1808       <varlistentry>
1809         <term>
1810           <literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable>
1811           <indexterm><primary><literal>:def</literal></primary></indexterm>
1812         </term>
1813         <listitem>
1814           <para>The command <literal>:def</literal>
1815           <replaceable>name</replaceable>
1816           <replaceable>expr</replaceable> defines a new GHCi command
1817           <literal>:<replaceable>name</replaceable></literal>,
1818           implemented by the Haskell expression
1819           <replaceable>expr</replaceable>, which must have type
1820           <literal>String -> IO String</literal>.  When
1821           <literal>:<replaceable>name</replaceable>
1822           <replaceable>args</replaceable></literal> is typed at the
1823           prompt, GHCi will run the expression
1824           <literal>(<replaceable>name</replaceable>
1825           <replaceable>args</replaceable>)</literal>, take the
1826           resulting <literal>String</literal>, and feed it back into
1827           GHCi as a new sequence of commands.  Separate commands in
1828           the result must be separated by
1829           &lsquo;<literal>\n</literal>&rsquo;.</para>
1830
1831           <para>That's all a little confusing, so here's a few
1832           examples.  To start with, here's a new GHCi command which
1833           doesn't take any arguments or produce any results, it just
1834           outputs the current date &amp; time:</para>
1835
1836 <screen>
1837 Prelude> let date _ = Time.getClockTime >>= print >> return ""
1838 Prelude> :def date date
1839 Prelude> :date
1840 Fri Mar 23 15:16:40 GMT 2001
1841 </screen>
1842
1843           <para>Here's an example of a command that takes an argument.
1844           It's a re-implementation of <literal>:cd</literal>:</para>
1845
1846 <screen>
1847 Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
1848 Prelude> :def mycd mycd
1849 Prelude> :mycd ..
1850 </screen>
1851
1852           <para>Or I could define a simple way to invoke
1853           &ldquo;<literal>ghc &ndash;&ndash;make Main</literal>&rdquo; in the
1854           current directory:</para>
1855
1856 <screen>
1857 Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")
1858 </screen>
1859
1860           <para>We can define a command that reads GHCi input from a
1861           file.  This might be useful for creating a set of bindings
1862           that we want to repeatedly load into the GHCi session:</para>
1863
1864 <screen>
1865 Prelude> :def . readFile
1866 Prelude> :. cmds.ghci
1867 </screen>
1868
1869           <para>Notice that we named the command
1870           <literal>:.</literal>, by analogy with the
1871           &lsquo;<literal>.</literal>&rsquo; Unix shell command that
1872           does the same thing.</para>
1873         </listitem>
1874       </varlistentry>
1875
1876       <varlistentry>
1877         <term>
1878           <literal>:delete * | <replaceable>num</replaceable> ...</literal>
1879           <indexterm><primary><literal>:delete</literal></primary></indexterm>
1880         </term>
1881         <listitem>
1882           <para>Delete one or more breakpoints by number (use <literal>:show
1883               breaks</literal> to see the number of each breakpoint).  The
1884             <literal>*</literal> form deletes all the breakpoints.</para>
1885         </listitem>
1886       </varlistentry>
1887
1888       <varlistentry>
1889         <term>
1890           <literal>:edit <optional><replaceable>file</replaceable></optional></literal>
1891           <indexterm><primary><literal>:edit</literal></primary></indexterm>
1892         </term>
1893         <listitem>
1894           <para>Opens an editor to edit the file
1895           <replaceable>file</replaceable>, or the most recently loaded
1896           module if <replaceable>file</replaceable> is omitted.  The
1897           editor to invoke is taken from the <literal>EDITOR</literal>
1898           environment variable, or a default editor on your system if
1899           <literal>EDITOR</literal> is not set.  You can change the
1900           editor using <literal>:set editor</literal>.</para>
1901         </listitem>
1902       </varlistentry>
1903
1904       <varlistentry>
1905         <term>
1906           <literal>:force <replaceable>identifier</replaceable> ...</literal>
1907           <indexterm><primary><literal>:force</literal></primary></indexterm>
1908         </term>
1909         <listitem>
1910           <para>Prints the value of <replaceable>identifier</replaceable> in
1911             the same way as <literal>:print</literal>.   Unlike
1912             <literal>:print</literal>, <literal>:force</literal> evaluates each
1913             thunk that it encounters while traversing the value.  This may
1914             cause exceptions or infinite loops, or further breakpoints (which
1915             are ignored, but displayed).</para>
1916         </listitem>
1917       </varlistentry>
1918
1919       <varlistentry>
1920         <term>
1921           <literal>:forward</literal>
1922           <indexterm><primary><literal>:forward</literal></primary></indexterm>
1923         </term>
1924         <listitem>
1925           <para>Move forward in the history.   See <xref
1926               linkend="tracing" />.  See also:
1927             <literal>:trace</literal>, <literal>:history</literal>,
1928             <literal>:back</literal>.</para>
1929         </listitem>
1930       </varlistentry>
1931
1932       <varlistentry>
1933         <term>
1934           <literal>:help</literal>
1935           <indexterm><primary><literal>:help</literal></primary></indexterm>
1936         </term>
1937         <term>
1938           <literal>:?</literal>
1939           <indexterm><primary><literal>:?</literal></primary></indexterm>
1940         </term>
1941         <listitem>
1942           <para>Displays a list of the available commands.</para>
1943         </listitem>
1944       </varlistentry>
1945
1946       <varlistentry>
1947         <term>
1948           <literal>:history [<replaceable>num</replaceable>]</literal>
1949           <indexterm><primary><literal>:history</literal></primary></indexterm>
1950         </term>
1951         <listitem>
1952           <para>Display the history of evaluation steps.  With a number,
1953             displays that many steps (default: 20).  For use with
1954             <literal>:trace</literal>; see <xref
1955               linkend="tracing" />.</para>
1956         </listitem>
1957       </varlistentry>
1958
1959       <varlistentry>
1960         <term>
1961           <literal>:info</literal> <replaceable>name</replaceable> ...
1962           <indexterm><primary><literal>:info</literal></primary></indexterm>
1963         </term>
1964         <listitem>
1965           <para>Displays information about the given name(s).  For
1966           example, if <replaceable>name</replaceable> is a class, then
1967           the class methods and their types will be printed;  if
1968           <replaceable>name</replaceable> is a type constructor, then
1969           its definition will be printed;  if
1970           <replaceable>name</replaceable> is a function, then its type
1971           will be printed.  If <replaceable>name</replaceable> has
1972           been loaded from a source file, then GHCi will also display
1973           the location of its definition in the source.</para>
1974         </listitem>
1975       </varlistentry>
1976
1977       <varlistentry>
1978         <term>
1979           <literal>:kind</literal> <replaceable>type</replaceable>
1980           <indexterm><primary><literal>:kind</literal></primary></indexterm>
1981         </term>
1982         <listitem>
1983           <para>Infers and prints the kind of
1984           <replaceable>type</replaceable>. The latter can be an arbitrary
1985             type expression, including a partial application of a type constructor,
1986             such as <literal>Either Int</literal>.</para>
1987         </listitem>
1988       </varlistentry>
1989
1990       <varlistentry>
1991         <term>
1992           <literal>:load</literal> <replaceable>module</replaceable> ...
1993           <indexterm><primary><literal>:load</literal></primary></indexterm>
1994         </term>
1995         <listitem>
1996           <para>Recursively loads the specified
1997           <replaceable>module</replaceable>s, and all the modules they
1998           depend on.  Here, each <replaceable>module</replaceable>
1999           must be a module name or filename, but may not be the name
2000           of a module in a package.</para>
2001
2002           <para>All previously loaded modules, except package modules,
2003           are forgotten.  The new set of modules is known as the
2004           <firstterm>target set</firstterm>.  Note that
2005           <literal>:load</literal> can be used without any arguments
2006           to unload all the currently loaded modules and
2007           bindings.</para>
2008
2009           <para>After a <literal>:load</literal> command, the current
2010           context is set to:</para>
2011
2012           <itemizedlist>
2013             <listitem>
2014               <para><replaceable>module</replaceable>, if it was loaded
2015               successfully, or</para>
2016             </listitem>
2017             <listitem>
2018               <para>the most recently successfully loaded module, if
2019               any other modules were loaded as a result of the current
2020               <literal>:load</literal>, or</para>
2021             </listitem>
2022             <listitem>
2023               <para><literal>Prelude</literal> otherwise.</para>
2024             </listitem>
2025           </itemizedlist>
2026         </listitem>
2027       </varlistentry>
2028
2029       <varlistentry>
2030         <term>
2031           <literal>:main <replaceable>arg<subscript>1</subscript></replaceable> ... <replaceable>arg<subscript>n</subscript></replaceable></literal>
2032           <indexterm><primary><literal>:main</literal></primary></indexterm>
2033         </term>
2034         <listitem>
2035           <para>
2036             When a program is compiled and executed, it can use the
2037             <literal>getArgs</literal> function to access the
2038             command-line arguments.
2039             However, we cannot simply pass the arguments to the
2040             <literal>main</literal> function while we are testing in ghci,
2041             as the <literal>main</literal> function doesn't take its
2042             directly.
2043           </para>
2044
2045           <para>
2046             Instead, we can use the <literal>:main</literal> command.
2047             This runs whatever <literal>main</literal> is in scope, with
2048             any arguments being treated the same as command-line arguments,
2049             e.g.:
2050           </para>
2051
2052 <screen>
2053 Prelude> let main = System.Environment.getArgs >>= print
2054 Prelude> :main foo bar
2055 ["foo","bar"]
2056 </screen>
2057
2058         </listitem>
2059       </varlistentry>
2060
2061       <varlistentry>
2062         <term>
2063           <literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal>
2064           <indexterm><primary><literal>:module</literal></primary></indexterm>
2065         </term>
2066         <term>
2067           <literal>import <replaceable>mod</replaceable></literal>
2068         </term>
2069         <listitem>
2070           <para>Sets or modifies the current context for statements
2071           typed at the prompt.  The form <literal>import
2072           <replaceable>mod</replaceable></literal> is equivalent to
2073           <literal>:module +<replaceable>mod</replaceable></literal>.
2074           See <xref linkend="ghci-scope"/> for
2075           more details.</para>
2076         </listitem>
2077       </varlistentry>
2078
2079       <varlistentry>
2080         <term>
2081           <literal>:print </literal> <replaceable>names</replaceable> ...
2082           <indexterm><primary><literal>:print</literal></primary></indexterm>
2083         </term>
2084         <listitem>
2085           <para>Prints a value without forcing its evaluation.
2086             <literal>:print</literal> may be used on values whose types are
2087             unkonwn or partially known, which might be the case for local
2088             variables with polymorphic types at a breakpoint.  While inspecting
2089             the runtime value, <literal>:print</literal> attempts to
2090             reconstruct the type of the value, and will elaborate the type in
2091             GHCi's environment if possible.  If any unevaluated components
2092             (thunks) are encountered, then <literal>:print</literal> binds
2093             a fresh variable with a name beginning with <literal>_t</literal>
2094             to each thunk.  See <xref linkend="breakpoints" /> for more
2095             information.  See also the <literal>:sprint</literal> command,
2096             which works like <literal>:print</literal> but does not bind new
2097             variables.</para>
2098         </listitem>
2099       </varlistentry>
2100
2101       <varlistentry>
2102         <term>
2103           <literal>:quit</literal>
2104           <indexterm><primary><literal>:quit</literal></primary></indexterm>
2105         </term>
2106         <listitem>
2107           <para>Quits GHCi.  You can also quit by typing a control-D
2108           at the prompt.</para>
2109         </listitem>
2110       </varlistentry>
2111
2112       <varlistentry>
2113         <term>
2114           <literal>:reload</literal>
2115           <indexterm><primary><literal>:reload</literal></primary></indexterm>
2116         </term>
2117         <listitem>
2118           <para>Attempts to reload the current target set (see
2119           <literal>:load</literal>) if any of the modules in the set,
2120           or any dependent module, has changed.  Note that this may
2121           entail loading new modules, or dropping modules which are no
2122           longer indirectly required by the target.</para>
2123         </listitem>
2124       </varlistentry>
2125
2126       <varlistentry>
2127         <term>
2128           <literal>:set</literal> <optional><replaceable>option</replaceable>...</optional>
2129           <indexterm><primary><literal>:set</literal></primary></indexterm>
2130         </term>
2131         <listitem>
2132           <para>Sets various options.  See <xref linkend="ghci-set"/>
2133           for a list of available options.  The
2134           <literal>:set</literal> command by itself shows which
2135           options are currently set.</para>
2136         </listitem>
2137       </varlistentry>
2138
2139       <varlistentry>
2140         <term>
2141           <literal>:set</literal> <literal>args</literal> <replaceable>arg</replaceable> ...
2142           <indexterm><primary><literal>:set args</literal></primary></indexterm>
2143         </term>
2144         <listitem>
2145           <para>Sets the list of arguments which are returned when the
2146           program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary>
2147             </indexterm>.</para>
2148         </listitem>
2149       </varlistentry>
2150
2151       <varlistentry>
2152         <term>
2153            <literal>:set</literal> <literal>editor</literal> <replaceable>cmd</replaceable>
2154         </term>
2155         <listitem>
2156           <para>Sets the command used by <literal>:edit</literal> to
2157           <replaceable>cmd</replaceable>.</para>
2158         </listitem>
2159       </varlistentry>
2160
2161       <varlistentry>
2162         <term>
2163            <literal>:set</literal> <literal>prog</literal> <replaceable>prog</replaceable>
2164            <indexterm><primary><literal>:set prog</literal></primary></indexterm>
2165         </term>
2166         <listitem>
2167           <para>Sets the string to be returned when the program calls
2168           <literal>System.getProgName</literal><indexterm><primary>getProgName</primary>
2169             </indexterm>.</para>
2170         </listitem>
2171       </varlistentry>
2172
2173       <varlistentry>
2174         <term>
2175            <literal>:set</literal> <literal>prompt</literal> <replaceable>prompt</replaceable>
2176         </term>
2177         <listitem>
2178           <para>Sets the string to be used as the prompt in GHCi.
2179           Inside <replaceable>prompt</replaceable>, the sequence
2180           <literal>%s</literal> is replaced by the names of the
2181           modules currently in scope, and <literal>%%</literal> is
2182           replaced by <literal>%</literal>.</para>
2183         </listitem>
2184       </varlistentry>
2185
2186       <varlistentry>
2187         <term>
2188            <literal>:set</literal> <literal>stop</literal>
2189           [<replaceable>num</replaceable>] <replaceable>cmd</replaceable>
2190         </term>
2191         <listitem>
2192           <para>Set a command to be executed when a breakpoint is hit, or a new
2193           item in the history is selected.  The most common use of
2194             <literal>:set stop</literal> is to display the source code at the
2195             current location, e.g. <literal>:set stop :list</literal>.</para>
2196
2197           <para>If a number is given before the command, then the commands are
2198             run when the specified breakpoint (only) is hit.  This can be quite
2199             useful: for example, <literal>:set stop 1 :continue</literal>
2200             effectively disables breakpoint 1, by running
2201             <literal>:continue</literal> whenever it is hit (although GHCi will
2202             still emit a message to say the breakpoint was hit).  What's more,
2203             with cunning use of <literal>:def</literal> and
2204             <literal>:cmd</literal> you can use <literal>:set stop</literal> to
2205             implement conditional breakpoints:</para>
2206 <screen>
2207 *Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
2208 *Main> :set stop 0 :cond (x &lt; 3)
2209 </screen>
2210           <para>Ignoring breakpoints for a specified number of iterations is
2211             also possible using similar techniques.</para>
2212         </listitem>
2213       </varlistentry>
2214
2215       <varlistentry>
2216         <term>
2217           <literal>:show bindings</literal>
2218           <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
2219         </term>
2220         <listitem>
2221           <para>Show the bindings made at the prompt and their
2222           types.</para>
2223         </listitem>
2224       </varlistentry>
2225
2226       <varlistentry>
2227         <term>
2228           <literal>:show breaks</literal>
2229           <indexterm><primary><literal>:show breaks</literal></primary></indexterm>
2230         </term>
2231         <listitem>
2232           <para>List the active breakpoints.</para>
2233         </listitem>
2234       </varlistentry>
2235
2236       <varlistentry>
2237         <term>
2238           <literal>:show context</literal>
2239           <indexterm><primary><literal>:show context</literal></primary></indexterm>
2240         </term>
2241         <listitem>
2242           <para>List the active evaluations that are stopped at breakpoints.</para>
2243         </listitem>
2244       </varlistentry>
2245
2246       <varlistentry>
2247         <term>
2248           <literal>:show modules</literal>
2249           <indexterm><primary><literal>:show modules</literal></primary></indexterm>
2250         </term>
2251         <listitem>
2252           <para>Show the list of modules currently load.</para>
2253         </listitem>
2254       </varlistentry>
2255
2256       <varlistentry>
2257         <term>
2258           <literal>:show [args|prog|prompt|editor|stop]</literal>
2259           <indexterm><primary><literal>:show</literal></primary></indexterm>
2260         </term>
2261         <listitem>
2262           <para>Displays the specified setting (see
2263             <literal>:set</literal>).</para>
2264         </listitem>
2265       </varlistentry>
2266
2267       <varlistentry>
2268         <term>
2269           <literal>:sprint</literal>
2270           <indexterm><primary><literal>:sprint</literal></primary></indexterm>
2271         </term>
2272         <listitem>
2273           <para>Prints a value without forcing its evaluation.
2274             <literal>:sprint</literal> is similar to <literal>:print</literal>,
2275             with the difference that unevaluated subterms are not bound to new
2276             variables, they are simply denoted by &lsquo;_&rsquo;.</para>
2277         </listitem>
2278       </varlistentry>
2279
2280       <varlistentry>
2281         <term>
2282           <literal>:step [<replaceable>expr</replaceable>]</literal>
2283           <indexterm><primary><literal>:step</literal></primary></indexterm>
2284         </term>
2285         <listitem>
2286           <para>Single-step from the last breakpoint.  With an expression
2287             argument, begins evaluation of the expression with a
2288             single-step.</para>
2289         </listitem>
2290       </varlistentry>
2291
2292       <varlistentry>
2293         <term>
2294           <literal>:trace [<replaceable>expr</replaceable>]</literal>
2295           <indexterm><primary><literal>:trace</literal></primary></indexterm>
2296         </term>
2297         <listitem>
2298           <para>Evaluates the given expression (or from the last breakpoint if
2299             no expression is given), and additionally logs the evaluation
2300             steps for later inspection using <literal>:history</literal>.  See
2301             <xref linkend="tracing" />.</para>
2302         </listitem>
2303       </varlistentry>
2304
2305       <varlistentry>
2306         <term>
2307          <literal>:type</literal> <replaceable>expression</replaceable>
2308          <indexterm><primary><literal>:type</literal></primary></indexterm>
2309         </term>
2310         <listitem>
2311           <para>Infers and prints the type of
2312           <replaceable>expression</replaceable>, including explicit
2313           forall quantifiers for polymorphic types.  The monomorphism
2314           restriction is <emphasis>not</emphasis> applied to the
2315           expression during type inference.</para>
2316         </listitem>
2317       </varlistentry>
2318
2319       <varlistentry>
2320         <term>
2321           <literal>:undef</literal> <replaceable>name</replaceable>
2322           <indexterm><primary><literal>:undef</literal></primary></indexterm>
2323         </term>
2324         <listitem>
2325           <para>Undefines the user-defined command
2326           <replaceable>name</replaceable> (see <literal>:def</literal>
2327           above).</para>
2328         </listitem>
2329       </varlistentry>
2330
2331       <varlistentry>
2332         <term>
2333           <literal>:unset</literal> <replaceable>option</replaceable>...
2334           <indexterm><primary><literal>:unset</literal></primary></indexterm>
2335         </term>
2336         <listitem>
2337           <para>Unsets certain options.  See <xref linkend="ghci-set"/>
2338           for a list of available options.</para>
2339         </listitem>
2340       </varlistentry>
2341
2342       <varlistentry>
2343         <term>
2344           <literal>:!</literal> <replaceable>command</replaceable>...
2345           <indexterm><primary><literal>:!</literal></primary></indexterm>
2346           <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm>
2347         </term>
2348         <listitem>
2349           <para>Executes the shell command
2350           <replaceable>command</replaceable>.</para>
2351         </listitem>
2352       </varlistentry>
2353
2354     </variablelist>
2355   </sect1>
2356
2357   <sect1 id="ghci-set">
2358     <title>The <literal>:set</literal> command</title>
2359     <indexterm><primary><literal>:set</literal></primary></indexterm>
2360
2361     <para>The <literal>:set</literal> command sets two types of
2362     options: GHCi options, which begin with
2363     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
2364     options, which begin with &lsquo;-&rsquo;.  </para>
2365
2366     <para>NOTE: at the moment, the <literal>:set</literal> command
2367     doesn't support any kind of quoting in its arguments: quotes will
2368     not be removed and cannot be used to group words together.  For
2369     example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what
2370     you expect.</para>
2371
2372     <sect2>
2373       <title>GHCi options</title>
2374       <indexterm><primary>options</primary><secondary>GHCi</secondary>
2375       </indexterm>
2376
2377       <para>GHCi options may be set using <literal>:set</literal> and
2378       unset using <literal>:unset</literal>.</para>
2379
2380       <para>The available GHCi options are:</para>
2381
2382       <variablelist>
2383         <varlistentry>
2384           <term>
2385             <literal>+r</literal>
2386             <indexterm><primary><literal>+r</literal></primary></indexterm>
2387             <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
2388             <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm>
2389           </term>
2390           <listitem>
2391             <para>Normally, any evaluation of top-level expressions
2392             (otherwise known as CAFs or Constant Applicative Forms) in
2393             loaded modules is retained between evaluations.  Turning
2394             on <literal>+r</literal> causes all evaluation of
2395             top-level expressions to be discarded after each
2396             evaluation (they are still retained
2397             <emphasis>during</emphasis> a single evaluation).</para>
2398
2399             <para>This option may help if the evaluated top-level
2400             expressions are consuming large amounts of space, or if
2401             you need repeatable performance measurements.</para>
2402           </listitem>
2403         </varlistentry>
2404
2405         <varlistentry>
2406           <term>
2407             <literal>+s</literal>
2408             <indexterm><primary><literal>+s</literal></primary></indexterm>
2409           </term>
2410           <listitem>
2411             <para>Display some stats after evaluating each expression,
2412             including the elapsed time and number of bytes allocated.
2413             NOTE: the allocation figure is only accurate to the size
2414             of the storage manager's allocation area, because it is
2415             calculated at every GC.  Hence, you might see values of
2416             zero if no GC has occurred.</para>
2417           </listitem>
2418         </varlistentry>
2419
2420         <varlistentry>
2421           <term>
2422             <literal>+t</literal>
2423             <indexterm><primary><literal>+t</literal></primary></indexterm>
2424           </term>
2425           <listitem>
2426             <para>Display the type of each variable bound after a
2427             statement is entered at the prompt.  If the statement is a
2428             single expression, then the only variable binding will be
2429             for the variable
2430             &lsquo;<literal>it</literal>&rsquo;.</para>
2431           </listitem>
2432         </varlistentry>
2433       </variablelist>
2434     </sect2>
2435
2436     <sect2 id="ghci-cmd-line-options">
2437       <title>Setting GHC command-line options in GHCi</title>
2438
2439       <para>Normal GHC command-line options may also be set using
2440       <literal>:set</literal>.  For example, to turn on
2441       <option>-fglasgow-exts</option>, you would say:</para>
2442
2443 <screen>
2444 Prelude> :set -fglasgow-exts
2445 </screen>
2446
2447       <para>Any GHC command-line option that is designated as
2448       <firstterm>dynamic</firstterm> (see the table in <xref
2449       linkend="flag-reference"/>), may be set using
2450       <literal>:set</literal>.  To unset an option, you can set the
2451       reverse option:</para>
2452       <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
2453
2454 <screen>
2455 Prelude> :set -fno-glasgow-exts
2456 </screen>
2457
2458       <para><xref linkend="flag-reference"/> lists the reverse for each
2459       option where applicable.</para>
2460
2461       <para>Certain static options (<option>-package</option>,
2462       <option>-I</option>, <option>-i</option>, and
2463       <option>-l</option> in particular) will also work, but some may
2464       not take effect until the next reload.</para>
2465       <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
2466     </sect2>
2467   </sect1>
2468   <sect1 id="ghci-dot-files">
2469     <title>The <filename>.ghci</filename> file</title>
2470     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
2471     </indexterm>
2472     <indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
2473     </indexterm>
2474
2475     <para>When it starts, GHCi always reads and executes commands from
2476     <filename>$HOME/.ghci</filename>, followed by
2477     <filename>./.ghci</filename>.</para>
2478
2479     <para>The <filename>.ghci</filename> in your home directory is
2480     most useful for turning on favourite options (eg. <literal>:set
2481     +s</literal>), and defining useful macros.  Placing a
2482     <filename>.ghci</filename> file in a directory with a Haskell
2483     project is a useful way to set certain project-wide options so you
2484     don't have to type them everytime you start GHCi: eg. if your
2485     project uses GHC extensions and CPP, and has source files in three
2486     subdirectories A B and C, you might put the following lines in
2487     <filename>.ghci</filename>:</para>
2488
2489 <screen>
2490 :set -fglasgow-exts -cpp
2491 :set -iA:B:C
2492 </screen>
2493
2494     <para>(Note that strictly speaking the <option>-i</option> flag is
2495     a static one, but in fact it works to set it using
2496     <literal>:set</literal> like this.  The changes won't take effect
2497     until the next <literal>:load</literal>, though.)</para>
2498
2499     <para>Two command-line options control whether the
2500     <filename>.ghci</filename> files are read:</para>
2501
2502     <variablelist>
2503       <varlistentry>
2504         <term>
2505           <option>-ignore-dot-ghci</option>
2506           <indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm>
2507         </term>
2508         <listitem>
2509           <para>Don't read either <filename>./.ghci</filename> or
2510           <filename>$HOME/.ghci</filename> when starting up.</para>
2511         </listitem>
2512       </varlistentry>
2513       <varlistentry>
2514         <term>
2515           <option>-read-dot-ghci</option>
2516           <indexterm><primary><option>-read-dot-ghci</option></primary></indexterm>
2517         </term>
2518         <listitem>
2519           <para>Read <filename>.ghci</filename> and
2520           <filename>$HOME/.ghci</filename>.  This is normally the
2521           default, but the <option>-read-dot-ghci</option> option may
2522           be used to override a previous
2523           <option>-ignore-dot-ghci</option> option.</para>
2524         </listitem>
2525       </varlistentry>
2526     </variablelist>
2527
2528   </sect1>
2529
2530   <sect1 id="ghci-obj">
2531     <title>Compiling to object code inside GHCi</title>
2532
2533     <para>By default, GHCi compiles Haskell source code into byte-code
2534     that is interpreted by the runtime system.  GHCi can also compile
2535     Haskell code to object code: to turn on this feature, use the
2536     <option>-fobject-code</option> flag either on the command line or
2537     with <literal>:set</literal> (the option
2538     <option>-fbyte-code</option> restores byte-code compilation
2539     again).  Compiling to object code takes longer, but typically the
2540     code will execute 10-20 times faster than byte-code.</para>
2541
2542     <para>Compiling to object code inside GHCi is particularly useful
2543     if you are developing a compiled application, because the
2544     <literal>:reload</literal> command typically runs much faster than
2545     restarting GHC with <option>--make</option> from the command-line,
2546     because all the interface files are already cached in
2547     memory.</para>
2548
2549     <para>There are disadvantages to compiling to object-code: you
2550     can't set breakpoints in object-code modules, for example.  Only
2551     the exports of an object-code module will be visible in GHCi,
2552     rather than all top-level bindings as in interpreted
2553     modules.</para>
2554   </sect1>
2555
2556   <sect1 id="ghci-faq">
2557     <title>FAQ and Things To Watch Out For</title>
2558
2559     <variablelist>
2560       <varlistentry>
2561         <term>The interpreter can't load modules with foreign export
2562         declarations!</term>
2563         <listitem>
2564           <para>Unfortunately not.  We haven't implemented it yet.
2565           Please compile any offending modules by hand before loading
2566           them into GHCi.</para>
2567         </listitem>
2568       </varlistentry>
2569
2570       <varlistentry>
2571         <term>
2572           <literal>-O</literal> doesn't work with GHCi!
2573           <indexterm><primary><option>-O</option></primary></indexterm>
2574          </term>
2575         <listitem>
2576           <para>For technical reasons, the bytecode compiler doesn't
2577           interact well with one of the optimisation passes, so we
2578           have disabled optimisation when using the interpreter.  This
2579           isn't a great loss: you'll get a much bigger win by
2580           compiling the bits of your code that need to go fast, rather
2581           than interpreting them with optimisation turned on.</para>
2582         </listitem>
2583       </varlistentry>
2584
2585       <varlistentry>
2586         <term>Unboxed tuples don't work with GHCi</term>
2587         <listitem>
2588           <para>That's right.  You can always compile a module that
2589           uses unboxed tuples and load it into GHCi, however.
2590           (Incidentally the previous point, namely that
2591           <literal>-O</literal> is incompatible with GHCi, is because
2592           the bytecode compiler can't deal with unboxed
2593           tuples).</para>
2594         </listitem>
2595       </varlistentry>
2596
2597       <varlistentry>
2598         <term>Concurrent threads don't carry on running when GHCi is
2599         waiting for input.</term>
2600         <listitem>
2601           <para>This should work, as long as your GHCi was built with
2602           the <option>-threaded</option> switch, which is the default.
2603           Consult whoever supplied your GHCi installation.</para>
2604         </listitem>
2605       </varlistentry>
2606
2607       <varlistentry>
2608         <term>After using <literal>getContents</literal>, I can't use
2609         <literal>stdin</literal> again until I do
2610         <literal>:load</literal> or <literal>:reload</literal>.</term>
2611
2612         <listitem>
2613           <para>This is the defined behaviour of
2614           <literal>getContents</literal>: it puts the stdin Handle in
2615           a state known as <firstterm>semi-closed</firstterm>, wherein
2616           any further I/O operations on it are forbidden.  Because I/O
2617           state is retained between computations, the semi-closed
2618           state persists until the next <literal>:load</literal> or
2619           <literal>:reload</literal> command.</para>
2620
2621           <para>You can make <literal>stdin</literal> reset itself
2622           after every evaluation by giving GHCi the command
2623           <literal>:set +r</literal>.  This works because
2624           <literal>stdin</literal> is just a top-level expression that
2625           can be reverted to its unevaluated state in the same way as
2626           any other top-level expression (CAF).</para>
2627         </listitem>
2628       </varlistentry>
2629
2630       <varlistentry>
2631         <term>I can't use Control-C to interrupt computations in
2632           GHCi on Windows.</term>
2633         <listitem>
2634           <para>See <xref linkend="ghci-windows"/></para>
2635         </listitem>
2636       </varlistentry>
2637     </variablelist>
2638   </sect1>
2639
2640 </chapter>
2641
2642 <!-- Emacs stuff:
2643      ;;; Local Variables: ***
2644      ;;; mode: xml ***
2645      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
2646      ;;; End: ***
2647  -->