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>
  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>
 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>
 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         <itemizedlist>
 751             <listitem><para> The type variable <literal>a</literal>
 752         appears in no other constraints </para></listitem>
 753             <listitem><para> All the classes <literal>Ci</literal> are standard.</para></listitem>
 754             <listitem><para> At least one of the classes <literal>Ci</literal> is
 755             numeric.</para></listitem>
 756       </itemizedlist>
 757    At the GHCi prompt, the second and third rules are relaxed as follows
 758    (differences italicised):
 759         <itemizedlist>
 760             <listitem><para> <emphasis>All</emphasis> of the classes
 761             <literal>Ci</literal> are single-parameter type classes.</para></listitem>
 762             <listitem><para> At least one of the classes <literal>Ci</literal> is
 763             numeric, <emphasis>or is <literal>Show</literal>,
 764                 <literal>Eq</literal>, or <literal>Ord</literal></emphasis>.</para></listitem>
 765       </itemizedlist>
 766    The same type-default behaviour can be enabled in an ordinary Haskell
 767    module, using the flag <literal>-fextended-default-rules</literal>.
 768    </para>
 769     </sect2>
 770   </sect1>
 771
 772   <sect1 id="ghci-invocation">
 773     <title>Invoking GHCi</title>
 774     <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
 775     <indexterm><primary><option>&ndash;&ndash;interactive</option></primary></indexterm>
 776
 777     <para>GHCi is invoked with the command <literal>ghci</literal> or
 778     <literal>ghc &ndash;&ndash;interactive</literal>.  One or more modules or
 779     filenames can also be specified on the command line; this
 780     instructs GHCi to load the specified modules or filenames (and all
 781     the modules they depend on), just as if you had said
 782     <literal>:load <replaceable>modules</replaceable></literal> at the
 783     GHCi prompt (see <xref linkend="ghci-commands"/>).  For example, to
 784     start GHCi and load the program whose topmost module is in the
 785     file <literal>Main.hs</literal>, we could say:</para>
 786
 787 <screen>
 788 $ ghci Main.hs
 789 </screen>
 790
 791     <para>Most of the command-line options accepted by GHC (see <xref
 792     linkend="using-ghc"/>) also make sense in interactive mode.  The ones
 793     that don't make sense are mostly obvious; for example, GHCi
 794     doesn't generate interface files, so options related to interface
 795     file generation won't have any effect.</para>
 796
 797     <sect2>
 798       <title>Packages</title>
 799       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
 800
 801       <para>Most packages (see <xref linkend="using-packages"/>) are
 802       available without needing to specify any extra flags at all:
 803       they will be automatically loaded the first time they are
 804       needed.</para>
 805
 806       <para>For non-auto packages, however, you need to request the
 807       package be loaded by using the <literal>-package</literal> flag:</para>
 808
 809 <screen>
 810 $ ghci -package readline
 811    ___         ___ _
 812   / _ \ /\  /\/ __(_)
 813  / /_\// /_/ / /  | |      GHC Interactive, version 6.6, for Haskell 98.
 814 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 815 \____/\/ /_/\____/|_|      Type :? for help.
 816
 817 Loading package base ... linking ... done.
 818 Loading package readline-1.0 ... linking ... done.
 819 Prelude>
 820 </screen>
 821
 822       <para>The following command works to load new packages into a
 823       running GHCi:</para>
 824
 825 <screen>
 826 Prelude> :set -package <replaceable>name</replaceable>
 827 </screen>
 828
 829       <para>But note that doing this will cause all currently loaded
 830       modules to be unloaded, and you'll be dumped back into the
 831       <literal>Prelude</literal>.</para>
 832     </sect2>
 833
 834     <sect2>
 835       <title>Extra libraries</title>
 836       <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
 837
 838       <para>Extra libraries may be specified on the command line using
 839       the normal <literal>-l<replaceable>lib</replaceable></literal>
 840       option.  (The term <emphasis>library</emphasis> here refers to
 841       libraries of foreign object code; for using libraries of Haskell
 842       source code, see <xref linkend="ghci-modules-filenames"/>.) For
 843       example, to load the &ldquo;m&rdquo; library:</para>
 844
 845 <screen>
 846 $ ghci -lm
 847 </screen>
 848
 849       <para>On systems with <literal>.so</literal>-style shared
 850       libraries, the actual library loaded will the
 851       <filename>lib<replaceable>lib</replaceable>.so</filename>.  GHCi
 852       searches the following places for libraries, in this order:</para>
 853
 854       <itemizedlist>
 855         <listitem>
 856           <para>Paths specified using the
 857           <literal>-L<replaceable>path</replaceable></literal>
 858           command-line option,</para>
 859         </listitem>
 860         <listitem>
 861           <para>the standard library search path for your system,
 862           which on some systems may be overridden by setting the
 863           <literal>LD_LIBRARY_PATH</literal> environment
 864           variable.</para>
 865         </listitem>
 866       </itemizedlist>
 867
 868       <para>On systems with <literal>.dll</literal>-style shared
 869       libraries, the actual library loaded will be
 870       <filename><replaceable>lib</replaceable>.dll</filename>.  Again,
 871       GHCi will signal an error if it can't find the library.</para>
 872
 873       <para>GHCi can also load plain object files
 874       (<literal>.o</literal> or <literal>.obj</literal> depending on
 875       your platform) from the command-line.  Just add the name the
 876       object file to the command line.</para>
 877
 878       <para>Ordering of <option>-l</option> options matters: a library
 879       should be mentioned <emphasis>before</emphasis> the libraries it
 880       depends on (see <xref linkend="options-linker"/>).</para>
 881     </sect2>
 882
 883   </sect1>
 884
 885   <sect1 id="ghci-commands">
 886     <title>GHCi commands</title>
 887
 888     <para>GHCi commands all begin with
 889     &lsquo;<literal>:</literal>&rsquo; and consist of a single command
 890     name followed by zero or more parameters.  The command name may be
 891     abbreviated, with ambiguities being resolved in favour of the more
 892     commonly used commands.</para>
 893
 894     <variablelist>
 895       <varlistentry>
 896         <term>
 897           <literal>:add</literal> <replaceable>module</replaceable> ...
 898           <indexterm><primary><literal>:add</literal></primary></indexterm>
 899         </term>
 900         <listitem>
 901           <para>Add <replaceable>module</replaceable>(s) to the
 902           current <firstterm>target set</firstterm>, and perform a
 903           reload.</para>
 904         </listitem>
 905       </varlistentry>
 906
 907       <varlistentry>
 908         <term>
 909           <literal>:breakpoint</literal> <replaceable>list|add|del|stop|step</replaceable> ...
 910           <indexterm><primary><literal>:breakpoint</literal></primary></indexterm>
 911         </term>
 912         <listitem>
 913           <para>Permits to add, delete or list the breakpoints in a debugging session.
 914           In order to make this command available, the
 915           <literal>-fdebugging</literal> flag must be active. The easiest way is to launch
 916           GHCi with the <literal>-fdebugging</literal> option. For more
 917           details on how the debugger works, see <xref linkend="ghci-debugger"/>.
 918           </para>
 919         </listitem>
 920       </varlistentry>
 921
 922       <varlistentry>
 923         <term>
 924           <literal>:browse</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
 925           <indexterm><primary><literal>:browse</literal></primary></indexterm>
 926         </term>
 927         <listitem>
 928           <para>Displays the identifiers defined by the module
 929           <replaceable>module</replaceable>, which must be either
 930           loaded into GHCi or be a member of a package.  If the
 931           <literal>*</literal> symbol is placed before the module
 932           name, then <emphasis>all</emphasis> the identifiers defined
 933           in <replaceable>module</replaceable> are shown; otherwise
 934           the list is limited to the exports of
 935           <replaceable>module</replaceable>.  The
 936           <literal>*</literal>-form is only available for modules
 937           which are interpreted; for compiled modules (including
 938           modules from packages) only the non-<literal>*</literal>
 939           form of <literal>:browse</literal> is available.</para>
 940         </listitem>
 941       </varlistentry>
 942
 943       <varlistentry>
 944         <term>
 945           <literal>:cd</literal> <replaceable>dir</replaceable>
 946           <indexterm><primary><literal>:cd</literal></primary></indexterm>
 947         </term>
 948         <listitem>
 949           <para>Changes the current working directory to
 950           <replaceable>dir</replaceable>.  A
 951           &lsquo;<literal>&tilde;</literal>&rsquo; symbol at the
 952           beginning of <replaceable>dir</replaceable> will be replaced
 953           by the contents of the environment variable
 954           <literal>HOME</literal>.</para>
 955
 956           <para>NOTE: changing directories causes all currently loaded
 957           modules to be unloaded.  This is because the search path is
 958           usually expressed using relative directories, and changing
 959           the search path in the middle of a session is not
 960           supported.</para>
 961         </listitem>
 962       </varlistentry>
 963
 964       <varlistentry>
 965         <term>
 966           <literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable>
 967           <indexterm><primary><literal>:def</literal></primary></indexterm>
 968         </term>
 969         <listitem>
 970           <para>The command <literal>:def</literal>
 971           <replaceable>name</replaceable>
 972           <replaceable>expr</replaceable> defines a new GHCi command
 973           <literal>:<replaceable>name</replaceable></literal>,
 974           implemented by the Haskell expression
 975           <replaceable>expr</replaceable>, which must have type
 976           <literal>String -> IO String</literal>.  When
 977           <literal>:<replaceable>name</replaceable>
 978           <replaceable>args</replaceable></literal> is typed at the
 979           prompt, GHCi will run the expression
 980           <literal>(<replaceable>name</replaceable>
 981           <replaceable>args</replaceable>)</literal>, take the
 982           resulting <literal>String</literal>, and feed it back into
 983           GHCi as a new sequence of commands.  Separate commands in
 984           the result must be separated by
 985           &lsquo;<literal>\n</literal>&rsquo;.</para>
 986
 987           <para>That's all a little confusing, so here's a few
 988           examples.  To start with, here's a new GHCi command which
 989           doesn't take any arguments or produce any results, it just
 990           outputs the current date &amp; time:</para>
 991
 992 <screen>
 993 Prelude> let date _ = Time.getClockTime >>= print >> return ""
 994 Prelude> :def date date
 995 Prelude> :date
 996 Fri Mar 23 15:16:40 GMT 2001
 997 </screen>
 998
 999           <para>Here's an example of a command that takes an argument.
1000           It's a re-implementation of <literal>:cd</literal>:</para>
1001
1002 <screen>
1003 Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
1004 Prelude> :def mycd mycd
1005 Prelude> :mycd ..
1006 </screen>
1007
1008           <para>Or I could define a simple way to invoke
1009           &ldquo;<literal>ghc &ndash;&ndash;make Main</literal>&rdquo; in the
1010           current directory:</para>
1011
1012 <screen>
1013 Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")
1014 </screen>
1015
1016           <para>We can define a command that reads GHCi input from a
1017           file.  This might be useful for creating a set of bindings
1018           that we want to repeatedly load into the GHCi session:</para>
1019
1020 <screen>
1021 Prelude> :def . readFile
1022 Prelude> :. cmds.ghci
1023 </screen>
1024
1025           <para>Notice that we named the command
1026           <literal>:.</literal>, by analogy with the
1027           &lsquo;<literal>.</literal>&rsquo; Unix shell command that
1028           does the same thing.</para>
1029         </listitem>
1030       </varlistentry>
1031
1032       <varlistentry>
1033         <term>
1034           <literal>:edit <optional><replaceable>file</replaceable></optional></literal>
1035           <indexterm><primary><literal>:edit</literal></primary></indexterm>
1036         </term>
1037         <listitem>
1038           <para>Opens an editor to edit the file
1039           <replaceable>file</replaceable>, or the most recently loaded
1040           module if <replaceable>file</replaceable> is omitted.  The
1041           editor to invoke is taken from the <literal>EDITOR</literal>
1042           environment variable, or a default editor on your system if
1043           <literal>EDITOR</literal> is not set.  You can change the
1044           editor using <literal>:set editor</literal>.</para>
1045         </listitem>
1046       </varlistentry>
1047
1048       <varlistentry>
1049         <term>
1050           <literal>:help</literal>
1051           <indexterm><primary><literal>:help</literal></primary></indexterm>
1052         </term>
1053         <term>
1054           <literal>:?</literal>
1055           <indexterm><primary><literal>:?</literal></primary></indexterm>
1056         </term>
1057         <listitem>
1058           <para>Displays a list of the available commands.</para>
1059         </listitem>
1060       </varlistentry>
1061
1062       <varlistentry>
1063         <term>
1064           <literal>:info</literal> <replaceable>name</replaceable> ...
1065           <indexterm><primary><literal>:info</literal></primary></indexterm>
1066         </term>
1067         <listitem>
1068           <para>Displays information about the given name(s).  For
1069           example, if <replaceable>name</replaceable> is a class, then
1070           the class methods and their types will be printed;  if
1071           <replaceable>name</replaceable> is a type constructor, then
1072           its definition will be printed;  if
1073           <replaceable>name</replaceable> is a function, then its type
1074           will be printed.  If <replaceable>name</replaceable> has
1075           been loaded from a source file, then GHCi will also display
1076           the location of its definition in the source.</para>
1077         </listitem>
1078       </varlistentry>
1079
1080       <varlistentry>
1081         <term>
1082           <literal>:load</literal> <replaceable>module</replaceable> ...
1083           <indexterm><primary><literal>:load</literal></primary></indexterm>
1084         </term>
1085         <listitem>
1086           <para>Recursively loads the specified
1087           <replaceable>module</replaceable>s, and all the modules they
1088           depend on.  Here, each <replaceable>module</replaceable>
1089           must be a module name or filename, but may not be the name
1090           of a module in a package.</para>
1091
1092           <para>All previously loaded modules, except package modules,
1093           are forgotten.  The new set of modules is known as the
1094           <firstterm>target set</firstterm>.  Note that
1095           <literal>:load</literal> can be used without any arguments
1096           to unload all the currently loaded modules and
1097           bindings.</para>
1098
1099           <para>After a <literal>:load</literal> command, the current
1100           context is set to:</para>
1101
1102           <itemizedlist>
1103             <listitem>
1104               <para><replaceable>module</replaceable>, if it was loaded
1105               successfully, or</para>
1106             </listitem>
1107             <listitem>
1108               <para>the most recently successfully loaded module, if
1109               any other modules were loaded as a result of the current
1110               <literal>:load</literal>, or</para>
1111             </listitem>
1112             <listitem>
1113               <para><literal>Prelude</literal> otherwise.</para>
1114             </listitem>
1115           </itemizedlist>
1116         </listitem>
1117       </varlistentry>
1118
1119       <varlistentry>
1120         <term>
1121           <literal>:main <replaceable>arg<subscript>1</subscript></replaceable> ... <replaceable>arg<subscript>n</subscript></replaceable></literal>
1122           <indexterm><primary><literal>:main</literal></primary></indexterm>
1123         </term>
1124         <listitem>
1125           <para>
1126             When a program is compiled and executed, it can use the
1127             <literal>getArgs</literal> function to access the
1128             command-line arguments.
1129             However, we cannot simply pass the arguments to the
1130             <literal>main</literal> function while we are testing in ghci,
1131             as the <literal>main</literal> function doesn't take its
1132             directly.
1133           </para>
1134
1135           <para>
1136             Instead, we can use the <literal>:main</literal> command.
1137             This runs whatever <literal>main</literal> is in scope, with
1138             any arguments being treated the same as command-line arguments,
1139             e.g.:
1140           </para>
1141
1142 <screen>
1143 Prelude> let main = System.Environment.getArgs >>= print
1144 Prelude> :main foo bar
1145 ["foo","bar"]
1146 </screen>
1147
1148         </listitem>
1149       </varlistentry>
1150
1151       <varlistentry>
1152         <term>
1153           <literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal>
1154           <indexterm><primary><literal>:module</literal></primary></indexterm>
1155         </term>
1156         <listitem>
1157           <para>Sets or modifies the current context for statements
1158           typed at the prompt.  See <xref linkend="ghci-scope"/> for
1159           more details.</para>
1160         </listitem>
1161       </varlistentry>
1162
1163       <varlistentry>
1164         <term>
1165           <literal>:print </literal> <replaceable>names</replaceable> ...
1166           <indexterm><primary><literal>:print</literal></primary></indexterm>
1167         </term>
1168         <listitem>
1169           <para> Prints a semievaluated value without forcing its evaluation.
1170           <literal>:print </literal> works just like <literal>:sprint</literal> but additionally,
1171            <literal>:print</literal> binds the unevaluated parts -called
1172            <quote>suspensions</quote>-
1173           to names which you can play with. For example:
1174 <screen>
1175 Prelude> let li = map Just [1..5]
1176 Prelude> :sp li
1177 li - _
1178 Prelude> :p li
1179 li - (_t1::[Maybe Integer])
1180 Prelude> head li
1181 Just 1
1182 Prelude> :sp li
1183 li - [Just 1 | _]
1184 Prelude> :p li
1185 li - [Just 1 | (_t2::[Maybe Integer])]
1186 Prelude> last li
1187 Just 5
1188 Prelude> :sp li
1189 li - [Just 1,_,_,_,Just 5]
1190 Prelude> :p li
1191 li - [Just 1,(_t3::Maybe Integer),(_t4::Maybe Integer),(_t5::Maybe Integer),Just 4]
1192 Prelude> _t4
1193 Just 3
1194 Prelude> :p li
1195 li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4]
1196 </screen>
1197          The example uses <literal>:print</literal> and  <literal>:sprint</literal>
1198          to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
1199          with it. Note for instance how <quote>last</quote> traverses all the elements of
1200          the list to compute its result, but without evaluating the individual elements.</para>
1201            <para>Finally note that the Prolog convention of [head | tail] is used by
1202          <literal>:sprint</literal> to display unevaluated lists.
1203           </para>
1204         </listitem>
1205       </varlistentry>
1206
1207       <varlistentry>
1208         <term>
1209           <literal>:quit</literal>
1210           <indexterm><primary><literal>:quit</literal></primary></indexterm>
1211         </term>
1212         <listitem>
1213           <para>Quits GHCi.  You can also quit by typing a control-D
1214           at the prompt.</para>
1215         </listitem>
1216       </varlistentry>
1217
1218       <varlistentry>
1219         <term>
1220           <literal>:reload</literal>
1221           <indexterm><primary><literal>:reload</literal></primary></indexterm>
1222         </term>
1223         <listitem>
1224           <para>Attempts to reload the current target set (see
1225           <literal>:load</literal>) if any of the modules in the set,
1226           or any dependent module, has changed.  Note that this may
1227           entail loading new modules, or dropping modules which are no
1228           longer indirectly required by the target.</para>
1229         </listitem>
1230       </varlistentry>
1231
1232       <varlistentry>
1233         <term>
1234           <literal>:set</literal> <optional><replaceable>option</replaceable>...</optional>
1235           <indexterm><primary><literal>:set</literal></primary></indexterm>
1236         </term>
1237         <listitem>
1238           <para>Sets various options.  See <xref linkend="ghci-set"/>
1239           for a list of available options.  The
1240           <literal>:set</literal> command by itself shows which
1241           options are currently set.</para>
1242         </listitem>
1243       </varlistentry>
1244
1245       <varlistentry>
1246         <term>
1247           <literal>:set</literal> <literal>args</literal> <replaceable>arg</replaceable> ...
1248           <indexterm><primary><literal>:set args</literal></primary></indexterm>
1249         </term>
1250         <listitem>
1251           <para>Sets the list of arguments which are returned when the
1252           program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary>
1253             </indexterm>.</para>
1254         </listitem>
1255       </varlistentry>
1256
1257       <varlistentry>
1258         <term>
1259            <literal>:set</literal> <literal>editor</literal> <replaceable>cmd</replaceable>
1260         </term>
1261         <listitem>
1262           <para>Sets the command used by <literal>:edit</literal> to
1263           <replaceable>cmd</replaceable>.</para>
1264         </listitem>
1265       </varlistentry>
1266
1267       <varlistentry>
1268         <term>
1269            <literal>:set</literal> <literal>prog</literal> <replaceable>prog</replaceable>
1270            <indexterm><primary><literal>:set prog</literal></primary></indexterm>
1271         </term>
1272         <listitem>
1273           <para>Sets the string to be returned when the program calls
1274           <literal>System.getProgName</literal><indexterm><primary>getProgName</primary>
1275             </indexterm>.</para>
1276         </listitem>
1277       </varlistentry>
1278
1279       <varlistentry>
1280         <term>
1281            <literal>:set</literal> <literal>prompt</literal> <replaceable>prompt</replaceable>
1282         </term>
1283         <listitem>
1284           <para>Sets the string to be used as the prompt in GHCi.
1285           Inside <replaceable>prompt</replaceable>, the sequence
1286           <literal>%s</literal> is replaced by the names of the
1287           modules currently in scope, and <literal>%%</literal> is
1288           replaced by <literal>%</literal>.</para>
1289         </listitem>
1290       </varlistentry>
1291
1292       <varlistentry>
1293         <term>
1294           <literal>:show bindings</literal>
1295           <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
1296         </term>
1297         <listitem>
1298           <para>Show the bindings made at the prompt and their
1299           types.</para>
1300         </listitem>
1301       </varlistentry>
1302
1303       <varlistentry>
1304         <term>
1305           <literal>:show modules</literal>
1306           <indexterm><primary><literal>:show modules</literal></primary></indexterm>
1307         </term>
1308         <listitem>
1309           <para>Show the list of modules currently load.</para>
1310         </listitem>
1311       </varlistentry>
1312       <varlistentry>
1313         <term>
1314           <literal>:sprint</literal>
1315           <indexterm><primary><literal>:sprint</literal></primary></indexterm>
1316         </term>
1317         <listitem>
1318           <para>Prints a semievaluated value without forcing its evaluation.
1319           <literal>:sprint</literal> and its sibling <literal>:print</literal>
1320           are very useful to observe how lazy evaluation works in your code. For example:
1321 <screen>
1322 Prelude> let li = map Just [1..5]
1323 Prelude> :sp li
1324 li - _
1325 Prelude> head li
1326 Just 1
1327 Prelude> :sp li
1328 li - [Just 1 | _]
1329 Prelude> last li
1330 Just 5
1331 Prelude> :sp li
1332 li - [Just 1,_,_,_,Just 5]
1333 </screen>
1334          The example uses <literal>:sprint</literal> to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
1335          with it. Note for instance how <quote>last</quote> traverses all the elements of
1336          the list to compute its result, but without evaluating the individual elements.</para>
1337            <para>Finally note that the Prolog convention of [head | tail] is used by
1338          <literal>:sprint</literal> to display unevaluated lists.
1339           </para>
1340         </listitem>
1341       </varlistentry>
1342       <varlistentry>
1343         <term>
1344           <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional>
1345           <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional>
1346           <indexterm><primary><literal>:etags</literal></primary>
1347           </indexterm>
1348           <indexterm><primary><literal>:etags</literal></primary>
1349           </indexterm>
1350         </term>
1351         <listitem>
1352           <para>Generates a &ldquo;tags&rdquo; file for Vi-style editors
1353             (<literal>:ctags</literal>) or Emacs-style editors (<literal>etags</literal>).  If
1354             no filename is specified, the defaulit <filename>tags</filename> or
1355             <filename>TAGS</filename> is
1356             used, respectively.  Tags for all the functions, constructors and
1357             types in the currently loaded modules are created.  All modules must
1358             be interpreted for these commands to work.</para>
1359           <para>See also <xref linkend="hasktags" />.</para>
1360         </listitem>
1361       </varlistentry>
1362
1363       <varlistentry>
1364         <term>
1365          <literal>:type</literal> <replaceable>expression</replaceable>
1366          <indexterm><primary><literal>:type</literal></primary></indexterm>
1367         </term>
1368         <listitem>
1369           <para>Infers and prints the type of
1370           <replaceable>expression</replaceable>, including explicit
1371           forall quantifiers for polymorphic types.  The monomorphism
1372           restriction is <emphasis>not</emphasis> applied to the
1373           expression during type inference.</para>
1374         </listitem>
1375       </varlistentry>
1376
1377       <varlistentry>
1378         <term>
1379           <literal>:kind</literal> <replaceable>type</replaceable>
1380           <indexterm><primary><literal>:kind</literal></primary></indexterm>
1381         </term>
1382         <listitem>
1383           <para>Infers and prints the kind of
1384           <replaceable>type</replaceable>. The latter can be an arbitrary
1385             type expression, including a partial application of a type constructor,
1386             such as <literal>Either Int</literal>.</para>
1387         </listitem>
1388       </varlistentry>
1389
1390       <varlistentry>
1391         <term>
1392           <literal>:undef</literal> <replaceable>name</replaceable>
1393           <indexterm><primary><literal>:undef</literal></primary></indexterm>
1394         </term>
1395         <listitem>
1396           <para>Undefines the user-defined command
1397           <replaceable>name</replaceable> (see <literal>:def</literal>
1398           above).</para>
1399         </listitem>
1400       </varlistentry>
1401
1402       <varlistentry>
1403         <term>
1404           <literal>:unset</literal> <replaceable>option</replaceable>...
1405           <indexterm><primary><literal>:unset</literal></primary></indexterm>
1406         </term>
1407         <listitem>
1408           <para>Unsets certain options.  See <xref linkend="ghci-set"/>
1409           for a list of available options.</para>
1410         </listitem>
1411       </varlistentry>
1412
1413       <varlistentry>
1414         <term>
1415           <literal>:!</literal> <replaceable>command</replaceable>...
1416           <indexterm><primary><literal>:!</literal></primary></indexterm>
1417           <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm>
1418         </term>
1419         <listitem>
1420           <para>Executes the shell command
1421           <replaceable>command</replaceable>.</para>
1422         </listitem>
1423       </varlistentry>
1424
1425     </variablelist>
1426   </sect1>
1427
1428   <sect1 id="ghci-set">
1429     <title>The <literal>:set</literal> command</title>
1430     <indexterm><primary><literal>:set</literal></primary></indexterm>
1431
1432     <para>The <literal>:set</literal> command sets two types of
1433     options: GHCi options, which begin with
1434     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
1435     options, which begin with &lsquo;-&rsquo;.  </para>
1436
1437     <para>NOTE: at the moment, the <literal>:set</literal> command
1438     doesn't support any kind of quoting in its arguments: quotes will
1439     not be removed and cannot be used to group words together.  For
1440     example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what
1441     you expect.</para>
1442
1443     <sect2>
1444       <title>GHCi options</title>
1445       <indexterm><primary>options</primary><secondary>GHCi</secondary>
1446       </indexterm>
1447
1448       <para>GHCi options may be set using <literal>:set</literal> and
1449       unset using <literal>:unset</literal>.</para>
1450
1451       <para>The available GHCi options are:</para>
1452
1453       <variablelist>
1454         <varlistentry>
1455           <term>
1456             <literal>+r</literal>
1457             <indexterm><primary><literal>+r</literal></primary></indexterm>
1458             <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
1459             <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm>
1460           </term>
1461           <listitem>
1462             <para>Normally, any evaluation of top-level expressions
1463             (otherwise known as CAFs or Constant Applicative Forms) in
1464             loaded modules is retained between evaluations.  Turning
1465             on <literal>+r</literal> causes all evaluation of
1466             top-level expressions to be discarded after each
1467             evaluation (they are still retained
1468             <emphasis>during</emphasis> a single evaluation).</para>
1469
1470             <para>This option may help if the evaluated top-level
1471             expressions are consuming large amounts of space, or if
1472             you need repeatable performance measurements.</para>
1473           </listitem>
1474         </varlistentry>
1475
1476         <varlistentry>
1477           <term>
1478             <literal>+s</literal>
1479             <indexterm><primary><literal>+s</literal></primary></indexterm>
1480           </term>
1481           <listitem>
1482             <para>Display some stats after evaluating each expression,
1483             including the elapsed time and number of bytes allocated.
1484             NOTE: the allocation figure is only accurate to the size
1485             of the storage manager's allocation area, because it is
1486             calculated at every GC.  Hence, you might see values of
1487             zero if no GC has occurred.</para>
1488           </listitem>
1489         </varlistentry>
1490
1491         <varlistentry>
1492           <term>
1493             <literal>+t</literal>
1494             <indexterm><primary><literal>+t</literal></primary></indexterm>
1495           </term>
1496           <listitem>
1497             <para>Display the type of each variable bound after a
1498             statement is entered at the prompt.  If the statement is a
1499             single expression, then the only variable binding will be
1500             for the variable
1501             &lsquo;<literal>it</literal>&rsquo;.</para>
1502           </listitem>
1503         </varlistentry>
1504       </variablelist>
1505     </sect2>
1506
1507     <sect2 id="ghci-cmd-line-options">
1508       <title>Setting GHC command-line options in GHCi</title>
1509
1510       <para>Normal GHC command-line options may also be set using
1511       <literal>:set</literal>.  For example, to turn on
1512       <option>-fglasgow-exts</option>, you would say:</para>
1513
1514 <screen>
1515 Prelude> :set -fglasgow-exts
1516 </screen>
1517
1518       <para>Any GHC command-line option that is designated as
1519       <firstterm>dynamic</firstterm> (see the table in <xref
1520       linkend="flag-reference"/>), may be set using
1521       <literal>:set</literal>.  To unset an option, you can set the
1522       reverse option:</para>
1523       <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
1524
1525 <screen>
1526 Prelude> :set -fno-glasgow-exts
1527 </screen>
1528
1529       <para><xref linkend="flag-reference"/> lists the reverse for each
1530       option where applicable.</para>
1531
1532       <para>Certain static options (<option>-package</option>,
1533       <option>-I</option>, <option>-i</option>, and
1534       <option>-l</option> in particular) will also work, but some may
1535       not take effect until the next reload.</para>
1536       <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
1537     </sect2>
1538   </sect1>
1539   <sect1 id="ghci-debugger">
1540     <title>The GHCi debugger</title>
1541     <indexterm><primary>debugger</primary></indexterm>
1542     <para>GHCi embeds an utility debugger with a very basic set of operations. The debugger
1543           is always available in ghci, you do not need to do anything to activate it. </para>
1544     <para>The following conditions must hold before a module can be debugged in GHCi:
1545       <itemizedlist>
1546          <listitem>
1547            <para>The module must have been loaded interpreted, i.e. not loaded from an <filename>.o</filename> file compiled by ghc </para>
1548          </listitem>
1549          <listitem>
1550            <para>The module must have been loaded with the <literal>-fdebugging</literal> flag
1551            </para></listitem>
1552        </itemizedlist></para>
1553     <sect2><title>Using the debugger</title>
1554     <para>The debugger allows the insertion of breakpoints at specific locations in the source code. These locations are goberned by event sites, and not by line as in traditional debuggers such as gdb. </para> <para>
1555       Once a breakpointed event is hit, the debugger stops the execution and you can examine the local variables in scope
1556       in the context of the event, as well as evaluate arbitrary Haskell expressions in
1557       a special interactive prompt. </para><para>
1558
1559      When you are done you issue the <literal>:quit</literal>
1560       command to leave the breakpoint and let the execution go on.
1561      Note that not all the GHCi commands are supported in a breakpoint.
1562
1563     </para>
1564     <sidebar><title>Events</title><?dbfo float-type="left"?>
1565     <para> Events are the places in source code where you can set a breakpoint.
1566 <programlisting>
1567 qsort [] = <co id="name-binding-co"/> []
1568 qsort (x:xs) =
1569    <coref linkend="name-binding-co"/> let left  = <coref linkend="name-binding-co"/> filter (\y -> <co id="lambda-co"/> y &lt; x) xs
1570            right = <coref linkend="name-binding-co"/> case filter (\y -> <coref linkend="lambda-co"/> y &gt; x) xs of
1571                               right_val -> <co id="case-co"/> right_val
1572     in <co id="let-co"/> qsort left ++ [x] ++ qsort right
1573 main = <coref linkend="name-binding-co"/> do {
1574    arg &lt;- <coref linkend="name-binding-co"/> getLine ;
1575    let num = <coref linkend="name-binding-co"/> read arg :: [Int] ;
1576  <co id="stmts-co"/> print (qsort num) ;
1577  <coref linkend="stmts-co"/> putStrLn "GoodBye!" }
1578 </programlisting>
1579      The GHCi debugger recognizes the following event types:
1580     <calloutlist>
1581       <callout arearefs="name-binding-co" id="name-binding">
1582         <para>Function definition and local bindings in let/where</para>
1583     </callout>
1584     <callout arearefs="lambda-co" id="lambda">
1585         <para>Lambda expression entry point</para>
1586     </callout>
1587     <callout arearefs="let-co" id="let">
1588       <para>Let expression body</para>
1589     </callout>
1590     <callout arearefs="case-co" id="case">
1591       <para>Case alternative body</para>
1592     </callout>
1593     <callout arearefs="stmts-co" id="stmts">
1594       <para>do notation statements</para>
1595     </callout>
1596     </calloutlist></para>
1597     <para>In reality however, ghci eliminates some redundant event sites.
1598     For instance, sites with two co-located breakpoint events are coalesced into a single one,
1599     and sites with no bindings in scope are assumed to be uninteresting and no breakpoint can be set in them.</para>
1600     </sidebar>
1601
1602 <para>
1603       You don't need to do anything special in order to start the debugging session.
1604       Simply use ghci to evaluate your Haskell expressions and whenever a breakpoint
1605       is hit, the debugger will enter the stage:
1606 <programlisting>
1607 *main:Main> :break add Main 2
1608 Breakpoint set at (2,15)
1609
1610 *main:Main> qsort [10,9..1]
1611 Local bindings in scope:
1612   x :: a, xs :: [a], left :: [a], right :: [a]
1613
1614 qsort2.hs:2:15-46>
1615 </programlisting>
1616       What is happening here is that GHCi has interrupted the evaluation of
1617       <code>qsort</code> at the breakpoint set in line 2, as the prompt indicates.
1618       At this point you can freely explore the contents of the bindings in scope,
1619       but with two catches. </para><para>
1620       First, take into account that due to the lazy nature of Haskell, some of
1621       these bindings may be unevaluated, and that exploring their contents may
1622       trigger a computation. </para><para>
1623       Second: look at the types of the things in scope.
1624       GHCi has left its types parameterised by a variable!
1625       Look at the type of <code>qsort</code>, which is
1626       polymorphic on the type of its argument. It does not
1627       tell us really what the types of <code>x</code> and <code>xs</code> can be.
1628       In general, polymorphic programs deal with polymorphic values,
1629       and this means that some of the bindings available in a breakpoint site
1630       will be parametrically typed.
1631       </para><para>
1632       So, what can we do with a value without concrete type? Very few interesting
1633       things. The <literal>:print</literal> command in ghci allows you to
1634       explore its contents and see if it is evaluated or not.
1635       This is useful because you cannot just type <literal>x</literal> in the
1636       prompt and expect GHCi to return you its value. Perhaps you know for
1637       sure that
1638       <literal>x</literal> is of type <code>Int</code>, which is an instance of
1639       <code>Show</code>, but GHCi does not have this information.
1640       <code>:print</code> however is fine, because it does not need to know the
1641       type to do its work. </para>
1642       <para> Let's go on with the debugging session of the <code>qsort</code>
1643       example:
1644 <programlisting>
1645 qsort2.hs:2:15-46> x
1646 This is an untyped, unevaluated computation. You can use seq to
1647 force its evaluation and then :print to recover its type <co id="seq1"/>
1648 qsort2.hs:2:15-46> seq x ()  <co id="seq2"/>
1649 ()
1650 qsort2.hs:2:15-46> x <co id="seq3"/>
1651 This is an untyped, unevaluated computation. You can use seq to
1652 force its evaluation and then :print to recover its type
1653
1654 qsort2.hs:2:15-46> :t x
1655 x :: GHC.Base.Unknown
1656 qsort2.hs:2:15-46> :p x <co id="seq4"/>
1657 x - 10
1658 qsort2.hs:2:15-46> :t x <co id="seq5"/>
1659 x :: Int
1660 </programlisting>
1661
1662       <calloutlist>
1663         <callout arearefs="seq1">
1664           <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
1665         </callout>
1666         <callout arearefs="seq2">
1667           <para>This line forces the evaluation of <code>x</code> </para>
1668         </callout>
1669         <callout arearefs="seq3">
1670           <para>Even though x has been evaluated, we cannot simply use its name to see its value!
1671           This is a bit counterintuitive, but currently in GHCi the type of a binding
1672           cannot be a type variable <code>a</code>.
1673           Thus, the binding <code>x</code> gets assigned the concrete type Unknown.</para>
1674         </callout>
1675         <callout arearefs="seq4">
1676           <para>We can explore <code>x</code> using the <literal>:print</literal>
1677           command, which does find out that <code>x</code> is of type Int and prints
1678           its value accordingly.</para>
1679         </callout>
1680         <callout arearefs="seq5">
1681            <literal>:print</literal> also updates the type of <code>x</code> with
1682            the most concrete type information available.
1683         </callout>
1684       </calloutlist>
1685       The example shows the standard way to proceeed with polymorphic values in a breakpoint.
1686       </para>
1687     </sect2>
1688     <sect2><title>Commands</title>
1689     <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.
1690 <variablelist>
1691 <varlistentry>
1692   <term>
1693     <literal>:breakpoint add <replaceable>module</replaceable> <replaceable>line</replaceable></literal>
1694   </term>
1695   <listitem><para>
1696     Adds a breakpoint at the first event found at line <literal>line</literal> in <literal>module</literal>, if any.
1697   </para></listitem>
1698 </varlistentry>
1699 <varlistentry>
1700   <term>
1701     <literal>:breakpoint add <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable></literal>
1702   </term>
1703   <listitem><para>
1704     Adds a breakpoint at the first event found after column <literal>column</literal>
1705     at line <literal>line</literal> in <literal>module</literal>, if any.
1706   </para></listitem>
1707 </varlistentry>
1708 <varlistentry>
1709   <term>
1710     <literal>:breakpoint list</literal>
1711   </term>
1712   <listitem><para>
1713     Lists the currently set up breakpoints.
1714   </para></listitem>
1715 </varlistentry>
1716 <varlistentry>
1717   <term>
1718     <literal>:breakpoint del <replaceable>num</replaceable></literal>
1719   </term>
1720   <listitem><para>
1721     Deletes the breakpoint at position <literal>num</literal> in the list of
1722     breakpoints shown by <literal>:breakpoint list</literal>.
1723   </para></listitem>
1724 </varlistentry>
1725 <varlistentry>
1726   <term>
1727     <literal>:breakpoint del <replaceable>module</replaceable> <replaceable>line</replaceable></literal>
1728   </term>
1729   <listitem><para>
1730   Dels the breakpoint at line <literal>line</literal> in <literal>module</literal>, if any.
1731   </para></listitem>
1732 </varlistentry>
1733 <varlistentry>
1734   <term>
1735     <literal>:breakpoint del <replaceable>module</replaceable> <replaceable>line</replaceable><replaceable>col</replaceable> </literal>
1736   </term>
1737   <listitem><para>
1738     Deletes the first breakpoint found after column <literal>column</literal>
1739     at line <literal>line</literal> in <literal>module</literal>, if any.
1740   </para></listitem>
1741 </varlistentry>
1742 <varlistentry>
1743   <term>
1744     <literal>:breakpoint stop </literal>
1745   </term>
1746   <listitem><para>
1747     Stop the program being executed. This interrupts a debugging session
1748     and returns to the top level.
1749   </para></listitem>
1750 </varlistentry>
1751 </variablelist></para>
1752     </sect2>
1753     <sect2><title>Limitations</title>
1754      <para>
1755       <itemizedlist>
1756         <listitem><para>
1757           <xref linkend="implicit-parameters" xrefstyle="select: title"/> are only available
1758           at the scope of a breakpoint if there is a explicit type signature.
1759         </para></listitem>
1760       </itemizedlist>
1761       <itemizedlist>
1762         <listitem><para>
1763           Modules compiled by GHCi under the <literal>-fdebugging
1764         </literal> flag  will perform slower: the debugging mode introduces some overhead.
1765       Modules compiled to object code by ghc are not affected.
1766         </para></listitem>
1767       </itemizedlist>
1768      </para>
1769     </sect2>
1770     </sect1>
1771   <sect1 id="ghci-dot-files">
1772     <title>The <filename>.ghci</filename> file</title>
1773     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
1774     </indexterm>
1775     <indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
1776     </indexterm>
1777
1778     <para>When it starts, GHCi always reads and executes commands from
1779     <filename>$HOME/.ghci</filename>, followed by
1780     <filename>./.ghci</filename>.</para>
1781
1782     <para>The <filename>.ghci</filename> in your home directory is
1783     most useful for turning on favourite options (eg. <literal>:set
1784     +s</literal>), and defining useful macros.  Placing a
1785     <filename>.ghci</filename> file in a directory with a Haskell
1786     project is a useful way to set certain project-wide options so you
1787     don't have to type them everytime you start GHCi: eg. if your
1788     project uses GHC extensions and CPP, and has source files in three
1789     subdirectories A B and C, you might put the following lines in
1790     <filename>.ghci</filename>:</para>
1791
1792 <screen>
1793 :set -fglasgow-exts -cpp
1794 :set -iA:B:C
1795 </screen>
1796
1797     <para>(Note that strictly speaking the <option>-i</option> flag is
1798     a static one, but in fact it works to set it using
1799     <literal>:set</literal> like this.  The changes won't take effect
1800     until the next <literal>:load</literal>, though.)</para>
1801
1802     <para>Two command-line options control whether the
1803     <filename>.ghci</filename> files are read:</para>
1804
1805     <variablelist>
1806       <varlistentry>
1807         <term>
1808           <option>-ignore-dot-ghci</option>
1809           <indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm>
1810         </term>
1811         <listitem>
1812           <para>Don't read either <filename>./.ghci</filename> or
1813           <filename>$HOME/.ghci</filename> when starting up.</para>
1814         </listitem>
1815       </varlistentry>
1816       <varlistentry>
1817         <term>
1818           <option>-read-dot-ghci</option>
1819           <indexterm><primary><option>-read-dot-ghci</option></primary></indexterm>
1820         </term>
1821         <listitem>
1822           <para>Read <filename>.ghci</filename> and
1823           <filename>$HOME/.ghci</filename>.  This is normally the
1824           default, but the <option>-read-dot-ghci</option> option may
1825           be used to override a previous
1826           <option>-ignore-dot-ghci</option> option.</para>
1827         </listitem>
1828       </varlistentry>
1829     </variablelist>
1830
1831   </sect1>
1832
1833   <sect1 id="ghci-faq">
1834     <title>FAQ and Things To Watch Out For</title>
1835
1836     <variablelist>
1837       <varlistentry>
1838         <term>The interpreter can't load modules with foreign export
1839         declarations!</term>
1840         <listitem>
1841           <para>Unfortunately not.  We haven't implemented it yet.
1842           Please compile any offending modules by hand before loading
1843           them into GHCi.</para>
1844         </listitem>
1845       </varlistentry>
1846
1847       <varlistentry>
1848         <term>
1849           <literal>-O</literal> doesn't work with GHCi!
1850           <indexterm><primary><option>-O</option></primary></indexterm>
1851          </term>
1852         <listitem>
1853           <para>For technical reasons, the bytecode compiler doesn't
1854           interact well with one of the optimisation passes, so we
1855           have disabled optimisation when using the interpreter.  This
1856           isn't a great loss: you'll get a much bigger win by
1857           compiling the bits of your code that need to go fast, rather
1858           than interpreting them with optimisation turned on.</para>
1859         </listitem>
1860       </varlistentry>
1861
1862       <varlistentry>
1863         <term>Unboxed tuples don't work with GHCi</term>
1864         <listitem>
1865           <para>That's right.  You can always compile a module that
1866           uses unboxed tuples and load it into GHCi, however.
1867           (Incidentally the previous point, namely that
1868           <literal>-O</literal> is incompatible with GHCi, is because
1869           the bytecode compiler can't deal with unboxed
1870           tuples).</para>
1871         </listitem>
1872       </varlistentry>
1873
1874       <varlistentry>
1875         <term>Concurrent threads don't carry on running when GHCi is
1876         waiting for input.</term>
1877         <listitem>
1878           <para>This should work, as long as your GHCi was built with
1879           the <option>-threaded</option> switch, which is the default.
1880           Consult whoever supplied your GHCi installation.</para>
1881         </listitem>
1882       </varlistentry>
1883
1884       <varlistentry>
1885         <term>After using <literal>getContents</literal>, I can't use
1886         <literal>stdin</literal> again until I do
1887         <literal>:load</literal> or <literal>:reload</literal>.</term>
1888
1889         <listitem>
1890           <para>This is the defined behaviour of
1891           <literal>getContents</literal>: it puts the stdin Handle in
1892           a state known as <firstterm>semi-closed</firstterm>, wherein
1893           any further I/O operations on it are forbidden.  Because I/O
1894           state is retained between computations, the semi-closed
1895           state persists until the next <literal>:load</literal> or
1896           <literal>:reload</literal> command.</para>
1897
1898           <para>You can make <literal>stdin</literal> reset itself
1899           after every evaluation by giving GHCi the command
1900           <literal>:set +r</literal>.  This works because
1901           <literal>stdin</literal> is just a top-level expression that
1902           can be reverted to its unevaluated state in the same way as
1903           any other top-level expression (CAF).</para>
1904         </listitem>
1905       </varlistentry>
1906
1907       <varlistentry>
1908         <term>I can't use Control-C to interrupt computations in
1909           GHCi on Windows.</term>
1910         <listitem>
1911           <para>See <xref linkend="ghci-windows">.</xref></para>
1912         </listitem>
1913       </varlistentry>
1914     </variablelist>
1915   </sect1>
1916
1917 </chapter>
1918
1919 <!-- Emacs stuff:
1920      ;;; Local Variables: ***
1921      ;;; mode: xml ***
1922      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
1923      ;;; End: ***
1924  -->