ghc/docs/users_guide/ghci.sgml

   1 <chapter id="ghci">
   2   <title>Using GHCi</title>
   3   <indexterm><primary>GHCi</primary></indexterm>
   4   <indexterm><primary>interpreter</primary><see>GHCi</see></indexterm>
   5   <indexterm><primary>interactive</primary><see>GHCi</see></indexterm>
   6
   7   <para>GHCi<footnote>
   8       <para>The &lsquo;i&rsquo; stands for &ldquo;Interactive&rdquo;</para>
   9     </footnote>
  10   is GHC's interactive environment, in which Haskell expressions can
  11   be interactively evaluated and programs can be interpreted.  If
  12   you're famililar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary>
  13   </indexterm>, then you'll be right at home with GHCi.  However, GHCi
  14   also has support for interactively loading compiled code, as well as
  15   supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
  16   </footnote> the language extensions that GHC provides.</para>
  17   <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
  18   <indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
  19
  20   <sect1>
  21     <title>Introduction to GHCi</title>
  22
  23     <para>Let's start with an example GHCi session.  You can fire up
  24     GHCi with the command <literal>ghci</literal>:</para>
  25
  26 <screen>
  27 $ ghci
  28    ___         ___ _
  29   / _ \ /\  /\/ __(_)
  30  / /_\// /_/ / /  | |      GHC Interactive, version 5.04, for Haskell 98.
  31 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
  32 \____/\/ /_/\____/|_|      Type :? for help.
  33
  34 Loading package base ... linking ... done.
  35 Loading package haskell98 ... 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    :help, :?                  display this list of commands
  53    :info [&lt;name&gt; ...]         display information about the given names
  54    :load &lt;filename&gt; ...       load module(s) and their dependents
  55    :module [+/-] [*]&lt;mod&gt; ... set the context for expression evaluation
  56    :reload                    reload the current module set
  57
  58    :set &lt;option&gt; ...          set options
  59    :set args &lt;arg&gt; ...        set the arguments returned by System.getArgs
  60    :set prog &lt;progname&gt;       set the value returned by System.getProgName
  61
  62    :show modules              show the currently loaded modules
  63    :show bindings             show the current bindings made at the prompt
  64
  65    :type &lt;expr&gt;               show the type of &lt;expr&gt;
  66    :undef &lt;cmd&gt;               undefine user-defined command :&lt;cmd&gt;
  67    :unset &lt;option&gt; ...        unset options
  68    :quit                      exit GHCi
  69    :!&lt;command&gt;                run the shell command &lt;command&gt;
  70
  71  Options for `:set' and `:unset':
  72
  73     +r                 revert top-level expressions after each evaluation
  74     +s                 print timing/memory stats after each evaluation
  75     +t                 print type after evaluation
  76     -&lt;flags&gt;           most GHC command line flags can also be set here
  77                          (eg. -v2, -fglasgow-exts, etc.)
  78 </screen>
  79
  80     <para>We'll explain most of these commands as we go along.  For
  81     Hugs users: many things work the same as in Hugs, so you should be
  82     able to get going straight away.</para>
  83
  84     <para>Haskell expressions can be typed at the prompt:</para>
  85     <indexterm><primary>prompt</primary><secondary>GHCi</secondary>
  86   </indexterm>
  87
  88 <screen>
  89 Prelude> 1+2
  90 3
  91 Prelude> let x = 42 in x / 9
  92 4.666666666666667
  93 Prelude>
  94 </screen>
  95
  96     <para>GHCi interprets the whole line as an expression to evaluate.
  97     The expression may not span several lines - as soon as you press
  98     enter, GHCi will attempt to evaluate it.</para>
  99   </sect1>
 100
 101   <sect1>
 102     <title>Loading source files</title>
 103
 104     <para>Suppose we have the following Haskell source code, which we
 105     place in a file <filename>Main.hs</filename>:</para>
 106
 107 <programlisting>
 108 main = print (fac 20)
 109
 110 fac 0 = 1
 111 fac n = n * fac (n-1)
 112 </programlisting>
 113
 114     <para>You can save <filename>Main.hs</filename> anywhere you like,
 115     but if you save it somewhere other than the current
 116     directory<footnote><para>If you started up GHCi from the command
 117     line then GHCi's current directory is the same as the current
 118     directory of the shell from which it was started.  If you started
 119     GHCi from the &ldquo;Start&rdquo; menu in Windows, then the
 120     current directory is probably something like
 121     <filename>C:\Documents and Settings\<replaceable>user
 122     name</replaceable></filename>.</para> </footnote> then we will
 123     need to change to the right directory in GHCi:</para>
 124
 125 <screen>
 126 Prelude> :cd <replaceable>dir</replaceable>
 127 </screen>
 128
 129     <para>where <replaceable>dir</replaceable> is the directory (or
 130     folder) in which you saved <filename>Main.hs</filename>.</para>
 131
 132     <para>To load a Haskell source file into GHCi, use the
 133     <literal>:load</literal> command:</para>
 134     <indexterm><primary><literal>:load</literal></primary></indexterm>
 135
 136 <screen>
 137 Prelude> :load Main
 138 Compiling Main             ( Main.hs, interpreted )
 139 Ok, modules loaded: Main.
 140 *Main>
 141 </screen>
 142
 143     <para>GHCi has loaded the <literal>Main</literal> module, and the
 144     prompt has changed to &ldquo;<literal>*Main></literal>&rdquo; to
 145     indicate that the current context for expressions typed at the
 146     prompt is the <literal>Main</literal> module we just loaded (we'll
 147     explain what the <literal>*</literal> means later in <xref
 148     linkend="ghci-scope">).  So we can now type expressions involving
 149     the functions from <filename>Main.hs</filename>:</para>
 150
 151 <screen>
 152 *Main> fac 17
 153 355687428096000
 154 </screen>
 155
 156     <para>Loading a multi-module program is just as straightforward;
 157     just give the name of the &ldquo;topmost&rdquo; module to the
 158     <literal>:load</literal> command (hint: <literal>:load</literal>
 159     can be abbreviated to <literal>:l</literal>).  The topmost module
 160     will normally be <literal>Main</literal>, but it doesn't have to
 161     be.  GHCi will discover which modules are required, directly or
 162     indirectly, by the topmost module, and load them all in dependency
 163     order.</para>
 164
 165     <sect2 id="ghci-modules-filenames">
 166       <title>Modules vs. filenames</title>
 167       <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
 168       <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>
 169
 170       <para>Question: How does GHC find the filename which contains
 171       module <replaceable>M</replaceable>?  Answer: it looks for the
 172       file <literal><replaceable>M</replaceable>.hs</literal>, or
 173       <literal><replaceable>M</replaceable>.lhs</literal>.  This means
 174       that for most modules, the module name must match the filename.
 175       If it doesn't, GHCi won't be able to find it.</para>
 176
 177       <para>There is one exception to this general rule: when you load
 178       a program with <literal>:load</literal>, or specify it when you
 179       invoke <literal>ghci</literal>, you can give a filename rather
 180       than a module name.  This filename is loaded if it exists, and
 181       it may contain any module you like.  This is particularly
 182       convenient if you have several <literal>Main</literal> modules
 183       in the same directory and you can't call them all
 184       <filename>Main.hs</filename>.</para>
 185
 186       <para>The search path for finding source files is specified with
 187       the <option>-i</option> option on the GHCi command line, like
 188       so:</para>
 189 <screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen>
 190
 191       <para>or it can be set using the <literal>:set</literal> command
 192       from within GHCi (see <xref
 193       linkend="ghci-cmd-line-options">)<footnote><para>Note that in
 194       GHCi, and <option>&ndash;&ndash;make</option> mode, the <option>-i</option>
 195       option is used to specify the search path for
 196       <emphasis>source</emphasis> files, whereas in standard
 197       batch-compilation mode the <option>-i</option> option is used to
 198       specify the search path for interface files, see <xref
 199       linkend="options-finding-imports">.</para> </footnote></para>
 200
 201       <para>One consequence of the way that GHCi follows dependencies
 202       to find modules to load is that every module must have a source
 203       file.  The only exception to the rule is modules that come from
 204       a package, including the <literal>Prelude</literal> and standard
 205       libraries such as <literal>IO</literal> and
 206       <literal>Complex</literal>.  If you attempt to load a module for
 207       which GHCi can't find a source file, even if there are object
 208       and interface files for the module, you'll get an error
 209       message.</para>
 210     </sect2>
 211
 212     <sect2>
 213       <title>Making changes and recompilation</title>
 214       <indexterm><primary><literal>:reload</literal></primary></indexterm>
 215
 216       <para>If you make some changes to the source code and want GHCi
 217       to recompile the program, give the <literal>:reload</literal>
 218       command.  The program will be recompiled as necessary, with GHCi
 219       doing its best to avoid actually recompiling modules if their
 220       external dependencies haven't changed.  This is the same
 221       mechanism we use to avoid re-compiling modules in the batch
 222       compilation setting (see <xref linkend="recomp">).</para>
 223     </sect2>
 224   </sect1>
 225
 226   <sect1 id="ghci-compiled">
 227     <title>Loading compiled code</title>
 228     <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm>
 229
 230     <para>When you load a Haskell source module into GHCi, it is
 231     normally converted to byte-code and run using the interpreter.
 232     However, interpreted code can also run alongside compiled code in
 233     GHCi; indeed, normally when GHCi starts, it loads up a compiled
 234     copy of the <literal>base</literal> package, which contains the
 235     <literal>Prelude</literal>.</para>
 236
 237     <para>Why should we want to run compiled code?  Well, compiled
 238     code is roughly 10x faster than interpreted code, but takes about
 239     2x longer to produce (perhaps longer if optimisation is on).  So
 240     it pays to compile the parts of a program that aren't changing
 241     very often, and use the interpreter for the code being actively
 242     developed.</para>
 243
 244     <para>When loading up source files with <literal>:load</literal>,
 245     GHCi looks for any corresponding compiled object files, and will
 246     use one in preference to interpreting the source if possible.  For
 247     example, suppose we have a 4-module program consisting of modules
 248     A, B, C, and D.  Modules B and C both import D only,
 249     and A imports both B & C:</para>
 250 <screen>
 251       A
 252      / \
 253     B   C
 254      \ /
 255       D
 256 </screen>
 257     <para>We can compile D, then load the whole program, like this:</para>
 258 <screen>
 259 Prelude> :! ghc -c D.hs
 260 Prelude> :load A
 261 Skipping  D                ( D.hs, D.o )
 262 Compiling C                ( C.hs, interpreted )
 263 Compiling B                ( B.hs, interpreted )
 264 Compiling A                ( A.hs, interpreted )
 265 Ok, modules loaded: A, B, C, D.
 266 *Main>
 267 </screen>
 268
 269     <para>In the messages from the compiler, we see that it skipped D,
 270     and used the object file <filename>D.o</filename>.  The message
 271     <literal>Skipping</literal> <replaceable>module</replaceable>
 272     indicates that compilation for <replaceable>module</replaceable>
 273     isn't necessary, because the source and everything it depends on
 274     is unchanged since the last compilation.</para>
 275
 276     <para>At any time you can use the command
 277     <literal>:show modules</literal>
 278     to get a list of the modules currently loaded
 279     into GHCi:</para>
 280
 281 <screen>
 282 *Main> :show modules
 283 D                ( D.hs, D.o )
 284 C                ( C.hs, interpreted )
 285 B                ( B.hs, interpreted )
 286 A                ( A.hs, interpreted )
 287 *Main></screen>
 288
 289     <para>If we now modify the source of D (or pretend to: using Unix
 290     command <literal>touch</literal> on the source file is handy for
 291     this), the compiler will no longer be able to use the object file,
 292     because it might be out of date:</para>
 293
 294 <screen>
 295 *Main> :! touch D.hs
 296 *Main> :reload
 297 Compiling D                ( D.hs, interpreted )
 298 Skipping  C                ( C.hs, interpreted )
 299 Skipping  B                ( B.hs, interpreted )
 300 Skipping  A                ( A.hs, interpreted )
 301 Ok, modules loaded: A, B, C, D.
 302 *Main>
 303 </screen>
 304
 305     <para>Note that module D was compiled, but in this instance
 306     because its source hadn't really changed, its interface remained
 307     the same, and the recompilation checker determined that A, B and C
 308     didn't need to be recompiled.</para>
 309
 310     <para>So let's try compiling one of the other modules:</para>
 311
 312 <screen>
 313 *Main> :! ghc -c C.hs
 314 *Main> :load A
 315 Compiling D                ( D.hs, interpreted )
 316 Compiling C                ( C.hs, interpreted )
 317 Compiling B                ( B.hs, interpreted )
 318 Compiling A                ( A.hs, interpreted )
 319 Ok, modules loaded: A, B, C, D.
 320 </screen>
 321
 322     <para>We didn't get the compiled version of C!  What happened?
 323     Well, in GHCi a compiled module may only depend on other compiled
 324     modules, and in this case C depends on D, which doesn't have an
 325     object file, so GHCi also rejected C's object file.  Ok, so let's
 326     also compile D:</para>
 327
 328 <screen>
 329 *Main> :! ghc -c D.hs
 330 *Main> :reload
 331 Ok, modules loaded: A, B, C, D.
 332 </screen>
 333
 334     <para>Nothing happened!  Here's another lesson: newly compiled
 335     modules aren't picked up by <literal>:reload</literal>, only
 336     <literal>:load</literal>:</para>
 337
 338 <screen>
 339 *Main> :load A
 340 Skipping  D                ( D.hs, D.o )
 341 Skipping  C                ( C.hs, C.o )
 342 Compiling B                ( B.hs, interpreted )
 343 Compiling A                ( A.hs, interpreted )
 344 Ok, modules loaded: A, B, C, D.
 345 </screen>
 346
 347     <para>HINT: since GHCi will only use a compiled object file if it
 348     can sure that the compiled version is up-to-date, a good technique
 349     when working on a large program is to occasionally run
 350     <literal>ghc &ndash;&ndash;make</literal> to compile the whole project (say
 351     before you go for lunch :-), then continue working in the
 352     interpreter.  As you modify code, the new modules will be
 353     interpreted, but the rest of the project will remain
 354     compiled.</para>
 355
 356   </sect1>
 357
 358   <sect1>
 359     <title>Interactive evaluation at the prompt</title>
 360
 361     <para>When you type an expression at the prompt, GHCi immediately
 362     evaluates and prints the result.  But that's not the whole story:
 363     if you type something of type <literal>IO a</literal> for some
 364     <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it
 365     as an IO-computation, and doesn't attempt to print the
 366     result:.</para>
 367
 368 <screen>
 369 Prelude> "hello"
 370 "hello"
 371 Prelude> putStrLn "hello"
 372 hello
 373 </screen>
 374
 375     <para>What actually happens is that GHCi typechecks the
 376     expression, and if it doesn't have an <literal>IO</literal> type,
 377     then it transforms it as follows: an expression
 378     <replaceable>e</replaceable> turns into
 379 <screen>
 380              let it = <replaceable>e</replaceable>;
 381              print it
 382 </screen>
 383     which is then run as an IO-action.</para>
 384
 385     <para>Hence, the original expression must have a type which is an
 386     instance of the <literal>Show</literal> class, or GHCi will
 387     complain:</para>
 388
 389 <screen>
 390 Prelude> id
 391 No instance for `Show (a -> a)'
 392 arising from use of `print'
 393 in a `do' expression pattern binding: print it
 394 </screen>
 395
 396     <para>The error message contains some clues as to the
 397     transformation happening internally.</para>
 398
 399     <sect2 id="ghci-scope">
 400       <title>What's really in scope at the prompt?</title>
 401
 402       <para>When you type an expression at the prompt, what
 403       identifiers and types are in scope?  GHCi provides a flexible
 404       way to control exactly how the context for an expression is
 405       constructed.  Let's start with the simple cases; when you start
 406       GHCi the prompt looks like this:</para>
 407
 408 <screen>Prelude></screen>
 409
 410       <para>Which indicates that everything from the module
 411       <literal>Prelude</literal> is currently in scope.  If we now
 412       load a file into GHCi, the prompt will change:</para>
 413
 414 <screen>
 415 Prelude> :load Main.hs
 416 Compiling Main             ( Main.hs, interpreted )
 417 *Main>
 418 </screen>
 419
 420       <para>The new prompt is <literal>*Main</literal>, which
 421       indicates that we are typing expressions in the context of the
 422       top-level of the <literal>Main</literal> module.  Everything
 423       that is in scope at the top-level in the module
 424       <literal>Main</literal> we just loaded is also in scope at the
 425       prompt (probably including <literal>Prelude</literal>, as long
 426       as <literal>Main</literal> doesn't explicitly hide it).</para>
 427
 428       <para>The syntax
 429       <literal>*<replaceable>module</replaceable></literal> indicates
 430       that it is the full top-level scope of
 431       <replaceable>module</replaceable> that is contributing to the
 432       scope for expressions typed at the prompt.  Without the
 433       <literal>*</literal>, just the exports of the module are
 434       visible.</para>
 435
 436       <para>We're not limited to a single module: GHCi can combine
 437       scopes from multiple modules, in any mixture of
 438       <literal>*</literal> and non-<literal>*</literal> forms.  GHCi
 439       combines the scopes from all of these modules to form the scope
 440       that is in effect at the prompt.  For technical reasons, GHCi
 441       can only support the <literal>*</literal>-form for modules which
 442       are interpreted, so compiled modules and package modules can
 443       only contribute their exports to the current scope.</para>
 444
 445       <para>The scope is manipulated using the
 446       <literal>:module</literal> command.  For example, if the current
 447       scope is <literal>Prelude</literal>, then we can bring into
 448       scope the exports from the module <literal>IO</literal> like
 449       so:</para>
 450
 451 <screen>
 452 Prelude> :module +IO
 453 Prelude,IO> hPutStrLn stdout "hello\n"
 454 hello
 455 Prelude,IO>
 456 </screen>
 457
 458       <para>(Note: <literal>:module</literal> can be shortened to
 459       <literal>:m</literal>). The full syntax of the
 460       <literal>:module</literal> command is:</para>
 461
 462 <screen>
 463 :module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
 464 </screen>
 465
 466       <para>Using the <literal>+</literal> form of the
 467       <literal>module</literal> commands adds modules to the current
 468       scope, and <literal>-</literal> removes them.  Without either
 469       <literal>+</literal> or <literal>-</literal>, the current scope
 470       is replaced by the set of modules specified.  Note that if you
 471       use this form and leave out <literal>Prelude</literal>, GHCi
 472       will assume that you really wanted the
 473       <literal>Prelude</literal> and add it in for you (if you don't
 474       want the <literal>Prelude</literal>, then ask to remove it with
 475       <literal>:m -Prelude</literal>).</para>
 476
 477       <para>The scope is automatically set after a
 478       <literal>:load</literal> command, to the most recently loaded
 479       "target" module, in a <literal>*</literal>-form if possible.
 480       For example, if you say <literal>:load foo.hs bar.hs</literal>
 481       and <filename>bar.hs</filename> contains module
 482       <literal>Bar</literal>, then the scope will be set to
 483       <literal>*Bar</literal> if <literal>Bar</literal> is
 484       interpreted, or if <literal>Bar</literal> is compiled it will be
 485       set to <literal>Prelude,Bar</literal> (GHCi automatically adds
 486       <literal>Prelude</literal> if it isn't present and there aren't
 487       any <literal>*</literal>-form modules).</para>
 488
 489       <para>With multiple modules in scope, especially multiple
 490       <literal>*</literal>-form modules, it is likely that name
 491       clashes will occur.  Haskell specifies that name clashes are
 492       only reported when an ambiguous identifier is used, and GHCi
 493       behaves in the same way for expressions typed at the
 494       prompt.</para>
 495
 496       <sect3>
 497         <title>Qualified names</title>
 498
 499         <para>To make life slightly easier, the GHCi prompt also
 500         behaves as if there is an implicit <literal>import
 501         qualified</literal> declaration for every module in every
 502         package, and every module currently loaded into GHCi.</para>
 503       </sect3>
 504     </sect2>
 505
 506     <sect2>
 507       <title>Using <literal>do-</literal>notation at the prompt</title>
 508       <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm>
 509       <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm>
 510
 511       <para>GHCi actually accepts <firstterm>statements</firstterm>
 512       rather than just expressions at the prompt.  This means you can
 513       bind values and functions to names, and use them in future
 514       expressions or statements.</para>
 515
 516       <para>The syntax of a statement accepted at the GHCi prompt is
 517       exactly the same as the syntax of a statement in a Haskell
 518       <literal>do</literal> expression.  However, there's no monad
 519       overloading here: statements typed at the prompt must be in the
 520       <literal>IO</literal> monad.</para>
 521
 522       <para>Here's an example:</para>
 523 <screen>
 524 Prelude> x <- return 42
 525 Prelude> print x
 526 42
 527 Prelude>
 528 </screen>
 529       <para>The statement <literal>x <- return 42</literal> means
 530       &ldquo;execute <literal>return 42</literal> in the
 531       <literal>IO</literal> monad, and bind the result to
 532       <literal>x</literal>&rdquo;.  We can then use
 533       <literal>x</literal> in future statements, for example to print
 534       it as we did above.</para>
 535
 536       <para>Of course, you can also bind normal non-IO expressions
 537       using the <literal>let</literal>-statement:</para>
 538 <screen>
 539 Prelude> let x = 42
 540 Prelude> print x
 541 42
 542 Prelude>
 543 </screen>
 544       <para>An important difference between the two types of binding
 545       is that the monadic bind (<literal>p <- e</literal>) is
 546       <emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
 547       whereas with the <literal>let</literal> form, the expression
 548       isn't evaluated immediately:</para>
 549 <screen>
 550 Prelude> let x = error "help!"
 551 Prelude> print x
 552 *** Exception: help!
 553 Prelude>
 554 </screen>
 555       <para>Any exceptions raised during the evaluation or execution
 556       of the statement are caught and printed by the GHCi command line
 557       interface (for more information on exceptions, see the module
 558       <literal>Control.Exception</literal> in the libraries
 559       documentation).</para>
 560
 561       <para>Every new binding shadows any existing bindings of the
 562       same name, including entities that are in scope in the current
 563       module context.</para>
 564
 565       <para>WARNING: temporary bindings introduced at the prompt only
 566       last until the next <literal>:load</literal> or
 567       <literal>:reload</literal> command, at which time they will be
 568       simply lost.  However, they do survive a change of context with
 569       <literal>:module</literal>: the temporary bindings just move to
 570       the new location.</para>
 571
 572       <para>HINT: To get a list of the bindings currently in scope, use the
 573       <literal>:show bindings</literal> command:</para>
 574
 575 <screen>
 576 Prelude> :show bindings
 577 x :: Int
 578 Prelude></screen>
 579
 580       <para>HINT: if you turn on the <literal>+t</literal> option,
 581       GHCi will show the type of each variable bound by a statement.
 582       For example:</para>
 583       <indexterm><primary><literal>+t</literal></primary></indexterm>
 584 <screen>
 585 Prelude> :set +t
 586 Prelude> let (x:xs) = [1..]
 587 x :: Integer
 588 xs :: [Integer]
 589 </screen>
 590
 591     </sect2>
 592
 593     <sect2>
 594       <title>The <literal>it</literal> variable</title>
 595       <indexterm><primary><literal>it</literal></primary>
 596       </indexterm>
 597
 598       <para>Whenever an expression (or a non-binding statement, to be
 599       precise) is typed at the prompt, GHCi implicitly binds its value
 600       to the variable <literal>it</literal>.  For example:</para>
 601 <screen>
 602 Prelude> 1+2
 603 3
 604 Prelude> it * 2
 605 6
 606 </screen>
 607
 608       <para>This is a result of the translation mentioned earlier,
 609       namely that an expression <replaceable>e</replaceable> is
 610       translated to
 611 <screen>
 612              let it = <replaceable>e</replaceable>;
 613              print it
 614 </screen>
 615       before execution, resulting in a binding for
 616       <literal>it</literal>.</para>
 617
 618       <para>If the expression was of type <literal>IO a</literal> for
 619       some <literal>a</literal>, then <literal>it</literal> will be
 620       bound to the result of the <literal>IO</literal> computation,
 621       which is of type <literal>a</literal>.  eg.:</para>
 622 <screen>
 623 Prelude> Time.getClockTime
 624 Prelude> print it
 625 Wed Mar 14 12:23:13 GMT 2001
 626 </screen>
 627
 628       <para>The corresponding translation for an IO-typed
 629       <replaceable>e</replaceable> is
 630 <screen>
 631              it <- <replaceable>e</replaceable>
 632 </screen>
 633       </para>
 634
 635       <para>Note that <literal>it</literal> is shadowed by the new
 636       value each time you evaluate a new expression, and the old value
 637       of <literal>it</literal> is lost.</para>
 638
 639     </sect2>
 640
 641     <sect2>
 642       <title>Type defaulting in GHCi</title>
 643     <indexterm><primary>Type default</primary></indexterm>
 644     <indexterm><primary><literal>Show</literal> class</primary></indexterm>
 645       <para>
 646       Consider this GHCi session:
 647 <programlisting>
 648   ghci> reverse []
 649 </programlisting>
 650       What should GHCi do?  Strictly speaking, the program is ambiguous.  <literal>show (reverse [])</literal>
 651       (which is what GHCi computes here) has type <literal>Show a => a</literal> and how that displays depends
 652       on the type <literal>a</literal>.  For example:
 653 <programlisting>
 654   ghci> (reverse []) :: String
 655   ""
 656   ghci> (reverse []) :: [Int]
 657   []
 658 </programlisting>
 659     However, it is tiresome for the user to have to specify the type, so GHCi extends Haskell's type-defaulting
 660     rules (Section 4.3.4 of the Haskell 98 Report (Revised)) as follows.  If the expression yields a set of
 661     type constraints that are all from standard classes (<literal>Num</literal>, <literal>Eq</literal> etc.),
 662    and at least one is either a numeric class <emphasis>or the <literal>Show</literal> class</emphasis>,
 663    GHCi will try to use one of the <literal>default</literal> types, just as described in the Report.
 664    </para>
 665     </sect2>
 666   </sect1>
 667
 668   <sect1 id="ghci-invokation">
 669     <title>Invoking GHCi</title>
 670     <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
 671     <indexterm><primary><option>&ndash;&ndash;interactive</option></primary></indexterm>
 672
 673     <para>GHCi is invoked with the command <literal>ghci</literal> or
 674     <literal>ghc &ndash;&ndash;interactive</literal>.  One or more modules or
 675     filenames can also be specified on the command line; this
 676     instructs GHCi to load the specified modules or filenames (and all
 677     the modules they depend on), just as if you had said
 678     <literal>:load <replaceable>modules</replaceable></literal> at the
 679     GHCi prompt (see <xref linkend="ghci-commands">).  For example, to
 680     start GHCi and load the program whose topmost module is in the
 681     file <literal>Main.hs</literal>, we could say:</para>
 682
 683 <screen>
 684 $ ghci Main.hs
 685 </screen>
 686
 687     <para>Most of the command-line options accepted by GHC (see <xref
 688     linkend="using-ghc">) also make sense in interactive mode.  The ones
 689     that don't make sense are mostly obvious; for example, GHCi
 690     doesn't generate interface files, so options related to interface
 691     file generation won't have any effect.</para>
 692
 693     <sect2>
 694       <title>Packages</title>
 695       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
 696
 697       <para>Most packages (see <xref linkend="using-packages">) are
 698       available without needing to specify any extra flags at all:
 699       they will be automatically loaded the first time they are
 700       needed.</para>
 701
 702       <para>For non-auto packages, however, you need to request the
 703       package be loaded by using the <literal>-package</literal> flag:</para>
 704
 705 <screen>
 706 $ ghci -package data
 707    ___         ___ _
 708   / _ \ /\  /\/ __(_)
 709  / /_\// /_/ / /  | |      GHC Interactive, version 5.05, for Haskell 98.
 710 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 711 \____/\/ /_/\____/|_|      Type :? for help.
 712
 713 Loading package base ... linking ... done.
 714 Loading package haskell98 ... linking ... done.
 715 Loading package lang ... linking ... done.
 716 Loading package concurrent ... linking ... done.
 717 Loading package readline ... linking ... done.
 718 Loading package unix ... linking ... done.
 719 Loading package posix ... linking ... done.
 720 Loading package util ... linking ... done.
 721 Loading package data ... linking ... done.
 722 Prelude>
 723 </screen>
 724
 725       <para>The following command works to load new packages into a
 726       running GHCi:</para>
 727
 728 <screen>
 729 Prelude> :set -package <replaceable>name</replaceable>
 730 </screen>
 731
 732       <para>But note that doing this will cause all currently loaded
 733       modules to be unloaded, and you'll be dumped back into the
 734       <literal>Prelude</literal>.</para>
 735     </sect2>
 736
 737     <sect2>
 738       <title>Extra libraries</title>
 739       <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
 740
 741       <para>Extra libraries may be specified on the command line using
 742       the normal <literal>-l<replaceable>lib</replaceable></literal>
 743       option.  (The term <emphasis>library</emphasis> here refers to
 744       libraries of foreign object code; for using libraries of Haskell
 745       source code, see <xref linkend="ghci-modules-filenames">.) For
 746       example, to load the &ldquo;m&rdquo; library:</para>
 747
 748 <screen>
 749 $ ghci -lm
 750 </screen>
 751
 752       <para>On systems with <literal>.so</literal>-style shared
 753       libraries, the actual library loaded will the
 754       <filename>lib<replaceable>lib</replaceable>.so</filename>.  GHCi
 755       searches the following places for libraries, in this order:</para>
 756
 757       <itemizedlist>
 758         <listitem>
 759           <para>Paths specified using the
 760           <literal>-L<replaceable>path</replaceable></literal>
 761           command-line option,</para>
 762         </listitem>
 763         <listitem>
 764           <para>the standard library search path for your system,
 765           which on some systems may be overriden by setting the
 766           <literal>LD_LIBRARY_PATH</literal> environment
 767           variable.</para>
 768         </listitem>
 769       </itemizedlist>
 770
 771       <para>On systems with <literal>.dll</literal>-style shared
 772       libraries, the actual library loaded will be
 773       <filename><replaceable>lib</replaceable>.dll</filename>.  Again,
 774       GHCi will signal an error if it can't find the library.</para>
 775
 776       <para>GHCi can also load plain object files
 777       (<literal>.o</literal> or <literal>.obj</literal> depending on
 778       your platform) from the command-line.  Just add the name the
 779       object file to the command line.</para>
 780     </sect2>
 781
 782   </sect1>
 783
 784   <sect1 id="ghci-commands">
 785     <title>GHCi commands</title>
 786
 787     <para>GHCi commands all begin with
 788     &lsquo;<literal>:</literal>&rsquo; and consist of a single command
 789     name followed by zero or more parameters.  The command name may be
 790     abbreviated, as long as the abbreviation is not ambiguous.  All of
 791     the builtin commands, with the exception of
 792     <literal>:unset</literal> and <literal>:undef</literal>, may be
 793     abbreviated to a single letter.</para>
 794
 795     <variablelist>
 796       <varlistentry>
 797         <term><literal>:add</literal>
 798         <replaceable>module</replaceable> ...</term>
 799         <indexterm><primary><literal>:add</literal></primary></indexterm>
 800         <listitem>
 801           <para>Add <replaceable>module</replaceable>(s) to the
 802           current <firstterm>target set</firstterm>, and perform a
 803           reload.</para>
 804         </listitem>
 805       </varlistentry>
 806
 807       <varlistentry>
 808         <term><literal>:browse</literal>
 809         <optional><literal>*</literal></optional><replaceable>module</replaceable>
 810         ...</term>
 811         <indexterm><primary><literal>:browse</literal></primary>
 812         </indexterm>
 813         <listitem>
 814           <para>Displays the identifiers defined by the module
 815           <replaceable>module</replaceable>, which must be either
 816           loaded into GHCi or be a member of a package.  If the
 817           <literal>*</literal> symbol is placed before the module
 818           name, then <emphasis>all</emphasis> the identifiers defined
 819           in <replaceable>module</replaceable> are shown; otherwise
 820           the list is limited to the exports of
 821           <replaceable>module</replaceable>.  The
 822           <literal>*</literal>-form is only available for modules
 823           which are interpreted; for compiled modules (including
 824           modules from packages) only the non-<literal>*</literal>
 825           form of <literal>:browse</literal> is available.</para>
 826         </listitem>
 827       </varlistentry>
 828
 829       <varlistentry>
 830         <term><literal>:cd</literal> <replaceable>dir</replaceable></term>
 831         <indexterm><primary><literal>:cd</literal></primary></indexterm>
 832         <listitem>
 833           <para>Changes the current working directory to
 834           <replaceable>dir</replaceable>.  A
 835           &lsquo;<literal>&tilde;</literal>&rsquo; symbol at the
 836           beginning of <replaceable>dir</replaceable> will be replaced
 837           by the contents of the environment variable
 838           <literal>HOME</literal>.</para>
 839         </listitem>
 840       </varlistentry>
 841
 842       <varlistentry>
 843         <term><literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable></term>
 844         <indexterm><primary><literal>:def</literal></primary></indexterm>
 845         <listitem>
 846           <para>The command <literal>:def</literal>
 847           <replaceable>name</replaceable>
 848           <replaceable>expr</replaceable> defines a new GHCi command
 849           <literal>:<replaceable>name</replaceable></literal>,
 850           implemented by the Haskell expression
 851           <replaceable>expr</replaceable>, which must have type
 852           <literal>String -> IO String</literal>.  When
 853           <literal>:<replaceable>name</replaceable>
 854           <replaceable>args</replaceable></literal> is typed at the
 855           prompt, GHCi will run the expression
 856           <literal>(<replaceable>name</replaceable>
 857           <replaceable>args</replaceable>)</literal>, take the
 858           resulting <literal>String</literal>, and feed it back into
 859           GHCi as a new sequence of commands.  Separate commands in
 860           the result must be separated by
 861           &lsquo;<literal>\n</literal>&rsquo;.</para>
 862
 863           <para>That's all a little confusing, so here's a few
 864           examples.  To start with, here's a new GHCi command which
 865           doesn't take any arguments or produce any results, it just
 866           outputs the current date & time:</para>
 867
 868 <screen>
 869 Prelude> let date _ = Time.getClockTime >>= print >> return ""
 870 Prelude> :def date date
 871 Prelude> :date
 872 Fri Mar 23 15:16:40 GMT 2001
 873 </screen>
 874
 875           <para>Here's an example of a command that takes an argument.
 876           It's a re-implementation of <literal>:cd</literal>:</para>
 877
 878 <screen>
 879 Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
 880 Prelude> :def mycd mycd
 881 Prelude> :mycd ..
 882 </screen>
 883
 884           <para>Or I could define a simple way to invoke
 885           &ldquo;<literal>ghc &ndash;&ndash;make Main</literal>&rdquo; in the
 886           current directory:</para>
 887
 888 <screen>
 889 Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")
 890 </screen>
 891
 892         </listitem>
 893       </varlistentry>
 894
 895       <varlistentry>
 896         <term><literal>:help</literal></term>
 897         <indexterm><primary><literal>:help</literal></primary></indexterm>
 898         <term><literal>:?</literal></term>
 899         <indexterm><primary><literal>:?</literal></primary></indexterm>
 900         <listitem>
 901           <para>Displays a list of the available commands.</para>
 902         </listitem>
 903       </varlistentry>
 904
 905       <varlistentry>
 906         <term><literal>:info</literal> <replaceable>name</replaceable>
 907         ...</term>
 908         <indexterm><primary><literal>:info</literal></primary>
 909         </indexterm>
 910         <listitem>
 911           <para>Displays information about the given name(s).  For
 912           example, if <replaceable>name</replaceable> is a class, then
 913           the class methods and their types will be printed;  if
 914           <replaceable>name</replaceable> is a type constructor, then
 915           its definition will be printed;  if
 916           <replaceable>name</replaceable> is a function, then its type
 917           will be printed.  If <replaceable>name</replaceable> has
 918           been loaded from a source file, then GHCi will also display
 919           the location of its definition in the source.</para>
 920         </listitem>
 921       </varlistentry>
 922
 923       <varlistentry>
 924         <term><literal>:load</literal>
 925         <replaceable>module</replaceable> ...</term>
 926         <indexterm><primary><literal>:load</literal></primary></indexterm>
 927         <listitem>
 928           <para>Recursively loads the specified
 929           <replaceable>module</replaceable>s, and all the modules they
 930           depend on.  Here, each <replaceable>module</replaceable>
 931           must be a module name or filename, but may not be the name
 932           of a module in a package.</para>
 933
 934           <para>All previously loaded modules, except package modules,
 935           are forgotten.  The new set of modules is known as the
 936           <firstterm>target set</firstterm>.  Note that
 937           <literal>:load</literal> can be used without any arguments
 938           to unload all the currently loaded modules and
 939           bindings.</para>
 940
 941           <para>After a <literal>:load</literal> command, the current
 942           context is set to:</para>
 943
 944           <itemizedlist>
 945             <listitem>
 946               <para><replaceable>module</replaceable>, if it was loaded
 947               successfully, or</para>
 948             </listitem>
 949             <listitem>
 950               <para>the most recently successfully loaded module, if
 951               any other modules were loaded as a result of the current
 952               <literal>:load</literal>, or</para>
 953             </listitem>
 954             <listitem>
 955               <para><literal>Prelude</literal> otherwise.</para>
 956             </listitem>
 957           </itemizedlist>
 958         </listitem>
 959       </varlistentry>
 960
 961       <varlistentry>
 962         <term><literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal></term>
 963         <indexterm><primary><literal>:module</literal></primary></indexterm>
 964         <listitem>
 965           <para>Sets or modifies the current context for statements
 966           typed at the prompt.  See <xref linkend="ghci-scope"> for
 967           more details.</para>
 968         </listitem>
 969       </varlistentry>
 970
 971       <varlistentry>
 972         <term><literal>:quit</literal></term>
 973         <indexterm><primary><literal>:quit</literal></primary></indexterm>
 974         <listitem>
 975           <para>Quits GHCi.  You can also quit by typing a control-D
 976           at the prompt.</para>
 977         </listitem>
 978       </varlistentry>
 979
 980       <varlistentry>
 981         <term><literal>:reload</literal></term>
 982         <indexterm><primary><literal>:reload</literal></primary></indexterm>
 983         <listitem>
 984           <para>Attempts to reload the current target set (see
 985           <literal>:load</literal>) if any of the modules in the set,
 986           or any dependent module, has changed.  Note that this may
 987           entail loading new modules, or dropping modules which are no
 988           longer indirectly required by the target.</para>
 989         </listitem>
 990       </varlistentry>
 991
 992       <varlistentry>
 993         <term><literal>:set</literal> <optional><replaceable>option</replaceable>...</optional></term>
 994         <indexterm><primary><literal>:set</literal></primary></indexterm>
 995         <listitem>
 996           <para>Sets various options.  See <xref linkend="ghci-set">
 997           for a list of available options.  The
 998           <literal>:set</literal> command by itself shows which
 999           options are currently set.</para>
1000         </listitem>
1001       </varlistentry>
1002
1003       <varlistentry>
1004         <term><literal>:set</literal> <literal>args</literal>
1005         <replaceable>arg</replaceable> ...</term>
1006         <indexterm><primary><literal>:set</literal></primary></indexterm>
1007         <listitem>
1008           <para>Sets the list of arguments which are returned when the
1009           program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary>
1010             </indexterm>.</para>
1011         </listitem>
1012       </varlistentry>
1013
1014       <varlistentry>
1015         <term><literal>:set</literal> <literal>prog</literal>
1016         <replaceable>prog</replaceable></term>
1017         <indexterm><primary><literal>:set</literal></primary></indexterm>
1018         <listitem>
1019           <para>Sets the string to be returned when the program calls
1020           <literal>System.getProgName</literal><indexterm><primary>getProgName</primary>
1021             </indexterm>.</para>
1022         </listitem>
1023       </varlistentry>
1024
1025       <varlistentry>
1026         <term><literal>:show bindings</literal></term>
1027         <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
1028         <listitem>
1029           <para>Show the bindings made at the prompt and their
1030           types.</para>
1031         </listitem>
1032       </varlistentry>
1033
1034       <varlistentry>
1035         <term><literal>:show modules</literal></term>
1036         <indexterm><primary><literal>:show modules</literal></primary></indexterm>
1037         <listitem>
1038           <para>Show the list of modules currently load.</para>
1039         </listitem>
1040       </varlistentry>
1041
1042       <varlistentry>
1043         <term><literal>:type</literal> <replaceable>expression</replaceable></term>
1044         <indexterm><primary><literal>:type</literal></primary></indexterm>
1045         <listitem>
1046           <para>Infers and prints the type of
1047           <replaceable>expression</replaceable>, including explicit
1048           forall quantifiers for polymorphic types.  The monomorphism
1049           restriction is <emphasis>not</emphasis> applied to the
1050           expression during type inference.</para>
1051         </listitem>
1052       </varlistentry>
1053
1054       <varlistentry>
1055         <term><literal>:undef</literal> <replaceable>name</replaceable></term>
1056         <indexterm><primary><literal>:undef</literal></primary></indexterm>
1057         <listitem>
1058           <para>Undefines the user-defined command
1059           <replaceable>name</replaceable> (see <literal>:def</literal>
1060           above).</para>
1061         </listitem>
1062       </varlistentry>
1063
1064       <varlistentry>
1065         <term><literal>:unset</literal> <replaceable>option</replaceable>...</term>
1066         <indexterm><primary><literal>:unset</literal></primary></indexterm>
1067         <listitem>
1068           <para>Unsets certain options.  See <xref linkend="ghci-set">
1069           for a list of available options.</para>
1070         </listitem>
1071       </varlistentry>
1072
1073       <varlistentry>
1074         <term><literal>:!</literal> <replaceable>command</replaceable>...</term>
1075         <indexterm><primary><literal>:!</literal></primary></indexterm>
1076         <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm>
1077         <listitem>
1078           <para>Executes the shell command
1079           <replaceable>command</replaceable>.</para>
1080         </listitem>
1081       </varlistentry>
1082
1083     </variablelist>
1084   </sect1>
1085
1086   <sect1 id="ghci-set">
1087     <title>The <literal>:set</literal> command</title>
1088     <indexterm><primary><literal>:set</literal></primary></indexterm>
1089
1090     <para>The <literal>:set</literal> command sets two types of
1091     options: GHCi options, which begin with
1092     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
1093     options, which begin with &lsquo;-&rsquo;.  </para>
1094
1095     <para>NOTE: at the moment, the <literal>:set</literal> command
1096     doesn't support any kind of quoting in its arguments: quotes will
1097     not be removed and cannot be used to group words together.  For
1098     example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what
1099     you expect.</para>
1100
1101     <sect2>
1102       <title>GHCi options</title>
1103       <indexterm><primary>options</primary><secondary>GHCi</secondary>
1104       </indexterm>
1105
1106       <para>GHCi options may be set using <literal>:set</literal> and
1107       unset using <literal>:unset</literal>.</para>
1108
1109       <para>The available GHCi options are:</para>
1110
1111       <variablelist>
1112         <varlistentry>
1113           <term><literal>+r</literal></term>
1114           <indexterm><primary><literal>+r</literal></primary></indexterm>
1115           <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
1116           <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm>
1117           <listitem>
1118             <para>Normally, any evaluation of top-level expressions
1119             (otherwise known as CAFs or Constant Applicative Forms) in
1120             loaded modules is retained between evaluations.  Turning
1121             on <literal>+r</literal> causes all evaluation of
1122             top-level expressions to be discarded after each
1123             evaluation (they are still retained
1124             <emphasis>during</emphasis> a single evaluation).</para>
1125
1126             <para>This option may help if the evaluated top-level
1127             expressions are consuming large amounts of space, or if
1128             you need repeatable performance measurements.</para>
1129           </listitem>
1130         </varlistentry>
1131
1132         <varlistentry>
1133           <term><literal>+s</literal></term>
1134           <indexterm><primary><literal>+s</literal></primary></indexterm>
1135           <listitem>
1136             <para>Display some stats after evaluating each expression,
1137             including the elapsed time and number of bytes allocated.
1138             NOTE: the allocation figure is only accurate to the size
1139             of the storage manager's allocation area, because it is
1140             calculated at every GC.  Hence, you might see values of
1141             zero if no GC has occurred.</para>
1142           </listitem>
1143         </varlistentry>
1144
1145         <varlistentry>
1146           <term><literal>+t</literal></term>
1147           <indexterm><primary><literal>+t</literal></primary></indexterm>
1148           <listitem>
1149             <para>Display the type of each variable bound after a
1150             statement is entered at the prompt.  If the statement is a
1151             single expression, then the only variable binding will be
1152             for the variable
1153             &lsquo;<literal>it</literal>&rsquo;.</para>
1154           </listitem>
1155         </varlistentry>
1156       </variablelist>
1157     </sect2>
1158
1159     <sect2 id="ghci-cmd-line-options">
1160       <title>Setting GHC command-line options in GHCi</title>
1161
1162       <para>Normal GHC command-line options may also be set using
1163       <literal>:set</literal>.  For example, to turn on
1164       <option>-fglasgow-exts</option>, you would say:</para>
1165
1166 <screen>
1167 Prelude> :set -fglasgow-exts
1168 </screen>
1169
1170       <para>Any GHC command-line option that is designated as
1171       <firstterm>dynamic</firstterm> (see the table in <xref
1172       linkend="flag-reference">), may be set using
1173       <literal>:set</literal>.  To unset an option, you can set the
1174       reverse option:</para>
1175       <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
1176
1177 <screen>
1178 Prelude> :set -fno-glasgow-exts
1179 </screen>
1180
1181       <para><xref linkend="flag-reference"> lists the reverse for each
1182       option where applicable.</para>
1183
1184       <para>Certain static options (<option>-package</option>,
1185       <option>-I</option>, <option>-i</option>, and
1186       <option>-l</option> in particular) will also work, but some may
1187       not take effect until the next reload.</para>
1188       <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
1189     </sect2>
1190   </sect1>
1191
1192   <sect1 id="ghci-dot-files">
1193     <title>The <filename>.ghci</filename> file</title>
1194     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
1195     </indexterm>
1196     <indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
1197     </indexterm>
1198
1199     <para>When it starts, GHCi always reads and executes commands from
1200     <filename>$HOME/.ghci</filename>, followed by
1201     <filename>./.ghci</filename>.</para>
1202
1203     <para>The <filename>.ghci</filename> in your home directory is
1204     most useful for turning on favourite options (eg. <literal>:set
1205     +s</literal>), and defining useful macros.  Placing a
1206     <filename>.ghci</filename> file in a directory with a Haskell
1207     project is a useful way to set certain project-wide options so you
1208     don't have to type them everytime you start GHCi: eg. if your
1209     project uses GHC extensions and CPP, and has source files in three
1210     subdirectories A B and C, you might put the following lines in
1211     <filename>.ghci</filename>:</para>
1212
1213 <screen>
1214 :set -fglasgow-exts -cpp
1215 :set -iA:B:C
1216 </screen>
1217
1218     <para>(Note that strictly speaking the <option>-i</option> flag is
1219     a static one, but in fact it works to set it using
1220     <literal>:set</literal> like this.  The changes won't take effect
1221     until the next <literal>:load</literal>, though.)</para>
1222
1223     <para>Two command-line options control whether the
1224     <filename>.ghci</filename> files are read:</para>
1225
1226     <variablelist>
1227       <varlistentry>
1228         <term><option>-ignore-dot-ghci</option></term>
1229         <indexterm><primary><option>-ignore-dot-ghci</option></primary>
1230         </indexterm>
1231         <listitem>
1232           <para>Don't read either <filename>./.ghci</filename> or
1233           <filename>$HOME/.ghci</filename> when starting up.</para>
1234         </listitem>
1235       </varlistentry>
1236       <varlistentry>
1237         <term><option>-read-dot-ghci</option></term>
1238         <indexterm><primary><option>-read-dot-ghci</option></primary>
1239         </indexterm>
1240         <listitem>
1241           <para>Read <filename>.ghci</filename> and
1242           <filename>$HOME/.ghci</filename>.  This is normally the
1243           default, but the <option>-read-dot-ghci</option> option may
1244           be used to override a previous
1245           <option>-ignore-dot-ghci</option> option.</para>
1246         </listitem>
1247       </varlistentry>
1248     </variablelist>
1249
1250   </sect1>
1251
1252   <sect1>
1253     <title>FAQ and Things To Watch Out For</title>
1254
1255     <variablelist>
1256       <varlistentry>
1257         <term>The interpreter can't load modules with foreign export
1258         declarations!</term>
1259         <listitem>
1260           <para>Unfortunately not.  We haven't implemented it yet.
1261           Please compile any offending modules by hand before loading
1262           them into GHCi.</para>
1263         </listitem>
1264       </varlistentry>
1265
1266       <varlistentry>
1267         <term><literal>-O</literal> doesn't work with GHCi!</term>
1268         <indexterm><primary><option>-O</option></primary>
1269         </indexterm>
1270         <listitem>
1271           <para>For technical reasons, the bytecode compiler doesn't
1272           interact well with one of the optimisation passes, so we
1273           have disabled optimisation when using the interpreter.  This
1274           isn't a great loss: you'll get a much bigger win by
1275           compiling the bits of your code that need to go fast, rather
1276           than interpreting them with optimisation turned on.</para>
1277         </listitem>
1278       </varlistentry>
1279
1280       <varlistentry>
1281         <term>Unboxed tuples don't work with GHCi</term>
1282         <listitem>
1283           <para>That's right.  You can always compile a module that
1284           uses unboxed tuples and load it into GHCi, however.
1285           (Incidentally the previous point, namely that
1286           <literal>-O</literal> is incompatible with GHCi, is because
1287           the bytecode compiler can't deal with unboxed
1288           tuples).</para>
1289         </listitem>
1290       </varlistentry>
1291
1292       <varlistentry>
1293         <term>Concurrent threads don't carry on running when GHCi is
1294         waiting for input.</term>
1295         <listitem>
1296           <para>No, they don't.  This is because the Haskell binding
1297           to the GNU readline library doesn't support reading from the
1298           terminal in a non-blocking way, which is required to work
1299           properly with GHC's concurrency model.</para>
1300         </listitem>
1301       </varlistentry>
1302
1303       <varlistentry>
1304         <term>After using <literal>getContents</literal>, I can't use
1305         <literal>stdin</literal> again until I do
1306         <literal>:load</literal> or <literal>:reload</literal>.</term>
1307
1308         <listitem>
1309           <para>This is the defined behaviour of
1310           <literal>getContents</literal>: it puts the stdin Handle in
1311           a state known as <firstterm>semi-closed</firstterm>, wherein
1312           any further I/O operations on it are forbidden.  Because I/O
1313           state is retained between computations, the semi-closed
1314           state persists until the next <literal>:load</literal> or
1315           <literal>:reload</literal> command.</para>
1316
1317           <para>You can make <literal>stdin</literal> reset itself
1318           after every evaluation by giving GHCi the command
1319           <literal>:set +r</literal>.  This works because
1320           <literal>stdin</literal> is just a top-level expression that
1321           can be reverted to its unevaluated state in the same way as
1322           any other top-level expression (CAF).</para>
1323         </listitem>
1324       </varlistentry>
1325
1326     </variablelist>
1327   </sect1>
1328
1329 </chapter>
1330
1331 <!-- Emacs stuff:
1332      ;;; Local Variables: ***
1333      ;;; mode: sgml ***
1334      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
1335      ;;; End: ***
1336  -->