ghci.xml 97.4 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
223
224
225
226
<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
Skipping  D                ( D.hs, D.o )
Compiling C                ( C.hs, interpreted )
Compiling B                ( B.hs, interpreted )
Compiling A                ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
227
*Main>
228
229
230
231
232
233
234
235
236
</screen>

    <para>In the messages from the compiler, we see that it skipped D,
    and used the object file <filename>D.o</filename>.  The message
    <literal>Skipping</literal> <replaceable>module</replaceable>
    indicates that compilation for <replaceable>module</replaceable>
    isn't necessary, because the source and everything it depends on
    is unchanged since the last compilation.</para>

237
238
239
240
241
242
243
244
245
246
247
248
249
    <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>

250
251
252
253
254
255
    <para>If we now modify the source of D (or pretend to: using Unix
    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>
256
257
*Main> :! touch D.hs
*Main> :reload
258
259
260
261
262
Compiling D                ( D.hs, interpreted )
Skipping  C                ( C.hs, interpreted )
Skipping  B                ( B.hs, interpreted )
Skipping  A                ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
263
*Main> 
264
265
266
267
268
269
270
271
272
273
</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>
274
275
*Main> :! ghc -c C.hs
*Main> :load A
276
277
278
279
280
281
282
283
284
285
286
287
288
289
Compiling D                ( D.hs, interpreted )
Compiling C                ( C.hs, interpreted )
Compiling B                ( B.hs, interpreted )
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>
290
291
*Main> :! ghc -c D.hs
*Main> :reload
292
293
294
295
296
297
298
299
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>
300
*Main> :load A
301
302
303
304
305
306
307
308
Skipping  D                ( D.hs, D.o )
Skipping  C                ( C.hs, C.o )
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
309
    can be sure that the compiled version is up-to-date, a good technique
310
    when working on a large program is to occasionally run
311
    <literal>ghc &ndash;&ndash;make</literal> to compile the whole project (say
312
313
314
315
316
317
318
    before you go for lunch :-), then continue working in the
    interpreter.  As you modify code, the new modules will be
    interpreted, but the rest of the project will remain
    compiled.</para>

  </sect1>

319
  <sect1 id="interactive-evaluation">
320
321
322
    <title>Interactive evaluation at the prompt</title>

    <para>When you type an expression at the prompt, GHCi immediately
323
324
325
326
327
328
329
330
331
332
    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>
333

334
335
336
337
<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.
338
339
340
341
342
343
<screen>
Prelude> "hello"
"hello"
Prelude> putStrLn "hello"
hello
</screen>
344
345
346
347
348
349
350
351
352
353
354
355
356
357
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"
358
</screen>
359
</para></sect2>
360

361
    <sect2 id="ghci-stmts">
362
363
364
365
366
367
368
369
      <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>
370

371
372
373
374
375
      <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.
376
<screen>
377
378
379
380
381
Prelude> x &lt;- return 42
42
Prelude> print x
42
Prelude>
382
</screen>
383
384
385
386
387
388
      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>
389

390
391
392
393
394
395
396
397
398
399
400
401
402
      <para>GHCi will print the result of a statement if and only if: 
	<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>
403
404
405
406
407
408
409
      The automatic printing of binding results can be supressed with
      <option>:set -fno-print-bind-result</option> (this does not
      supress printing the result of non-binding statements).
      <indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm><indexterm><primary><option>-fprint-bind-result</option></primary></indexterm>.
      You might want to do this to prevent the result of binding
      statements from being fully evaluated by the act of printing
      them, for example.</para>
410

411
412
413
414
      <para>Of course, you can also bind normal non-IO expressions
      using the <literal>let</literal>-statement:</para>
<screen>
Prelude> let x = 42
415
Prelude> x
416
417
418
42
Prelude>
</screen>
419
      <para>Another important difference between the two types of binding
420
421
422
423
424
425
426
427
428
429
      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>
430
431
432
433

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

434
435
436
437
438
439
      <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>

440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
      <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>
469

470
    </sect2>
471
472
473
474

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

475
476
477
478
479
      <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>
480

481
<screen>Prelude></screen>
482

483
484
485
      <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>
486

487
488
489
490
491
<screen>
Prelude> :load Main.hs
Compiling Main             ( Main.hs, interpreted )
*Main>
</screen>
492

493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
      <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>
523

524
525
<screen>
Prelude> :module +IO
Ian Lynagh's avatar
Ian Lynagh committed
526
Prelude IO> hPutStrLn stdout "hello\n"
527
hello
Ian Lynagh's avatar
Ian Lynagh committed
528
Prelude IO>
529
530
</screen>

531
532
533
      <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 
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
      <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
560
      set to <literal>Prelude Bar</literal> (GHCi automatically adds
561
562
563
564
565
566
567
568
569
570
      <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
571
572
573
574
575
576
      <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>
        then GHCi will expand it to <literal>Just </literal>.
      </para>

577
578
579
580
581
582
583
584
      <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
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612

      <sect3>
        <title>The <literal>:main</literal> command</title>

        <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"]
</screen>

      </sect3>
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
    </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>
630
631
632
633
    <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
634
635
636
<screen>
let it = <replaceable>e</replaceable>;
print it
637
</screen>
638
639
640
641
642
643
644
    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
645
646
647
648
649
650
651
652
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
653
654
655
656
</screen>

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

658
      <para>If the expression was instead of type <literal>IO a</literal> for
659
660
661
662
663
      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
664
Wed Mar 14 12:23:13 GMT 2001
665
666
667
668
Prelude> print it
Wed Mar 14 12:23:13 GMT 2001
</screen>

669
670
      <para>The corresponding translation for an IO-typed
      <replaceable>e</replaceable> is
Ian Lynagh's avatar
Ian Lynagh committed
671
672
<screen>
it &lt;- <replaceable>e</replaceable>
673
674
675
</screen>
      </para>

676
677
678
679
680
      <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>
681

682
    <sect2 id="extended-default-rules">
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
      <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
701
702
703
704
    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 
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
    <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
    <literal>-fextended-default-rules</literal> flag is given,
    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>
    (the reason for the instance having this type is to not require
    extensions to the class system), so if the type defaults to
    <literal>Integer</literal> then ghci gives an error when running a
    printf.
778
779
   </para>
    </sect2>
780
781
  </sect1>

Simon Marlow's avatar
Simon Marlow committed
782
783
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
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
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
888
889
890
891
892
893
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
  <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
      default: no flags are required to enable the debugging facilities.  There
      is one major restriction: breakpoints and single-stepping are only
      available in <emphasis>interpreted</emphasis> modules; compiled code is
      invisible to the debugger.</para>

    <para>The debugger provides the following:
    <itemizedlist>
        <listitem>
          <para>The abilty to set a <firstterm>breakpoint</firstterm> on a
            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
      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.</para>
      
    <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>

<screen>
[qsort.hs:2:15-46] *Main> :print left
left = (_t1::[a])
</screen>

      <para>This isn't particularly enlightening.  What happened is that
        <literal>left</literal> is bound to an unevaluated computation (a
        suspension, or <firstterm>thunk</firstterm>), and
        <literal>:print</literal> does not force any evaluation.  The idea is
        that <literal>:print</literal> can be used to inspect values at a
        breakpoint without any unfortunate side effects.  It won't force any
        evaluation, which could cause the program to give a different answer
        than it would normally, and hence it won't cause any exceptions to be
        raised, infinite loops, or further breakpoints to be triggered (see
        <xref linkend="nested-breakpoints" />).
        Rather than forcing thunks, <literal>:print</literal>
        binds each thunk to a fresh variable beginning with an
        underscore, in this case
        <literal>_t1</literal>.</para>

      <para>If we aren't concerned about preserving the evaluatedness of a
        variable, we can use <literal>:force</literal> instead of
        <literal>:print</literal>.  The <literal>:force</literal> command
        behaves exactly like <literal>:print</literal>, except that it forces
        the evaluation of any thunks it encounters:</para>

<screen>
[qsort.hs:2:15-46] *Main> :force left
left = [4,0,3,1]
</screen>

      <para>Now, since <literal>:force</literal> has inspected the runtime
        value of <literal>left</literal>, it has reconstructed its type.  We
        can see the results of this type reconstruction:</para>

<screen>
[qsort.hs:2:15-46] *Main> :show bindings
_result :: [Integer]
a :: Integer
left :: [Integer]
right :: [Integer]
_t1 :: [Integer]
</screen>

      <para>Not only do we now know the type of <literal>left</literal>, but
        all the other partial types have also been resolved.  So we can ask
        for the value of <literal>a</literal>, for example:</para>

<screen>
[qsort.hs:2:15-46] *Main> a
8
</screen>
      
      <para>You might find it useful to use Haskell's
        <literal>seq</literal> function to evaluate individual thunks rather
        than evaluating the whole expression with <literal>:force</literal>.
        For example:</para>

<screen>
[qsort.hs:2:15-46] *Main> :print right
right = (_t1::[Integer])
[qsort.hs:2:15-46] *Main> seq _t1 ()
()