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></indexterm>
   5
   6   <para>GHCi<footnote>
   7       <para>The &lsquo;i&rsquo; stands for &ldquo;Interactive&rdquo;</para>
   8     </footnote>
   9   is GHC's interactive environment, in which Haskell expressions can
  10   be interactively evaluated and programs can be interpreted.  If
  11   you're famililar with Hugs<indexterm><primary>Hugs</primary>
  12   </indexterm>, then you'll be right at home with GHCi.  However, GHCi
  13   also has support for interactively loading compiled code, as well as
  14   supporting all<footnote><para>except the FFI, at the moment</para>
  15   </footnote>the language extensions that GHC provides.</para>
  16
  17   <sect1>
  18     <title>Introduction to GHCi</title>
  19
  20     <para>Let's start with an example GHCi session.  You can fire up
  21     GHCi with the command <literal>ghci</literal>:</para>
  22
  23 <screen>
  24 $ ghci
  25    ___         ___ _
  26   / _ \ /\  /\/ __(_)
  27  / /_\// /_/ / /  | |      GHC Interactive, version 4.11, For Haskell 98.
  28 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
  29 \____/\/ /_/\____/|_|      Type :? for help.
  30
  31 Loading package std ... linking ... done.
  32 Prelude>
  33 </screen>
  34
  35     <para>There may be a short pause while GHCi loads the prelude and
  36     standard libraries, after which the prompt is shown.  If we follow
  37     the instructions and type <literal>:?</literal> for help, we
  38     get:</para>
  39
  40 <screen>
  41  Commands available from the prompt:
  42    &lt;stmt&gt;              evaluate/run &lt;stmt&gt;
  43    :cd &lt;dir&gt;           change directory to &lt;dir&gt;
  44    :def &lt;cmd&gt; &lt;expr&gt;   define a macro :&lt;cmd&gt;
  45    :help, :?           display this list of commands
  46    :load &lt;filename&gt;    load a module (and it dependents)
  47    :module &lt;mod&gt;       set the context for expression evaluation to &lt;mod&gt;
  48    :reload             reload the current module set
  49    :set &lt;option&gt; ...   set options
  50    :type &lt;expr&gt;        show the type of &lt;expr&gt;
  51    :unset &lt;option&gt; ... unset options
  52    :quit               exit GHCi
  53    :!&lt;command&gt;         run the shell command &lt;command&gt;
  54  Options for `:set' and `:unset':
  55     +r                 revert top-level expressions after each evaluation
  56     +s                 print timing/memory stats after each evaluation
  57     +t                 print type after evaluation
  58     -&lt;flag&gt;            most GHC command line flags can also be set here
  59                          (eg. -v2, -fglasgow-exts, etc.)
  60 </screen>
  61
  62     <para>We'll explain most of these commands as we go along.  For
  63     Hugs users: many things work the same as in Hugs, so you should be
  64     able to get going straight away.</para>
  65
  66     <para>Haskell expressions can be typed at the prompt:</para>
  67     <indexterm><primary>prompt</primary><secondary>GHCi</secondary>
  68   </indexterm>
  69
  70 <screen>
  71 Prelude> 1+2
  72 3
  73 PrePrelude> let x = 42 in x / 9
  74 4.666666666666667
  75 Prelude>
  76 </screen>
  77
  78     <para>GHCi interprets the whole line as an expression to evaluate.
  79     The expression may not span several lines - as soon as you press
  80     enter, GHCi will attempt to evaluate it.</para>
  81   </sect1>
  82
  83   <sect1>
  84     <title>Loading source files</title>
  85
  86     <para>Suppose we have the following Haskell source code, which we
  87     place in a file <filename>Main.hs</filename> in the current
  88     directory:</para>
  89
  90 <programlisting>
  91 main = print (fac 20)
  92
  93 fac 0 = 1
  94 fac n = n * fac (n-1)
  95 </programlisting>
  96
  97     <para>To load a Haskell source file into GHCi, use the
  98     <literal>:load</literal> command:</para>
  99
 100 <screen>
 101 Prelude> :load Main
 102 Compiling Main             ( Main.hs, interpreted )
 103 Ok, modules loaded: Main.
 104 Main>
 105 </screen>
 106
 107     <para>GHCi has loaded the <literal>Main</literal> module, and the
 108     prompt has changed to &ldquo;<literal>Main></literal>&rdquo; to
 109     indicate that the current context for expressions typed at the
 110     prompt is the <literal>Main</literal> module we just
 111     loaded.  So we can now type expressions involving the functions
 112     from <filename>Main.hs</filename>:</para>
 113
 114 <screen>
 115 Main> fac 17
 116 355687428096000
 117 </screen>
 118
 119     <para>Loading a multi-module program is just as straightforward;
 120     just give the name of the &ldquo;topmost&rdquo; module to the
 121     <literal>:load</literal> command (hint: <literal>:load</literal>
 122     can be abbreviated to <literal>:l</literal>).  The topmost module
 123     will normally be <literal>Main</literal>, but it doesn't have to
 124     be.  GHCi will discover which modules are required, directly or
 125     indirectly, by the topmost module, and load them all in dependency
 126     order.</para>
 127
 128     <sect2>
 129       <title>Modules vs. filenames</title>
 130
 131       <para>Question: How does GHC find the filename which contains
 132       module <replaceable>M</replaceable>?  Answer: it looks for the
 133       file <literal><replaceable>M</replaceable>.hs</literal>, or
 134       <literal><replaceable>M</replaceable>.lhs</literal>.  This means
 135       that for most modules, the module name must match the filename.
 136       If it doesn't, GHCi won't be able to find it.</para>
 137
 138       <para>There is one exception to this general rule: when you load
 139       a program with <literal>:load</literal>, or specify it when you
 140       invoke <literal>ghci</literal>, you can give a filename rather
 141       than a module name.  This filename is loaded if it exists, and
 142       it may contain any module you like.  This is particularly
 143       convenient if you have several <literal>Main</literal> modules
 144       in the same directory and you can't call them all
 145       <filename>Main.hs</filename>.</para>
 146
 147       <para>One final note: if you load a module called Main, it must
 148       contain a <literal>main</literal> function, just like in
 149       GHC.</para>
 150     </sect2>
 151
 152     <sect2>
 153       <title>Making changes and recompilation</title>
 154
 155       <para>If you make some changes to the source code and want GHCi
 156       to recompile the program, give the <literal>:reload</literal>
 157       command.  The program will be recompiled as necessary, with GHCi
 158       doing its best to avoid actually recompiling modules if their
 159       external dependencies haven't changed.  This is the same
 160       mechanism we use to avoid re-compiling modules in the batch
 161       compilation setting (see <xref linkend="recomp">).</para>
 162     </sect2>
 163   </sect1>
 164
 165   <sect1 id="ghci-compiled">
 166     <title>Loading compiled code</title>
 167
 168     <para>When you load a Haskell source module into GHCi, it is
 169     normally converted to byte-code and run using the interpreter.
 170     However, interpreted code can also run alongside compiled code in
 171     GHCi; indeed, normally when GHCi starts, it loads up a compiled
 172     copy of package <literal>std</literal>, which contains the Prelude
 173     and standard libraries.</para>
 174
 175     <para>Why should we want to run compiled code?  Well, compiled
 176     code is roughly 10x faster than interpreted code, but takes about
 177     2x longer to produce (perhaps longer if optimisation is on).  So
 178     it pays to compile the parts of a program that aren't changing
 179     very often, and use the interpreter for the code being actively
 180     developed.</para>
 181
 182     <para>When loading up source files with <literal>:load</literal>,
 183     GHCi looks for any corresponding compiled object files, and will
 184     use one in preference to interpreting the source if possible.  For
 185     example, suppose we have a 4-module program consisting of modules
 186     A, B, C, and D.  Modules B and C both import D only,
 187     and A imports both B & C:</para>
 188 <screen>
 189       A
 190      / \
 191     B   C
 192      \ /
 193       D
 194 </screen>
 195     <para>We can compile D, then load the whole program, like this:</para>
 196 <screen>
 197 Prelude> :! ghc -c D.hs
 198 Prelude> :load A
 199 Skipping  D                ( D.hs, D.o )
 200 Compiling C                ( C.hs, interpreted )
 201 Compiling B                ( B.hs, interpreted )
 202 Compiling A                ( A.hs, interpreted )
 203 Ok, modules loaded: A, B, C, D.
 204 Main>
 205 </screen>
 206
 207     <para>In the messages from the compiler, we see that it skipped D,
 208     and used the object file <filename>D.o</filename>.  The message
 209     <literal>Skipping</literal> <replaceable>module</replaceable>
 210     indicates that compilation for <replaceable>module</replaceable>
 211     isn't necessary, because the source and everything it depends on
 212     is unchanged since the last compilation.</para>
 213
 214     <para>If we now modify the source of D (or pretend to: using Unix
 215     command <literal>touch</literal> on the source file is handy for
 216     this), the compiler will no longer be able to use the object file,
 217     because it might be out of date:</para>
 218
 219 <screen>
 220 Main> :! touch D.hs
 221 Main> :reload
 222 Compiling D                ( D.hs, interpreted )
 223 Skipping  C                ( C.hs, interpreted )
 224 Skipping  B                ( B.hs, interpreted )
 225 Skipping  A                ( A.hs, interpreted )
 226 Ok, modules loaded: A, B, C, D.
 227 Main>
 228 </screen>
 229
 230     <para>Note that module D was compiled, but in this instance
 231     because its source hadn't really changed, its interface remained
 232     the same, and the recompilation checker determined that A, B and C
 233     didn't need to be recompiled.</para>
 234
 235     <para>So let's try compiling one of the other modules:</para>
 236
 237 <screen>
 238 Main> :! ghc -c C.hs
 239 Main> :load A
 240 Compiling D                ( D.hs, interpreted )
 241 Compiling C                ( C.hs, interpreted )
 242 Compiling B                ( B.hs, interpreted )
 243 Compiling A                ( A.hs, interpreted )
 244 Ok, modules loaded: A, B, C, D.
 245 </screen>
 246
 247     <para>We didn't get the compiled version of C!  What happened?
 248     Well, in GHCi a compiled module may only depend on other compiled
 249     modules, and in this case C depends on D, which doesn't have an
 250     object file, so GHCi also rejected C's object file.  Ok, so let's
 251     also compile D:</para>
 252
 253 <screen>
 254 Main> :! ghc -c D.hs
 255 Main> :reload
 256 Ok, modules loaded: A, B, C, D.
 257 </screen>
 258
 259     <para>Nothing happened!  Here's another lesson: newly compiled
 260     modules aren't picked up by <literal>:reload</literal>, only
 261     <literal>:load</literal>:</para>
 262
 263 <screen>
 264 Main> :load A
 265 Skipping  D                ( D.hs, D.o )
 266 Skipping  C                ( C.hs, C.o )
 267 Compiling B                ( B.hs, interpreted )
 268 Compiling A                ( A.hs, interpreted )
 269 Ok, modules loaded: A, B, C, D.
 270 </screen>
 271
 272     <para>HINT: since GHCi will only use a compiled object file if it
 273     can sure that the compiled version is up-to-date, a good technique
 274     when working on a large program is to occasionally run
 275     <literal>ghc --make</literal> to compile the whole project (say
 276     before you go for lunch :-), then continue working in the
 277     interpreter.  As you modify code, the new modules will be
 278     interpreted, but the rest of the project will remain
 279     compiled.</para>
 280
 281   </sect1>
 282
 283   <sect1>
 284     <title>Interactive evaluation at the prompt</title>
 285
 286     <para>When you type an expression at the prompt, GHCi immediately
 287     evaluates and prints the result.  But that's not the whole story:
 288     if you type something of type <literal>IO a</literal> for some
 289     <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it
 290     as an IO-computation, and doesn't attempt to print the
 291     result:.</para>
 292
 293 <screen>
 294 Prelude> "hello"
 295 "hello"
 296 Prelude> putStrLn "hello"
 297 hello
 298 </screen>
 299
 300     <para>What actually happens is that GHCi typechecks the
 301     expression, and if it doesn't have an <literal>IO</literal> type,
 302     then it transforms it as follows: an expression
 303     <replaceable>e</replaceable> turns into <literal>let it =
 304     <replaceable>e</replaceable> in print it</literal>.  It then runs
 305     the new expression as an IO-action.</para>
 306
 307     <para>Hence the original expression must have a type which is an
 308     instance of the <literal>Show</literal> class, or GHCi will
 309     complain:</para>
 310
 311 <screen>
 312 Prelude> id
 313 No instance for `Show (a -> a)'
 314 arising from use of `print'
 315 in a `do' expression pattern binding: print it
 316 </screen>
 317
 318     <para>The error message contains some clues as to the
 319     transformation happening internally.</para>
 320
 321     <sect2 id="ghci-scope">
 322       <title>What's really in scope at the prompt?</title>
 323
 324        <para>When you type an expression at the prompt, what
 325        identifiers and types are in scope?  GHCi has a concept of a
 326        <firstterm>context</firstterm> module, which can be set using
 327        the <literal>:module</literal> command.</para>
 328
 329       <para>The context module is shown in the prompt: for example,
 330       the prompt <literal>Prelude></literal> indicates that the
 331       current context for evaluating expressions is the Haskell
 332       <literal>Prelude</literal> module.  This is the default context
 333       when you start up GHCi.</para>
 334       <indexterm><primary><literal>Prelude</literal></primary></indexterm>
 335
 336       <para>Exactly which entities are in scope in a given context
 337       depends on whether the context module is compiled or
 338       interpreted:</para>
 339
 340       <itemizedlist>
 341         <listitem>
 342           <para>If the context module is interpreted, then everything
 343           that was in scope during compilation of that module is also
 344           in scope at the prompt, i.e. all the imports and any
 345           top-level functions, types and classes defined in that
 346           module.</para>
 347         </listitem>
 348
 349         <listitem>
 350           <para>If the context module comes from a package, or is
 351           otherwise compiled, then only the exports of that module are
 352           in scope at the prompt.  So for example, when the current
 353           context module is <literal>Prelude</literal>, everything the
 354           <literal>Prelude</literal> exports is in scope, but if we
 355           switch context to eg. <literal>Time</literal>, then
 356           everything from the <literal>Prelude</literal> is now
 357           invisible.</para>
 358         </listitem>
 359       </itemizedlist>
 360
 361       <para>The reason for this unfortunate distinction is boring: for
 362       a compiled module when the source isn't available, the compiler
 363       has no way of knowing what was in scope when the module was
 364       compiled (and we don't store this information in the interface
 365       file).  However, in practice it shouldn't be a problem: if you
 366       want both <literal>Time</literal> and <literal>Prelude</literal>
 367       in scope at the same time, just create a file containing the
 368       line <literal>import Time</literal> and load it into
 369       GHCi.</para>
 370
 371       <para>To make life slightly easier, the GHCi prompt also behaves
 372       as if there is an implicit <literal>import qualified</literal>
 373       declaration for every module in every package, and every module
 374       currently loaded into GHCi.  So in the above example where the
 375       <literal>Prelude</literal> was invisible, we can always get at
 376       <literal>Prelude</literal> identifiers by qualifying them, eg.
 377       <literal>Prelude.map</literal>.</para>
 378     </sect2>
 379
 380     <sect2>
 381       <title>Using <literal>do-</literal>notation at the prompt</title>
 382
 383       <para>GHCi actually accepts <firstterm>statements</firstterm>
 384       rather than just expressions at the prompt.  This means you can
 385       bind values and functions to names, and use them in future
 386       expressions or statements.</para>
 387
 388       <para>The syntax of a statement accepted at the GHCi prompt is
 389       exactly the same as the syntax of a statement in a Haskell
 390       <literal>do</literal> expression.  However, there's no monad
 391       overloading here: statements typed at the prompt must be in the
 392       <literal>IO</literal> monad.</para>
 393
 394       <para>Here's an example:</para>
 395 <screen>
 396 Prelude> x <- return 42
 397 Prelude> print x
 398 42
 399 Prelude>
 400 </screen>
 401       <para>The statement <literal>x <- return 42</literal> means
 402       &ldquo;execute <literal>return 42</literal> in the
 403       <literal>IO</literal> monad, and bind the result to
 404       <literal>x</literal>&rdquo;.  We can then use
 405       <literal>x</literal> in future statements, for example to print
 406       it as we did above.</para>
 407
 408       <para>Of course, you can also bind normal non-IO expressions
 409       using the <literal>let</literal>-statement:</para>
 410 <screen>
 411 Prelude> let x = 42
 412 Prelude> print x
 413 42
 414 Prelude>
 415 </screen>
 416       <para>An important difference between the two types of binding
 417       is that the monadic bind (<literal>p <- e</literal>) is
 418       <emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
 419       whereas with the <literal>let</literal> form, the expression
 420       isn't evaluated immediately:</para>
 421 <screen>
 422 Prelude> let x = error "help!"
 423 Prelude> print x
 424 *** Exception: help!
 425 Prelude>
 426 </screen>
 427       <para>Any exceptions raised during the evaluation or execution
 428       of the statement are caught and printed by the GHCi command line
 429       interface (see <xref linkend="sec-Exception"> for more
 430       information on GHC's Exception support).</para>
 431
 432       <para>Every new binding shadows any existing bindings of the
 433       same name, including entities that are in scope in the current
 434       module context.</para>
 435
 436       <para>WARNING: temporary bindings introduced at the prompt only
 437       last until the next <literal>:load</literal> or
 438       <literal>:reload</literal> command, at which time they will be
 439       simply lost.  However, they do survive a change of context with
 440       <literal>:module</literal>: the temporary bindings just move to
 441       the new location.</para>
 442
 443       <para>HINT: if you turn on the <literal>+t</literal> option,
 444       GHCi will show the type of each variable bound by a statement.
 445       For example:</para>
 446 <screen>
 447 Prelude> :set +t
 448 Prelude> let (x:xs) = [1..]
 449 x :: Integer
 450 xs :: [Integer]
 451 </screen>
 452
 453     </sect2>
 454
 455     <sect2>
 456       <title>The <literal>it</literal> variable</title>
 457       <indexterm><primary><literal>it</literal></primary>
 458       </indexterm>
 459
 460       <para>Whenever an expression (or a non-binding statement, to be
 461       precise) is typed at the prompt, GHCi implicitly binds its value
 462       to the variable <literal>it</literal>.  For example:</para>
 463 <screen>
 464 Prelude> 1+2
 465 3
 466 Prelude> it * 2
 467 6
 468 </screen>
 469
 470       <para>If the expression was of type <literal>IO a</literal> for
 471       some <literal>a</literal>, then <literal>it</literal> will be
 472       bound to the result of the <literal>IO</literal> computation,
 473       which is of type <literal>a</literal>.  eg.:</para>
 474 <screen>
 475 Prelude> Time.getClockTime
 476 Prelude> print it
 477 Wed Mar 14 12:23:13 GMT 2001
 478 </screen>
 479
 480       <para>Note that <literal>it</literal> is shadowed by the new
 481       value each time you evaluate a new expression, and the old value
 482       of <literal>it</literal> is lost.</para>
 483
 484     </sect2>
 485   </sect1>
 486
 487   <sect1>
 488     <title>Invoking GHCi</title>
 489
 490     <para>GHCi is invoked with the command <literal>ghci</literal> or
 491     <literal>ghc --interactive</literal>.  A module or filename can
 492     also be specified on the command line; this instructs GHCi to load
 493     the that module or filename (and all the modules it depends on),
 494     just as if you had said
 495     <literal>:load <replaceable>module</replaceable></literal> at the GHCi prompt
 496     (see <xref linkend="ghci-commands">).  For example, to start GHCi
 497     and load the program whose topmost module is in the file
 498     <literal>Main.hs</literal>, we could say:</para>
 499
 500 <screen>
 501 $ ghci Main.hs
 502 </screen>
 503
 504     <para>Note: only <emphasis>one</emphasis> module name or filename
 505     may be given on the command line.</para>
 506
 507     <para>Most of the command-line options accepted by GHC (see <xref
 508     linkend="using-ghc">) also make sense in interactive mode.  The ones
 509     that don't make sense are mostly obvious; for example, GHCi
 510     doesn't generate interface files, so options related to interface
 511     file generation won't have any effect.</para>
 512
 513     <sect2>
 514       <title>Packages</title>
 515
 516       <para>GHCi can make use of all the packages that come with GHC,
 517       but note: packages <emphasis>must</emphasis> be specified on the
 518       GHCi command line, you can't add extra packages after GHCi has
 519       started up.  For example, to start up GHCi with the
 520       <literal>text</literal> package loaded:</para>
 521
 522 <screen>
 523 $ ghci -package text
 524    ___         ___ _
 525   / _ \ /\  /\/ __(_)
 526  / /_\// /_/ / /  | |      GHC Interactive, version 4.11, For Haskell 98.
 527 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 528 \____/\/ /_/\____/|_|      Type :? for help.
 529
 530 Loading package std ... linking ... done.
 531 Loading package lang ... linking ... done.
 532 Loading package text ... linking ... done.
 533 Prelude>
 534 </screen>
 535
 536       <para>Note that GHCi also loaded the <literal>lang</literal>
 537       package even though we didn't ask for it: that's because the
 538       <literal>text</literal> package makes use of one or more of the
 539       modules in <literal>lang</literal>, and therefore has a
 540       dependency on it.</para>
 541     </sect2>
 542
 543     <sect2>
 544       <title>Extra libraries</title>
 545
 546       <para>Extra libraries may be specified on the command line using
 547       the normal <literal>-l<replaceable>lib</replaceable></literal>
 548       option.  For example, to load the &ldquo;m&rdquo; library:</para>
 549
 550 <screen>
 551 $ ghci -lm
 552 </screen>
 553
 554       <para>On systems with <literal>.so</literal>-style shared
 555       libraries, the actual library loaded will the
 556       <filename>lib<replaceable>lib</replaceable>.so</filename>.  If
 557       no such library exists on the standard library search path,
 558       including paths given using
 559       <literal>-L<replaceable>path</replaceable></literal>, then
 560       <literal>ghci</literal> will signal an error.</para>
 561
 562       <para>On systems with <literal>.dll</literal>-style shared
 563       libraries, the actual library loaded will be
 564       <filename><replaceable>lib</replaceable>.dll</filename>.  Again,
 565       GHCi will signal an error if it can't find the library.</para>
 566     </sect2>
 567
 568   </sect1>
 569
 570   <sect1 id="ghci-commands">
 571     <title>GHCi commands</title>
 572
 573     <para>GHCi commands all begin with
 574     &lsquo;<literal>:</literal>&rsquo; and consist of a single command
 575     name followed by zero or more parameters.  The command name may be
 576     abbreviated, as long as the abbreviation is not ambiguous.  All of
 577     the builtin commands, with the exception of
 578     <literal>:unset</literal> and <literal>:undef</literal>, may be
 579     abbreviated to a single letter.</para>
 580
 581     <variablelist>
 582       <varlistentry>
 583         <term><literal>:cd</literal> <replaceable>dir</replaceable></term>
 584         <listitem>
 585           <para>Changes the current working directory to
 586           <replaceable>dir</replaceable>.  A
 587           &lsquo;<literal>&tilde;</literal>&rsquo; symbol at the
 588           beginning of <replaceable>dir</replaceable> will be replaced
 589           by the contents of the environment variable
 590           <literal>HOME</literal>.</para>
 591         </listitem>
 592       </varlistentry>
 593
 594       <varlistentry>
 595         <term><literal>:def</literal></term>
 596         <listitem>
 597           <para>ToDo.</para>
 598         </listitem>
 599       </varlistentry>
 600
 601       <varlistentry>
 602         <term><literal>:help</literal></term>
 603         <term><literal>:?</literal></term>
 604         <listitem>
 605           <para>Displays a list of the available commands.</para>
 606         </listitem>
 607       </varlistentry>
 608
 609       <varlistentry>
 610         <term><literal>:load</literal> <replaceable>module</replaceable></term>
 611         <listitem>
 612           <para>Recursively loads <replaceable>module</replaceable>
 613           (which may be a module name or filename), and all the
 614           modules it depends on.  All previously loaded modules are
 615           forgotten.  The module <replaceable>module</replaceable> is
 616           known as the <firstterm>target</firstterm>.</para>
 617         </listitem>
 618       </varlistentry>
 619
 620       <varlistentry>
 621         <term><literal>:module</literal> <replaceable>module</replaceable></term>
 622         <listitem>
 623           <para>Sets the current context for statements typed at the
 624           prompt to <replaceable>module</replaceable>, which must be a
 625           module name which is already loaded or in a package.  See
 626           <xref linkend="ghci-scope"> for more information on what
 627           effect the context has on what entities are in scope at the
 628           prompt.</para>
 629         </listitem>
 630       </varlistentry>
 631
 632       <varlistentry>
 633         <term><literal>:quit</literal> <replaceable>module</replaceable></term>
 634         <listitem>
 635           <para>Quits GHCi.  You can also quit by typing a control-D
 636           at the prompt.</para>
 637         </listitem>
 638       </varlistentry>
 639
 640       <varlistentry>
 641         <term><literal>:reload</literal></term>
 642         <listitem>
 643           <para>Attempts to reload the current target (see
 644           <literal>:load</literal>) if it, or any module it depends
 645           on, has changed.  Note that this may entail loading new
 646           modules, or even dropping modules which are no longer
 647           indirectly required by the target.</para>
 648         </listitem>
 649       </varlistentry>
 650
 651       <varlistentry>
 652         <term><literal>:set</literal> <optional><replaceable>option</replaceable>...</optional></term>
 653         <listitem>
 654           <para>Sets various options.  See <xref linkend="ghci-set">
 655           for a list of available options.  The
 656           <literal>:set</literal> command by itself shows which
 657           options are currently set.</para>
 658         </listitem>
 659       </varlistentry>
 660
 661       <varlistentry>
 662         <term><literal>:type</literal> <replaceable>expression</replaceable></term>
 663         <listitem>
 664           <para>Infers and prints the type of
 665           <replaceable>expression</replaceable>, including explicit
 666           forall quantifiers for polymorphic types.  The monomorphism
 667           restriction is <emphasis>not</emphasis> applied to the
 668           expression during type inference.</para>
 669         </listitem>
 670       </varlistentry>
 671
 672       <varlistentry>
 673         <term><literal>:unset</literal> <replaceable>option</replaceable>...</term>
 674         <listitem>
 675           <para>Unsets certain options.  See <xref linkend="ghci-set">
 676           for a list of available options.</para>
 677         </listitem>
 678       </varlistentry>
 679
 680       <varlistentry>
 681         <term><literal>:!</literal> <replaceable>command</replaceable>...</term>
 682         <listitem>
 683           <para>Executes the shell command
 684           <replaceable>command</replaceable>.</para>
 685         </listitem>
 686       </varlistentry>
 687
 688     </variablelist>
 689   </sect1>
 690
 691   <sect1 id="ghci-set">
 692     <title>The <literal>:set</literal> command</title>
 693
 694     <para>The <literal>:set</literal> command sets two types of
 695     options: GHCi options, which begin with
 696     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
 697     options, which begin with &lsquo;-&rsquo;.  Either type of option
 698     may be set using <literal>:set</literal> and unset using
 699     <literal>:unset</literal>.</para>
 700
 701     <para>The available GHCi options are:</para>
 702
 703     <variablelist>
 704       <varlistentry>
 705         <term><literal>+r</literal></term>
 706         <listitem>
 707           <para>Normally, any evaluation of top-level expressions
 708           (otherwise known as CAFs or Constant Applicative Forms) in
 709           loaded modules is retained between evaluations.  Turning on
 710           <literal>+r</literal> causes all evaluation of top-level
 711           expressions to be discarded after each evaluation (they are
 712           still retained <emphasis>during</emphasis> a single
 713           evaluation).</para>
 714
 715           <para>This option may help if the evaluated top-level
 716           expressions are consuming large amounts of space, or if you
 717           need repeatable performance measurements.</para>
 718         </listitem>
 719       </varlistentry>
 720
 721       <varlistentry>
 722         <term><literal>+s</literal></term>
 723         <listitem>
 724           <para>Display some stats after evaluating each expression,
 725           including the elapsed time and number of bytes allocated.
 726           NOTE: the allocation figure is only accurate to the size of
 727           the storage manager's allocation area, because it is
 728           calculated at every GC.  Hence, you might see values of zero
 729           if no GC has occurred.</para>
 730         </listitem>
 731       </varlistentry>
 732
 733       <varlistentry>
 734         <term><literal>+t</literal></term>
 735         <listitem>
 736           <para>Display the type of each variable bound after a
 737           statement is entered at the prompt.  If the statement is a
 738           single expression, then the only variable binding will be
 739           for the variable &lsquo;<literal>it</literal>&rsquo;.</para>
 740         </listitem>
 741       </varlistentry>
 742     </variablelist>
 743
 744     <para>In addition, any normal GHC command-line option that is
 745     designated as <firstterm>dynamic</firstterm> (see the table in
 746     <xref linkend="flag-reference">), may be set using
 747     <literal>:set</literal>.  Certain static options
 748     (<option>-I</option>, <option>-i</option>, and <option>-l</option>
 749     in particular) will also work, but may not take effect until the
 750     next reload.</para>
 751   </sect1>
 752
 753   <sect1>
 754     <title>The <filename>.ghci</filename> file</title>
 755     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
 756     </indexterm>
 757     <indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
 758     </indexterm>
 759
 760     <para>When it starts, GHCi always reads and executes commands from
 761     <filename>$HOME/.ghci</filename>, followed by
 762     <filename>./.ghci</filename>.</para>
 763
 764     <para>The <filename>.ghci</filename> in your home directory is
 765     most useful for turning on favourite options (eg. <literal>:set
 766     +s</literal>), and defining useful macros.  Placing a
 767     <filename>.ghci</filename> file in a directory with a Haskell
 768     project is a useful way to set certain project-wide options so you
 769     don't have to type them everytime you start GHCi: eg. if your
 770     project uses GHC extensions and CPP, and has source files in three
 771     subdirectories A B and C, you might put the following lines in
 772     <filename>.ghci</filename>:</para>
 773
 774 <screen>
 775 :set -fglasgow-exts -cpp
 776 :set -iA:B:C
 777 </screen>
 778
 779     <para>(Note that strictly speaking the <option>-i</option> flag is
 780     a static one, but in fact it works to set it using
 781     <literal>:set</literal> like this.  The changes won't take effect
 782     until the next <literal>:load</literal>, though.)</para>
 783   </sect1>
 784
 785   <sect1>
 786     <title>FAQ and Things To Watch Out For</title>
 787
 788     <variablelist>
 789       <varlistentry>
 790         <term><literal>System.exit</literal> causes GHCi to exit!</term>
 791         <listitem>
 792           <para>Yes, it does.</para>
 793         </listitem>
 794       </varlistentry>
 795
 796       <varlistentry>
 797         <term><literal>System.getArgs</literal> returns GHCi's command
 798         line arguments!</term>
 799         <listitem>
 800           <para>Yes, it does.</para>
 801         </listitem>
 802       </varlistentry>
 803
 804       <varlistentry>
 805         <term>The interpreter can't load modules with FFI
 806         declarations!</term>
 807         <listitem>
 808           <para>Unfortunately not.  We haven't implemented it yet.
 809           Please compile any offending modules by hand before loading
 810           them into GHCi.</para>
 811         </listitem>
 812       </varlistentry>
 813
 814       <varlistentry>
 815         <term>Hugs has a <literal>:add</literal> command for adding
 816         modules without throwing away any that are already loaded.
 817         Why doesn't this work in GHCi?</term>
 818         <listitem>
 819           <para>We haven't implemented it yet.  Sorry about that.</para>
 820         </listitem>
 821       </varlistentry>
 822
 823       <varlistentry>
 824         <term><literal>-O</literal> doesn't work with GHCi!</term>
 825         <indexterm><primary><option>-O</option></primary>
 826         </indexterm>
 827         <listitem>
 828           <para>For technical reasons, the bytecode compiler doesn't
 829           interact well with one of the optimisation passes, so we
 830           have disabled optimisation when using the interpreter.  This
 831           isn't a great loss: you'll get a much bigger win by
 832           compiling the bits of your code that need to go fast, rather
 833           than interpreting them with optimisation turned on.</para>
 834         </listitem>
 835       </varlistentry>
 836
 837       <varlistentry>
 838         <term>Unboxed tuples don't work with GHCi</term>
 839         <listitem>
 840           <para>That's right.  You can always compile a module that
 841           uses unboxed tuples and load it into GHCi, however.
 842           (Incidentally the previous point, namely that
 843           <literal>-O</literal> is incompatible with GHCi, is because
 844           the bytecode compiler can't deal with unboxed
 845           tuples).</para>
 846         </listitem>
 847       </varlistentry>
 848
 849       <varlistentry>
 850         <term>Concurrent threads don't carry on running when GHCi is
 851         waiting for input.</term>
 852         <listitem>
 853           <para>No, they don't.  This is because the Haskell binding
 854           to the GNU readline library doesn't support reading from the
 855           terminal in a non-blocking way, which is required to work
 856           properly with GHC's concurrency model.</para>
 857         </listitem>
 858       </varlistentry>
 859     </variablelist>
 860
 861   </sect1>
 862
 863 </chapter>
 864
 865 <!-- Emacs stuff:
 866      ;;; Local Variables: ***
 867      ;;; mode: sgml ***
 868      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 869      ;;; End: ***
 870  -->