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.</para>
  18   <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
  19   <indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
  20
  21   <sect1 id="ghci-introduction">
  22     <title>Introduction to GHCi</title>
  23
  24     <para>Let's start with an example GHCi session.  You can fire up
  25     GHCi with the command <literal>ghci</literal>:</para>
  26
  27 <screen>
  28 $ ghci
  29    ___         ___ _
  30   / _ \ /\  /\/ __(_)
  31  / /_\// /_/ / /  | |      GHC Interactive, version 6.6, for Haskell 98.
  32 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
  33 \____/\/ /_/\____/|_|      Type :? for help.
  34
  35 Loading package base ... linking ... done.
  36 Prelude>
  37 </screen>
  38
  39     <para>There may be a short pause while GHCi loads the prelude and
  40     standard libraries, after which the prompt is shown.  If we follow
  41     the instructions and type <literal>:?</literal> for help, we
  42     get:</para>
  43
  44 <screen>
  45  Commands available from the prompt:
  46
  47    &lt;stmt&gt;                      evaluate/run &lt;stmt&gt;
  48    :add &lt;filename&gt; ...         add module(s) to the current target set
  49    :browse [*]&lt;module&gt;         display the names defined by &lt;module&gt;
  50    :cd &lt;dir&gt;                   change directory to &lt;dir&gt;
  51    :def &lt;cmd&gt; &lt;expr&gt;           define a command :&lt;cmd&gt;
  52    :edit &lt;file&gt;                edit file
  53    :edit                       edit last module
  54    :help, :?                   display this list of commands
  55    :info [&lt;name&gt; ...]          display information about the given names
  56    :load &lt;filename&gt; ...        load module(s) and their dependents
  57    :module [+/-] [*]&lt;mod&gt; ...  set the context for expression evaluation
  58    :main [&lt;arguments&gt; ...]     run the main function with the given arguments
  59    :reload                     reload the current module set
  60
  61    :set &lt;option&gt; ...           set options
  62    :set args &lt;arg&gt; ...         set the arguments returned by System.getArgs
  63    :set prog &lt;progname&gt;        set the value returned by System.getProgName
  64    :set prompt &lt;prompt&gt;        set the prompt used in GHCi
  65    :set editor &lt;cmd&gt;        set the command used for :edit
  66
  67    :show modules               show the currently loaded modules
  68    :show bindings              show the current bindings made at the prompt
  69
  70    :ctags [&lt;file&gt;]             create tags file for Vi (default: "tags")
  71    :etags [&lt;file&gt;]             create tags file for Emacs (default: "TAGS")
  72    :type &lt;expr&gt;                show the type of &lt;expr&gt;
  73    :kind &lt;type&gt;                show the kind of &lt;type&gt;
  74    :undef &lt;cmd&gt;                undefine user-defined command :&lt;cmd&gt;
  75    :unset &lt;option&gt; ...         unset options
  76    :quit                       exit GHCi
  77    :!&lt;command&gt;                 run the shell command &lt;command&gt;
  78
  79  Options for ':set' and ':unset':
  80
  81     +r            revert top-level expressions after each evaluation
  82     +s            print timing/memory stats after each evaluation
  83     +t            print type after evaluation
  84     -&lt;flags&gt;      most GHC command line flags can also be set here
  85                          (eg. -v2, -fglasgow-exts, etc.)
  86 </screen>
  87
  88     <para>We'll explain most of these commands as we go along.  For
  89     Hugs users: many things work the same as in Hugs, so you should be
  90     able to get going straight away.</para>
  91
  92     <para>Haskell expressions can be typed at the prompt:</para>
  93     <indexterm><primary>prompt</primary><secondary>GHCi</secondary>
  94   </indexterm>
  95
  96 <screen>
  97 Prelude> 1+2
  98 3
  99 Prelude> let x = 42 in x / 9
 100 4.666666666666667
 101 Prelude>
 102 </screen>
 103
 104     <para>GHCi interprets the whole line as an expression to evaluate.
 105     The expression may not span several lines - as soon as you press
 106     enter, GHCi will attempt to evaluate it.</para>
 107   </sect1>
 108
 109   <sect1 id="loading-source-files">
 110     <title>Loading source files</title>
 111
 112     <para>Suppose we have the following Haskell source code, which we
 113     place in a file <filename>Main.hs</filename>:</para>
 114
 115 <programlisting>
 116 main = print (fac 20)
 117
 118 fac 0 = 1
 119 fac n = n * fac (n-1)
 120 </programlisting>
 121
 122     <para>You can save <filename>Main.hs</filename> anywhere you like,
 123     but if you save it somewhere other than the current
 124     directory<footnote><para>If you started up GHCi from the command
 125     line then GHCi's current directory is the same as the current
 126     directory of the shell from which it was started.  If you started
 127     GHCi from the &ldquo;Start&rdquo; menu in Windows, then the
 128     current directory is probably something like
 129     <filename>C:\Documents and Settings\<replaceable>user
 130     name</replaceable></filename>.</para> </footnote> then we will
 131     need to change to the right directory in GHCi:</para>
 132
 133 <screen>
 134 Prelude> :cd <replaceable>dir</replaceable>
 135 </screen>
 136
 137     <para>where <replaceable>dir</replaceable> is the directory (or
 138     folder) in which you saved <filename>Main.hs</filename>.</para>
 139
 140     <para>To load a Haskell source file into GHCi, use the
 141     <literal>:load</literal> command:</para>
 142     <indexterm><primary><literal>:load</literal></primary></indexterm>
 143
 144 <screen>
 145 Prelude> :load Main
 146 Compiling Main             ( Main.hs, interpreted )
 147 Ok, modules loaded: Main.
 148 *Main>
 149 </screen>
 150
 151     <para>GHCi has loaded the <literal>Main</literal> module, and the
 152     prompt has changed to &ldquo;<literal>*Main></literal>&rdquo; to
 153     indicate that the current context for expressions typed at the
 154     prompt is the <literal>Main</literal> module we just loaded (we'll
 155     explain what the <literal>*</literal> means later in <xref
 156     linkend="ghci-scope"/>).  So we can now type expressions involving
 157     the functions from <filename>Main.hs</filename>:</para>
 158
 159 <screen>
 160 *Main> fac 17
 161 355687428096000
 162 </screen>
 163
 164     <para>Loading a multi-module program is just as straightforward;
 165     just give the name of the &ldquo;topmost&rdquo; module to the
 166     <literal>:load</literal> command (hint: <literal>:load</literal>
 167     can be abbreviated to <literal>:l</literal>).  The topmost module
 168     will normally be <literal>Main</literal>, but it doesn't have to
 169     be.  GHCi will discover which modules are required, directly or
 170     indirectly, by the topmost module, and load them all in dependency
 171     order.</para>
 172
 173     <sect2 id="ghci-modules-filenames">
 174       <title>Modules vs. filenames</title>
 175       <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
 176       <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>
 177
 178       <para>Question: How does GHC find the filename which contains
 179       module <replaceable>M</replaceable>?  Answer: it looks for the
 180       file <literal><replaceable>M</replaceable>.hs</literal>, or
 181       <literal><replaceable>M</replaceable>.lhs</literal>.  This means
 182       that for most modules, the module name must match the filename.
 183       If it doesn't, GHCi won't be able to find it.</para>
 184
 185       <para>There is one exception to this general rule: when you load
 186       a program with <literal>:load</literal>, or specify it when you
 187       invoke <literal>ghci</literal>, you can give a filename rather
 188       than a module name.  This filename is loaded if it exists, and
 189       it may contain any module you like.  This is particularly
 190       convenient if you have several <literal>Main</literal> modules
 191       in the same directory and you can't call them all
 192       <filename>Main.hs</filename>.</para>
 193
 194       <para>The search path for finding source files is specified with
 195       the <option>-i</option> option on the GHCi command line, like
 196       so:</para>
 197 <screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen>
 198
 199       <para>or it can be set using the <literal>:set</literal> command
 200       from within GHCi (see <xref
 201       linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in
 202       GHCi, and <option>&ndash;&ndash;make</option> mode, the <option>-i</option>
 203       option is used to specify the search path for
 204       <emphasis>source</emphasis> files, whereas in standard
 205       batch-compilation mode the <option>-i</option> option is used to
 206       specify the search path for interface files, see <xref
 207       linkend="search-path"/>.</para> </footnote></para>
 208
 209       <para>One consequence of the way that GHCi follows dependencies
 210       to find modules to load is that every module must have a source
 211       file.  The only exception to the rule is modules that come from
 212       a package, including the <literal>Prelude</literal> and standard
 213       libraries such as <literal>IO</literal> and
 214       <literal>Complex</literal>.  If you attempt to load a module for
 215       which GHCi can't find a source file, even if there are object
 216       and interface files for the module, you'll get an error
 217       message.</para>
 218     </sect2>
 219
 220     <sect2>
 221       <title>Making changes and recompilation</title>
 222       <indexterm><primary><literal>:reload</literal></primary></indexterm>
 223
 224       <para>If you make some changes to the source code and want GHCi
 225       to recompile the program, give the <literal>:reload</literal>
 226       command.  The program will be recompiled as necessary, with GHCi
 227       doing its best to avoid actually recompiling modules if their
 228       external dependencies haven't changed.  This is the same
 229       mechanism we use to avoid re-compiling modules in the batch
 230       compilation setting (see <xref linkend="recomp"/>).</para>
 231     </sect2>
 232   </sect1>
 233
 234   <sect1 id="ghci-compiled">
 235     <title>Loading compiled code</title>
 236     <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm>
 237
 238     <para>When you load a Haskell source module into GHCi, it is
 239     normally converted to byte-code and run using the interpreter.
 240     However, interpreted code can also run alongside compiled code in
 241     GHCi; indeed, normally when GHCi starts, it loads up a compiled
 242     copy of the <literal>base</literal> package, which contains the
 243     <literal>Prelude</literal>.</para>
 244
 245     <para>Why should we want to run compiled code?  Well, compiled
 246     code is roughly 10x faster than interpreted code, but takes about
 247     2x longer to produce (perhaps longer if optimisation is on).  So
 248     it pays to compile the parts of a program that aren't changing
 249     very often, and use the interpreter for the code being actively
 250     developed.</para>
 251
 252     <para>When loading up source files with <literal>:load</literal>,
 253     GHCi looks for any corresponding compiled object files, and will
 254     use one in preference to interpreting the source if possible.  For
 255     example, suppose we have a 4-module program consisting of modules
 256     A, B, C, and D.  Modules B and C both import D only,
 257     and A imports both B &amp; C:</para>
 258 <screen>
 259       A
 260      / \
 261     B   C
 262      \ /
 263       D
 264 </screen>
 265     <para>We can compile D, then load the whole program, like this:</para>
 266 <screen>
 267 Prelude> :! ghc -c D.hs
 268 Prelude> :load A
 269 Skipping  D                ( D.hs, D.o )
 270 Compiling C                ( C.hs, interpreted )
 271 Compiling B                ( B.hs, interpreted )
 272 Compiling A                ( A.hs, interpreted )
 273 Ok, modules loaded: A, B, C, D.
 274 *Main>
 275 </screen>
 276
 277     <para>In the messages from the compiler, we see that it skipped D,
 278     and used the object file <filename>D.o</filename>.  The message
 279     <literal>Skipping</literal> <replaceable>module</replaceable>
 280     indicates that compilation for <replaceable>module</replaceable>
 281     isn't necessary, because the source and everything it depends on
 282     is unchanged since the last compilation.</para>
 283
 284     <para>At any time you can use the command
 285     <literal>:show modules</literal>
 286     to get a list of the modules currently loaded
 287     into GHCi:</para>
 288
 289 <screen>
 290 *Main> :show modules
 291 D                ( D.hs, D.o )
 292 C                ( C.hs, interpreted )
 293 B                ( B.hs, interpreted )
 294 A                ( A.hs, interpreted )
 295 *Main></screen>
 296
 297     <para>If we now modify the source of D (or pretend to: using Unix
 298     command <literal>touch</literal> on the source file is handy for
 299     this), the compiler will no longer be able to use the object file,
 300     because it might be out of date:</para>
 301
 302 <screen>
 303 *Main> :! touch D.hs
 304 *Main> :reload
 305 Compiling D                ( D.hs, interpreted )
 306 Skipping  C                ( C.hs, interpreted )
 307 Skipping  B                ( B.hs, interpreted )
 308 Skipping  A                ( A.hs, interpreted )
 309 Ok, modules loaded: A, B, C, D.
 310 *Main>
 311 </screen>
 312
 313     <para>Note that module D was compiled, but in this instance
 314     because its source hadn't really changed, its interface remained
 315     the same, and the recompilation checker determined that A, B and C
 316     didn't need to be recompiled.</para>
 317
 318     <para>So let's try compiling one of the other modules:</para>
 319
 320 <screen>
 321 *Main> :! ghc -c C.hs
 322 *Main> :load A
 323 Compiling D                ( D.hs, interpreted )
 324 Compiling C                ( C.hs, interpreted )
 325 Compiling B                ( B.hs, interpreted )
 326 Compiling A                ( A.hs, interpreted )
 327 Ok, modules loaded: A, B, C, D.
 328 </screen>
 329
 330     <para>We didn't get the compiled version of C!  What happened?
 331     Well, in GHCi a compiled module may only depend on other compiled
 332     modules, and in this case C depends on D, which doesn't have an
 333     object file, so GHCi also rejected C's object file.  Ok, so let's
 334     also compile D:</para>
 335
 336 <screen>
 337 *Main> :! ghc -c D.hs
 338 *Main> :reload
 339 Ok, modules loaded: A, B, C, D.
 340 </screen>
 341
 342     <para>Nothing happened!  Here's another lesson: newly compiled
 343     modules aren't picked up by <literal>:reload</literal>, only
 344     <literal>:load</literal>:</para>
 345
 346 <screen>
 347 *Main> :load A
 348 Skipping  D                ( D.hs, D.o )
 349 Skipping  C                ( C.hs, C.o )
 350 Compiling B                ( B.hs, interpreted )
 351 Compiling A                ( A.hs, interpreted )
 352 Ok, modules loaded: A, B, C, D.
 353 </screen>
 354
 355     <para>HINT: since GHCi will only use a compiled object file if it
 356     can be sure that the compiled version is up-to-date, a good technique
 357     when working on a large program is to occasionally run
 358     <literal>ghc &ndash;&ndash;make</literal> to compile the whole project (say
 359     before you go for lunch :-), then continue working in the
 360     interpreter.  As you modify code, the new modules will be
 361     interpreted, but the rest of the project will remain
 362     compiled.</para>
 363
 364   </sect1>
 365
 366   <sect1 id="interactive-evaluation">
 367     <title>Interactive evaluation at the prompt</title>
 368
 369     <para>When you type an expression at the prompt, GHCi immediately
 370     evaluates and prints the result:
 371 <screen>
 372 Prelude> reverse "hello"
 373 "olleh"
 374 Prelude> 5+5
 375 10
 376 </screen>
 377 </para>
 378
 379 <sect2><title>I/O actions at the prompt</title>
 380
 381 <para>GHCi does more than simple expression evaluation at the prompt.
 382 If you type something of type <literal>IO a</literal> for some
 383     <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it
 384     as an IO-computation.
 385 <screen>
 386 Prelude> "hello"
 387 "hello"
 388 Prelude> putStrLn "hello"
 389 hello
 390 </screen>
 391 Furthermore, GHCi will print the result of the I/O action if (and only
 392 if):
 393 <itemizedlist>
 394   <listitem><para>The result type is an instance of <literal>Show</literal>.</para></listitem>
 395   <listitem><para>The result type is not
 396   <literal>()</literal>.</para></listitem>
 397 </itemizedlist>
 398 For example, remembering that <literal>putStrLn :: String -> IO ()</literal>:
 399 <screen>
 400 Prelude> putStrLn "hello"
 401 hello
 402 Prelude> do { putStrLn "hello"; return "yes" }
 403 hello
 404 "yes"
 405 </screen>
 406 </para></sect2>
 407
 408     <sect2 id="ghci-stmts">
 409       <title>Using <literal>do-</literal>notation at the prompt</title>
 410       <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm>
 411       <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm>
 412
 413       <para>GHCi actually accepts <firstterm>statements</firstterm>
 414       rather than just expressions at the prompt.  This means you can
 415       bind values and functions to names, and use them in future
 416       expressions or statements.</para>
 417
 418       <para>The syntax of a statement accepted at the GHCi prompt is
 419       exactly the same as the syntax of a statement in a Haskell
 420       <literal>do</literal> expression.  However, there's no monad
 421       overloading here: statements typed at the prompt must be in the
 422       <literal>IO</literal> monad.
 423 <screen>
 424 Prelude> x &lt;- return 42
 425 42
 426 Prelude> print x
 427 42
 428 Prelude>
 429 </screen>
 430       The statement <literal>x &lt;- return 42</literal> means
 431       &ldquo;execute <literal>return 42</literal> in the
 432       <literal>IO</literal> monad, and bind the result to
 433       <literal>x</literal>&rdquo;.  We can then use
 434       <literal>x</literal> in future statements, for example to print
 435       it as we did above.</para>
 436
 437       <para>GHCi will print the result of a statement if and only if:
 438         <itemizedlist>
 439           <listitem>
 440             <para>The statement is not a binding, or it is a monadic binding
 441               (<literal>p &lt;- e</literal>) that binds exactly one
 442               variable.</para>
 443           </listitem>
 444           <listitem>
 445             <para>The variable's type is not polymorphic, is not
 446               <literal>()</literal>, and is an instance of
 447               <literal>Show</literal></para>
 448           </listitem>
 449         </itemizedlist>
 450       The automatic printing of binding results can be supressed with
 451       <option>:set -fno-print-bind-result</option> (this does not
 452       supress printing the result of non-binding statements).
 453       <indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm><indexterm><primary><option>-fprint-bind-result</option></primary></indexterm>.
 454       You might want to do this to prevent the result of binding
 455       statements from being fully evaluated by the act of printing
 456       them, for example.</para>
 457
 458       <para>Of course, you can also bind normal non-IO expressions
 459       using the <literal>let</literal>-statement:</para>
 460 <screen>
 461 Prelude> let x = 42
 462 Prelude> x
 463 42
 464 Prelude>
 465 </screen>
 466       <para>Another important difference between the two types of binding
 467       is that the monadic bind (<literal>p &lt;- e</literal>) is
 468       <emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
 469       whereas with the <literal>let</literal> form, the expression
 470       isn't evaluated immediately:</para>
 471 <screen>
 472 Prelude> let x = error "help!"
 473 Prelude> print x
 474 *** Exception: help!
 475 Prelude>
 476 </screen>
 477
 478       <para>Note that <literal>let</literal> bindings do not automatically
 479         print the value bound, unlike monadic bindings.</para>
 480
 481       <para>Any exceptions raised during the evaluation or execution
 482       of the statement are caught and printed by the GHCi command line
 483       interface (for more information on exceptions, see the module
 484       <literal>Control.Exception</literal> in the libraries
 485       documentation).</para>
 486
 487       <para>Every new binding shadows any existing bindings of the
 488       same name, including entities that are in scope in the current
 489       module context.</para>
 490
 491       <para>WARNING: temporary bindings introduced at the prompt only
 492       last until the next <literal>:load</literal> or
 493       <literal>:reload</literal> command, at which time they will be
 494       simply lost.  However, they do survive a change of context with
 495       <literal>:module</literal>: the temporary bindings just move to
 496       the new location.</para>
 497
 498       <para>HINT: To get a list of the bindings currently in scope, use the
 499       <literal>:show bindings</literal> command:</para>
 500
 501 <screen>
 502 Prelude> :show bindings
 503 x :: Int
 504 Prelude></screen>
 505
 506       <para>HINT: if you turn on the <literal>+t</literal> option,
 507       GHCi will show the type of each variable bound by a statement.
 508       For example:</para>
 509       <indexterm><primary><literal>+t</literal></primary></indexterm>
 510 <screen>
 511 Prelude> :set +t
 512 Prelude> let (x:xs) = [1..]
 513 x :: Integer
 514 xs :: [Integer]
 515 </screen>
 516
 517     </sect2>
 518
 519     <sect2 id="ghci-scope">
 520       <title>What's really in scope at the prompt?</title>
 521
 522       <para>When you type an expression at the prompt, what
 523       identifiers and types are in scope?  GHCi provides a flexible
 524       way to control exactly how the context for an expression is
 525       constructed.  Let's start with the simple cases; when you start
 526       GHCi the prompt looks like this:</para>
 527
 528 <screen>Prelude></screen>
 529
 530       <para>Which indicates that everything from the module
 531       <literal>Prelude</literal> is currently in scope.  If we now
 532       load a file into GHCi, the prompt will change:</para>
 533
 534 <screen>
 535 Prelude> :load Main.hs
 536 Compiling Main             ( Main.hs, interpreted )
 537 *Main>
 538 </screen>
 539
 540       <para>The new prompt is <literal>*Main</literal>, which
 541       indicates that we are typing expressions in the context of the
 542       top-level of the <literal>Main</literal> module.  Everything
 543       that is in scope at the top-level in the module
 544       <literal>Main</literal> we just loaded is also in scope at the
 545       prompt (probably including <literal>Prelude</literal>, as long
 546       as <literal>Main</literal> doesn't explicitly hide it).</para>
 547
 548       <para>The syntax
 549       <literal>*<replaceable>module</replaceable></literal> indicates
 550       that it is the full top-level scope of
 551       <replaceable>module</replaceable> that is contributing to the
 552       scope for expressions typed at the prompt.  Without the
 553       <literal>*</literal>, just the exports of the module are
 554       visible.</para>
 555
 556       <para>We're not limited to a single module: GHCi can combine
 557       scopes from multiple modules, in any mixture of
 558       <literal>*</literal> and non-<literal>*</literal> forms.  GHCi
 559       combines the scopes from all of these modules to form the scope
 560       that is in effect at the prompt.  For technical reasons, GHCi
 561       can only support the <literal>*</literal>-form for modules which
 562       are interpreted, so compiled modules and package modules can
 563       only contribute their exports to the current scope.</para>
 564
 565       <para>The scope is manipulated using the
 566       <literal>:module</literal> command.  For example, if the current
 567       scope is <literal>Prelude</literal>, then we can bring into
 568       scope the exports from the module <literal>IO</literal> like
 569       so:</para>
 570
 571 <screen>
 572 Prelude> :module +IO
 573 Prelude IO> hPutStrLn stdout "hello\n"
 574 hello
 575 Prelude IO>
 576 </screen>
 577
 578       <para>(Note: <literal>:module</literal> can be shortened to
 579       <literal>:m</literal>). The full syntax of the
 580       <literal>:module</literal> command is:</para>
 581
 582 <screen>
 583 :module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
 584 </screen>
 585
 586       <para>Using the <literal>+</literal> form of the
 587       <literal>module</literal> commands adds modules to the current
 588       scope, and <literal>-</literal> removes them.  Without either
 589       <literal>+</literal> or <literal>-</literal>, the current scope
 590       is replaced by the set of modules specified.  Note that if you
 591       use this form and leave out <literal>Prelude</literal>, GHCi
 592       will assume that you really wanted the
 593       <literal>Prelude</literal> and add it in for you (if you don't
 594       want the <literal>Prelude</literal>, then ask to remove it with
 595       <literal>:m -Prelude</literal>).</para>
 596
 597       <para>The scope is automatically set after a
 598       <literal>:load</literal> command, to the most recently loaded
 599       "target" module, in a <literal>*</literal>-form if possible.
 600       For example, if you say <literal>:load foo.hs bar.hs</literal>
 601       and <filename>bar.hs</filename> contains module
 602       <literal>Bar</literal>, then the scope will be set to
 603       <literal>*Bar</literal> if <literal>Bar</literal> is
 604       interpreted, or if <literal>Bar</literal> is compiled it will be
 605       set to <literal>Prelude Bar</literal> (GHCi automatically adds
 606       <literal>Prelude</literal> if it isn't present and there aren't
 607       any <literal>*</literal>-form modules).</para>
 608
 609       <para>With multiple modules in scope, especially multiple
 610       <literal>*</literal>-form modules, it is likely that name
 611       clashes will occur.  Haskell specifies that name clashes are
 612       only reported when an ambiguous identifier is used, and GHCi
 613       behaves in the same way for expressions typed at the
 614       prompt.</para>
 615
 616       <para>
 617         Hint: GHCi will tab-complete names that are in scope; for
 618         example, if you run GHCi and type <literal>J&lt;tab&gt;</literal>
 619         then GHCi will expand it to <literal>Just </literal>.
 620       </para>
 621
 622       <sect3>
 623         <title>Qualified names</title>
 624
 625         <para>To make life slightly easier, the GHCi prompt also
 626         behaves as if there is an implicit <literal>import
 627         qualified</literal> declaration for every module in every
 628         package, and every module currently loaded into GHCi.</para>
 629       </sect3>
 630
 631       <sect3>
 632         <title>The <literal>:main</literal> command</title>
 633
 634         <para>
 635           When a program is compiled and executed, it can use the
 636           <literal>getArgs</literal> function to access the
 637           command-line arguments.
 638           However, we cannot simply pass the arguments to the
 639           <literal>main</literal> function while we are testing in ghci,
 640           as the <literal>main</literal> function doesn't take its
 641           directly.
 642         </para>
 643
 644         <para>
 645           Instead, we can use the <literal>:main</literal> command.
 646           This runs whatever <literal>main</literal> is in scope, with
 647           any arguments being treated the same as command-line arguments,
 648           e.g.:
 649         </para>
 650
 651 <screen>
 652 Prelude> let main = System.Environment.getArgs >>= print
 653 Prelude> :main foo bar
 654 ["foo","bar"]
 655 </screen>
 656
 657       </sect3>
 658     </sect2>
 659
 660
 661     <sect2>
 662       <title>The <literal>it</literal> variable</title>
 663       <indexterm><primary><literal>it</literal></primary>
 664       </indexterm>
 665
 666       <para>Whenever an expression (or a non-binding statement, to be
 667       precise) is typed at the prompt, GHCi implicitly binds its value
 668       to the variable <literal>it</literal>.  For example:</para>
 669 <screen>
 670 Prelude> 1+2
 671 3
 672 Prelude> it * 2
 673 6
 674 </screen>
 675     <para>What actually happens is that GHCi typechecks the
 676     expression, and if it doesn't have an <literal>IO</literal> type,
 677     then it transforms it as follows: an expression
 678     <replaceable>e</replaceable> turns into
 679 <screen>
 680 let it = <replaceable>e</replaceable>;
 681 print it
 682 </screen>
 683     which is then run as an IO-action.</para>
 684
 685     <para>Hence, the original expression must have a type which is an
 686     instance of the <literal>Show</literal> class, or GHCi will
 687     complain:</para>
 688
 689 <screen>
 690 Prelude&gt; id
 691
 692 &lt;interactive&gt;:1:0:
 693     No instance for (Show (a -&gt; a))
 694       arising from use of `print' at &lt;interactive&gt;:1:0-1
 695     Possible fix: add an instance declaration for (Show (a -> a))
 696     In the expression: print it
 697     In a 'do' expression: print it
 698 </screen>
 699
 700     <para>The error message contains some clues as to the
 701     transformation happening internally.</para>
 702
 703       <para>If the expression was instead of type <literal>IO a</literal> for
 704       some <literal>a</literal>, then <literal>it</literal> will be
 705       bound to the result of the <literal>IO</literal> computation,
 706       which is of type <literal>a</literal>.  eg.:</para>
 707 <screen>
 708 Prelude> Time.getClockTime
 709 Wed Mar 14 12:23:13 GMT 2001
 710 Prelude> print it
 711 Wed Mar 14 12:23:13 GMT 2001
 712 </screen>
 713
 714       <para>The corresponding translation for an IO-typed
 715       <replaceable>e</replaceable> is
 716 <screen>
 717 it &lt;- <replaceable>e</replaceable>
 718 </screen>
 719       </para>
 720
 721       <para>Note that <literal>it</literal> is shadowed by the new
 722       value each time you evaluate a new expression, and the old value
 723       of <literal>it</literal> is lost.</para>
 724
 725     </sect2>
 726
 727     <sect2 id="extended-default-rules">
 728       <title>Type defaulting in GHCi</title>
 729     <indexterm><primary>Type default</primary></indexterm>
 730     <indexterm><primary><literal>Show</literal> class</primary></indexterm>
 731       <para>
 732       Consider this GHCi session:
 733 <programlisting>
 734   ghci> reverse []
 735 </programlisting>
 736       What should GHCi do?  Strictly speaking, the program is ambiguous.  <literal>show (reverse [])</literal>
 737       (which is what GHCi computes here) has type <literal>Show a => a</literal> and how that displays depends
 738       on the type <literal>a</literal>.  For example:
 739 <programlisting>
 740   ghci> (reverse []) :: String
 741   ""
 742   ghci> (reverse []) :: [Int]
 743   []
 744 </programlisting>
 745     However, it is tiresome for the user to have to specify the type, so GHCi extends Haskell's type-defaulting
 746     rules (Section 4.3.4 of the Haskell 98 Report (Revised)) as follows.  The
 747     standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
 748     a)</literal> for each type variable <literal>a</literal>, and defaults the
 749     type variable if
 750     <orderedlist>
 751         <listitem>
 752             <para>
 753                 The type variable <literal>a</literal> appears in no
 754                 other constraints
 755             </para>
 756         </listitem>
 757         <listitem>
 758             <para>
 759                 All the classes <literal>Ci</literal> are standard.
 760             </para>
 761         </listitem>
 762         <listitem>
 763             <para>
 764                 At least one of the classes <literal>Ci</literal> is
 765                 numeric.
 766             </para>
 767         </listitem>
 768     </orderedlist>
 769     At the GHCi prompt, or with GHC if the
 770     <literal>-fextended-default-rules</literal> flag is given,
 771     the following additional differences apply:
 772     <itemizedlist>
 773         <listitem>
 774             <para>
 775                 Rule 2 above is relaxed thus:
 776                 <emphasis>All</emphasis> of the classes
 777                 <literal>Ci</literal> are single-parameter type classes.
 778             </para>
 779         </listitem>
 780         <listitem>
 781             <para>
 782                 Rule 3 above is relaxed this:
 783                 At least one of the classes <literal>Ci</literal> is
 784                 numeric, <emphasis>or is <literal>Show</literal>,
 785                 <literal>Eq</literal>, or
 786                 <literal>Ord</literal></emphasis>.
 787             </para>
 788         </listitem>
 789         <listitem>
 790             <para>
 791                 The unit type <literal>()</literal> is added to the
 792                 start of the standard list of types which are tried when
 793                 doing type defaulting.
 794             </para>
 795         </listitem>
 796     </itemizedlist>
 797     The last point means that, for example, this program:
 798 <programlisting>
 799 main :: IO ()
 800 main = print def
 801
 802 instance Num ()
 803
 804 def :: (Num a, Enum a) => a
 805 def = toEnum 0
 806 </programlisting>
 807     prints <literal>()</literal> rather than <literal>0</literal> as the
 808     type is defaulted to <literal>()</literal> rather than
 809     <literal>Integer</literal>.
 810    </para>
 811    <para>
 812     The motivation for the change is that it means <literal>IO a</literal>
 813     actions default to <literal>IO ()</literal>, which in turn means that
 814     ghci won't try to print a result when running them. This is
 815     particularly important for <literal>printf</literal>, which has an
 816     instance that returns <literal>IO a</literal>.
 817     However, it is only able to return
 818     <literal>undefined</literal>
 819     (the reason for the instance having this type is to not require
 820     extensions to the class system), so if the type defaults to
 821     <literal>Integer</literal> then ghci gives an error when running a
 822     printf.
 823    </para>
 824     </sect2>
 825   </sect1>
 826
 827   <sect1 id="ghci-invocation">
 828     <title>Invoking GHCi</title>
 829     <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
 830     <indexterm><primary><option>&ndash;&ndash;interactive</option></primary></indexterm>
 831
 832     <para>GHCi is invoked with the command <literal>ghci</literal> or
 833     <literal>ghc &ndash;&ndash;interactive</literal>.  One or more modules or
 834     filenames can also be specified on the command line; this
 835     instructs GHCi to load the specified modules or filenames (and all
 836     the modules they depend on), just as if you had said
 837     <literal>:load <replaceable>modules</replaceable></literal> at the
 838     GHCi prompt (see <xref linkend="ghci-commands"/>).  For example, to
 839     start GHCi and load the program whose topmost module is in the
 840     file <literal>Main.hs</literal>, we could say:</para>
 841
 842 <screen>
 843 $ ghci Main.hs
 844 </screen>
 845
 846     <para>Most of the command-line options accepted by GHC (see <xref
 847     linkend="using-ghc"/>) also make sense in interactive mode.  The ones
 848     that don't make sense are mostly obvious; for example, GHCi
 849     doesn't generate interface files, so options related to interface
 850     file generation won't have any effect.</para>
 851
 852     <sect2>
 853       <title>Packages</title>
 854       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
 855
 856       <para>Most packages (see <xref linkend="using-packages"/>) are
 857       available without needing to specify any extra flags at all:
 858       they will be automatically loaded the first time they are
 859       needed.</para>
 860
 861       <para>For non-auto packages, however, you need to request the
 862       package be loaded by using the <literal>-package</literal> flag:</para>
 863
 864 <screen>
 865 $ ghci -package readline
 866    ___         ___ _
 867   / _ \ /\  /\/ __(_)
 868  / /_\// /_/ / /  | |      GHC Interactive, version 6.6, for Haskell 98.
 869 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 870 \____/\/ /_/\____/|_|      Type :? for help.
 871
 872 Loading package base ... linking ... done.
 873 Loading package readline-1.0 ... linking ... done.
 874 Prelude>
 875 </screen>
 876
 877       <para>The following command works to load new packages into a
 878       running GHCi:</para>
 879
 880 <screen>
 881 Prelude> :set -package <replaceable>name</replaceable>
 882 </screen>
 883
 884       <para>But note that doing this will cause all currently loaded
 885       modules to be unloaded, and you'll be dumped back into the
 886       <literal>Prelude</literal>.</para>
 887     </sect2>
 888
 889     <sect2>
 890       <title>Extra libraries</title>
 891       <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
 892
 893       <para>Extra libraries may be specified on the command line using
 894       the normal <literal>-l<replaceable>lib</replaceable></literal>
 895       option.  (The term <emphasis>library</emphasis> here refers to
 896       libraries of foreign object code; for using libraries of Haskell
 897       source code, see <xref linkend="ghci-modules-filenames"/>.) For
 898       example, to load the &ldquo;m&rdquo; library:</para>
 899
 900 <screen>
 901 $ ghci -lm
 902 </screen>
 903
 904       <para>On systems with <literal>.so</literal>-style shared
 905       libraries, the actual library loaded will the
 906       <filename>lib<replaceable>lib</replaceable>.so</filename>.  GHCi
 907       searches the following places for libraries, in this order:</para>
 908
 909       <itemizedlist>
 910         <listitem>
 911           <para>Paths specified using the
 912           <literal>-L<replaceable>path</replaceable></literal>
 913           command-line option,</para>
 914         </listitem>
 915         <listitem>
 916           <para>the standard library search path for your system,
 917           which on some systems may be overridden by setting the
 918           <literal>LD_LIBRARY_PATH</literal> environment
 919           variable.</para>
 920         </listitem>
 921       </itemizedlist>
 922
 923       <para>On systems with <literal>.dll</literal>-style shared
 924       libraries, the actual library loaded will be
 925       <filename><replaceable>lib</replaceable>.dll</filename>.  Again,
 926       GHCi will signal an error if it can't find the library.</para>
 927
 928       <para>GHCi can also load plain object files
 929       (<literal>.o</literal> or <literal>.obj</literal> depending on
 930       your platform) from the command-line.  Just add the name the
 931       object file to the command line.</para>
 932
 933       <para>Ordering of <option>-l</option> options matters: a library
 934       should be mentioned <emphasis>before</emphasis> the libraries it
 935       depends on (see <xref linkend="options-linker"/>).</para>
 936     </sect2>
 937
 938   </sect1>
 939
 940   <sect1 id="ghci-commands">
 941     <title>GHCi commands</title>
 942
 943     <para>GHCi commands all begin with
 944     &lsquo;<literal>:</literal>&rsquo; and consist of a single command
 945     name followed by zero or more parameters.  The command name may be
 946     abbreviated, with ambiguities being resolved in favour of the more
 947     commonly used commands.</para>
 948
 949     <variablelist>
 950       <varlistentry>
 951         <term>
 952           <literal>:add</literal> <replaceable>module</replaceable> ...
 953           <indexterm><primary><literal>:add</literal></primary></indexterm>
 954         </term>
 955         <listitem>
 956           <para>Add <replaceable>module</replaceable>(s) to the
 957           current <firstterm>target set</firstterm>, and perform a
 958           reload.</para>
 959         </listitem>
 960       </varlistentry>
 961
 962       <varlistentry>
 963         <term>
 964           <literal>:breakpoint</literal> <replaceable>list|add|continue|del|stop|step</replaceable> ...
 965           <indexterm><primary><literal>:breakpoint</literal></primary></indexterm>
 966         </term>
 967         <listitem>
 968           <para>Permits to add, delete or list the breakpoints in a debugging session.
 969           In order to make this command available, the
 970           <literal>-fdebugging</literal> flag must be active. The easiest way is to launch
 971           GHCi with the <literal>-fdebugging</literal> option. For more
 972           details on how the debugger works, see <xref linkend="ghci-debugger"/>.
 973           </para>
 974         </listitem>
 975       </varlistentry>
 976
 977       <varlistentry>
 978         <term>
 979           <literal>:browse</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
 980           <indexterm><primary><literal>:browse</literal></primary></indexterm>
 981         </term>
 982         <listitem>
 983           <para>Displays the identifiers defined by the module
 984           <replaceable>module</replaceable>, which must be either
 985           loaded into GHCi or be a member of a package.  If the
 986           <literal>*</literal> symbol is placed before the module
 987           name, then <emphasis>all</emphasis> the identifiers defined
 988           in <replaceable>module</replaceable> are shown; otherwise
 989           the list is limited to the exports of
 990           <replaceable>module</replaceable>.  The
 991           <literal>*</literal>-form is only available for modules
 992           which are interpreted; for compiled modules (including
 993           modules from packages) only the non-<literal>*</literal>
 994           form of <literal>:browse</literal> is available.</para>
 995         </listitem>
 996       </varlistentry>
 997
 998       <varlistentry>
 999         <term>
1000           <literal>:cd</literal> <replaceable>dir</replaceable>
1001           <indexterm><primary><literal>:cd</literal></primary></indexterm>
1002         </term>
1003         <listitem>
1004           <para>Changes the current working directory to
1005           <replaceable>dir</replaceable>.  A
1006           &lsquo;<literal>&tilde;</literal>&rsquo; symbol at the
1007           beginning of <replaceable>dir</replaceable> will be replaced
1008           by the contents of the environment variable
1009           <literal>HOME</literal>.</para>
1010
1011           <para>NOTE: changing directories causes all currently loaded
1012           modules to be unloaded.  This is because the search path is
1013           usually expressed using relative directories, and changing
1014           the search path in the middle of a session is not
1015           supported.</para>
1016         </listitem>
1017       </varlistentry>
1018
1019       <varlistentry>
1020         <term>
1021           <literal>:continue</literal>
1022           <indexterm><primary><literal>:continue</literal></primary></indexterm>
1023         </term>
1024         <listitem><para>Shortcut to <literal>:breakpoint continue</literal></para>
1025         </listitem>
1026       </varlistentry>
1027
1028       <varlistentry>
1029         <term>
1030           <literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable>
1031           <indexterm><primary><literal>:def</literal></primary></indexterm>
1032         </term>
1033         <listitem>
1034           <para>The command <literal>:def</literal>
1035           <replaceable>name</replaceable>
1036           <replaceable>expr</replaceable> defines a new GHCi command
1037           <literal>:<replaceable>name</replaceable></literal>,
1038           implemented by the Haskell expression
1039           <replaceable>expr</replaceable>, which must have type
1040           <literal>String -> IO String</literal>.  When
1041           <literal>:<replaceable>name</replaceable>
1042           <replaceable>args</replaceable></literal> is typed at the
1043           prompt, GHCi will run the expression
1044           <literal>(<replaceable>name</replaceable>
1045           <replaceable>args</replaceable>)</literal>, take the
1046           resulting <literal>String</literal>, and feed it back into
1047           GHCi as a new sequence of commands.  Separate commands in
1048           the result must be separated by
1049           &lsquo;<literal>\n</literal>&rsquo;.</para>
1050
1051           <para>That's all a little confusing, so here's a few
1052           examples.  To start with, here's a new GHCi command which
1053           doesn't take any arguments or produce any results, it just
1054           outputs the current date &amp; time:</para>
1055
1056 <screen>
1057 Prelude> let date _ = Time.getClockTime >>= print >> return ""
1058 Prelude> :def date date
1059 Prelude> :date
1060 Fri Mar 23 15:16:40 GMT 2001
1061 </screen>
1062
1063           <para>Here's an example of a command that takes an argument.
1064           It's a re-implementation of <literal>:cd</literal>:</para>
1065
1066 <screen>
1067 Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
1068 Prelude> :def mycd mycd
1069 Prelude> :mycd ..
1070 </screen>
1071
1072           <para>Or I could define a simple way to invoke
1073           &ldquo;<literal>ghc &ndash;&ndash;make Main</literal>&rdquo; in the
1074           current directory:</para>
1075
1076 <screen>
1077 Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")
1078 </screen>
1079
1080           <para>We can define a command that reads GHCi input from a
1081           file.  This might be useful for creating a set of bindings
1082           that we want to repeatedly load into the GHCi session:</para>
1083
1084 <screen>
1085 Prelude> :def . readFile
1086 Prelude> :. cmds.ghci
1087 </screen>
1088
1089           <para>Notice that we named the command
1090           <literal>:.</literal>, by analogy with the
1091           &lsquo;<literal>.</literal>&rsquo; Unix shell command that
1092           does the same thing.</para>
1093         </listitem>
1094       </varlistentry>
1095
1096       <varlistentry>
1097         <term>
1098           <literal>:edit <optional><replaceable>file</replaceable></optional></literal>
1099           <indexterm><primary><literal>:edit</literal></primary></indexterm>
1100         </term>
1101         <listitem>
1102           <para>Opens an editor to edit the file
1103           <replaceable>file</replaceable>, or the most recently loaded
1104           module if <replaceable>file</replaceable> is omitted.  The
1105           editor to invoke is taken from the <literal>EDITOR</literal>
1106           environment variable, or a default editor on your system if
1107           <literal>EDITOR</literal> is not set.  You can change the
1108           editor using <literal>:set editor</literal>.</para>
1109         </listitem>
1110       </varlistentry>
1111
1112       <varlistentry>
1113         <term>
1114           <literal>:help</literal>
1115           <indexterm><primary><literal>:help</literal></primary></indexterm>
1116         </term>
1117         <term>
1118           <literal>:?</literal>
1119           <indexterm><primary><literal>:?</literal></primary></indexterm>
1120         </term>
1121         <listitem>
1122           <para>Displays a list of the available commands.</para>
1123         </listitem>
1124       </varlistentry>
1125
1126       <varlistentry>
1127         <term>
1128           <literal>:info</literal> <replaceable>name</replaceable> ...
1129           <indexterm><primary><literal>:info</literal></primary></indexterm>
1130         </term>
1131         <listitem>
1132           <para>Displays information about the given name(s).  For
1133           example, if <replaceable>name</replaceable> is a class, then
1134           the class methods and their types will be printed;  if
1135           <replaceable>name</replaceable> is a type constructor, then
1136           its definition will be printed;  if
1137           <replaceable>name</replaceable> is a function, then its type
1138           will be printed.  If <replaceable>name</replaceable> has
1139           been loaded from a source file, then GHCi will also display
1140           the location of its definition in the source.</para>
1141         </listitem>
1142       </varlistentry>
1143
1144       <varlistentry>
1145         <term>
1146           <literal>:load</literal> <replaceable>module</replaceable> ...
1147           <indexterm><primary><literal>:load</literal></primary></indexterm>
1148         </term>
1149         <listitem>
1150           <para>Recursively loads the specified
1151           <replaceable>module</replaceable>s, and all the modules they
1152           depend on.  Here, each <replaceable>module</replaceable>
1153           must be a module name or filename, but may not be the name
1154           of a module in a package.</para>
1155
1156           <para>All previously loaded modules, except package modules,
1157           are forgotten.  The new set of modules is known as the
1158           <firstterm>target set</firstterm>.  Note that
1159           <literal>:load</literal> can be used without any arguments
1160           to unload all the currently loaded modules and
1161           bindings.</para>
1162
1163           <para>After a <literal>:load</literal> command, the current
1164           context is set to:</para>
1165
1166           <itemizedlist>
1167             <listitem>
1168               <para><replaceable>module</replaceable>, if it was loaded
1169               successfully, or</para>
1170             </listitem>
1171             <listitem>
1172               <para>the most recently successfully loaded module, if
1173               any other modules were loaded as a result of the current
1174               <literal>:load</literal>, or</para>
1175             </listitem>
1176             <listitem>
1177               <para><literal>Prelude</literal> otherwise.</para>
1178             </listitem>
1179           </itemizedlist>
1180         </listitem>
1181       </varlistentry>
1182
1183       <varlistentry>
1184         <term>
1185           <literal>:main <replaceable>arg<subscript>1</subscript></replaceable> ... <replaceable>arg<subscript>n</subscript></replaceable></literal>
1186           <indexterm><primary><literal>:main</literal></primary></indexterm>
1187         </term>
1188         <listitem>
1189           <para>
1190             When a program is compiled and executed, it can use the
1191             <literal>getArgs</literal> function to access the
1192             command-line arguments.
1193             However, we cannot simply pass the arguments to the
1194             <literal>main</literal> function while we are testing in ghci,
1195             as the <literal>main</literal> function doesn't take its
1196             directly.
1197           </para>
1198
1199           <para>
1200             Instead, we can use the <literal>:main</literal> command.
1201             This runs whatever <literal>main</literal> is in scope, with
1202             any arguments being treated the same as command-line arguments,
1203             e.g.:
1204           </para>
1205
1206 <screen>
1207 Prelude> let main = System.Environment.getArgs >>= print
1208 Prelude> :main foo bar
1209 ["foo","bar"]
1210 </screen>
1211
1212         </listitem>
1213       </varlistentry>
1214
1215       <varlistentry>
1216         <term>
1217           <literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal>
1218           <indexterm><primary><literal>:module</literal></primary></indexterm>
1219         </term>
1220         <listitem>
1221           <para>Sets or modifies the current context for statements
1222           typed at the prompt.  See <xref linkend="ghci-scope"/> for
1223           more details.</para>
1224         </listitem>
1225       </varlistentry>
1226
1227       <varlistentry>
1228         <term>
1229           <literal>:print </literal> <replaceable>names</replaceable> ...
1230           <indexterm><primary><literal>:print</literal></primary></indexterm>
1231         </term>
1232         <listitem>
1233           <para> Prints a semievaluated value without forcing its evaluation.
1234           <literal>:print </literal> works just like <literal>:sprint</literal> but additionally,
1235            <literal>:print</literal> binds the unevaluated parts -called
1236            <quote>suspensions</quote>-
1237           to names which you can play with. For example:
1238 <screen>
1239 Prelude> let li = map Just [1..5]
1240 Prelude> :sp li
1241 li - _
1242 Prelude> :p li
1243 li - (_t1::[Maybe Integer])
1244 Prelude> head li
1245 Just 1
1246 Prelude> :sp li
1247 li - [Just 1 | _]
1248 Prelude> :p li
1249 li - [Just 1 | (_t2::[Maybe Integer])]
1250 Prelude> last li
1251 Just 5
1252 Prelude> :sp li
1253 li - [Just 1,_,_,_,Just 5]
1254 Prelude> :p li
1255 li - [Just 1,(_t3::Maybe Integer),(_t4::Maybe Integer),(_t5::Maybe Integer),Just 4]
1256 Prelude> _t4
1257 Just 3
1258 Prelude> :p li
1259 li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4]
1260 </screen>
1261          The example uses <literal>:print</literal> and  <literal>:sprint</literal>
1262          to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
1263          with it. Note for instance how <quote>last</quote> traverses all the elements of
1264          the list to compute its result, but without evaluating the individual elements.</para>
1265            <para>Finally note that the Prolog convention of [head | tail] is used by
1266          <literal>:sprint</literal> to display unevaluated lists.
1267           </para>
1268         </listitem>
1269       </varlistentry>
1270
1271       <varlistentry>
1272         <term>
1273           <literal>:quit</literal>
1274           <indexterm><primary><literal>:quit</literal></primary></indexterm>
1275         </term>
1276         <listitem>
1277           <para>Quits GHCi.  You can also quit by typing a control-D
1278           at the prompt.</para>
1279         </listitem>
1280       </varlistentry>
1281
1282       <varlistentry>
1283         <term>
1284           <literal>:reload</literal>
1285           <indexterm><primary><literal>:reload</literal></primary></indexterm>
1286         </term>
1287         <listitem>
1288           <para>Attempts to reload the current target set (see
1289           <literal>:load</literal>) if any of the modules in the set,
1290           or any dependent module, has changed.  Note that this may
1291           entail loading new modules, or dropping modules which are no
1292           longer indirectly required by the target.</para>
1293         </listitem>
1294       </varlistentry>
1295
1296       <varlistentry>
1297         <term>
1298           <literal>:set</literal> <optional><replaceable>option</replaceable>...</optional>
1299           <indexterm><primary><literal>:set</literal></primary></indexterm>
1300         </term>
1301         <listitem>
1302           <para>Sets various options.  See <xref linkend="ghci-set"/>
1303           for a list of available options.  The
1304           <literal>:set</literal> command by itself shows which
1305           options are currently set.</para>
1306         </listitem>
1307       </varlistentry>
1308
1309       <varlistentry>
1310         <term>
1311           <literal>:set</literal> <literal>args</literal> <replaceable>arg</replaceable> ...
1312           <indexterm><primary><literal>:set args</literal></primary></indexterm>
1313         </term>
1314         <listitem>
1315           <para>Sets the list of arguments which are returned when the
1316           program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary>
1317             </indexterm>.</para>
1318         </listitem>
1319       </varlistentry>
1320
1321       <varlistentry>
1322         <term>
1323            <literal>:set</literal> <literal>editor</literal> <replaceable>cmd</replaceable>
1324         </term>
1325         <listitem>
1326           <para>Sets the command used by <literal>:edit</literal> to
1327           <replaceable>cmd</replaceable>.</para>
1328         </listitem>
1329       </varlistentry>
1330
1331       <varlistentry>
1332         <term>
1333            <literal>:set</literal> <literal>prog</literal> <replaceable>prog</replaceable>
1334            <indexterm><primary><literal>:set prog</literal></primary></indexterm>
1335         </term>
1336         <listitem>
1337           <para>Sets the string to be returned when the program calls
1338           <literal>System.getProgName</literal><indexterm><primary>getProgName</primary>
1339             </indexterm>.</para>
1340         </listitem>
1341       </varlistentry>
1342
1343       <varlistentry>
1344         <term>
1345            <literal>:set</literal> <literal>prompt</literal> <replaceable>prompt</replaceable>
1346         </term>
1347         <listitem>
1348           <para>Sets the string to be used as the prompt in GHCi.
1349           Inside <replaceable>prompt</replaceable>, the sequence
1350           <literal>%s</literal> is replaced by the names of the
1351           modules currently in scope, and <literal>%%</literal> is
1352           replaced by <literal>%</literal>.</para>
1353         </listitem>
1354       </varlistentry>
1355
1356       <varlistentry>
1357         <term>
1358           <literal>:show bindings</literal>
1359           <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
1360         </term>
1361         <listitem>
1362           <para>Show the bindings made at the prompt and their
1363           types.</para>
1364         </listitem>
1365       </varlistentry>
1366
1367       <varlistentry>
1368         <term>
1369           <literal>:show modules</literal>
1370           <indexterm><primary><literal>:show modules</literal></primary></indexterm>
1371         </term>
1372         <listitem>
1373           <para>Show the list of modules currently load.</para>
1374         </listitem>
1375       </varlistentry>
1376       <varlistentry>
1377         <term>
1378           <literal>:sprint</literal>
1379           <indexterm><primary><literal>:sprint</literal></primary></indexterm>
1380         </term>
1381         <listitem>
1382           <para>Prints a semievaluated value without forcing its evaluation.
1383           <literal>:sprint</literal> and its sibling <literal>:print</literal>
1384           are very useful to observe how lazy evaluation works in your code. For example:
1385 <screen>
1386 Prelude> let li = map Just [1..5]
1387 Prelude> :sp li
1388 li - _
1389 Prelude> head li
1390 Just 1
1391 Prelude> :sp li
1392 li - [Just 1 | _]
1393 Prelude> last li
1394 Just 5
1395 Prelude> :sp li
1396 li - [Just 1,_,_,_,Just 5]
1397 </screen>
1398          The example uses <literal>:sprint</literal> to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
1399          with it. Note for instance how <quote>last</quote> traverses all the elements of
1400          the list to compute its result, but without evaluating the individual elements.</para>
1401            <para>Finally note that the Prolog convention of [head | tail] is used by
1402          <literal>:sprint</literal> to display unevaluated lists.
1403           </para>
1404         </listitem>
1405       </varlistentry>
1406       <varlistentry>
1407         <term>
1408           <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional>
1409           <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional>
1410           <indexterm><primary><literal>:etags</literal></primary>
1411           </indexterm>
1412           <indexterm><primary><literal>:etags</literal></primary>
1413           </indexterm>
1414         </term>
1415         <listitem>
1416           <para>Generates a &ldquo;tags&rdquo; file for Vi-style editors
1417             (<literal>:ctags</literal>) or Emacs-style editors (<literal>etags</literal>).  If
1418             no filename is specified, the defaulit <filename>tags</filename> or
1419             <filename>TAGS</filename> is
1420             used, respectively.  Tags for all the functions, constructors and
1421             types in the currently loaded modules are created.  All modules must
1422             be interpreted for these commands to work.</para>
1423           <para>See also <xref linkend="hasktags" />.</para>
1424         </listitem>
1425       </varlistentry>
1426
1427       <varlistentry>
1428         <term>
1429          <literal>:type</literal> <replaceable>expression</replaceable>
1430          <indexterm><primary><literal>:type</literal></primary></indexterm>
1431         </term>
1432         <listitem>
1433           <para>Infers and prints the type of
1434           <replaceable>expression</replaceable>, including explicit
1435           forall quantifiers for polymorphic types.  The monomorphism
1436           restriction is <emphasis>not</emphasis> applied to the
1437           expression during type inference.</para>
1438         </listitem>
1439       </varlistentry>
1440
1441       <varlistentry>
1442         <term>
1443           <literal>:kind</literal> <replaceable>type</replaceable>
1444           <indexterm><primary><literal>:kind</literal></primary></indexterm>
1445         </term>
1446         <listitem>
1447           <para>Infers and prints the kind of
1448           <replaceable>type</replaceable>. The latter can be an arbitrary
1449             type expression, including a partial application of a type constructor,
1450             such as <literal>Either Int</literal>.</para>
1451         </listitem>
1452       </varlistentry>
1453
1454       <varlistentry>
1455         <term>
1456           <literal>:undef</literal> <replaceable>name</replaceable>
1457           <indexterm><primary><literal>:undef</literal></primary></indexterm>
1458         </term>
1459         <listitem>
1460           <para>Undefines the user-defined command
1461           <replaceable>name</replaceable> (see <literal>:def</literal>
1462           above).</para>
1463         </listitem>
1464       </varlistentry>
1465
1466       <varlistentry>
1467         <term>
1468           <literal>:unset</literal> <replaceable>option</replaceable>...
1469           <indexterm><primary><literal>:unset</literal></primary></indexterm>
1470         </term>
1471         <listitem>
1472           <para>Unsets certain options.  See <xref linkend="ghci-set"/>
1473           for a list of available options.</para>
1474         </listitem>
1475       </varlistentry>
1476
1477       <varlistentry>
1478         <term>
1479           <literal>:!</literal> <replaceable>command</replaceable>...
1480           <indexterm><primary><literal>:!</literal></primary></indexterm>
1481           <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm>
1482         </term>
1483         <listitem>
1484           <para>Executes the shell command
1485           <replaceable>command</replaceable>.</para>
1486         </listitem>
1487       </varlistentry>
1488
1489     </variablelist>
1490   </sect1>
1491
1492   <sect1 id="ghci-set">
1493     <title>The <literal>:set</literal> command</title>
1494     <indexterm><primary><literal>:set</literal></primary></indexterm>
1495
1496     <para>The <literal>:set</literal> command sets two types of
1497     options: GHCi options, which begin with
1498     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
1499     options, which begin with &lsquo;-&rsquo;.  </para>
1500
1501     <para>NOTE: at the moment, the <literal>:set</literal> command
1502     doesn't support any kind of quoting in its arguments: quotes will
1503     not be removed and cannot be used to group words together.  For
1504     example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what
1505     you expect.</para>
1506
1507     <sect2>
1508       <title>GHCi options</title>
1509       <indexterm><primary>options</primary><secondary>GHCi</secondary>
1510       </indexterm>
1511
1512       <para>GHCi options may be set using <literal>:set</literal> and
1513       unset using <literal>:unset</literal>.</para>
1514
1515       <para>The available GHCi options are:</para>
1516
1517       <variablelist>
1518         <varlistentry>
1519           <term>
1520             <literal>+r</literal>
1521             <indexterm><primary><literal>+r</literal></primary></indexterm>
1522             <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
1523             <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm>
1524           </term>
1525           <listitem>
1526             <para>Normally, any evaluation of top-level expressions
1527             (otherwise known as CAFs or Constant Applicative Forms) in
1528             loaded modules is retained between evaluations.  Turning
1529             on <literal>+r</literal> causes all evaluation of
1530             top-level expressions to be discarded after each
1531             evaluation (they are still retained
1532             <emphasis>during</emphasis> a single evaluation).</para>
1533
1534             <para>This option may help if the evaluated top-level
1535             expressions are consuming large amounts of space, or if
1536             you need repeatable performance measurements.</para>
1537           </listitem>
1538         </varlistentry>
1539
1540         <varlistentry>
1541           <term>
1542             <literal>+s</literal>
1543             <indexterm><primary><literal>+s</literal></primary></indexterm>
1544           </term>
1545           <listitem>
1546             <para>Display some stats after evaluating each expression,
1547             including the elapsed time and number of bytes allocated.
1548             NOTE: the allocation figure is only accurate to the size
1549             of the storage manager's allocation area, because it is
1550             calculated at every GC.  Hence, you might see values of
1551             zero if no GC has occurred.</para>
1552           </listitem>
1553         </varlistentry>
1554
1555         <varlistentry>
1556           <term>
1557             <literal>+t</literal>
1558             <indexterm><primary><literal>+t</literal></primary></indexterm>
1559           </term>
1560           <listitem>
1561             <para>Display the type of each variable bound after a
1562             statement is entered at the prompt.  If the statement is a
1563             single expression, then the only variable binding will be
1564             for the variable
1565             &lsquo;<literal>it</literal>&rsquo;.</para>
1566           </listitem>
1567         </varlistentry>
1568       </variablelist>
1569     </sect2>
1570
1571     <sect2 id="ghci-cmd-line-options">
1572       <title>Setting GHC command-line options in GHCi</title>
1573
1574       <para>Normal GHC command-line options may also be set using
1575       <literal>:set</literal>.  For example, to turn on
1576       <option>-fglasgow-exts</option>, you would say:</para>
1577
1578 <screen>
1579 Prelude> :set -fglasgow-exts
1580 </screen>
1581
1582       <para>Any GHC command-line option that is designated as
1583       <firstterm>dynamic</firstterm> (see the table in <xref
1584       linkend="flag-reference"/>), may be set using
1585       <literal>:set</literal>.  To unset an option, you can set the
1586       reverse option:</para>
1587       <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
1588
1589 <screen>
1590 Prelude> :set -fno-glasgow-exts
1591 </screen>
1592
1593       <para><xref linkend="flag-reference"/> lists the reverse for each
1594       option where applicable.</para>
1595
1596       <para>Certain static options (<option>-package</option>,
1597       <option>-I</option>, <option>-i</option>, and
1598       <option>-l</option> in particular) will also work, but some may
1599       not take effect until the next reload.</para>
1600       <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
1601     </sect2>
1602   </sect1>
1603   <sect1 id="ghci-debugger">
1604     <title>The GHCi debugger</title>
1605     <indexterm><primary>debugger</primary></indexterm>
1606     <para>GHCi embeds an utility debugger with a very basic set of operations. The debugger
1607           is always available in ghci, you do not need to do anything to activate it. </para>
1608     <para>The following conditions must hold before a module can be debugged in GHCi:
1609       <itemizedlist>
1610          <listitem>
1611            <para>The module must have been loaded interpreted, i.e. not loaded from an <filename>.o</filename> file compiled by ghc </para>
1612          </listitem>
1613          <listitem>
1614            <para>The module must have been loaded with the <literal>-fdebugging</literal> flag
1615            </para></listitem>
1616        </itemizedlist></para>
1617     <sect2><title>Using the debugger</title>
1618     <para>The debugger allows the insertion of breakpoints at specific locations in the source code. These locations are governed by event sites, and not by line as in traditional debuggers such as gdb. </para> <para>
1619       Once a breakpointed event is hit, the debugger stops the execution and you can examine the local variables in scope
1620       in the context of the event, as well as evaluate arbitrary Haskell expressions in
1621       a special interactive prompt. </para><para>
1622
1623      When you are done you issue the <literal>:continue</literal>
1624       command to leave the breakpoint and let the execution go on.
1625      Note that not all the GHCi commands are supported in a breakpoint.
1626
1627     </para>
1628     <sidebar><title>Events</title><?dbfo float-type="left"?>
1629     <para> Events are the places in source code where you can set a breakpoint.
1630 <programlisting>
1631 qsort [] = <co id="name-binding-co"/> []
1632 qsort (x:xs) =
1633    <coref linkend="name-binding-co"/> let left  = <coref linkend="name-binding-co"/> filter (\y -> <co id="lambda-co"/> y &lt; x) xs
1634            right = <coref linkend="name-binding-co"/> case filter (\y -> <coref linkend="lambda-co"/> y &gt; x) xs of
1635                               right_val -> <co id="case-co"/> right_val
1636     in <co id="let-co"/> qsort left ++ [x] ++ qsort right
1637 main = <coref linkend="name-binding-co"/> do {
1638    arg &lt;- <coref linkend="name-binding-co"/> getLine ;
1639    let num = <coref linkend="name-binding-co"/> read arg :: [Int] ;
1640  <co id="stmts-co"/> print (qsort num) ;
1641  <coref linkend="stmts-co"/> putStrLn "GoodBye!" }
1642 </programlisting>
1643      The GHCi debugger recognizes the following event types:
1644     <calloutlist>
1645       <callout arearefs="name-binding-co" id="name-binding">
1646         <para>Function definition and local bindings in let/where</para>
1647     </callout>
1648     <callout arearefs="lambda-co" id="lambda">
1649         <para>Lambda expression entry point</para>
1650     </callout>
1651     <callout arearefs="let-co" id="let">
1652       <para>Let expression body</para>
1653     </callout>
1654     <callout arearefs="case-co" id="case">
1655       <para>Case alternative body</para>
1656     </callout>
1657     <callout arearefs="stmts-co" id="stmts">
1658       <para>do notation statements</para>
1659     </callout>
1660     </calloutlist></para>
1661     <para>In reality however, ghci eliminates some redundant event sites.
1662     For instance, sites with two co-located breakpoint events are coalesced into a single one,
1663     and sites with no bindings in scope are assumed to be uninteresting and no breakpoint can be set in them.</para>
1664     </sidebar>
1665
1666 <para>
1667       You don't need to do anything special in order to start the debugging session.
1668       Simply use ghci to evaluate your Haskell expressions and whenever a breakpoint
1669       is hit, the debugger will enter the stage:
1670 <programlisting>
1671 *main:Main> :break add Main 2
1672 Breakpoint set at (2,15)
1673
1674 *main:Main> qsort [10,9..1]
1675 Local bindings in scope:
1676   x :: a, xs :: [a], left :: [a], right :: [a]
1677
1678 qsort2.hs:2:15-46>
1679 </programlisting>
1680       What is happening here is that GHCi has interrupted the evaluation of
1681       <literal>qsort</literal> at the breakpoint set in line 2, as the prompt indicates.
1682       At this point you can freely explore the contents of the bindings in scope,
1683       but with two catches. </para><para>
1684       First, take into account that due to the lazy nature of Haskell, some of
1685       these bindings may be unevaluated, and that exploring their contents may
1686       trigger a computation. </para><para>
1687       Second: look at the types of the things in scope.
1688       GHCi has left its types parameterised by a variable!
1689       Look at the type of <literal>qsort</literal>, which is
1690       polymorphic on the type of its argument. It does not
1691       tell us really what the types of <literal>x</literal> and <literal>xs</literal> can be.
1692       In general, polymorphic programs deal with polymorphic values,
1693       and this means that some of the bindings available in a breakpoint site
1694       will be parametrically typed.
1695       </para><para>
1696       So, what can we do with a value without concrete type? Very few interesting
1697       things. The <literal>:print</literal> command in ghci allows you to
1698       explore its contents and see if it is evaluated or not.
1699       This is useful because you cannot just type <literal>x</literal> in the
1700       prompt and expect GHCi to return you its value. Perhaps you know for
1701       sure that
1702       <literal>x</literal> is of type <literal>Int</literal>, which is an instance of
1703       <literal>Show</literal>, but GHCi does not have this information.
1704       <literal>:print</literal> however is fine, because it does not need to know the
1705       type to do its work. </para>
1706       <para> Let's go on with the debugging session of the <literal>qsort</literal>
1707       example:
1708 <example id="debuggingEx"><title>A short debugging session</title>
1709 <programlisting>
1710 qsort2.hs:2:15-46> x
1711 This is an untyped, unevaluated computation. You can use seq to
1712 force its evaluation and then :print to recover its type <co id="seq1"/>
1713 qsort2.hs:2:15-46> seq x ()  <co id="seq2"/>
1714 ()
1715 qsort2.hs:2:15-46> x <co id="seq3"/>
1716 This is an untyped, unevaluated computation. You can use seq to
1717 force its evaluation and then :print to recover its type
1718
1719 qsort2.hs:2:15-46> :t x
1720 x :: GHC.Base.Unknown
1721 qsort2.hs:2:15-46> :p x <co id="seq4"/>
1722 x - 10
1723 qsort2.hs:2:15-46> :t x <co id="seq5"/>
1724 x :: Int
1725 </programlisting>
1726 </example>
1727       <calloutlist>
1728         <callout arearefs="seq1">
1729           <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
1730         </callout>
1731         <callout arearefs="seq2">
1732           <para>This line forces the evaluation of <literal>x</literal> </para>
1733         </callout>
1734         <callout arearefs="seq3">
1735           <para>Even though x has been evaluated, we cannot simply use its name to see its value!
1736           This is a bit counterintuitive, but currently in GHCi the type of a binding
1737           cannot be a type variable <literal>a</literal>.
1738           Thus, the binding <literal>x</literal> gets assigned the concrete type Unknown.</para>
1739         </callout>
1740         <callout arearefs="seq4">
1741           <para>We can explore <literal>x</literal> using the <literal>:print</literal>
1742           command, which does find out that <literal>x</literal> is of type Int and prints
1743           its value accordingly.</para>
1744         </callout>
1745         <callout arearefs="seq5">
1746            <para><literal>:print</literal> also updates the type of <literal>x</literal> with
1747            the most concrete type information available.</para>
1748         </callout>
1749       </calloutlist>
1750       The example shows the standard way to proceeed with polymorphic values in a breakpoint.
1751       </para>
1752     </sect2>
1753     <sect2><title>Commands</title>
1754     <para>Breakpoints can be set in several ways using the <literal>:breakpoint</literal> command. Note that you can take advantage of the command abbreviation feature of GHCi and use simply <literal>:bre</literal> to save quite a few keystrokes.
1755 <variablelist>
1756 <varlistentry>
1757   <term>
1758     <literal>:breakpoint add <replaceable>module</replaceable> <replaceable>line</replaceable></literal>
1759   </term>
1760   <listitem><para>
1761     Adds a breakpoint at the first event found at line <literal>line</literal> in <literal>module</literal>, if any.
1762   </para></listitem>
1763 </varlistentry>
1764 <varlistentry>
1765   <term>
1766     <literal>:breakpoint add <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable></literal>
1767   </term>
1768   <listitem><para>
1769     Adds a breakpoint at the first event found after column <literal>column</literal>
1770     at line <literal>line</literal> in <literal>module</literal>, if any.
1771   </para></listitem>
1772 </varlistentry>
1773
1774 <varlistentry>
1775   <term>
1776     <literal>:breakpoint continue</literal>
1777   </term>
1778   <listitem><para>
1779    When at a breakpoint, continue execution up to the next breakpoint
1780    or end of evaluation.
1781   </para></listitem>
1782 </varlistentry>
1783
1784 <varlistentry>
1785   <term>
1786     <literal>:continue</literal>
1787   </term>
1788   <listitem><para>
1789       Shortcut for <literal>:breakpoint continue</literal>
1790   </para></listitem>
1791 </varlistentry>
1792
1793 <varlistentry>
1794   <term>
1795     <literal>:breakpoint list</literal>
1796   </term>
1797   <listitem><para>
1798     Lists the currently set up breakpoints.
1799   </para></listitem>
1800 </varlistentry>
1801 <varlistentry>
1802   <term>
1803     <literal>:breakpoint del <replaceable>num</replaceable></literal>
1804   </term>
1805   <listitem><para>
1806     Deletes the breakpoint at position <literal>num</literal> in the list of
1807     breakpoints shown by <literal>:breakpoint list</literal>.
1808   </para></listitem>
1809 </varlistentry>
1810 <varlistentry>
1811   <term>
1812     <literal>:breakpoint del <replaceable>module</replaceable> <replaceable>line</replaceable></literal>
1813   </term>
1814   <listitem><para>
1815   Dels the breakpoint at line <literal>line</literal> in <literal>module</literal>, if any.
1816   </para></listitem>
1817 </varlistentry>
1818 <varlistentry>
1819   <term>
1820     <literal>:breakpoint del <replaceable>module</replaceable> <replaceable>line</replaceable><replaceable>col</replaceable> </literal>
1821   </term>
1822   <listitem><para>
1823     Deletes the first breakpoint found after column <literal>column</literal>
1824     at line <literal>line</literal> in <literal>module</literal>, if any.
1825   </para></listitem>
1826 </varlistentry>
1827 <varlistentry>
1828   <term>
1829     <literal>:breakpoint stop </literal>
1830   </term>
1831   <listitem><para>
1832     Stop the program being executed. This interrupts a debugging session
1833     and returns to the top level.
1834   </para></listitem>
1835 </varlistentry>
1836 </variablelist></para>
1837     </sect2>
1838     <sect2><title>Limitations</title>
1839      <para>
1840       <itemizedlist>
1841         <listitem><para>
1842           Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available
1843           at the scope of a breakpoint if there is a explicit type signature.
1844         </para></listitem>
1845       </itemizedlist>
1846       <itemizedlist>
1847         <listitem><para>
1848           Modules compiled by GHCi under the <literal>-fdebugging
1849         </literal> flag  will perform slower: the debugging mode introduces some overhead.
1850       Modules compiled to object code by ghc are not affected.
1851         </para></listitem>
1852       </itemizedlist>
1853      </para>
1854     </sect2>
1855     <sect2><title>Tips</title>
1856       <variablelist>
1857         <varlistentry><term>* Use PRAGMAs to fine tune which modules are loaded under debugging mode</term>
1858           <listitem>
1859             <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
1860           </listitem>
1861         </varlistentry>
1862         <varlistentry> <term>* Repeated use of <literal>seq</literal> and
1863             <literal>:print</literal> may be necessary to observe unevaluated
1864             untyped bindings</term>
1865           <listitem><para>see <xref linkend="debuggingEx"/>
1866           </para></listitem>
1867         </varlistentry>
1868         <varlistentry> <term> * <literal>GHC.Exts.unsafeCoerce</literal> can help if you are positive about the type of a binding</term>
1869           <listitem><para><programlisting>
1870 type MyLongType a = [Maybe [Maybe a]]
1871
1872 main:Main> :m +GHC.Exts
1873 main:Main> main
1874 Local bindings in scope:
1875   x :: a
1876 Main.hs:15> let x' = unsafeCoerce x :: MyLongType Bool
1877 Main.hs:15> x'
1878 [Just [Just False, Just True]]
1879           </programlisting>
1880            Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault
1881           </para></listitem>
1882         </varlistentry>
1883         <varlistentry> <term> * The undocumented (and unsupported) &colon;force command </term>
1884           <listitem><para>
1885               equivalent to <literal> :print</literal> with automatic
1886               <literal>seq</literal> forcing,
1887               may prove useful to replace sequences of <literal>seq</literal> and
1888               <literal>&colon;print</literal> in some situations.
1889           </para></listitem>
1890         </varlistentry>
1891     </variablelist>
1892     </sect2></sect1>
1893   <sect1 id="ghci-dot-files">
1894     <title>The <filename>.ghci</filename> file</title>
1895     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
1896     </indexterm>
1897     <indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
1898     </indexterm>
1899
1900     <para>When it starts, GHCi always reads and executes commands from
1901     <filename>$HOME/.ghci</filename>, followed by
1902     <filename>./.ghci</filename>.</para>
1903
1904     <para>The <filename>.ghci</filename> in your home directory is
1905     most useful for turning on favourite options (eg. <literal>:set
1906     +s</literal>), and defining useful macros.  Placing a
1907     <filename>.ghci</filename> file in a directory with a Haskell
1908     project is a useful way to set certain project-wide options so you
1909     don't have to type them everytime you start GHCi: eg. if your
1910     project uses GHC extensions and CPP, and has source files in three
1911     subdirectories A B and C, you might put the following lines in
1912     <filename>.ghci</filename>:</para>
1913
1914 <screen>
1915 :set -fglasgow-exts -cpp
1916 :set -iA:B:C
1917 </screen>
1918
1919     <para>(Note that strictly speaking the <option>-i</option> flag is
1920     a static one, but in fact it works to set it using
1921     <literal>:set</literal> like this.  The changes won't take effect
1922     until the next <literal>:load</literal>, though.)</para>
1923
1924     <para>Two command-line options control whether the
1925     <filename>.ghci</filename> files are read:</para>
1926
1927     <variablelist>
1928       <varlistentry>
1929         <term>
1930           <option>-ignore-dot-ghci</option>
1931           <indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm>
1932         </term>
1933         <listitem>
1934           <para>Don't read either <filename>./.ghci</filename> or
1935           <filename>$HOME/.ghci</filename> when starting up.</para>
1936         </listitem>
1937       </varlistentry>
1938       <varlistentry>
1939         <term>
1940           <option>-read-dot-ghci</option>
1941           <indexterm><primary><option>-read-dot-ghci</option></primary></indexterm>
1942         </term>
1943         <listitem>
1944           <para>Read <filename>.ghci</filename> and
1945           <filename>$HOME/.ghci</filename>.  This is normally the
1946           default, but the <option>-read-dot-ghci</option> option may
1947           be used to override a previous
1948           <option>-ignore-dot-ghci</option> option.</para>
1949         </listitem>
1950       </varlistentry>
1951     </variablelist>
1952
1953   </sect1>
1954
1955   <sect1 id="ghci-obj">
1956     <title>Compiling to object code inside GHCi</title>
1957
1958     <para>By default, GHCi compiles Haskell source code into byte-code
1959     that is interpreted by the runtime system.  GHCi can also compile
1960     Haskell code to object code: to turn on this feature, use the
1961     <option>-fobject-code</option> flag either on the command line or
1962     with <literal>:set</literal> (the option
1963     <option>-fbyte-code</option> restores byte-code compilation
1964     again).  Compiling to object code takes longer, but typically the
1965     code will execute 10-20 times faster than byte-code.</para>
1966
1967     <para>Compiling to object code inside GHCi is particularly useful
1968     if you are developing a compiled application, because the
1969     <literal>:reload</literal> command typically runs much faster than
1970     restarting GHC with <option>--make</option> from the command-line,
1971     because all the interface files are already cached in
1972     memory.</para>
1973
1974     <para>There are disadvantages to compiling to object-code: you
1975     can't set breakpoints in object-code modules, for example.  Only
1976     the exports of an object-code module will be visible in GHCi,
1977     rather than all top-level bindings as in interpreted
1978     modules.</para>
1979   </sect1>
1980
1981   <sect1 id="ghci-faq">
1982     <title>FAQ and Things To Watch Out For</title>
1983
1984     <variablelist>
1985       <varlistentry>
1986         <term>The interpreter can't load modules with foreign export
1987         declarations!</term>
1988         <listitem>
1989           <para>Unfortunately not.  We haven't implemented it yet.
1990           Please compile any offending modules by hand before loading
1991           them into GHCi.</para>
1992         </listitem>
1993       </varlistentry>
1994
1995       <varlistentry>
1996         <term>
1997           <literal>-O</literal> doesn't work with GHCi!
1998           <indexterm><primary><option>-O</option></primary></indexterm>
1999          </term>
2000         <listitem>
2001           <para>For technical reasons, the bytecode compiler doesn't
2002           interact well with one of the optimisation passes, so we
2003           have disabled optimisation when using the interpreter.  This
2004           isn't a great loss: you'll get a much bigger win by
2005           compiling the bits of your code that need to go fast, rather
2006           than interpreting them with optimisation turned on.</para>
2007         </listitem>
2008       </varlistentry>
2009
2010       <varlistentry>
2011         <term>Unboxed tuples don't work with GHCi</term>
2012         <listitem>
2013           <para>That's right.  You can always compile a module that
2014           uses unboxed tuples and load it into GHCi, however.
2015           (Incidentally the previous point, namely that
2016           <literal>-O</literal> is incompatible with GHCi, is because
2017           the bytecode compiler can't deal with unboxed
2018           tuples).</para>
2019         </listitem>
2020       </varlistentry>
2021
2022       <varlistentry>
2023         <term>Concurrent threads don't carry on running when GHCi is
2024         waiting for input.</term>
2025         <listitem>
2026           <para>This should work, as long as your GHCi was built with
2027           the <option>-threaded</option> switch, which is the default.
2028           Consult whoever supplied your GHCi installation.</para>
2029         </listitem>
2030       </varlistentry>
2031
2032       <varlistentry>
2033         <term>After using <literal>getContents</literal>, I can't use
2034         <literal>stdin</literal> again until I do
2035         <literal>:load</literal> or <literal>:reload</literal>.</term>
2036
2037         <listitem>
2038           <para>This is the defined behaviour of
2039           <literal>getContents</literal>: it puts the stdin Handle in
2040           a state known as <firstterm>semi-closed</firstterm>, wherein
2041           any further I/O operations on it are forbidden.  Because I/O
2042           state is retained between computations, the semi-closed
2043           state persists until the next <literal>:load</literal> or
2044           <literal>:reload</literal> command.</para>
2045
2046           <para>You can make <literal>stdin</literal> reset itself
2047           after every evaluation by giving GHCi the command
2048           <literal>:set +r</literal>.  This works because
2049           <literal>stdin</literal> is just a top-level expression that
2050           can be reverted to its unevaluated state in the same way as
2051           any other top-level expression (CAF).</para>
2052         </listitem>
2053       </varlistentry>
2054
2055       <varlistentry>
2056         <term>I can't use Control-C to interrupt computations in
2057           GHCi on Windows.</term>
2058         <listitem>
2059           <para>See <xref linkend="ghci-windows"/></para>
2060         </listitem>
2061       </varlistentry>
2062     </variablelist>
2063   </sect1>
2064
2065 </chapter>
2066
2067 <!-- Emacs stuff:
2068      ;;; Local Variables: ***
2069      ;;; mode: xml ***
2070      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
2071      ;;; End: ***
2072  -->