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>,
 663    <literal>Eq</literal>, or <literal>Ord</literal> class</emphasis>,
 664    GHCi will try to use one of the <literal>default</literal> types, just as described in the Report.
 665    </para>
 666     </sect2>
 667   </sect1>
 668
 669   <sect1 id="ghci-invokation">
 670     <title>Invoking GHCi</title>
 671     <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
 672     <indexterm><primary><option>&ndash;&ndash;interactive</option></primary></indexterm>
 673
 674     <para>GHCi is invoked with the command <literal>ghci</literal> or
 675     <literal>ghc &ndash;&ndash;interactive</literal>.  One or more modules or
 676     filenames can also be specified on the command line; this
 677     instructs GHCi to load the specified modules or filenames (and all
 678     the modules they depend on), just as if you had said
 679     <literal>:load <replaceable>modules</replaceable></literal> at the
 680     GHCi prompt (see <xref linkend="ghci-commands">).  For example, to
 681     start GHCi and load the program whose topmost module is in the
 682     file <literal>Main.hs</literal>, we could say:</para>
 683
 684 <screen>
 685 $ ghci Main.hs
 686 </screen>
 687
 688     <para>Most of the command-line options accepted by GHC (see <xref
 689     linkend="using-ghc">) also make sense in interactive mode.  The ones
 690     that don't make sense are mostly obvious; for example, GHCi
 691     doesn't generate interface files, so options related to interface
 692     file generation won't have any effect.</para>
 693
 694     <sect2>
 695       <title>Packages</title>
 696       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
 697
 698       <para>Most packages (see <xref linkend="using-packages">) are
 699       available without needing to specify any extra flags at all:
 700       they will be automatically loaded the first time they are
 701       needed.</para>
 702
 703       <para>For non-auto packages, however, you need to request the
 704       package be loaded by using the <literal>-package</literal> flag:</para>
 705
 706 <screen>
 707 $ ghci -package data
 708    ___         ___ _
 709   / _ \ /\  /\/ __(_)
 710  / /_\// /_/ / /  | |      GHC Interactive, version 5.05, for Haskell 98.
 711 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 712 \____/\/ /_/\____/|_|      Type :? for help.
 713
 714 Loading package base ... linking ... done.
 715 Loading package haskell98 ... linking ... done.
 716 Loading package lang ... linking ... done.
 717 Loading package concurrent ... linking ... done.
 718 Loading package readline ... linking ... done.
 719 Loading package unix ... linking ... done.
 720 Loading package posix ... linking ... done.
 721 Loading package util ... linking ... done.
 722 Loading package data ... linking ... done.
 723 Prelude>
 724 </screen>
 725
 726       <para>The following command works to load new packages into a
 727       running GHCi:</para>
 728
 729 <screen>
 730 Prelude> :set -package <replaceable>name</replaceable>
 731 </screen>
 732
 733       <para>But note that doing this will cause all currently loaded
 734       modules to be unloaded, and you'll be dumped back into the
 735       <literal>Prelude</literal>.</para>
 736     </sect2>
 737
 738     <sect2>
 739       <title>Extra libraries</title>
 740       <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
 741
 742       <para>Extra libraries may be specified on the command line using
 743       the normal <literal>-l<replaceable>lib</replaceable></literal>
 744       option.  (The term <emphasis>library</emphasis> here refers to
 745       libraries of foreign object code; for using libraries of Haskell
 746       source code, see <xref linkend="ghci-modules-filenames">.) For
 747       example, to load the &ldquo;m&rdquo; library:</para>
 748
 749 <screen>
 750 $ ghci -lm
 751 </screen>
 752
 753       <para>On systems with <literal>.so</literal>-style shared
 754       libraries, the actual library loaded will the
 755       <filename>lib<replaceable>lib</replaceable>.so</filename>.  GHCi
 756       searches the following places for libraries, in this order:</para>
 757
 758       <itemizedlist>
 759         <listitem>
 760           <para>Paths specified using the
 761           <literal>-L<replaceable>path</replaceable></literal>
 762           command-line option,</para>
 763         </listitem>
 764         <listitem>
 765           <para>the standard library search path for your system,
 766           which on some systems may be overriden by setting the
 767           <literal>LD_LIBRARY_PATH</literal> environment
 768           variable.</para>
 769         </listitem>
 770       </itemizedlist>
 771
 772       <para>On systems with <literal>.dll</literal>-style shared
 773       libraries, the actual library loaded will be
 774       <filename><replaceable>lib</replaceable>.dll</filename>.  Again,
 775       GHCi will signal an error if it can't find the library.</para>
 776
 777       <para>GHCi can also load plain object files
 778       (<literal>.o</literal> or <literal>.obj</literal> depending on
 779       your platform) from the command-line.  Just add the name the
 780       object file to the command line.</para>
 781     </sect2>
 782
 783   </sect1>
 784
 785   <sect1 id="ghci-commands">
 786     <title>GHCi commands</title>
 787
 788     <para>GHCi commands all begin with
 789     &lsquo;<literal>:</literal>&rsquo; and consist of a single command
 790     name followed by zero or more parameters.  The command name may be
 791     abbreviated, as long as the abbreviation is not ambiguous.  All of
 792     the builtin commands, with the exception of
 793     <literal>:unset</literal> and <literal>:undef</literal>, may be
 794     abbreviated to a single letter.</para>
 795
 796     <variablelist>
 797       <varlistentry>
 798         <term><literal>:add</literal>
 799         <replaceable>module</replaceable> ...</term>
 800         <indexterm><primary><literal>:add</literal></primary></indexterm>
 801         <listitem>
 802           <para>Add <replaceable>module</replaceable>(s) to the
 803           current <firstterm>target set</firstterm>, and perform a
 804           reload.</para>
 805         </listitem>
 806       </varlistentry>
 807
 808       <varlistentry>
 809         <term><literal>:browse</literal>
 810         <optional><literal>*</literal></optional><replaceable>module</replaceable>
 811         ...</term>
 812         <indexterm><primary><literal>:browse</literal></primary>
 813         </indexterm>
 814         <listitem>
 815           <para>Displays the identifiers defined by the module
 816           <replaceable>module</replaceable>, which must be either
 817           loaded into GHCi or be a member of a package.  If the
 818           <literal>*</literal> symbol is placed before the module
 819           name, then <emphasis>all</emphasis> the identifiers defined
 820           in <replaceable>module</replaceable> are shown; otherwise
 821           the list is limited to the exports of
 822           <replaceable>module</replaceable>.  The
 823           <literal>*</literal>-form is only available for modules
 824           which are interpreted; for compiled modules (including
 825           modules from packages) only the non-<literal>*</literal>
 826           form of <literal>:browse</literal> is available.</para>
 827         </listitem>
 828       </varlistentry>
 829
 830       <varlistentry>
 831         <term><literal>:cd</literal> <replaceable>dir</replaceable></term>
 832         <indexterm><primary><literal>:cd</literal></primary></indexterm>
 833         <listitem>
 834           <para>Changes the current working directory to
 835           <replaceable>dir</replaceable>.  A
 836           &lsquo;<literal>&tilde;</literal>&rsquo; symbol at the
 837           beginning of <replaceable>dir</replaceable> will be replaced
 838           by the contents of the environment variable
 839           <literal>HOME</literal>.</para>
 840
 841           <para>NOTE: changing directories causes all currently loaded
 842           modules to be unloaded.  This is because the search path is
 843           usually expressed using relative directories, and changing
 844           the search path in the middle of a session is not
 845           supported.</para>
 846         </listitem>
 847       </varlistentry>
 848
 849       <varlistentry>
 850         <term><literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable></term>
 851         <indexterm><primary><literal>:def</literal></primary></indexterm>
 852         <listitem>
 853           <para>The command <literal>:def</literal>
 854           <replaceable>name</replaceable>
 855           <replaceable>expr</replaceable> defines a new GHCi command
 856           <literal>:<replaceable>name</replaceable></literal>,
 857           implemented by the Haskell expression
 858           <replaceable>expr</replaceable>, which must have type
 859           <literal>String -> IO String</literal>.  When
 860           <literal>:<replaceable>name</replaceable>
 861           <replaceable>args</replaceable></literal> is typed at the
 862           prompt, GHCi will run the expression
 863           <literal>(<replaceable>name</replaceable>
 864           <replaceable>args</replaceable>)</literal>, take the
 865           resulting <literal>String</literal>, and feed it back into
 866           GHCi as a new sequence of commands.  Separate commands in
 867           the result must be separated by
 868           &lsquo;<literal>\n</literal>&rsquo;.</para>
 869
 870           <para>That's all a little confusing, so here's a few
 871           examples.  To start with, here's a new GHCi command which
 872           doesn't take any arguments or produce any results, it just
 873           outputs the current date & time:</para>
 874
 875 <screen>
 876 Prelude> let date _ = Time.getClockTime >>= print >> return ""
 877 Prelude> :def date date
 878 Prelude> :date
 879 Fri Mar 23 15:16:40 GMT 2001
 880 </screen>
 881
 882           <para>Here's an example of a command that takes an argument.
 883           It's a re-implementation of <literal>:cd</literal>:</para>
 884
 885 <screen>
 886 Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
 887 Prelude> :def mycd mycd
 888 Prelude> :mycd ..
 889 </screen>
 890
 891           <para>Or I could define a simple way to invoke
 892           &ldquo;<literal>ghc &ndash;&ndash;make Main</literal>&rdquo; in the
 893           current directory:</para>
 894
 895 <screen>
 896 Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")
 897 </screen>
 898
 899         </listitem>
 900       </varlistentry>
 901
 902       <varlistentry>
 903         <term><literal>:help</literal></term>
 904         <indexterm><primary><literal>:help</literal></primary></indexterm>
 905         <term><literal>:?</literal></term>
 906         <indexterm><primary><literal>:?</literal></primary></indexterm>
 907         <listitem>
 908           <para>Displays a list of the available commands.</para>
 909         </listitem>
 910       </varlistentry>
 911
 912       <varlistentry>
 913         <term><literal>:info</literal> <replaceable>name</replaceable>
 914         ...</term>
 915         <indexterm><primary><literal>:info</literal></primary>
 916         </indexterm>
 917         <listitem>
 918           <para>Displays information about the given name(s).  For
 919           example, if <replaceable>name</replaceable> is a class, then
 920           the class methods and their types will be printed;  if
 921           <replaceable>name</replaceable> is a type constructor, then
 922           its definition will be printed;  if
 923           <replaceable>name</replaceable> is a function, then its type
 924           will be printed.  If <replaceable>name</replaceable> has
 925           been loaded from a source file, then GHCi will also display
 926           the location of its definition in the source.</para>
 927         </listitem>
 928       </varlistentry>
 929
 930       <varlistentry>
 931         <term><literal>:load</literal>
 932         <replaceable>module</replaceable> ...</term>
 933         <indexterm><primary><literal>:load</literal></primary></indexterm>
 934         <listitem>
 935           <para>Recursively loads the specified
 936           <replaceable>module</replaceable>s, and all the modules they
 937           depend on.  Here, each <replaceable>module</replaceable>
 938           must be a module name or filename, but may not be the name
 939           of a module in a package.</para>
 940
 941           <para>All previously loaded modules, except package modules,
 942           are forgotten.  The new set of modules is known as the
 943           <firstterm>target set</firstterm>.  Note that
 944           <literal>:load</literal> can be used without any arguments
 945           to unload all the currently loaded modules and
 946           bindings.</para>
 947
 948           <para>After a <literal>:load</literal> command, the current
 949           context is set to:</para>
 950
 951           <itemizedlist>
 952             <listitem>
 953               <para><replaceable>module</replaceable>, if it was loaded
 954               successfully, or</para>
 955             </listitem>
 956             <listitem>
 957               <para>the most recently successfully loaded module, if
 958               any other modules were loaded as a result of the current
 959               <literal>:load</literal>, or</para>
 960             </listitem>
 961             <listitem>
 962               <para><literal>Prelude</literal> otherwise.</para>
 963             </listitem>
 964           </itemizedlist>
 965         </listitem>
 966       </varlistentry>
 967
 968       <varlistentry>
 969         <term><literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal></term>
 970         <indexterm><primary><literal>:module</literal></primary></indexterm>
 971         <listitem>
 972           <para>Sets or modifies the current context for statements
 973           typed at the prompt.  See <xref linkend="ghci-scope"> for
 974           more details.</para>
 975         </listitem>
 976       </varlistentry>
 977
 978       <varlistentry>
 979         <term><literal>:quit</literal></term>
 980         <indexterm><primary><literal>:quit</literal></primary></indexterm>
 981         <listitem>
 982           <para>Quits GHCi.  You can also quit by typing a control-D
 983           at the prompt.</para>
 984         </listitem>
 985       </varlistentry>
 986
 987       <varlistentry>
 988         <term><literal>:reload</literal></term>
 989         <indexterm><primary><literal>:reload</literal></primary></indexterm>
 990         <listitem>
 991           <para>Attempts to reload the current target set (see
 992           <literal>:load</literal>) if any of the modules in the set,
 993           or any dependent module, has changed.  Note that this may
 994           entail loading new modules, or dropping modules which are no
 995           longer indirectly required by the target.</para>
 996         </listitem>
 997       </varlistentry>
 998
 999       <varlistentry>
1000         <term><literal>:set</literal> <optional><replaceable>option</replaceable>...</optional></term>
1001         <indexterm><primary><literal>:set</literal></primary></indexterm>
1002         <listitem>
1003           <para>Sets various options.  See <xref linkend="ghci-set">
1004           for a list of available options.  The
1005           <literal>:set</literal> command by itself shows which
1006           options are currently set.</para>
1007         </listitem>
1008       </varlistentry>
1009
1010       <varlistentry>
1011         <term><literal>:set</literal> <literal>args</literal>
1012         <replaceable>arg</replaceable> ...</term>
1013         <indexterm><primary><literal>:set</literal></primary></indexterm>
1014         <listitem>
1015           <para>Sets the list of arguments which are returned when the
1016           program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary>
1017             </indexterm>.</para>
1018         </listitem>
1019       </varlistentry>
1020
1021       <varlistentry>
1022         <term><literal>:set</literal> <literal>prog</literal>
1023         <replaceable>prog</replaceable></term>
1024         <indexterm><primary><literal>:set</literal></primary></indexterm>
1025         <listitem>
1026           <para>Sets the string to be returned when the program calls
1027           <literal>System.getProgName</literal><indexterm><primary>getProgName</primary>
1028             </indexterm>.</para>
1029         </listitem>
1030       </varlistentry>
1031
1032       <varlistentry>
1033         <term><literal>:show bindings</literal></term>
1034         <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
1035         <listitem>
1036           <para>Show the bindings made at the prompt and their
1037           types.</para>
1038         </listitem>
1039       </varlistentry>
1040
1041       <varlistentry>
1042         <term><literal>:show modules</literal></term>
1043         <indexterm><primary><literal>:show modules</literal></primary></indexterm>
1044         <listitem>
1045           <para>Show the list of modules currently load.</para>
1046         </listitem>
1047       </varlistentry>
1048
1049       <varlistentry>
1050         <term><literal>:type</literal> <replaceable>expression</replaceable></term>
1051         <indexterm><primary><literal>:type</literal></primary></indexterm>
1052         <listitem>
1053           <para>Infers and prints the type of
1054           <replaceable>expression</replaceable>, including explicit
1055           forall quantifiers for polymorphic types.  The monomorphism
1056           restriction is <emphasis>not</emphasis> applied to the
1057           expression during type inference.</para>
1058         </listitem>
1059       </varlistentry>
1060
1061       <varlistentry>
1062         <term><literal>:undef</literal> <replaceable>name</replaceable></term>
1063         <indexterm><primary><literal>:undef</literal></primary></indexterm>
1064         <listitem>
1065           <para>Undefines the user-defined command
1066           <replaceable>name</replaceable> (see <literal>:def</literal>
1067           above).</para>
1068         </listitem>
1069       </varlistentry>
1070
1071       <varlistentry>
1072         <term><literal>:unset</literal> <replaceable>option</replaceable>...</term>
1073         <indexterm><primary><literal>:unset</literal></primary></indexterm>
1074         <listitem>
1075           <para>Unsets certain options.  See <xref linkend="ghci-set">
1076           for a list of available options.</para>
1077         </listitem>
1078       </varlistentry>
1079
1080       <varlistentry>
1081         <term><literal>:!</literal> <replaceable>command</replaceable>...</term>
1082         <indexterm><primary><literal>:!</literal></primary></indexterm>
1083         <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm>
1084         <listitem>
1085           <para>Executes the shell command
1086           <replaceable>command</replaceable>.</para>
1087         </listitem>
1088       </varlistentry>
1089
1090     </variablelist>
1091   </sect1>
1092
1093   <sect1 id="ghci-set">
1094     <title>The <literal>:set</literal> command</title>
1095     <indexterm><primary><literal>:set</literal></primary></indexterm>
1096
1097     <para>The <literal>:set</literal> command sets two types of
1098     options: GHCi options, which begin with
1099     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
1100     options, which begin with &lsquo;-&rsquo;.  </para>
1101
1102     <para>NOTE: at the moment, the <literal>:set</literal> command
1103     doesn't support any kind of quoting in its arguments: quotes will
1104     not be removed and cannot be used to group words together.  For
1105     example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what
1106     you expect.</para>
1107
1108     <sect2>
1109       <title>GHCi options</title>
1110       <indexterm><primary>options</primary><secondary>GHCi</secondary>
1111       </indexterm>
1112
1113       <para>GHCi options may be set using <literal>:set</literal> and
1114       unset using <literal>:unset</literal>.</para>
1115
1116       <para>The available GHCi options are:</para>
1117
1118       <variablelist>
1119         <varlistentry>
1120           <term><literal>+r</literal></term>
1121           <indexterm><primary><literal>+r</literal></primary></indexterm>
1122           <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
1123           <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm>
1124           <listitem>
1125             <para>Normally, any evaluation of top-level expressions
1126             (otherwise known as CAFs or Constant Applicative Forms) in
1127             loaded modules is retained between evaluations.  Turning
1128             on <literal>+r</literal> causes all evaluation of
1129             top-level expressions to be discarded after each
1130             evaluation (they are still retained
1131             <emphasis>during</emphasis> a single evaluation).</para>
1132
1133             <para>This option may help if the evaluated top-level
1134             expressions are consuming large amounts of space, or if
1135             you need repeatable performance measurements.</para>
1136           </listitem>
1137         </varlistentry>
1138
1139         <varlistentry>
1140           <term><literal>+s</literal></term>
1141           <indexterm><primary><literal>+s</literal></primary></indexterm>
1142           <listitem>
1143             <para>Display some stats after evaluating each expression,
1144             including the elapsed time and number of bytes allocated.
1145             NOTE: the allocation figure is only accurate to the size
1146             of the storage manager's allocation area, because it is
1147             calculated at every GC.  Hence, you might see values of
1148             zero if no GC has occurred.</para>
1149           </listitem>
1150         </varlistentry>
1151
1152         <varlistentry>
1153           <term><literal>+t</literal></term>
1154           <indexterm><primary><literal>+t</literal></primary></indexterm>
1155           <listitem>
1156             <para>Display the type of each variable bound after a
1157             statement is entered at the prompt.  If the statement is a
1158             single expression, then the only variable binding will be
1159             for the variable
1160             &lsquo;<literal>it</literal>&rsquo;.</para>
1161           </listitem>
1162         </varlistentry>
1163       </variablelist>
1164     </sect2>
1165
1166     <sect2 id="ghci-cmd-line-options">
1167       <title>Setting GHC command-line options in GHCi</title>
1168
1169       <para>Normal GHC command-line options may also be set using
1170       <literal>:set</literal>.  For example, to turn on
1171       <option>-fglasgow-exts</option>, you would say:</para>
1172
1173 <screen>
1174 Prelude> :set -fglasgow-exts
1175 </screen>
1176
1177       <para>Any GHC command-line option that is designated as
1178       <firstterm>dynamic</firstterm> (see the table in <xref
1179       linkend="flag-reference">), may be set using
1180       <literal>:set</literal>.  To unset an option, you can set the
1181       reverse option:</para>
1182       <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
1183
1184 <screen>
1185 Prelude> :set -fno-glasgow-exts
1186 </screen>
1187
1188       <para><xref linkend="flag-reference"> lists the reverse for each
1189       option where applicable.</para>
1190
1191       <para>Certain static options (<option>-package</option>,
1192       <option>-I</option>, <option>-i</option>, and
1193       <option>-l</option> in particular) will also work, but some may
1194       not take effect until the next reload.</para>
1195       <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
1196     </sect2>
1197   </sect1>
1198
1199   <sect1 id="ghci-dot-files">
1200     <title>The <filename>.ghci</filename> file</title>
1201     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
1202     </indexterm>
1203     <indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
1204     </indexterm>
1205
1206     <para>When it starts, GHCi always reads and executes commands from
1207     <filename>$HOME/.ghci</filename>, followed by
1208     <filename>./.ghci</filename>.</para>
1209
1210     <para>The <filename>.ghci</filename> in your home directory is
1211     most useful for turning on favourite options (eg. <literal>:set
1212     +s</literal>), and defining useful macros.  Placing a
1213     <filename>.ghci</filename> file in a directory with a Haskell
1214     project is a useful way to set certain project-wide options so you
1215     don't have to type them everytime you start GHCi: eg. if your
1216     project uses GHC extensions and CPP, and has source files in three
1217     subdirectories A B and C, you might put the following lines in
1218     <filename>.ghci</filename>:</para>
1219
1220 <screen>
1221 :set -fglasgow-exts -cpp
1222 :set -iA:B:C
1223 </screen>
1224
1225     <para>(Note that strictly speaking the <option>-i</option> flag is
1226     a static one, but in fact it works to set it using
1227     <literal>:set</literal> like this.  The changes won't take effect
1228     until the next <literal>:load</literal>, though.)</para>
1229
1230     <para>Two command-line options control whether the
1231     <filename>.ghci</filename> files are read:</para>
1232
1233     <variablelist>
1234       <varlistentry>
1235         <term><option>-ignore-dot-ghci</option></term>
1236         <indexterm><primary><option>-ignore-dot-ghci</option></primary>
1237         </indexterm>
1238         <listitem>
1239           <para>Don't read either <filename>./.ghci</filename> or
1240           <filename>$HOME/.ghci</filename> when starting up.</para>
1241         </listitem>
1242       </varlistentry>
1243       <varlistentry>
1244         <term><option>-read-dot-ghci</option></term>
1245         <indexterm><primary><option>-read-dot-ghci</option></primary>
1246         </indexterm>
1247         <listitem>
1248           <para>Read <filename>.ghci</filename> and
1249           <filename>$HOME/.ghci</filename>.  This is normally the
1250           default, but the <option>-read-dot-ghci</option> option may
1251           be used to override a previous
1252           <option>-ignore-dot-ghci</option> option.</para>
1253         </listitem>
1254       </varlistentry>
1255     </variablelist>
1256
1257   </sect1>
1258
1259   <sect1>
1260     <title>FAQ and Things To Watch Out For</title>
1261
1262     <variablelist>
1263       <varlistentry>
1264         <term>The interpreter can't load modules with foreign export
1265         declarations!</term>
1266         <listitem>
1267           <para>Unfortunately not.  We haven't implemented it yet.
1268           Please compile any offending modules by hand before loading
1269           them into GHCi.</para>
1270         </listitem>
1271       </varlistentry>
1272
1273       <varlistentry>
1274         <term><literal>-O</literal> doesn't work with GHCi!</term>
1275         <indexterm><primary><option>-O</option></primary>
1276         </indexterm>
1277         <listitem>
1278           <para>For technical reasons, the bytecode compiler doesn't
1279           interact well with one of the optimisation passes, so we
1280           have disabled optimisation when using the interpreter.  This
1281           isn't a great loss: you'll get a much bigger win by
1282           compiling the bits of your code that need to go fast, rather
1283           than interpreting them with optimisation turned on.</para>
1284         </listitem>
1285       </varlistentry>
1286
1287       <varlistentry>
1288         <term>Unboxed tuples don't work with GHCi</term>
1289         <listitem>
1290           <para>That's right.  You can always compile a module that
1291           uses unboxed tuples and load it into GHCi, however.
1292           (Incidentally the previous point, namely that
1293           <literal>-O</literal> is incompatible with GHCi, is because
1294           the bytecode compiler can't deal with unboxed
1295           tuples).</para>
1296         </listitem>
1297       </varlistentry>
1298
1299       <varlistentry>
1300         <term>Concurrent threads don't carry on running when GHCi is
1301         waiting for input.</term>
1302         <listitem>
1303           <para>No, they don't.  This is because the Haskell binding
1304           to the GNU readline library doesn't support reading from the
1305           terminal in a non-blocking way, which is required to work
1306           properly with GHC's concurrency model.</para>
1307         </listitem>
1308       </varlistentry>
1309
1310       <varlistentry>
1311         <term>After using <literal>getContents</literal>, I can't use
1312         <literal>stdin</literal> again until I do
1313         <literal>:load</literal> or <literal>:reload</literal>.</term>
1314
1315         <listitem>
1316           <para>This is the defined behaviour of
1317           <literal>getContents</literal>: it puts the stdin Handle in
1318           a state known as <firstterm>semi-closed</firstterm>, wherein
1319           any further I/O operations on it are forbidden.  Because I/O
1320           state is retained between computations, the semi-closed
1321           state persists until the next <literal>:load</literal> or
1322           <literal>:reload</literal> command.</para>
1323
1324           <para>You can make <literal>stdin</literal> reset itself
1325           after every evaluation by giving GHCi the command
1326           <literal>:set +r</literal>.  This works because
1327           <literal>stdin</literal> is just a top-level expression that
1328           can be reverted to its unevaluated state in the same way as
1329           any other top-level expression (CAF).</para>
1330         </listitem>
1331       </varlistentry>
1332
1333     </variablelist>
1334   </sect1>
1335
1336 </chapter>
1337
1338 <!-- Emacs stuff:
1339      ;;; Local Variables: ***
1340      ;;; mode: sgml ***
1341      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
1342      ;;; End: ***
1343  -->