ghci.xml 106 KB
Newer Older
1
<?xml version="1.0" encoding="iso-8859-1"?>
2
<chapter id="ghci">
3
  <title>Using GHCi</title>
4
  <indexterm><primary>GHCi</primary></indexterm>
5
6
  <indexterm><primary>interpreter</primary><see>GHCi</see></indexterm>
  <indexterm><primary>interactive</primary><see>GHCi</see></indexterm>
7
  
8
9
10
11
12
  <para>GHCi<footnote>
      <para>The &lsquo;i&rsquo; stands for &ldquo;Interactive&rdquo;</para>
    </footnote>
  is GHC's interactive environment, in which Haskell expressions can
  be interactively evaluated and programs can be interpreted.  If
ross's avatar
ross committed
13
  you're familiar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary>
14
15
  </indexterm>, then you'll be right at home with GHCi.  However, GHCi
  also has support for interactively loading compiled code, as well as
16
  supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
Simon Marlow's avatar
Simon Marlow committed
17
  </footnote> the language extensions that GHC provides.
18
  <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
Simon Marlow's avatar
Simon Marlow committed
19
20
  <indexterm><primary>Foreign Function
  Interface</primary><secondary>GHCi support</secondary></indexterm>.
Ian Lynagh's avatar
Ian Lynagh committed
21
  GHCi also includes an interactive debugger (see <xref linkend="ghci-debugger"/>).</para>
22

23
  <sect1 id="ghci-introduction">
24
25
26
27
28
29
30
    <title>Introduction to GHCi</title>

    <para>Let's start with an example GHCi session.  You can fire up
    GHCi with the command <literal>ghci</literal>:</para>

<screen>
$ ghci
Ian Lynagh's avatar
Ian Lynagh committed
31
GHCi, version 6.8.1: http://www.haskell.org/ghc/  :? for help
32
Loading package base ... linking ... done.
33
34
35
36
Prelude> 
</screen>

    <para>There may be a short pause while GHCi loads the prelude and
37
38
39
    standard libraries, after which the prompt is shown. As the banner
    says, you can type <literal>:?</literal> to see the list of commands
    available, and a half line description of each of them.</para>
40
41
42
43
44
45
46
47
48
49
50
51

    <para>We'll explain most of these commands as we go along.  For
    Hugs users: many things work the same as in Hugs, so you should be
    able to get going straight away.</para>

    <para>Haskell expressions can be typed at the prompt:</para>
    <indexterm><primary>prompt</primary><secondary>GHCi</secondary>
  </indexterm>

<screen>
Prelude> 1+2
3
52
Prelude> let x = 42 in x / 9
53
54
55
56
57
58
59
60
61
4.666666666666667
Prelude> 
</screen>

    <para>GHCi interprets the whole line as an expression to evaluate.
    The expression may not span several lines - as soon as you press
    enter, GHCi will attempt to evaluate it.</para>
  </sect1>

62
  <sect1 id="loading-source-files">
63
64
65
    <title>Loading source files</title>

    <para>Suppose we have the following Haskell source code, which we
66
    place in a file <filename>Main.hs</filename>:</para>
67
68
69
70
71
72
73
74

<programlisting>
main = print (fac 20)

fac 0 = 1
fac n = n * fac (n-1)
</programlisting>

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
    <para>You can save <filename>Main.hs</filename> anywhere you like,
    but if you save it somewhere other than the current
    directory<footnote><para>If you started up GHCi from the command
    line then GHCi's current directory is the same as the current
    directory of the shell from which it was started.  If you started
    GHCi from the &ldquo;Start&rdquo; menu in Windows, then the
    current directory is probably something like
    <filename>C:\Documents and Settings\<replaceable>user
    name</replaceable></filename>.</para> </footnote> then we will
    need to change to the right directory in GHCi:</para>

<screen>
Prelude> :cd <replaceable>dir</replaceable>
</screen>

    <para>where <replaceable>dir</replaceable> is the directory (or
    folder) in which you saved <filename>Main.hs</filename>.</para>

93
94
    <para>To load a Haskell source file into GHCi, use the
    <literal>:load</literal> command:</para>
95
    <indexterm><primary><literal>:load</literal></primary></indexterm>
96
97
98
99
100

<screen>
Prelude> :load Main
Compiling Main             ( Main.hs, interpreted )
Ok, modules loaded: Main.
101
*Main>
102
103
104
</screen>

    <para>GHCi has loaded the <literal>Main</literal> module, and the
105
    prompt has changed to &ldquo;<literal>*Main></literal>&rdquo; to
106
    indicate that the current context for expressions typed at the
107
108
    prompt is the <literal>Main</literal> module we just loaded (we'll
    explain what the <literal>*</literal> means later in <xref
109
    linkend="ghci-scope"/>).  So we can now type expressions involving
110
    the functions from <filename>Main.hs</filename>:</para>
111
112

<screen>
113
*Main> fac 17
114
115
116
117
118
119
120
121
122
123
124
125
355687428096000
</screen>

    <para>Loading a multi-module program is just as straightforward;
    just give the name of the &ldquo;topmost&rdquo; module to the
    <literal>:load</literal> command (hint: <literal>:load</literal>
    can be abbreviated to <literal>:l</literal>).  The topmost module
    will normally be <literal>Main</literal>, but it doesn't have to
    be.  GHCi will discover which modules are required, directly or
    indirectly, by the topmost module, and load them all in dependency
    order.</para>

126
    <sect2 id="ghci-modules-filenames">
127
      <title>Modules vs. filenames</title>
128
129
      <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
      <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
      
      <para>Question: How does GHC find the filename which contains
      module <replaceable>M</replaceable>?  Answer: it looks for the
      file <literal><replaceable>M</replaceable>.hs</literal>, or
      <literal><replaceable>M</replaceable>.lhs</literal>.  This means
      that for most modules, the module name must match the filename.
      If it doesn't, GHCi won't be able to find it.</para>

      <para>There is one exception to this general rule: when you load
      a program with <literal>:load</literal>, or specify it when you
      invoke <literal>ghci</literal>, you can give a filename rather
      than a module name.  This filename is loaded if it exists, and
      it may contain any module you like.  This is particularly
      convenient if you have several <literal>Main</literal> modules
      in the same directory and you can't call them all
      <filename>Main.hs</filename>.</para>

147
148
149
150
151
152
153
      <para>The search path for finding source files is specified with
      the <option>-i</option> option on the GHCi command line, like
      so:</para>
<screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen>

      <para>or it can be set using the <literal>:set</literal> command
      from within GHCi (see <xref
154
      linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in
155
      GHCi, and <option>&ndash;&ndash;make</option> mode, the <option>-i</option>
156
157
158
159
      option is used to specify the search path for
      <emphasis>source</emphasis> files, whereas in standard
      batch-compilation mode the <option>-i</option> option is used to
      specify the search path for interface files, see <xref
160
      linkend="search-path"/>.</para> </footnote></para>
161

162
163
164
165
166
167
168
169
170
      <para>One consequence of the way that GHCi follows dependencies
      to find modules to load is that every module must have a source
      file.  The only exception to the rule is modules that come from
      a package, including the <literal>Prelude</literal> and standard
      libraries such as <literal>IO</literal> and
      <literal>Complex</literal>.  If you attempt to load a module for
      which GHCi can't find a source file, even if there are object
      and interface files for the module, you'll get an error
      message.</para>
171
172
173
174
    </sect2>

    <sect2>
      <title>Making changes and recompilation</title>
175
      <indexterm><primary><literal>:reload</literal></primary></indexterm>
176
177
178
179
180
181
182

      <para>If you make some changes to the source code and want GHCi
      to recompile the program, give the <literal>:reload</literal>
      command.  The program will be recompiled as necessary, with GHCi
      doing its best to avoid actually recompiling modules if their
      external dependencies haven't changed.  This is the same
      mechanism we use to avoid re-compiling modules in the batch
183
      compilation setting (see <xref linkend="recomp"/>).</para>
184
185
186
187
188
    </sect2>
  </sect1>

  <sect1 id="ghci-compiled">
    <title>Loading compiled code</title>
189
    <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm>
190
191
192
193
194

    <para>When you load a Haskell source module into GHCi, it is
    normally converted to byte-code and run using the interpreter.
    However, interpreted code can also run alongside compiled code in
    GHCi; indeed, normally when GHCi starts, it loads up a compiled
195
196
    copy of the <literal>base</literal> package, which contains the
    <literal>Prelude</literal>.</para>
197
198
199
200
201
202
203
204
205
206
207
208
209

    <para>Why should we want to run compiled code?  Well, compiled
    code is roughly 10x faster than interpreted code, but takes about
    2x longer to produce (perhaps longer if optimisation is on).  So
    it pays to compile the parts of a program that aren't changing
    very often, and use the interpreter for the code being actively
    developed.</para>

    <para>When loading up source files with <literal>:load</literal>,
    GHCi looks for any corresponding compiled object files, and will
    use one in preference to interpreting the source if possible.  For
    example, suppose we have a 4-module program consisting of modules
    A, B, C, and D.  Modules B and C both import D only,
210
    and A imports both B &amp; C:</para>
211
212
213
214
215
216
217
218
219
220
221
222
<screen>
      A
     / \
    B   C
     \ /
      D
</screen>
    <para>We can compile D, then load the whole program, like this:</para>
<screen>
Prelude> :! ghc -c D.hs
Prelude> :load A
Compiling B                ( B.hs, interpreted )
223
Compiling C                ( C.hs, interpreted )
224
225
Compiling A                ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
226
*Main>
227
228
</screen>

229
230
231
232
    <para>In the messages from the compiler, we see that there is no line
    for <literal>D</literal>. This is because
    it isn't necessary to compile <literal>D</literal>,
    because the source and everything it depends on
233
234
    is unchanged since the last compilation.</para>

235
236
237
238
239
240
241
242
243
244
245
246
247
    <para>At any time you can use the command 
    <literal>:show modules</literal>
    to get a list of the modules currently loaded
    into GHCi:</para>

<screen>
*Main> :show modules
D                ( D.hs, D.o )
C                ( C.hs, interpreted )
B                ( B.hs, interpreted )
A                ( A.hs, interpreted )
*Main></screen>

248
    <para>If we now modify the source of D (or pretend to: using the Unix
249
250
251
252
253
    command <literal>touch</literal> on the source file is handy for
    this), the compiler will no longer be able to use the object file,
    because it might be out of date:</para>

<screen>
254
255
*Main> :! touch D.hs
*Main> :reload
256
257
Compiling D                ( D.hs, interpreted )
Ok, modules loaded: A, B, C, D.
258
*Main> 
259
260
261
262
263
264
265
266
267
268
</screen>

    <para>Note that module D was compiled, but in this instance
    because its source hadn't really changed, its interface remained
    the same, and the recompilation checker determined that A, B and C
    didn't need to be recompiled.</para>

    <para>So let's try compiling one of the other modules:</para>

<screen>
269
270
*Main> :! ghc -c C.hs
*Main> :load A
271
272
Compiling D                ( D.hs, interpreted )
Compiling B                ( B.hs, interpreted )
273
Compiling C                ( C.hs, interpreted )
274
275
276
277
278
279
280
281
282
283
284
Compiling A                ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
</screen>

    <para>We didn't get the compiled version of C!  What happened?
    Well, in GHCi a compiled module may only depend on other compiled
    modules, and in this case C depends on D, which doesn't have an
    object file, so GHCi also rejected C's object file.  Ok, so let's
    also compile D:</para>

<screen>
285
286
*Main> :! ghc -c D.hs
*Main> :reload
287
288
289
290
291
292
293
294
Ok, modules loaded: A, B, C, D.
</screen>

    <para>Nothing happened!  Here's another lesson: newly compiled
    modules aren't picked up by <literal>:reload</literal>, only
    <literal>:load</literal>:</para>

<screen>
295
*Main> :load A
296
297
298
299
300
301
Compiling B                ( B.hs, interpreted )
Compiling A                ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
</screen>

    <para>HINT: since GHCi will only use a compiled object file if it
Ian Lynagh's avatar
Ian Lynagh committed
302
    can be sure that the compiled version is up-to-date, a good technique
303
    when working on a large program is to occasionally run
304
    <literal>ghc &ndash;&ndash;make</literal> to compile the whole project (say
305
    before you go for lunch :-), then continue working in the
306
    interpreter.  As you modify code, the changed modules will be
307
308
309
310
311
    interpreted, but the rest of the project will remain
    compiled.</para>

  </sect1>

312
  <sect1 id="interactive-evaluation">
313
314
315
    <title>Interactive evaluation at the prompt</title>

    <para>When you type an expression at the prompt, GHCi immediately
316
317
318
319
320
321
322
323
324
325
    evaluates and prints the result:
<screen>
Prelude> reverse "hello"
"olleh"
Prelude> 5+5
10
</screen>
</para>

<sect2><title>I/O actions at the prompt</title>
326

327
328
329
330
<para>GHCi does more than simple expression evaluation at the prompt.
If you type something of type <literal>IO a</literal> for some
    <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it
    as an IO-computation.
331
332
333
334
335
336
<screen>
Prelude> "hello"
"hello"
Prelude> putStrLn "hello"
hello
</screen>
337
338
339
340
341
342
343
344
345
346
347
348
349
350
Furthermore, GHCi will print the result of the I/O action if (and only
if):
<itemizedlist>
  <listitem><para>The result type is an instance of <literal>Show</literal>.</para></listitem>
  <listitem><para>The result type is not
  <literal>()</literal>.</para></listitem>
</itemizedlist>
For example, remembering that <literal>putStrLn :: String -> IO ()</literal>:
<screen>
Prelude> putStrLn "hello"
hello
Prelude> do { putStrLn "hello"; return "yes" }
hello
"yes"
351
</screen>
352
</para></sect2>
353

354
    <sect2 id="ghci-stmts">
355
356
357
358
359
360
361
362
      <title>Using <literal>do-</literal>notation at the prompt</title>
      <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm>
      <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm>
      
      <para>GHCi actually accepts <firstterm>statements</firstterm>
      rather than just expressions at the prompt.  This means you can
      bind values and functions to names, and use them in future
      expressions or statements.</para>
363

364
365
366
367
368
      <para>The syntax of a statement accepted at the GHCi prompt is
      exactly the same as the syntax of a statement in a Haskell
      <literal>do</literal> expression.  However, there's no monad
      overloading here: statements typed at the prompt must be in the
      <literal>IO</literal> monad.
369
<screen>
370
371
372
373
Prelude> x &lt;- return 42
Prelude> print x
42
Prelude>
374
</screen>
375
376
377
378
379
380
      The statement <literal>x &lt;- return 42</literal> means
      &ldquo;execute <literal>return 42</literal> in the
      <literal>IO</literal> monad, and bind the result to
      <literal>x</literal>&rdquo;.  We can then use
      <literal>x</literal> in future statements, for example to print
      it as we did above.</para>
381

382
383
      <para>If <option>-fprint-bind-result</option> is set then
      GHCi will print the result of a statement if and only if: 
384
385
386
387
388
389
390
391
392
393
394
395
	<itemizedlist>
	  <listitem>
	    <para>The statement is not a binding, or it is a monadic binding 
	      (<literal>p &lt;- e</literal>) that binds exactly one
	      variable.</para>
	  </listitem>
	  <listitem>
	    <para>The variable's type is not polymorphic, is not
	      <literal>()</literal>, and is an instance of
	      <literal>Show</literal></para>
	  </listitem>
	</itemizedlist>
396
397
      <indexterm><primary><option>-fprint-bind-result</option></primary></indexterm><indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm>.
      </para>
398

399
400
401
402
      <para>Of course, you can also bind normal non-IO expressions
      using the <literal>let</literal>-statement:</para>
<screen>
Prelude> let x = 42
403
Prelude> x
404
405
406
42
Prelude>
</screen>
407
      <para>Another important difference between the two types of binding
408
409
410
411
412
413
414
415
416
417
      is that the monadic bind (<literal>p &lt;- e</literal>) is
      <emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
      whereas with the <literal>let</literal> form, the expression
      isn't evaluated immediately:</para>
<screen>
Prelude> let x = error "help!"
Prelude> print x
*** Exception: help!
Prelude>
</screen>
418
419
420
421

      <para>Note that <literal>let</literal> bindings do not automatically
	print the value bound, unlike monadic bindings.</para>

422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
      <para>Hint: you can also use <literal>let</literal>-statements
      to define functions at the prompt:</para>
<screen>
Prelude> let add a b = a + b
Prelude> add 1 2
3
Prelude>
</screen>
        <para>However, this quickly gets tedious when defining functions 
        with multiple clauses, or groups of mutually recursive functions,
        because the complete definition has to be given on a single line, 
        using explicit braces and semicolons instead of layout:</para>
<screen>
Prelude> let { f op n [] = n ; f op n (h:t) = h `op` f op n t }
Prelude> f (+) 0 [1..3]
6
Prelude>
</screen>
      <para>To alleviate this issue, GHCi commands can be split over
      multiple lines, by wrapping them in <literal>:{</literal> and
      <literal>:}</literal> (each on a single line of its own):</para>
<screen>
Prelude> :{
Prelude| let { g op n [] = n
Prelude|     ; g op n (h:t) = h `op` g op n t
Prelude|     }
Prelude| :}
Prelude> g (*) 1 [1..3]
6
</screen>
      <para>Such multiline commands can be used with any GHCi command,
      and the lines between <literal>:{</literal> and
      <literal>:}</literal> are simply merged into a single line for 
      interpretation. That implies that each such group must form a single
      valid command when merged, and that no layout rule is used. 
      The main purpose of multiline commands is not to replace module
      loading but to make definitions in .ghci-files (see <xref
      linkend="ghci-dot-files"/>) more readable and maintainable.</para>

461
462
463
464
465
466
      <para>Any exceptions raised during the evaluation or execution
      of the statement are caught and printed by the GHCi command line
      interface (for more information on exceptions, see the module
      <literal>Control.Exception</literal> in the libraries
      documentation).</para>

467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
      <para>Every new binding shadows any existing bindings of the
      same name, including entities that are in scope in the current
      module context.</para>

      <para>WARNING: temporary bindings introduced at the prompt only
      last until the next <literal>:load</literal> or
      <literal>:reload</literal> command, at which time they will be
      simply lost.  However, they do survive a change of context with
      <literal>:module</literal>: the temporary bindings just move to
      the new location.</para>

      <para>HINT: To get a list of the bindings currently in scope, use the
      <literal>:show bindings</literal> command:</para>

<screen>
Prelude> :show bindings
x :: Int
Prelude></screen>

      <para>HINT: if you turn on the <literal>+t</literal> option,
      GHCi will show the type of each variable bound by a statement.
      For example:</para>
      <indexterm><primary><literal>+t</literal></primary></indexterm>
<screen>
Prelude> :set +t
Prelude> let (x:xs) = [1..]
x :: Integer
xs :: [Integer]
</screen>
496

497
    </sect2>
498
499
500
501

    <sect2 id="ghci-scope">
      <title>What's really in scope at the prompt?</title> 

502
503
504
505
506
      <para>When you type an expression at the prompt, what
      identifiers and types are in scope?  GHCi provides a flexible
      way to control exactly how the context for an expression is
      constructed.  Let's start with the simple cases; when you start
      GHCi the prompt looks like this:</para>
507

508
<screen>Prelude></screen>
509

510
511
512
      <para>Which indicates that everything from the module
      <literal>Prelude</literal> is currently in scope.  If we now
      load a file into GHCi, the prompt will change:</para>
513

514
515
516
517
518
<screen>
Prelude> :load Main.hs
Compiling Main             ( Main.hs, interpreted )
*Main>
</screen>
519

520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
      <para>The new prompt is <literal>*Main</literal>, which
      indicates that we are typing expressions in the context of the
      top-level of the <literal>Main</literal> module.  Everything
      that is in scope at the top-level in the module
      <literal>Main</literal> we just loaded is also in scope at the
      prompt (probably including <literal>Prelude</literal>, as long
      as <literal>Main</literal> doesn't explicitly hide it).</para>

      <para>The syntax
      <literal>*<replaceable>module</replaceable></literal> indicates
      that it is the full top-level scope of
      <replaceable>module</replaceable> that is contributing to the
      scope for expressions typed at the prompt.  Without the
      <literal>*</literal>, just the exports of the module are
      visible.</para>

      <para>We're not limited to a single module: GHCi can combine
      scopes from multiple modules, in any mixture of
      <literal>*</literal> and non-<literal>*</literal> forms.  GHCi
      combines the scopes from all of these modules to form the scope
      that is in effect at the prompt.  For technical reasons, GHCi
      can only support the <literal>*</literal>-form for modules which
      are interpreted, so compiled modules and package modules can
      only contribute their exports to the current scope.</para>

      <para>The scope is manipulated using the
      <literal>:module</literal> command.  For example, if the current
      scope is <literal>Prelude</literal>, then we can bring into
      scope the exports from the module <literal>IO</literal> like
      so:</para>
550

551
552
<screen>
Prelude> :module +IO
Ian Lynagh's avatar
Ian Lynagh committed
553
Prelude IO> hPutStrLn stdout "hello\n"
554
hello
Ian Lynagh's avatar
Ian Lynagh committed
555
Prelude IO>
556
557
</screen>

558
559
560
      <para>(Note: you can use <literal>import M</literal> as an
      alternative to <literal>:module +M</literal>, and
      <literal>:module</literal> can also be shortened to 
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
      <literal>:m</literal>). The full syntax of the
      <literal>:module</literal> command is:</para>

<screen>
:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
</screen>

      <para>Using the <literal>+</literal> form of the
      <literal>module</literal> commands adds modules to the current
      scope, and <literal>-</literal> removes them.  Without either
      <literal>+</literal> or <literal>-</literal>, the current scope
      is replaced by the set of modules specified.  Note that if you
      use this form and leave out <literal>Prelude</literal>, GHCi
      will assume that you really wanted the
      <literal>Prelude</literal> and add it in for you (if you don't
      want the <literal>Prelude</literal>, then ask to remove it with
      <literal>:m -Prelude</literal>).</para>

      <para>The scope is automatically set after a
      <literal>:load</literal> command, to the most recently loaded
      "target" module, in a <literal>*</literal>-form if possible.
      For example, if you say <literal>:load foo.hs bar.hs</literal>
      and <filename>bar.hs</filename> contains module
      <literal>Bar</literal>, then the scope will be set to
      <literal>*Bar</literal> if <literal>Bar</literal> is
      interpreted, or if <literal>Bar</literal> is compiled it will be
Ian Lynagh's avatar
Ian Lynagh committed
587
      set to <literal>Prelude Bar</literal> (GHCi automatically adds
588
589
590
591
592
593
594
595
596
597
      <literal>Prelude</literal> if it isn't present and there aren't
      any <literal>*</literal>-form modules).</para>

      <para>With multiple modules in scope, especially multiple
      <literal>*</literal>-form modules, it is likely that name
      clashes will occur.  Haskell specifies that name clashes are
      only reported when an ambiguous identifier is used, and GHCi
      behaves in the same way for expressions typed at the
      prompt.</para>

Ian Lynagh's avatar
Ian Lynagh committed
598
599
600
      <para>
        Hint: GHCi will tab-complete names that are in scope; for
        example, if you run GHCi and type <literal>J&lt;tab&gt;</literal>
Ian Lynagh's avatar
Ian Lynagh committed
601
        then GHCi will expand it to &ldquo;<literal>Just </literal>&rdquo;.
Ian Lynagh's avatar
Ian Lynagh committed
602
603
      </para>

604
605
606
607
608
609
610
611
      <sect3>
	<title>Qualified names</title>

	<para>To make life slightly easier, the GHCi prompt also
        behaves as if there is an implicit <literal>import
        qualified</literal> declaration for every module in every
        package, and every module currently loaded into GHCi.</para>
      </sect3>
Ian Lynagh's avatar
Ian Lynagh committed
612
613

      <sect3>
Ian Lynagh's avatar
Ian Lynagh committed
614
        <title>The <literal>:main</literal> and <literal>:run</literal> commands</title>
Ian Lynagh's avatar
Ian Lynagh committed
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636

        <para>
          When a program is compiled and executed, it can use the
          <literal>getArgs</literal> function to access the
          command-line arguments.
          However, we cannot simply pass the arguments to the
          <literal>main</literal> function while we are testing in ghci,
          as the <literal>main</literal> function doesn't take its
          directly.
        </para>

        <para>
          Instead, we can use the <literal>:main</literal> command.
          This runs whatever <literal>main</literal> is in scope, with
          any arguments being treated the same as command-line arguments,
          e.g.:
        </para>

<screen>
Prelude> let main = System.Environment.getArgs >>= print
Prelude> :main foo bar
["foo","bar"]
Ian Lynagh's avatar
Ian Lynagh committed
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
</screen>

        <para>
            We can also quote arguments which contains characters like
            spaces, and they are treated like Haskell strings, or we can
            just use Haskell list syntax:
        </para>

<screen>
Prelude> :main foo "bar baz"
["foo","bar baz"]
Prelude> :main ["foo", "bar baz"]
["foo","bar baz"]
</screen>

        <para>
            Finally, other functions can be called, either with the
            <literal>-main-is</literal> flag or the <literal>:run</literal>
            command:
        </para>

<screen>
Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
Prelude> :set -main-is foo
Prelude> :main foo "bar baz"
foo
["foo","bar baz"]
Prelude> :run bar ["foo", "bar baz"]
bar
["foo","bar baz"]
Ian Lynagh's avatar
Ian Lynagh committed
668
669
670
</screen>

      </sect3>
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
    </sect2>
  

    <sect2>
      <title>The <literal>it</literal> variable</title>
      <indexterm><primary><literal>it</literal></primary>
      </indexterm>
      
      <para>Whenever an expression (or a non-binding statement, to be
      precise) is typed at the prompt, GHCi implicitly binds its value
      to the variable <literal>it</literal>.  For example:</para>
<screen>
Prelude> 1+2
3
Prelude> it * 2
6
</screen>
688
689
690
691
    <para>What actually happens is that GHCi typechecks the
    expression, and if it doesn't have an <literal>IO</literal> type,
    then it transforms it as follows: an expression
    <replaceable>e</replaceable> turns into 
Ian Lynagh's avatar
Ian Lynagh committed
692
693
694
<screen>
let it = <replaceable>e</replaceable>;
print it
695
</screen>
696
697
698
699
700
701
702
    which is then run as an IO-action.</para>

    <para>Hence, the original expression must have a type which is an
    instance of the <literal>Show</literal> class, or GHCi will
    complain:</para>

<screen>
Ian Lynagh's avatar
Ian Lynagh committed
703
704
705
706
707
708
709
710
Prelude&gt; id

&lt;interactive&gt;:1:0:
    No instance for (Show (a -&gt; a))
      arising from use of `print' at &lt;interactive&gt;:1:0-1
    Possible fix: add an instance declaration for (Show (a -> a))
    In the expression: print it
    In a 'do' expression: print it
711
712
713
714
</screen>

    <para>The error message contains some clues as to the
    transformation happening internally.</para>
715

716
      <para>If the expression was instead of type <literal>IO a</literal> for
717
718
719
720
721
      some <literal>a</literal>, then <literal>it</literal> will be
      bound to the result of the <literal>IO</literal> computation,
      which is of type <literal>a</literal>.  eg.:</para>
<screen>
Prelude> Time.getClockTime
Ian Lynagh's avatar
Ian Lynagh committed
722
Wed Mar 14 12:23:13 GMT 2001
723
724
725
726
Prelude> print it
Wed Mar 14 12:23:13 GMT 2001
</screen>

727
728
      <para>The corresponding translation for an IO-typed
      <replaceable>e</replaceable> is
Ian Lynagh's avatar
Ian Lynagh committed
729
730
<screen>
it &lt;- <replaceable>e</replaceable>
731
732
733
</screen>
      </para>

734
735
736
737
738
      <para>Note that <literal>it</literal> is shadowed by the new
      value each time you evaluate a new expression, and the old value
      of <literal>it</literal> is lost.</para>

    </sect2>
739

740
    <sect2 id="extended-default-rules">
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
      <title>Type defaulting in GHCi</title>
    <indexterm><primary>Type default</primary></indexterm>
    <indexterm><primary><literal>Show</literal> class</primary></indexterm>
      <para>
      Consider this GHCi session:
<programlisting>
  ghci> reverse []
</programlisting>
      What should GHCi do?  Strictly speaking, the program is ambiguous.  <literal>show (reverse [])</literal>
      (which is what GHCi computes here) has type <literal>Show a => a</literal> and how that displays depends 
      on the type <literal>a</literal>.  For example:
<programlisting>
  ghci> (reverse []) :: String
  ""
  ghci> (reverse []) :: [Int]
  []
</programlisting>
    However, it is tiresome for the user to have to specify the type, so GHCi extends Haskell's type-defaulting
759
760
761
762
    rules (Section 4.3.4 of the Haskell 98 Report (Revised)) as follows.  The
    standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
    a)</literal> for each type variable <literal>a</literal>, and defaults the
    type variable if 
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
    <orderedlist>
        <listitem>
            <para>
                The type variable <literal>a</literal> appears in no
                other constraints
            </para>
        </listitem>
        <listitem>
            <para>
                All the classes <literal>Ci</literal> are standard.
            </para>
        </listitem>
        <listitem>
            <para>
                At least one of the classes <literal>Ci</literal> is
                numeric.
            </para>
        </listitem>
    </orderedlist>
    At the GHCi prompt, or with GHC if the
Ian Lynagh's avatar
Ian Lynagh committed
783
    <literal>-XExtendedDefaultRules</literal> flag is given,
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
    the following additional differences apply:
    <itemizedlist>
        <listitem>
            <para>
                Rule 2 above is relaxed thus:
                <emphasis>All</emphasis> of the classes
                <literal>Ci</literal> are single-parameter type classes.
            </para>
        </listitem>
        <listitem>
            <para>
                Rule 3 above is relaxed this:
                At least one of the classes <literal>Ci</literal> is
                numeric, <emphasis>or is <literal>Show</literal>,
                <literal>Eq</literal>, or
                <literal>Ord</literal></emphasis>.
            </para>
        </listitem>
        <listitem>
            <para>
                The unit type <literal>()</literal> is added to the
                start of the standard list of types which are tried when
                doing type defaulting.
            </para>
        </listitem>
    </itemizedlist>
    The last point means that, for example, this program:
<programlisting>
main :: IO ()
main = print def

instance Num ()

def :: (Num a, Enum a) => a
def = toEnum 0
</programlisting>
    prints <literal>()</literal> rather than <literal>0</literal> as the
    type is defaulted to <literal>()</literal> rather than
    <literal>Integer</literal>.
   </para>
   <para>
    The motivation for the change is that it means <literal>IO a</literal>
    actions default to <literal>IO ()</literal>, which in turn means that
    ghci won't try to print a result when running them. This is
    particularly important for <literal>printf</literal>, which has an
    instance that returns <literal>IO a</literal>.
    However, it is only able to return
    <literal>undefined</literal>
Ian Lynagh's avatar
Ian Lynagh committed
832
833
    (the reason for the instance having this type is so that printf
    doesn't require extensions to the class system), so if the type defaults to
834
835
    <literal>Integer</literal> then ghci gives an error when running a
    printf.
836
837
   </para>
    </sect2>
838
839
  </sect1>

Simon Marlow's avatar
Simon Marlow committed
840
841
842
843
844
845
846
847
  <sect1 id="ghci-debugger">
    <title>The GHCi Debugger</title>
    <indexterm><primary>debugger</primary><secondary>in GHCi</secondary>
    </indexterm>

    <para>GHCi contains a simple imperative-style debugger in which you can
      stop a running computation in order to examine the values of
      variables.  The debugger is integrated into GHCi, and is turned on by
848
849
850
851
852
853
      default: no flags are required to enable the debugging
      facilities.  There is one major restriction: breakpoints and
      single-stepping are only available in interpreted modules;
      compiled code is invisible to the debugger<footnote><para>Note that packages
      only contain compiled code, so debugging a package requires
      finding its source and loading that directly.</para></footnote>.</para>
Simon Marlow's avatar
Simon Marlow committed
854
855
856
857

    <para>The debugger provides the following:
    <itemizedlist>
        <listitem>
Ian Lynagh's avatar
Ian Lynagh committed
858
          <para>The ability to set a <firstterm>breakpoint</firstterm> on a
Simon Marlow's avatar
Simon Marlow committed
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
            function definition or expression in the program.  When the function
            is called, or the expression evaluated, GHCi suspends 
            execution and returns to the prompt, where you can inspect the
            values of local variables before continuing with the
            execution.</para>
        </listitem>
        <listitem>
          <para>Execution can be <firstterm>single-stepped</firstterm>: the
            evaluator will suspend execution approximately after every
            reduction, allowing local variables to be inspected.  This is
            equivalent to setting a breakpoint at every point in the
            program.</para>
        </listitem>
        <listitem>
          <para>Execution can take place in <firstterm>tracing
              mode</firstterm>, in which the evaluator remembers each
            evaluation step as it happens, but doesn't suspend execution until
            an actual breakpoint is reached.  When this happens, the history of
            evaluation steps can be inspected.</para>
        </listitem>
        <listitem>
          <para>Exceptions (e.g. pattern matching failure and
            <literal>error</literal>) can be treated as breakpoints, to help
            locate the source of an exception in the program.</para>
        </listitem>
      </itemizedlist>
    </para>
      
    <para>There is currently no support for obtaining a &ldquo;stack
888
889
890
891
892
893
    trace&rdquo;, but the tracing and history features provide a
    useful second-best, which will often be enough to establish the
    context of an error.  For instance, it is possible to break
    automatically when an exception is thrown, even if it is thrown
    from within compiled code (see <xref
    linkend="ghci-debugger-exceptions" />).</para>
Simon Marlow's avatar
Simon Marlow committed
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
      
    <sect2 id="breakpoints">
      <title>Breakpoints and inspecting variables</title>
      
      <para>Let's use quicksort as a running example.  Here's the code:</para>

<programlisting>
qsort [] = [] 
qsort (a:as) = qsort left ++ [a] ++ qsort right
  where (left,right) = (filter (&lt;=a) as, filter (&gt;a) as)

main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
</programlisting>

      <para>First, load the module into GHCi:</para>

<screen>
Prelude> :l qsort.hs
[1 of 1] Compiling Main             ( qsort.hs, interpreted )
Ok, modules loaded: Main.
*Main>
      </screen>       

      <para>Now, let's set a breakpoint on the right-hand-side of the second
        equation of qsort:</para>

<programlisting>
*Main> :break 2
Breakpoint 0 activated at qsort.hs:2:15-46
*Main>
</programlisting>
      
      <para>The command <literal>:break 2</literal> sets a breakpoint on line
        2 of the most recently-loaded module, in this case
        <literal>qsort.hs</literal>.   Specifically, it picks the
        leftmost complete subexpression on that line on which to set the
        breakpoint, which in this case is the expression 
        <literal>(qsort left ++ [a] ++ qsort right)</literal>.</para>

      <para>Now, we run the program:</para>

<programlisting>
*Main> main
Stopped at qsort.hs:2:15-46
_result :: [a]
a :: a
left :: [a]
right :: [a]
[qsort.hs:2:15-46] *Main>
</programlisting>

      <para>Execution has stopped at the breakpoint.  The prompt has changed to
        indicate that we are currently stopped at a breakpoint, and the location:
        <literal>[qsort.hs:2:15-46]</literal>.  To further clarify the
        location, we can use the <literal>:list</literal> command:</para>

<programlisting>
[qsort.hs:2:15-46] *Main> :list 
1  qsort [] = [] 
2  qsort (a:as) = qsort left ++ [a] ++ qsort right
3    where (left,right) = (filter (&lt;=a) as, filter (&gt;a) as)
</programlisting>

      <para>The <literal>:list</literal> command lists the source code around
        the current breakpoint.  If your output device supports it, then GHCi
        will highlight the active subexpression in bold.</para>

      <para>GHCi has provided bindings for the free variables<footnote><para>We
            originally provided bindings for all variables in scope, rather
            than just
            the free variables of the expression, but found that this affected
            performance considerably, hence the current restriction to just the
            free variables.</para>
        </footnote> of the expression
        on which the
        breakpoint was placed (<literal>a</literal>, <literal>left</literal>,
        <literal>right</literal>), and additionally a binding for the result of
        the expression (<literal>_result</literal>).  These variables are just
        like other variables that you might define in GHCi; you
        can use them in expressions that you type at the prompt, you can ask
        for their types with <literal>:type</literal>, and so on.  There is one
        important difference though: these variables may only have partial
        types.  For example, if we try to display the value of
        <literal>left</literal>:</para>

<screen>
[qsort.hs:2:15-46] *Main> left

&lt;interactive&gt;:1:0:
    Ambiguous type variable `a' in the constraint:
      `Show a' arising from a use of `print' at &lt;interactive&gt;:1:0-3
    Cannot resolve unknown runtime types: a
    Use :print or :force to determine these types
</screen>

      <para>This is because <literal>qsort</literal> is a polymorphic function,
        and because GHCi does not carry type information at runtime, it cannot
        determine the runtime types of free variables that involve type
        variables.  Hence, when you ask to display <literal>left</literal> at
        the prompt, GHCi can't figure out which instance of
        <literal>Show</literal> to use, so it emits the type error above.</para>

      <para>Fortunately, the debugger includes a generic printing command,
        <literal>:print</literal>, which can inspect the actual runtime value of a
        variable and attempt to reconstruct its type.  If we try it on
        <literal>left</literal>:</para>