Move user's guide to ReStructuredText
[ghc.git] / docs / users_guide / ghci.rst
1 .. _ghci:
2
3 Using GHCi
4 ==========
5
6 .. index::
7    single: GHCi
8    single: interpreter
9    single: interactive
10    single: Hugs
11    single: Foreign Function Interface; GHCi support
12    single: FFI; GHCi support
13
14 GHCi [1]_ is GHC's interactive environment, in which Haskell expressions
15 can be interactively evaluated and programs can be interpreted. If
16 you're familiar with `Hugs <http://www.haskell.org/hugs/>`__, then
17 you'll be right at home with GHCi. However, GHCi also has support for
18 interactively loading compiled code, as well as supporting all [2]_ the
19 language extensions that GHC provides. GHCi also includes an interactive
20 debugger (see :ref:`ghci-debugger`).
21
22 .. [1]
23    The ‘i’ stands for “Interactive”
24
25 .. [2]
26    except ``foreign export``, at the moment
27
28
29 .. _ghci-introduction:
30
31 Introduction to GHCi
32 --------------------
33
34 Let's start with an example GHCi session. You can fire up GHCi with the
35 command ``ghci``:
36
37 ::
38
39     $ ghci
40     GHCi, version 6.12.1: http://www.haskell.org/ghc/  :? for help
41     Loading package ghc-prim ... linking ... done.
42     Loading package integer-gmp ... linking ... done.
43     Loading package base ... linking ... done.
44     Loading package ffi-1.0 ... linking ... done.
45     Prelude>
46
47 There may be a short pause while GHCi loads the prelude and standard
48 libraries, after which the prompt is shown. As the banner says, you can
49 type ``:?`` to see the list of commands available, and a half line
50 description of each of them. We'll explain most of these commands as we
51 go along, and there is complete documentation for all the commands in
52 :ref:`ghci-commands`.
53
54 Haskell expressions can be typed at the prompt:
55
56 .. index::
57    single: prompt; GHCi
58
59 ::
60
61     Prelude> 1+2
62     3
63     Prelude> let x = 42 in x / 9
64     4.666666666666667
65     Prelude>
66
67 GHCi interprets the whole line as an expression to evaluate. The
68 expression may not span several lines - as soon as you press enter, GHCi
69 will attempt to evaluate it.
70
71 In Haskell, a ``let`` expression is followed by ``in``. However, in
72 GHCi, since the expression can also be interpreted in the ``IO`` monad,
73 a ``let`` binding with no accompanying ``in`` statement can be signalled
74 by an empty line, as in the above example.
75
76 .. _loading-source-files:
77
78 Loading source files
79 --------------------
80
81 Suppose we have the following Haskell source code, which we place in a
82 file ``Main.hs``:
83
84 ::
85
86     main = print (fac 20)
87
88     fac 0 = 1
89     fac n = n * fac (n-1)
90
91 You can save ``Main.hs`` anywhere you like, but if you save it somewhere
92 other than the current directory [3]_ then we will need to change to the
93 right directory in GHCi:
94
95 ::
96
97     Prelude> :cd dir
98
99 where ⟨dir⟩ is the directory (or folder) in which you saved ``Main.hs``.
100
101 To load a Haskell source file into GHCi, use the ``:load`` command:
102
103 .. index::
104    single: :load
105
106 ::
107
108     Prelude> :load Main
109     Compiling Main             ( Main.hs, interpreted )
110     Ok, modules loaded: Main.
111     *Main>
112
113 GHCi has loaded the ``Main`` module, and the prompt has changed to
114 “\ ``*Main>``\ ” to indicate that the current context for expressions
115 typed at the prompt is the ``Main`` module we just loaded (we'll explain
116 what the ``*`` means later in :ref:`ghci-scope`). So we can now type
117 expressions involving the functions from ``Main.hs``:
118
119 ::
120
121     *Main> fac 17
122     355687428096000
123
124 Loading a multi-module program is just as straightforward; just give the
125 name of the “topmost” module to the ``:load`` command (hint: ``:load``
126 can be abbreviated to ``:l``). The topmost module will normally be
127 ``Main``, but it doesn't have to be. GHCi will discover which modules
128 are required, directly or indirectly, by the topmost module, and load
129 them all in dependency order.
130
131 .. [3]
132    If you started up GHCi from the command line then GHCi's current
133    directory is the same as the current directory of the shell from
134    which it was started. If you started GHCi from the “Start” menu in
135    Windows, then the current directory is probably something like
136    ``C:\Documents and Settings\user name``.
137
138
139 .. _ghci-modules-filenames:
140
141 Modules vs. filenames
142 ~~~~~~~~~~~~~~~~~~~~~
143
144 .. index::
145    single: modules; and filenames
146    single: filenames; of modules
147
148 Question: How does GHC find the filename which contains module ⟨M⟩?
149 Answer: it looks for the file ``M.hs``, or ``M.lhs``. This means that
150 for most modules, the module name must match the filename. If it
151 doesn't, GHCi won't be able to find it.
152
153 There is one exception to this general rule: when you load a program
154 with ``:load``, or specify it when you invoke ``ghci``, you can give a
155 filename rather than a module name. This filename is loaded if it
156 exists, and it may contain any module you like. This is particularly
157 convenient if you have several ``Main`` modules in the same directory
158 and you can't call them all ``Main.hs``.
159
160 The search path for finding source files is specified with the ``-i``
161 option on the GHCi command line, like so:
162
163 ::
164
165     ghci -idir1:...:dirn
166
167 or it can be set using the ``:set`` command from within GHCi (see
168 :ref:`ghci-cmd-line-options`) [4]_
169
170 One consequence of the way that GHCi follows dependencies to find
171 modules to load is that every module must have a source file. The only
172 exception to the rule is modules that come from a package, including the
173 ``Prelude`` and standard libraries such as ``IO`` and ``Complex``. If
174 you attempt to load a module for which GHCi can't find a source file,
175 even if there are object and interface files for the module, you'll get
176 an error message.
177
178 .. [4]
179    Note that in GHCi, and ``--make`` mode, the ``-i`` option is used to
180    specify the search path for *source* files, whereas in standard
181    batch-compilation mode the ``-i`` option is used to specify the
182    search path for interface files, see :ref:`search-path`.
183
184
185 Making changes and recompilation
186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187
188 .. index::
189    single: :reload
190
191 If you make some changes to the source code and want GHCi to recompile
192 the program, give the ``:reload`` command. The program will be
193 recompiled as necessary, with GHCi doing its best to avoid actually
194 recompiling modules if their external dependencies haven't changed. This
195 is the same mechanism we use to avoid re-compiling modules in the batch
196 compilation setting (see :ref:`recomp`).
197
198 .. _ghci-compiled:
199
200 Loading compiled code
201 ---------------------
202
203 .. index::
204    single: compiled code; in GHCi
205
206 When you load a Haskell source module into GHCi, it is normally
207 converted to byte-code and run using the interpreter. However,
208 interpreted code can also run alongside compiled code in GHCi; indeed,
209 normally when GHCi starts, it loads up a compiled copy of the ``base``
210 package, which contains the ``Prelude``.
211
212 Why should we want to run compiled code? Well, compiled code is roughly
213 10x faster than interpreted code, but takes about 2x longer to produce
214 (perhaps longer if optimisation is on). So it pays to compile the parts
215 of a program that aren't changing very often, and use the interpreter
216 for the code being actively developed.
217
218 When loading up source modules with ``:load``, GHCi normally looks for
219 any corresponding compiled object files, and will use one in preference
220 to interpreting the source if possible. For example, suppose we have a 4-module
221 program consisting of modules ``A``, ``B``, ``C``, and ``D``. Modules ``B`` and
222 ``C`` both import ``D`` only, and ``A`` imports both ``B`` and ``C``:
223
224 ::
225
226           A
227          / \
228         B   C
229          \ /
230           D
231
232 We can compile ``D``, then load the whole program, like this:
233
234 ::
235
236     Prelude> :! ghc -c -dynamic D.hs
237     Prelude> :load A
238     Compiling B                ( B.hs, interpreted )
239     Compiling C                ( C.hs, interpreted )
240     Compiling A                ( A.hs, interpreted )
241     Ok, modules loaded: A, B, C, D.
242     *Main>
243
244 In the messages from the compiler, we see that there is no line for
245 ``D``. This is because it isn't necessary to compile ``D``, because the
246 source and everything it depends on is unchanged since the last
247 compilation.
248
249 Note the ``-dynamic`` flag to GHC: GHCi uses dynamically-linked object
250 code (if you are on a platform that supports it), and so in order to use
251 compiled code with GHCi it must be compiled for dynamic linking.
252
253 At any time you can use the command ``:show modules`` to get a list of
254 the modules currently loaded into GHCi:
255
256 ::
257
258     *Main> :show modules
259     D                ( D.hs, D.o )
260     C                ( C.hs, interpreted )
261     B                ( B.hs, interpreted )
262     A                ( A.hs, interpreted )
263     *Main>
264
265 If we now modify the source of ``D`` (or pretend to: using the Unix command
266 ``touch`` on the source file is handy for this), the compiler will no
267 longer be able to use the object file, because it might be out of date:
268
269 ::
270
271     *Main> :! touch D.hs
272     *Main> :reload
273     Compiling D                ( D.hs, interpreted )
274     Ok, modules loaded: A, B, C, D.
275     *Main>
276
277 Note that module ``D`` was compiled, but in this instance because its source
278 hadn't really changed, its interface remained the same, and the
279 recompilation checker determined that ``A``, ``B`` and ``C`` didn't need to be
280 recompiled.
281
282 So let's try compiling one of the other modules:
283
284 ::
285
286     *Main> :! ghc -c C.hs
287     *Main> :load A
288     Compiling D                ( D.hs, interpreted )
289     Compiling B                ( B.hs, interpreted )
290     Compiling C                ( C.hs, interpreted )
291     Compiling A                ( A.hs, interpreted )
292     Ok, modules loaded: A, B, C, D.
293
294 We didn't get the compiled version of ``C``! What happened? Well, in GHCi a
295 compiled module may only depend on other compiled modules, and in this
296 case ``C`` depends on ``D``, which doesn't have an object file, so GHCi also
297 rejected ``C``\'s object file. Ok, so let's also compile ``D``:
298
299 ::
300
301     *Main> :! ghc -c D.hs
302     *Main> :reload
303     Ok, modules loaded: A, B, C, D.
304
305 Nothing happened! Here's another lesson: newly compiled modules aren't
306 picked up by ``:reload``, only ``:load``:
307
308 ::
309
310     *Main> :load A
311     Compiling B                ( B.hs, interpreted )
312     Compiling A                ( A.hs, interpreted )
313     Ok, modules loaded: A, B, C, D.
314
315 The automatic loading of object files can sometimes lead to confusion,
316 because non-exported top-level definitions of a module are only
317 available for use in expressions at the prompt when the module is
318 interpreted (see :ref:`ghci-scope`). For this reason, you might
319 sometimes want to force GHCi to load a module using the interpreter.
320 This can be done by prefixing a ``*`` to the module name or filename
321 when using ``:load``, for example
322
323 ::
324
325     Prelude> :load *A
326     Compiling A                ( A.hs, interpreted )
327     *A>
328
329 When the ``*`` is used, GHCi ignores any pre-compiled object code and
330 interprets the module. If you have already loaded a number of modules as
331 object code and decide that you wanted to interpret one of them, instead
332 of re-loading the whole set you can use ``:add *M`` to specify that you
333 want ``M`` to be interpreted (note that this might cause other modules
334 to be interpreted too, because compiled modules cannot depend on
335 interpreted ones).
336
337 To always compile everything to object code and never use the
338 interpreter, use the ``-fobject-code`` option (see :ref:`ghci-obj`).
339
340 .. hint::
341     Since GHCi will only use a compiled object file if it can be sure
342     that the compiled version is up-to-date, a good technique when working
343     on a large program is to occasionally run ``ghc --make`` to compile the
344     whole project (say before you go for lunch :-), then continue working in
345     the interpreter. As you modify code, the changed modules will be
346     interpreted, but the rest of the project will remain compiled.
347
348 .. _interactive-evaluation:
349
350 Interactive evaluation at the prompt
351 ------------------------------------
352
353 When you type an expression at the prompt, GHCi immediately evaluates
354 and prints the result:
355
356 ::
357
358     Prelude> reverse "hello"
359     "olleh"
360     Prelude> 5+5
361     10
362
363 .. _actions-at-prompt:
364
365 I/O actions at the prompt
366 ~~~~~~~~~~~~~~~~~~~~~~~~~
367
368 GHCi does more than simple expression evaluation at the prompt. If you
369 enter an expression of type ``IO a`` for some ``a``, then GHCi
370 *executes* it as an IO-computation.
371
372 ::
373
374     Prelude> "hello"
375     "hello"
376     Prelude> putStrLn "hello"
377     hello
378
379 This works even if the type of the expression is more general, provided
380 it can be *instantiated* to ``IO a``. For example
381
382 ::
383
384     Prelude> return True
385     True
386
387 Furthermore, GHCi will print the result of the I/O action if (and only
388 if):
389
390 -  The result type is an instance of ``Show``.
391
392 -  The result type is not ``()``.
393
394 For example, remembering that ``putStrLn :: String -> IO ()``:
395
396 ::
397
398     Prelude> putStrLn "hello"
399     hello
400     Prelude> do { putStrLn "hello"; return "yes" }
401     hello
402     "yes"
403
404 .. _ghci-stmts:
405
406 Using ``do-``\ notation at the prompt
407 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
408
409 .. index::
410    single: do-notation; in GHCi
411    single: statements; in GHCi
412
413 GHCi actually accepts statements rather than just expressions at the
414 prompt. This means you can bind values and functions to names, and use
415 them in future expressions or statements.
416
417 The syntax of a statement accepted at the GHCi prompt is exactly the
418 same as the syntax of a statement in a Haskell ``do`` expression.
419 However, there's no monad overloading here: statements typed at the
420 prompt must be in the ``IO`` monad.
421
422 ::
423
424     Prelude> x <- return 42
425     Prelude> print x
426     42
427     Prelude>
428
429 The statement ``x <- return 42`` means “execute ``return 42`` in the
430 ``IO`` monad, and bind the result to ``x``\ ”. We can then use ``x`` in
431 future statements, for example to print it as we did above.
432
433 If ``-fprint-bind-result`` is set then GHCi will print the result of a
434 statement if and only if:
435
436 -  The statement is not a binding, or it is a monadic binding
437    (``p <- e``) that binds exactly one variable.
438
439 -  The variable's type is not polymorphic, is not ``()``, and is an
440    instance of ``Show``.
441
442 .. index::
443    single: -fprint-bind-result
444
445 Of course, you can also bind normal non-IO expressions using the
446 ``let``\-statement:
447
448 ::
449
450     Prelude> let x = 42
451     Prelude> x
452     42
453     Prelude>
454
455 Another important difference between the two types of binding is that
456 the monadic bind (``p <- e``) is *strict* (it evaluates ``e``), whereas
457 with the ``let`` form, the expression isn't evaluated immediately:
458
459 ::
460
461     Prelude> let x = error "help!"
462     Prelude> print x
463     *** Exception: help!
464     Prelude>
465
466 Note that ``let`` bindings do not automatically print the value bound,
467 unlike monadic bindings.
468
469 You can also use ``let``-statements to define functions at the
470 prompt:
471
472 ::
473
474     Prelude> let add a b = a + b
475     Prelude> add 1 2
476     3
477     Prelude>
478
479 However, this quickly gets tedious when defining functions with multiple
480 clauses, or groups of mutually recursive functions, because the complete
481 definition has to be given on a single line, using explicit semicolons
482 instead of layout:
483
484 ::
485
486     Prelude> let f op n [] = n ; f op n (h:t) = h `op` f op n t
487     Prelude> f (+) 0 [1..3]
488     6
489     Prelude>
490
491 To alleviate this issue, GHCi commands can be split over multiple lines,
492 by wrapping them in ``:{`` and ``:}`` (each on a single line of its
493 own):
494
495 ::
496
497     Prelude> :{
498     Prelude| let g op n [] = n
499     Prelude|     g op n (h:t) = h `op` g op n t
500     Prelude| :}
501     Prelude> g (*) 1 [1..3]
502     6
503
504 Such multiline commands can be used with any GHCi command, and note that
505 the layout rule is in effect. The main purpose of multiline commands is
506 not to replace module loading but to make definitions in .ghci-files
507 (see :ref:`ghci-dot-files`) more readable and maintainable.
508
509 Any exceptions raised during the evaluation or execution of the
510 statement are caught and printed by the GHCi command line interface (for
511 more information on exceptions, see the module ``Control.Exception`` in
512 the libraries documentation).
513
514 Every new binding shadows any existing bindings of the same name,
515 including entities that are in scope in the current module context.
516
517 .. warning::
518     Temporary bindings introduced at the prompt only last until the
519     next ``:load`` or ``:reload`` command, at which time they will be simply
520     lost. However, they do survive a change of context with ``:module``: the
521     temporary bindings just move to the new location.
522
523 .. hint::
524     To get a list of the bindings currently in scope, use the
525     ``:show bindings`` command:
526
527     ::
528
529         Prelude> :show bindings
530         x :: Int
531         Prelude>
532
533 .. hint::
534     If you turn on the ``+t`` option, GHCi will show the type of each
535     variable bound by a statement. For example:
536
537     ::
538
539         Prelude> :set +t
540         Prelude> let (x:xs) = [1..]
541         x :: Integer
542         xs :: [Integer]
543
544     .. index::
545         single: +t option; in GHCi
546
547
548 .. _ghci-multiline:
549
550 Multiline input
551 ~~~~~~~~~~~~~~~
552
553 Apart from the ``:{ ... :}`` syntax for multi-line input mentioned
554 above, GHCi also has a multiline mode, enabled by ``:set +m``,
555 ``:set +m`` in which GHCi detects automatically when the current
556 statement is unfinished and allows further lines to be added. A
557 multi-line input is terminated with an empty line. For example:
558
559 ::
560
561     Prelude> :set +m
562     Prelude> let x = 42
563     Prelude|
564
565 Further bindings can be added to this ``let`` statement, so GHCi
566 indicates that the next line continues the previous one by changing the
567 prompt. Note that layout is in effect, so to add more bindings to this
568 ``let`` we have to line them up:
569
570 ::
571
572     Prelude> :set +m
573     Prelude> let x = 42
574     Prelude|     y = 3
575     Prelude|
576     Prelude>
577
578 Explicit braces and semicolons can be used instead of layout:
579
580 ::
581
582     Prelude> do {
583     Prelude| putStrLn "hello"
584     Prelude| ;putStrLn "world"
585     Prelude| }
586     hello
587     world
588     Prelude>
589
590 Note that after the closing brace, GHCi knows that the current statement
591 is finished, so no empty line is required.
592
593 Multiline mode is useful when entering monadic ``do`` statements:
594
595 ::
596
597     Control.Monad.State> flip evalStateT 0 $ do
598     Control.Monad.State| i <- get
599     Control.Monad.State| lift $ do
600     Control.Monad.State|   putStrLn "Hello World!"
601     Control.Monad.State|   print i
602     Control.Monad.State|
603     "Hello World!"
604     0
605     Control.Monad.State>
606
607 During a multiline interaction, the user can interrupt and return to the
608 top-level prompt.
609
610 ::
611
612     Prelude> do
613     Prelude| putStrLn "Hello, World!"
614     Prelude| ^C
615     Prelude>
616
617 .. _ghci-decls:
618
619 Type, class and other declarations
620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
621
622 At the GHCi prompt you can also enter any top-level Haskell declaration,
623 including ``data``, ``type``, ``newtype``, ``class``, ``instance``,
624 ``deriving``, and ``foreign`` declarations. For example:
625
626 ::
627
628     Prelude> data T = A | B | C deriving (Eq, Ord, Show, Enum)
629     Prelude> [A ..]
630     [A,B,C]
631     Prelude> :i T
632     data T = A | B | C      -- Defined at <interactive>:2:6
633     instance Enum T -- Defined at <interactive>:2:45
634     instance Eq T -- Defined at <interactive>:2:30
635     instance Ord T -- Defined at <interactive>:2:34
636     instance Show T -- Defined at <interactive>:2:39
637
638 As with ordinary variable bindings, later definitions shadow earlier
639 ones, so you can re-enter a declaration to fix a problem with it or
640 extend it. But there's a gotcha: when a new type declaration shadows an
641 older one, there might be other declarations that refer to the old type.
642 The thing to remember is that the old type still exists, and these other
643 declarations still refer to the old type. However, while the old and the
644 new type have the same name, GHCi will treat them as distinct. For
645 example:
646
647 ::
648
649     Prelude> data T = A | B
650     Prelude> let f A = True; f B = False
651     Prelude> data T = A | B | C
652     Prelude> f A
653
654     <interactive>:2:3:
655         Couldn't match expected type `main::Interactive.T'
656                     with actual type `T'
657         In the first argument of `f', namely `A'
658         In the expression: f A
659         In an equation for `it': it = f A
660     Prelude>
661
662 The old, shadowed, version of ``T`` is displayed as
663 ``main::Interactive.T`` by GHCi in an attempt to distinguish it from the
664 new ``T``, which is displayed as simply ``T``.
665
666 Class and type-family instance declarations are simply added to the list
667 of available instances, with one exception. Since you might want to
668 re-define one, a class or type-family instance *replaces* any earlier
669 instance with an identical head or left hand side (respectively). (See
670 :ref:`type-families`.)
671
672 .. _ghci-scope:
673
674 What's really in scope at the prompt?
675 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
676
677 When you type an expression at the prompt, what identifiers and types
678 are in scope? GHCi provides a flexible way to control exactly how the
679 context for an expression is constructed:
680
681 -  The ``:load``, ``:add``, and ``:reload`` commands
682    (:ref:`ghci-load-scope`).
683
684 -  The ``import`` declaration (:ref:`ghci-import-decl`).
685
686 -  The ``:module`` command (:ref:`ghci-module-cmd`).
687
688 The command ``:show imports`` will show a summary of which modules
689 contribute to the top-level scope.
690
691 .. hint::
692     GHCi will tab-complete names that are in scope; for example, if
693     you run GHCi and type ``J<tab>`` then GHCi will expand it to
694     “\ ``Just``\ ”.
695
696 .. _ghci-load-scope:
697
698 The effect of ``:load`` on what is in scope
699 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
700
701 The ``:load``, ``:add``, and ``:reload`` commands
702 (:ref:`loading-source-files` and :ref:`ghci-compiled`) affect the
703 top-level scope. Let's start with the simple cases; when you start GHCi
704 the prompt looks like this:
705
706 ::
707
708     Prelude>
709
710 which indicates that everything from the module ``Prelude`` is currently
711 in scope; the visible identifiers are exactly those that would be
712 visible in a Haskell source file with no ``import`` declarations.
713
714 If we now load a file into GHCi, the prompt will change:
715
716 ::
717
718     Prelude> :load Main.hs
719     Compiling Main             ( Main.hs, interpreted )
720     *Main>
721
722 The new prompt is ``*Main``, which indicates that we are typing
723 expressions in the context of the top-level of the ``Main`` module.
724 Everything that is in scope at the top-level in the module ``Main`` we
725 just loaded is also in scope at the prompt (probably including
726 ``Prelude``, as long as ``Main`` doesn't explicitly hide it).
727
728 The syntax in the prompt ``*module`` indicates that it is the full
729 top-level scope of ⟨module⟩ that is contributing to the scope for
730 expressions typed at the prompt. Without the ``*``, just the exports of
731 the module are visible.
732
733 .. note::
734     For technical reasons, GHCi can only support the ``*``-form for
735     modules that are interpreted. Compiled modules and package modules can
736     only contribute their exports to the current scope. To ensure that GHCi
737     loads the interpreted version of a module, add the ``*`` when loading
738     the module, e.g. ``:load *M``.
739
740 In general, after a ``:load`` command, an automatic import is added to
741 the scope for the most recently loaded "target" module, in a ``*``-form
742 if possible. For example, if you say ``:load foo.hs bar.hs`` and
743 ``bar.hs`` contains module ``Bar``, then the scope will be set to
744 ``*Bar`` if ``Bar`` is interpreted, or if ``Bar`` is compiled it will be
745 set to ``Prelude Bar`` (GHCi automatically adds ``Prelude`` if it isn't
746 present and there aren't any ``*``-form modules). These
747 automatically-added imports can be seen with ``:show imports``:
748
749 ::
750
751     Prelude> :load hello.hs
752     [1 of 1] Compiling Main             ( hello.hs, interpreted )
753     Ok, modules loaded: Main.
754     *Main> :show imports
755     :module +*Main -- added automatically
756     *Main>
757
758 and the automatically-added import is replaced the next time you use
759 ``:load``, ``:add``, or ``:reload``. It can also be removed by
760 ``:module`` as with normal imports.
761
762 .. _ghci-import-decl:
763
764 Controlling what is in scope with ``import``
765 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
766
767 We are not limited to a single module: GHCi can combine scopes from
768 multiple modules, in any mixture of ``*`` and non-\ ``*`` forms. GHCi
769 combines the scopes from all of these modules to form the scope that is
770 in effect at the prompt.
771
772 To add modules to the scope, use ordinary Haskell ``import`` syntax:
773
774 ::
775
776     Prelude> import System.IO
777     Prelude System.IO> hPutStrLn stdout "hello\n"
778     hello
779     Prelude System.IO>
780
781 The full Haskell import syntax is supported, including ``hiding`` and
782 ``as`` clauses. The prompt shows the modules that are currently
783 imported, but it omits details about ``hiding``, ``as``, and so on. To
784 see the full story, use ``:show imports``:
785
786 ::
787
788     Prelude> import System.IO
789     Prelude System.IO> import Data.Map as Map
790     Prelude System.IO Map> :show imports
791     import Prelude -- implicit
792     import System.IO
793     import Data.Map as Map
794     Prelude System.IO Map>
795
796 Note that the ``Prelude`` import is marked as implicit. It can be
797 overridden with an explicit ``Prelude`` import, just like in a Haskell
798 module.
799
800 With multiple modules in scope, especially multiple ``*``-form modules,
801 it is likely that name clashes will occur. Haskell specifies that name
802 clashes are only reported when an ambiguous identifier is used, and GHCi
803 behaves in the same way for expressions typed at the prompt.
804
805 .. _ghci-module-cmd:
806
807 Controlling what is in scope with the ``:module`` command
808 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
809
810 Another way to manipulate the scope is to use the ``:module`` command,
811 whose syntax is this:
812
813 ::
814
815     :module +|- *mod1 ... *modn
816
817 Using the ``+`` form of the ``module`` commands adds modules to the
818 current scope, and ``-`` removes them. Without either ``+`` or ``-``,
819 the current scope is replaced by the set of modules specified. Note that
820 if you use this form and leave out ``Prelude``, an implicit ``Prelude``
821 import will be added automatically.
822
823 The ``:module`` command provides a way to do two things that cannot be
824 done with ordinary ``import`` declarations:
825
826 -  ``:module`` supports the ``*`` modifier on modules, which opens the
827    full top-level scope of a module, rather than just its exports.
828
829 -  Imports can be *removed* from the context, using the syntax
830    ``:module -M``. The ``import`` syntax is cumulative (as in a Haskell
831    module), so this is the only way to subtract from the scope.
832
833 .. _ghci-import-qualified:
834
835 Qualified names
836 ^^^^^^^^^^^^^^^
837
838 To make life slightly easier, the GHCi prompt also behaves as if there
839 is an implicit ``import qualified`` declaration for every module in
840 every package, and every module currently loaded into GHCi. This
841 behaviour can be disabled with the ``-fno-implicit-import-qualified`` flag.
842
843 .. index::
844    single: -fno-implicit-import-qualified
845
846 ``:module`` and ``:load``
847 ^^^^^^^^^^^^^^^^^^^^^^^^^
848
849 It might seem that ``:module``/``import`` and
850 ``:load``/``:add``/``:reload`` do similar things: you can use both to
851 bring a module into scope. However, there is a very important
852 difference. GHCi is concerned with two sets of modules:
853
854 -  The set of modules that are currently *loaded*. This set is modified
855    by ``:load``, ``:add`` and ``:reload``, and can be shown with
856    ``:show modules``.
857
858 -  The set of modules that are currently *in scope* at the prompt. This
859    set is modified by ``import`` and ``:module``, and it is also
860    modified automatically after ``:load``, ``:add``, and ``:reload``, as
861    described above. The set of modules in scope can be shown with
862    ``:show imports``.
863
864 You can add a module to the scope (via ``:module`` or ``import``) only
865 if either (a) it is loaded, or (b) it is a module from a package that
866 GHCi knows about. Using ``:module`` or ``import`` to try bring into
867 scope a non-loaded module may result in the message
868 “\ ``module M is not loaded``\ ”.
869
870 The ``:main`` and ``:run`` commands
871 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
872
873 When a program is compiled and executed, it can use the ``getArgs``
874 function to access the command-line arguments. However, we cannot simply
875 pass the arguments to the ``main`` function while we are testing in
876 ghci, as the ``main`` function doesn't take its directly.
877
878 Instead, we can use the ``:main`` command. This runs whatever ``main``
879 is in scope, with any arguments being treated the same as command-line
880 arguments, e.g.:
881
882 ::
883
884     Prelude> let main = System.Environment.getArgs >>= print
885     Prelude> :main foo bar
886     ["foo","bar"]
887
888 We can also quote arguments which contains characters like spaces, and
889 they are treated like Haskell strings, or we can just use Haskell list
890 syntax:
891
892 ::
893
894     Prelude> :main foo "bar baz"
895     ["foo","bar baz"]
896     Prelude> :main ["foo", "bar baz"]
897     ["foo","bar baz"]
898
899 Finally, other functions can be called, either with the ``-main-is``
900 flag or the ``:run`` command:
901
902 ::
903
904     Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
905     Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
906     Prelude> :set -main-is foo
907     Prelude> :main foo "bar baz"
908     foo
909     ["foo","bar baz"]
910     Prelude> :run bar ["foo", "bar baz"]
911     bar
912     ["foo","bar baz"]
913
914 The ``it`` variable
915 ~~~~~~~~~~~~~~~~~~~
916
917 .. index::
918    single: it variable
919
920 Whenever an expression (or a non-binding statement, to be precise) is
921 typed at the prompt, GHCi implicitly binds its value to the variable
922 ``it``. For example:
923
924 ::
925
926     Prelude> 1+2
927     3
928     Prelude> it * 2
929     6
930
931 What actually happens is that GHCi typechecks the expression, and if it
932 doesn't have an ``IO`` type, then it transforms it as follows: an
933 expression ``e`` turns into
934
935 ::
936
937     let it = e;
938     print it
939
940 which is then run as an IO-action.
941
942 Hence, the original expression must have a type which is an instance of
943 the ``Show`` class, or GHCi will complain:
944
945 ::
946
947     Prelude> id
948
949     <interactive>:1:0:
950         No instance for (Show (a -> a))
951           arising from use of `print' at <interactive>:1:0-1
952         Possible fix: add an instance declaration for (Show (a -> a))
953         In the expression: print it
954         In a 'do' expression: print it
955
956 The error message contains some clues as to the transformation happening
957 internally.
958
959 If the expression was instead of type ``IO a`` for some ``a``, then
960 ``it`` will be bound to the result of the ``IO`` computation, which is
961 of type ``a``. eg.:
962
963 ::
964
965     Prelude> Time.getClockTime
966     Wed Mar 14 12:23:13 GMT 2001
967     Prelude> print it
968     Wed Mar 14 12:23:13 GMT 2001
969
970 The corresponding translation for an IO-typed ``e`` is
971
972 ::
973
974     it <- e
975
976 Note that ``it`` is shadowed by the new value each time you evaluate a
977 new expression, and the old value of ``it`` is lost.
978
979 .. _extended-default-rules:
980
981 Type defaulting in GHCi
982 ~~~~~~~~~~~~~~~~~~~~~~~
983
984 .. index::
985    single: Type defaulting; in GHCi
986    single: Show class
987
988 Consider this GHCi session:
989
990 ::
991
992       ghci> reverse []
993
994 What should GHCi do? Strictly speaking, the program is ambiguous.
995 ``show (reverse [])`` (which is what GHCi computes here) has type
996 ``Show a => String`` and how that displays depends on the type ``a``.
997 For example:
998
999 ::
1000
1001       ghci> reverse ([] :: String)
1002       ""
1003       ghci> reverse ([] :: [Int])
1004       []
1005
1006 However, it is tiresome for the user to have to specify the type, so
1007 GHCi extends Haskell's type-defaulting rules (Section 4.3.4 of the
1008 Haskell 2010 Report) as follows. The standard rules take each group of
1009 constraints ``(C1 a, C2 a, ..., Cn a)`` for each type variable ``a``,
1010 and defaults the type variable if
1011
1012 1. The type variable ``a`` appears in no other constraints
1013
1014 2. All the classes ``Ci`` are standard.
1015
1016 3. At least one of the classes ``Ci`` is numeric.
1017
1018 At the GHCi prompt, or with GHC if the ``-XExtendedDefaultRules`` flag
1019 is given, the following additional differences apply:
1020
1021 -  Rule 2 above is relaxed thus: *All* of the classes ``Ci`` are
1022    single-parameter type classes.
1023
1024 -  Rule 3 above is relaxed this: At least one of the classes ``Ci`` is
1025    numeric, or is ``Show``, ``Eq``, or ``Ord``.
1026
1027 -  The unit type ``()`` is added to the start of the standard list of
1028    types which are tried when doing type defaulting.
1029
1030 The last point means that, for example, this program:
1031
1032 ::
1033
1034     main :: IO ()
1035     main = print def
1036
1037     instance Num ()
1038
1039     def :: (Num a, Enum a) => a
1040     def = toEnum 0
1041
1042 prints ``()`` rather than ``0`` as the type is defaulted to ``()``
1043 rather than ``Integer``.
1044
1045 The motivation for the change is that it means ``IO a`` actions default
1046 to ``IO ()``, which in turn means that ghci won't try to print a result
1047 when running them. This is particularly important for ``printf``, which
1048 has an instance that returns ``IO a``. However, it is only able to
1049 return ``undefined`` (the reason for the instance having this type is so
1050 that printf doesn't require extensions to the class system), so if the
1051 type defaults to ``Integer`` then ghci gives an error when running a
1052 printf.
1053
1054 See also :ref:`actions-at-prompt` for how the monad of a computational
1055 expression defaults to ``IO`` if possible.
1056
1057 .. _ghci-interactive-print:
1058
1059 Using a custom interactive printing function
1060 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1061
1062 .. index::
1063    single: Custom printing function; in GHCi
1064
1065 [**New in version 7.6.1**] By default, GHCi prints the result of
1066 expressions typed at the prompt using the function ``System.IO.print``.
1067 Its type signature is ``Show a => a -> IO ()``, and it works by
1068 converting the value to ``String`` using ``show``.
1069
1070 This is not ideal in certain cases, like when the output is long, or
1071 contains strings with non-ascii characters.
1072
1073 The ``-interactive-print`` flag allows to specify any function of type
1074 ``C a => a -> IO ()``, for some constraint ``C``, as the function for
1075 printing evaluated expressions. The function can reside in any loaded
1076 module or any registered package.
1077
1078 As an example, suppose we have following special printing module:
1079
1080 ::
1081
1082              module SpecPrinter where
1083              import System.IO
1084
1085              sprint a = putStrLn $ show a ++ "!"
1086
1087 The ``sprint`` function adds an exclamation mark at the end of any
1088 printed value. Running GHCi with the command:
1089
1090 ::
1091
1092              ghci -interactive-print=SpecPrinter.sprinter SpecPrinter
1093
1094 will start an interactive session where values with be printed using
1095 ``sprint``:
1096
1097 ::
1098
1099              *SpecPrinter> [1,2,3]
1100              [1,2,3]!
1101              *SpecPrinter> 42
1102              42!
1103
1104 A custom pretty printing function can be used, for example, to format
1105 tree-like and nested structures in a more readable way.
1106
1107 The ``-interactive-print`` flag can also be used when running GHC in
1108 ``-e mode``:
1109
1110 ::
1111
1112              % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter
1113              [1,2,3]!
1114
1115 .. _ghci-debugger:
1116
1117 The GHCi Debugger
1118 -----------------
1119
1120 .. index::
1121    single: debugger; in GHCi
1122
1123 GHCi contains a simple imperative-style debugger in which you can stop a
1124 running computation in order to examine the values of variables. The
1125 debugger is integrated into GHCi, and is turned on by default: no flags
1126 are required to enable the debugging facilities. There is one major
1127 restriction: breakpoints and single-stepping are only available in
1128 interpreted modules; compiled code is invisible to the debugger [5]_.
1129
1130 The debugger provides the following:
1131
1132 -  The ability to set a breakpoint on a function definition or
1133    expression in the program. When the function is called, or the
1134    expression evaluated, GHCi suspends execution and returns to the
1135    prompt, where you can inspect the values of local variables before
1136    continuing with the execution.
1137
1138 -  Execution can be single-stepped: the evaluator will suspend execution
1139    approximately after every reduction, allowing local variables to be
1140    inspected. This is equivalent to setting a breakpoint at every point
1141    in the program.
1142
1143 -  Execution can take place in tracing mode, in which the evaluator
1144    remembers each evaluation step as it happens, but doesn't suspend
1145    execution until an actual breakpoint is reached. When this happens,
1146    the history of evaluation steps can be inspected.
1147
1148 -  Exceptions (e.g. pattern matching failure and ``error``) can be
1149    treated as breakpoints, to help locate the source of an exception in
1150    the program.
1151
1152 There is currently no support for obtaining a “stack trace”, but the
1153 tracing and history features provide a useful second-best, which will
1154 often be enough to establish the context of an error. For instance, it
1155 is possible to break automatically when an exception is thrown, even if
1156 it is thrown from within compiled code (see
1157 :ref:`ghci-debugger-exceptions`).
1158
1159 .. _breakpoints:
1160
1161 Breakpoints and inspecting variables
1162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1163
1164 Let's use quicksort as a running example. Here's the code:
1165
1166 ::
1167
1168     qsort [] = []
1169     qsort (a:as) = qsort left ++ [a] ++ qsort right
1170       where (left,right) = (filter (<=a) as, filter (>a) as)
1171
1172     main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1173
1174 First, load the module into GHCi:
1175
1176 ::
1177
1178     Prelude> :l qsort.hs
1179     [1 of 1] Compiling Main             ( qsort.hs, interpreted )
1180     Ok, modules loaded: Main.
1181     *Main>
1182
1183 Now, let's set a breakpoint on the right-hand-side of the second
1184 equation of qsort:
1185
1186 ::
1187
1188     *Main> :break 2
1189     Breakpoint 0 activated at qsort.hs:2:15-46
1190     *Main>
1191
1192 The command ``:break 2`` sets a breakpoint on line 2 of the most
1193 recently-loaded module, in this case ``qsort.hs``. Specifically, it
1194 picks the leftmost complete subexpression on that line on which to set
1195 the breakpoint, which in this case is the expression
1196 ``(qsort left ++ [a] ++ qsort right)``.
1197
1198 Now, we run the program:
1199
1200 ::
1201
1202     *Main> main
1203     Stopped at qsort.hs:2:15-46
1204     _result :: [a]
1205     a :: a
1206     left :: [a]
1207     right :: [a]
1208     [qsort.hs:2:15-46] *Main>
1209
1210 Execution has stopped at the breakpoint. The prompt has changed to
1211 indicate that we are currently stopped at a breakpoint, and the
1212 location: ``[qsort.hs:2:15-46]``. To further clarify the location, we
1213 can use the ``:list`` command:
1214
1215 ::
1216
1217     [qsort.hs:2:15-46] *Main> :list
1218     1  qsort [] = []
1219     2  qsort (a:as) = qsort left ++ [a] ++ qsort right
1220     3    where (left,right) = (filter (<=a) as, filter (>a) as)
1221
1222 The ``:list`` command lists the source code around the current
1223 breakpoint. If your output device supports it, then GHCi will highlight
1224 the active subexpression in bold.
1225
1226 GHCi has provided bindings for the free variables [6]_ of the expression
1227 on which the breakpoint was placed (``a``, ``left``, ``right``), and
1228 additionally a binding for the result of the expression (``_result``).
1229 These variables are just like other variables that you might define in
1230 GHCi; you can use them in expressions that you type at the prompt, you
1231 can ask for their types with ``:type``, and so on. There is one
1232 important difference though: these variables may only have partial
1233 types. For example, if we try to display the value of ``left``:
1234
1235 ::
1236
1237     [qsort.hs:2:15-46] *Main> left
1238
1239     <interactive>:1:0:
1240         Ambiguous type variable `a' in the constraint:
1241           `Show a' arising from a use of `print' at <interactive>:1:0-3
1242         Cannot resolve unknown runtime types: a
1243         Use :print or :force to determine these types
1244
1245 This is because ``qsort`` is a polymorphic function, and because GHCi
1246 does not carry type information at runtime, it cannot determine the
1247 runtime types of free variables that involve type variables. Hence, when
1248 you ask to display ``left`` at the prompt, GHCi can't figure out which
1249 instance of ``Show`` to use, so it emits the type error above.
1250
1251 Fortunately, the debugger includes a generic printing command,
1252 ``:print``, which can inspect the actual runtime value of a variable and
1253 attempt to reconstruct its type. If we try it on ``left``:
1254
1255 ::
1256
1257     [qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show
1258     [qsort.hs:2:15-46] *Main> :print left
1259     left = (_t1::[a])
1260
1261 This isn't particularly enlightening. What happened is that ``left`` is
1262 bound to an unevaluated computation (a suspension, or thunk), and
1263 ``:print`` does not force any evaluation. The idea is that ``:print``
1264 can be used to inspect values at a breakpoint without any unfortunate
1265 side effects. It won't force any evaluation, which could cause the
1266 program to give a different answer than it would normally, and hence it
1267 won't cause any exceptions to be raised, infinite loops, or further
1268 breakpoints to be triggered (see :ref:`nested-breakpoints`). Rather than
1269 forcing thunks, ``:print`` binds each thunk to a fresh variable
1270 beginning with an underscore, in this case ``_t1``.
1271
1272 The flag ``-fprint-evld-with-show`` instructs ``:print`` to reuse
1273 available ``Show`` instances when possible. This happens only when the
1274 contents of the variable being inspected are completely evaluated.
1275
1276 If we aren't concerned about preserving the evaluatedness of a variable,
1277 we can use ``:force`` instead of ``:print``. The ``:force`` command
1278 behaves exactly like ``:print``, except that it forces the evaluation of
1279 any thunks it encounters:
1280
1281 ::
1282
1283     [qsort.hs:2:15-46] *Main> :force left
1284     left = [4,0,3,1]
1285
1286 Now, since ``:force`` has inspected the runtime value of ``left``, it
1287 has reconstructed its type. We can see the results of this type
1288 reconstruction:
1289
1290 ::
1291
1292     [qsort.hs:2:15-46] *Main> :show bindings
1293     _result :: [Integer]
1294     a :: Integer
1295     left :: [Integer]
1296     right :: [Integer]
1297     _t1 :: [Integer]
1298
1299 Not only do we now know the type of ``left``, but all the other partial
1300 types have also been resolved. So we can ask for the value of ``a``, for
1301 example:
1302
1303 ::
1304
1305     [qsort.hs:2:15-46] *Main> a
1306     8
1307
1308 You might find it useful to use Haskell's ``seq`` function to evaluate
1309 individual thunks rather than evaluating the whole expression with
1310 ``:force``. For example:
1311
1312 ::
1313
1314     [qsort.hs:2:15-46] *Main> :print right
1315     right = (_t1::[Integer])
1316     [qsort.hs:2:15-46] *Main> seq _t1 ()
1317     ()
1318     [qsort.hs:2:15-46] *Main> :print right
1319     right = 23 : (_t2::[Integer])
1320
1321 We evaluated only the ``_t1`` thunk, revealing the head of the list, and
1322 the tail is another thunk now bound to ``_t2``. The ``seq`` function is
1323 a little inconvenient to use here, so you might want to use ``:def`` to
1324 make a nicer interface (left as an exercise for the reader!).
1325
1326 Finally, we can continue the current execution:
1327
1328 ::
1329
1330     [qsort.hs:2:15-46] *Main> :continue
1331     Stopped at qsort.hs:2:15-46
1332     _result :: [a]
1333     a :: a
1334     left :: [a]
1335     right :: [a]
1336     [qsort.hs:2:15-46] *Main>
1337
1338 The execution continued at the point it previously stopped, and has now
1339 stopped at the breakpoint for a second time.
1340
1341 .. _setting-breakpoints:
1342
1343 Setting breakpoints
1344 ^^^^^^^^^^^^^^^^^^^
1345
1346 Breakpoints can be set in various ways. Perhaps the easiest way to set a
1347 breakpoint is to name a top-level function:
1348
1349 ::
1350
1351        :break identifier
1352
1353 Where ⟨identifier⟩ names any top-level function in an interpreted module
1354 currently loaded into GHCi (qualified names may be used). The breakpoint
1355 will be set on the body of the function, when it is fully applied but
1356 before any pattern matching has taken place.
1357
1358 Breakpoints can also be set by line (and optionally column) number:
1359
1360 ::
1361
1362        :break line
1363        :break line column
1364        :break module line
1365        :break module line column
1366
1367 When a breakpoint is set on a particular line, GHCi sets the breakpoint
1368 on the leftmost subexpression that begins and ends on that line. If two
1369 complete subexpressions start at the same column, the longest one is
1370 picked. If there is no complete subexpression on the line, then the
1371 leftmost expression starting on the line is picked, and failing that the
1372 rightmost expression that partially or completely covers the line.
1373
1374 When a breakpoint is set on a particular line and column, GHCi picks the
1375 smallest subexpression that encloses that location on which to set the
1376 breakpoint. Note: GHC considers the TAB character to have a width of 1,
1377 wherever it occurs; in other words it counts characters, rather than
1378 columns. This matches what some editors do, and doesn't match others.
1379 The best advice is to avoid tab characters in your source code
1380 altogether (see ``-fwarn-tabs`` in :ref:`options-sanity`).
1381
1382 If the module is omitted, then the most recently-loaded module is used.
1383
1384 Not all subexpressions are potential breakpoint locations. Single
1385 variables are typically not considered to be breakpoint locations
1386 (unless the variable is the right-hand-side of a function definition,
1387 lambda, or case alternative). The rule of thumb is that all redexes are
1388 breakpoint locations, together with the bodies of functions, lambdas,
1389 case alternatives and binding statements. There is normally no
1390 breakpoint on a let expression, but there will always be a breakpoint on
1391 its body, because we are usually interested in inspecting the values of
1392 the variables bound by the let.
1393
1394 Listing and deleting breakpoints
1395 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1396
1397 The list of breakpoints currently enabled can be displayed using
1398 ``:show breaks``:
1399
1400 ::
1401
1402     *Main> :show breaks
1403     [0] Main qsort.hs:1:11-12
1404     [1] Main qsort.hs:2:15-46
1405
1406 To delete a breakpoint, use the ``:delete`` command with the number
1407 given in the output from ``:show breaks``:
1408
1409 ::
1410
1411     *Main> :delete 0
1412     *Main> :show breaks
1413     [1] Main qsort.hs:2:15-46
1414
1415 To delete all breakpoints at once, use ``:delete *``.
1416
1417 .. _single-stepping:
1418
1419 Single-stepping
1420 ~~~~~~~~~~~~~~~
1421
1422 Single-stepping is a great way to visualise the execution of your
1423 program, and it is also a useful tool for identifying the source of a
1424 bug. GHCi offers two variants of stepping. Use ``:step`` to enable all
1425 the breakpoints in the program, and execute until the next breakpoint is
1426 reached. Use ``:steplocal`` to limit the set of enabled breakpoints to
1427 those in the current top level function. Similarly, use ``:stepmodule``
1428 to single step only on breakpoints contained in the current module. For
1429 example:
1430
1431 ::
1432
1433     *Main> :step main
1434     Stopped at qsort.hs:5:7-47
1435     _result :: IO ()
1436
1437 The command ``:step expr`` begins the evaluation of ⟨expr⟩ in
1438 single-stepping mode. If ⟨expr⟩ is omitted, then it single-steps from
1439 the current breakpoint. ``:steplocal`` and ``:stepmodule`` work
1440 similarly.
1441
1442 The ``:list`` command is particularly useful when single-stepping, to
1443 see where you currently are:
1444
1445 ::
1446
1447     [qsort.hs:5:7-47] *Main> :list
1448     4
1449     5  main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1450     6
1451     [qsort.hs:5:7-47] *Main>
1452
1453 In fact, GHCi provides a way to run a command when a breakpoint is hit,
1454 so we can make it automatically do ``:list``:
1455
1456 ::
1457
1458     [qsort.hs:5:7-47] *Main> :set stop :list
1459     [qsort.hs:5:7-47] *Main> :step
1460     Stopped at qsort.hs:5:14-46
1461     _result :: [Integer]
1462     4
1463     5  main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1464     6
1465     [qsort.hs:5:14-46] *Main>
1466
1467 .. _nested-breakpoints:
1468
1469 Nested breakpoints
1470 ~~~~~~~~~~~~~~~~~~
1471
1472 When GHCi is stopped at a breakpoint, and an expression entered at the
1473 prompt triggers a second breakpoint, the new breakpoint becomes the
1474 "current" one, and the old one is saved on a stack. An arbitrary number
1475 of breakpoint contexts can be built up in this way. For example:
1476
1477 ::
1478
1479     [qsort.hs:2:15-46] *Main> :st qsort [1,3]
1480     Stopped at qsort.hs:(1,0)-(3,55)
1481     _result :: [a]
1482     ... [qsort.hs:(1,0)-(3,55)] *Main>
1483
1484 While stopped at the breakpoint on line 2 that we set earlier, we
1485 started a new evaluation with ``:step qsort [1,3]``. This new evaluation
1486 stopped after one step (at the definition of ``qsort``). The prompt has
1487 changed, now prefixed with ``...``, to indicate that there are saved
1488 breakpoints beyond the current one. To see the stack of contexts, use
1489 ``:show context``:
1490
1491 ::
1492
1493     ... [qsort.hs:(1,0)-(3,55)] *Main> :show context
1494     --> main
1495       Stopped at qsort.hs:2:15-46
1496     --> qsort [1,3]
1497       Stopped at qsort.hs:(1,0)-(3,55)
1498     ... [qsort.hs:(1,0)-(3,55)] *Main>
1499
1500 To abandon the current evaluation, use ``:abandon``:
1501
1502 ::
1503
1504     ... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
1505     [qsort.hs:2:15-46] *Main> :abandon
1506     *Main>
1507
1508 .. _ghci-debugger-result:
1509
1510 The ``_result`` variable
1511 ~~~~~~~~~~~~~~~~~~~~~~~~
1512
1513 When stopped at a breakpoint or single-step, GHCi binds the variable
1514 ``_result`` to the value of the currently active expression. The value
1515 of ``_result`` is presumably not available yet, because we stopped its
1516 evaluation, but it can be forced: if the type is known and showable,
1517 then just entering ``_result`` at the prompt will show it. However,
1518 there's one caveat to doing this: evaluating ``_result`` will be likely
1519 to trigger further breakpoints, starting with the breakpoint we are
1520 currently stopped at (if we stopped at a real breakpoint, rather than
1521 due to ``:step``). So it will probably be necessary to issue a
1522 ``:continue`` immediately when evaluating ``_result``. Alternatively,
1523 you can use ``:force`` which ignores breakpoints.
1524
1525 .. _tracing:
1526
1527 Tracing and history
1528 ~~~~~~~~~~~~~~~~~~~
1529
1530 A question that we often want to ask when debugging a program is “how
1531 did I get here?”. Traditional imperative debuggers usually provide some
1532 kind of stack-tracing feature that lets you see the stack of active
1533 function calls (sometimes called the “lexical call stack”), describing a
1534 path through the code to the current location. Unfortunately this is
1535 hard to provide in Haskell, because execution proceeds on a
1536 demand-driven basis, rather than a depth-first basis as in strict
1537 languages. The “stack“ in GHC's execution engine bears little
1538 resemblance to the lexical call stack. Ideally GHCi would maintain a
1539 separate lexical call stack in addition to the dynamic call stack, and
1540 in fact this is exactly what our profiling system does
1541 (:ref:`profiling`), and what some other Haskell debuggers do. For the
1542 time being, however, GHCi doesn't maintain a lexical call stack (there
1543 are some technical challenges to be overcome). Instead, we provide a way
1544 to backtrack from a breakpoint to previous evaluation steps: essentially
1545 this is like single-stepping backwards, and should in many cases provide
1546 enough information to answer the "how did I get here?" question.
1547
1548 To use tracing, evaluate an expression with the ``:trace`` command. For
1549 example, if we set a breakpoint on the base case of ``qsort``:
1550
1551 ::
1552
1553     *Main> :list qsort
1554     1  qsort [] = []
1555     2  qsort (a:as) = qsort left ++ [a] ++ qsort right
1556     3    where (left,right) = (filter (<=a) as, filter (>a) as)
1557     4
1558     *Main> :b 1
1559     Breakpoint 1 activated at qsort.hs:1:11-12
1560     *Main>
1561
1562 and then run a small ``qsort`` with tracing:
1563
1564 ::
1565
1566     *Main> :trace qsort [3,2,1]
1567     Stopped at qsort.hs:1:11-12
1568     _result :: [a]
1569     [qsort.hs:1:11-12] *Main>
1570
1571 We can now inspect the history of evaluation steps:
1572
1573 ::
1574
1575     [qsort.hs:1:11-12] *Main> :hist
1576     -1  : qsort.hs:3:24-38
1577     -2  : qsort.hs:3:23-55
1578     -3  : qsort.hs:(1,0)-(3,55)
1579     -4  : qsort.hs:2:15-24
1580     -5  : qsort.hs:2:15-46
1581     -6  : qsort.hs:3:24-38
1582     -7  : qsort.hs:3:23-55
1583     -8  : qsort.hs:(1,0)-(3,55)
1584     -9  : qsort.hs:2:15-24
1585     -10 : qsort.hs:2:15-46
1586     -11 : qsort.hs:3:24-38
1587     -12 : qsort.hs:3:23-55
1588     -13 : qsort.hs:(1,0)-(3,55)
1589     -14 : qsort.hs:2:15-24
1590     -15 : qsort.hs:2:15-46
1591     -16 : qsort.hs:(1,0)-(3,55)
1592     <end of history>
1593
1594 To examine one of the steps in the history, use ``:back``:
1595
1596 ::
1597
1598     [qsort.hs:1:11-12] *Main> :back
1599     Logged breakpoint at qsort.hs:3:24-38
1600     _result :: [a]
1601     as :: [a]
1602     a :: a
1603     [-1: qsort.hs:3:24-38] *Main>
1604
1605 Note that the local variables at each step in the history have been
1606 preserved, and can be examined as usual. Also note that the prompt has
1607 changed to indicate that we're currently examining the first step in the
1608 history: ``-1``. The command ``:forward`` can be used to traverse
1609 forward in the history.
1610
1611 The ``:trace`` command can be used with or without an expression. When
1612 used without an expression, tracing begins from the current breakpoint,
1613 just like ``:step``.
1614
1615 The history is only available when using ``:trace``; the reason for this
1616 is we found that logging each breakpoint in the history cuts performance
1617 by a factor of 2 or more. By default, GHCi remembers the last 50 steps
1618 in the history, but this can be changed with the ``-fghci-hist-size=n`` option).
1619
1620 .. index::
1621    single: -fghci-hist-size
1622
1623 .. _ghci-debugger-exceptions:
1624
1625 Debugging exceptions
1626 ~~~~~~~~~~~~~~~~~~~~
1627
1628 Another common question that comes up when debugging is "where did this
1629 exception come from?". Exceptions such as those raised by ``error`` or
1630 ``head []`` have no context information attached to them. Finding which
1631 particular call to ``head`` in your program resulted in the error can be
1632 a painstaking process, usually involving ``Debug.Trace.trace``, or
1633 compiling with profiling and using ``Debug.Trace.traceStack`` or
1634 ``+RTS -xc`` (see :ref:`prof-time-options`).
1635
1636 The GHCi debugger offers a way to hopefully shed some light on these
1637 errors quickly and without modifying or recompiling the source code. One
1638 way would be to set a breakpoint on the location in the source code that
1639 throws the exception, and then use ``:trace`` and ``:history`` to
1640 establish the context. However, ``head`` is in a library and we can't
1641 set a breakpoint on it directly. For this reason, GHCi provides the
1642 flags ``-fbreak-on-exception`` which causes the evaluator to stop when
1643 an exception is thrown, and ``-fbreak-on-error``, which works similarly
1644 but stops only on uncaught exceptions. When stopping at an exception,
1645 GHCi will act just as it does when a breakpoint is hit, with the
1646 deviation that it will not show you any source code location. Due to
1647 this, these commands are only really useful in conjunction with
1648 ``:trace``, in order to log the steps leading up to the exception. For
1649 example:
1650
1651 ::
1652
1653     *Main> :set -fbreak-on-exception
1654     *Main> :trace qsort ("abc" ++ undefined)
1655     “Stopped at <exception thrown>
1656     _exception :: e
1657     [<exception thrown>] *Main> :hist
1658     -1  : qsort.hs:3:24-38
1659     -2  : qsort.hs:3:23-55
1660     -3  : qsort.hs:(1,0)-(3,55)
1661     -4  : qsort.hs:2:15-24
1662     -5  : qsort.hs:2:15-46
1663     -6  : qsort.hs:(1,0)-(3,55)
1664     <end of history>
1665     [<exception thrown>] *Main> :back
1666     Logged breakpoint at qsort.hs:3:24-38
1667     _result :: [a]
1668     as :: [a]
1669     a :: a
1670     [-1: qsort.hs:3:24-38] *Main> :force as
1671     *** Exception: Prelude.undefined
1672     [-1: qsort.hs:3:24-38] *Main> :print as
1673     as = 'b' : 'c' : (_t1::[Char])
1674
1675 The exception itself is bound to a new variable, ``_exception``.
1676
1677 Breaking on exceptions is particularly useful for finding out what your
1678 program was doing when it was in an infinite loop. Just hit Control-C,
1679 and examine the history to find out what was going on.
1680
1681 Example: inspecting functions
1682 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1683
1684 It is possible to use the debugger to examine function values. When we
1685 are at a breakpoint and a function is in scope, the debugger cannot show
1686 you the source code for it; however, it is possible to get some
1687 information by applying it to some arguments and observing the result.
1688
1689 The process is slightly complicated when the binding is polymorphic. We
1690 show the process by means of an example. To keep things simple, we will
1691 use the well known ``map`` function:
1692
1693 ::
1694
1695     import Prelude hiding (map)
1696
1697     map :: (a->b) -> [a] -> [b]
1698     map f [] = []
1699     map f (x:xs) = f x : map f xs
1700
1701 We set a breakpoint on ``map``, and call it.
1702
1703 ::
1704
1705     *Main> :break 5
1706     Breakpoint 0 activated at  map.hs:5:15-28
1707     *Main> map Just [1..5]
1708     Stopped at map.hs:(4,0)-(5,12)
1709     _result :: [b]
1710     x :: a
1711     f :: a -> b
1712     xs :: [a]
1713
1714 GHCi tells us that, among other bindings, ``f`` is in scope. However,
1715 its type is not fully known yet, and thus it is not possible to apply it
1716 to any arguments. Nevertheless, observe that the type of its first
1717 argument is the same as the type of ``x``, and its result type is shared
1718 with ``_result``.
1719
1720 As we demonstrated earlier (:ref:`breakpoints`), the debugger has some
1721 intelligence built-in to update the type of ``f`` whenever the types of
1722 ``x`` or ``_result`` are discovered. So what we do in this scenario is
1723 force ``x`` a bit, in order to recover both its type and the argument
1724 part of ``f``.
1725
1726 ::
1727
1728     *Main> seq x ()
1729     *Main> :print x
1730     x = 1
1731
1732 We can check now that as expected, the type of ``x`` has been
1733 reconstructed, and with it the type of ``f`` has been too:
1734
1735 ::
1736
1737     *Main> :t x
1738     x :: Integer
1739     *Main> :t f
1740     f :: Integer -> b
1741
1742 From here, we can apply f to any argument of type Integer and observe
1743 the results.
1744
1745 ::
1746
1747     *Main> let b = f 10
1748     *Main> :t b
1749     b :: b
1750     *Main> b
1751     <interactive>:1:0:
1752         Ambiguous type variable `b' in the constraint:
1753           `Show b' arising from a use of `print' at <interactive>:1:0
1754     *Main> :p b
1755     b = (_t2::a)
1756     *Main> seq b ()
1757     ()
1758     *Main> :t b
1759     b :: a
1760     *Main> :p b
1761     b = Just 10
1762     *Main> :t b
1763     b :: Maybe Integer
1764     *Main> :t f
1765     f :: Integer -> Maybe Integer
1766     *Main> f 20
1767     Just 20
1768     *Main> map f [1..5]
1769     [Just 1, Just 2, Just 3, Just 4, Just 5]
1770
1771 In the first application of ``f``, we had to do some more type
1772 reconstruction in order to recover the result type of ``f``. But after
1773 that, we are free to use ``f`` normally.
1774
1775 Limitations
1776 ~~~~~~~~~~~
1777
1778 -  When stopped at a breakpoint, if you try to evaluate a variable that
1779    is already under evaluation, the second evaluation will hang. The
1780    reason is that GHC knows the variable is under evaluation, so the new
1781    evaluation just waits for the result before continuing, but of course
1782    this isn't going to happen because the first evaluation is stopped at
1783    a breakpoint. Control-C can interrupt the hung evaluation and return
1784    to the prompt.
1785
1786    The most common way this can happen is when you're evaluating a CAF
1787    (e.g. main), stop at a breakpoint, and ask for the value of the CAF
1788    at the prompt again.
1789
1790 -  Implicit parameters (see :ref:`implicit-parameters`) are only
1791    available at the scope of a breakpoint if there is an explicit type
1792    signature.
1793
1794 .. _ghci-invocation:
1795
1796 Invoking GHCi
1797 -------------
1798
1799 .. index::
1800    single: invoking; GHCi
1801    single: --interactive
1802
1803 GHCi is invoked with the command ``ghci`` or ``ghc --interactive``. One
1804 or more modules or filenames can also be specified on the command line;
1805 this instructs GHCi to load the specified modules or filenames (and all
1806 the modules they depend on), just as if you had said ``:load modules``
1807 at the GHCi prompt (see :ref:`ghci-commands`). For example, to start
1808 GHCi and load the program whose topmost module is in the file
1809 ``Main.hs``, we could say:
1810
1811 ::
1812
1813     $ ghci Main.hs
1814
1815 Most of the command-line options accepted by GHC (see :ref:`using-ghc`)
1816 also make sense in interactive mode. The ones that don't make sense are
1817 mostly obvious.
1818
1819 Packages
1820 ~~~~~~~~
1821
1822 .. index::
1823    single: packages; with GHCi
1824
1825 Most packages (see :ref:`using-packages`) are available without needing
1826 to specify any extra flags at all: they will be automatically loaded the
1827 first time they are needed.
1828
1829 For hidden packages, however, you need to request the package be loaded
1830 by using the ``-package`` flag:
1831
1832 ::
1833
1834     $ ghci -package readline
1835     GHCi, version 6.8.1: http://www.haskell.org/ghc/  :? for help
1836     Loading package base ... linking ... done.
1837     Loading package readline-1.0 ... linking ... done.
1838     Prelude>
1839
1840 The following command works to load new packages into a running GHCi:
1841
1842 ::
1843
1844     Prelude> :set -package name
1845
1846 But note that doing this will cause all currently loaded modules to be
1847 unloaded, and you'll be dumped back into the ``Prelude``.
1848
1849 Extra libraries
1850 ~~~~~~~~~~~~~~~
1851
1852 .. index::
1853    single: libraries; with GHCi
1854
1855 Extra libraries may be specified on the command line using the normal
1856 ``-llib`` option. (The term *library* here refers to libraries of
1857 foreign object code; for using libraries of Haskell source code, see
1858 :ref:`ghci-modules-filenames`.) For example, to load the “m” library:
1859
1860 ::
1861
1862     $ ghci -lm
1863
1864 On systems with ``.so``-style shared libraries, the actual library
1865 loaded will the ``liblib.so``. GHCi searches the following places for
1866 libraries, in this order:
1867
1868 -  Paths specified using the ``-Lpath`` command-line option,
1869
1870 -  the standard library search path for your system, which on some
1871    systems may be overridden by setting the ``LD_LIBRARY_PATH``
1872    environment variable.
1873
1874 On systems with ``.dll``-style shared libraries, the actual library
1875 loaded will be ``lib.dll``. Again, GHCi will signal an error if it can't
1876 find the library.
1877
1878 GHCi can also load plain object files (``.o`` or ``.obj`` depending on
1879 your platform) from the command-line. Just add the name the object file
1880 to the command line.
1881
1882 Ordering of ``-l`` options matters: a library should be mentioned
1883 *before* the libraries it depends on (see :ref:`options-linker`).
1884
1885 .. _ghci-commands:
1886
1887 GHCi commands
1888 -------------
1889
1890 GHCi commands all begin with "``:``" and consist of a single command
1891 name followed by zero or more parameters. The command name may be
1892 abbreviated, with ambiguities being resolved in favour of the more
1893 commonly used commands.
1894
1895 ``:abandon``
1896     .. index::
1897        single: :abandon
1898
1899     Abandons the current evaluation (only available when stopped at a
1900     breakpoint).
1901
1902 ``:add[*] ⟨module⟩``
1903     .. index::
1904        single: :add
1905
1906     Add ⟨module⟩(s) to the current target set, and perform a reload.
1907     Normally pre-compiled code for the module will be loaded if
1908     available, or otherwise the module will be compiled to byte-code.
1909     Using the ``*`` prefix forces the module to be loaded as byte-code.
1910
1911 ``:back ⟨n⟩``
1912     .. index::
1913        single: :back
1914
1915     Travel back ⟨n⟩ steps in the history. ⟨n⟩ is one if omitted. See
1916     :ref:`tracing` for more about GHCi's debugging facilities. See also:
1917     ``:trace``, ``:history``, ``:forward``.
1918
1919 ``:break [⟨identifier⟩ | [⟨module⟩] ⟨line⟩ [⟨column⟩]]``
1920     .. index::
1921        single: :break
1922
1923     Set a breakpoint on the specified function or line and column. See
1924     :ref:`setting-breakpoints`.
1925
1926 ``:browse[!] [[*] ⟨module⟩]``
1927     .. index::
1928        single: :browse
1929
1930     Displays the identifiers exported by the module ⟨module⟩, which must
1931     be either loaded into GHCi or be a member of a package. If ⟨module⟩
1932     is omitted, the most recently-loaded module is used.
1933
1934     Like all other GHCi commands, the output is always displayed in the
1935     current GHCi scope (:ref:`ghci-scope`).
1936
1937     There are two variants of the browse command:
1938
1939     -  If the ``*`` symbol is placed before the module name, then *all*
1940        the identifiers in scope in ⟨module⟩ (rather that just its
1941        exports) are shown.
1942
1943        The ``*``-form is only available for modules which are
1944        interpreted; for compiled modules (including modules from
1945        packages) only the non-\ ``*`` form of ``:browse`` is available.
1946
1947     -  Data constructors and class methods are usually displayed in the
1948        context of their data type or class declaration. However, if the
1949        ``!`` symbol is appended to the command, thus ``:browse!``, they
1950        are listed individually. The ``!``-form also annotates the
1951        listing with comments giving possible imports for each group of
1952        entries. Here is an example:
1953
1954        ::
1955
1956            Prelude> :browse! Data.Maybe
1957            -- not currently imported
1958            Data.Maybe.catMaybes :: [Maybe a] -> [a]
1959            Data.Maybe.fromJust :: Maybe a -> a
1960            Data.Maybe.fromMaybe :: a -> Maybe a -> a
1961            Data.Maybe.isJust :: Maybe a -> Bool
1962            Data.Maybe.isNothing :: Maybe a -> Bool
1963            Data.Maybe.listToMaybe :: [a] -> Maybe a
1964            Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
1965            Data.Maybe.maybeToList :: Maybe a -> [a]
1966            -- imported via Prelude
1967            Just :: a -> Maybe a
1968            data Maybe a = Nothing | Just a
1969            Nothing :: Maybe a
1970            maybe :: b -> (a -> b) -> Maybe a -> b
1971
1972        This output shows that, in the context of the current session (ie
1973        in the scope of ``Prelude``), the first group of items from
1974        ``Data.Maybe`` are not in scope (althought they are available in
1975        fully qualified form in the GHCi session - see
1976        :ref:`ghci-scope`), whereas the second group of items are in
1977        scope (via ``Prelude``) and are therefore available either
1978        unqualified, or with a ``Prelude.`` qualifier.
1979
1980 ``:cd ⟨dir⟩``
1981     .. index::
1982        single: :cd
1983
1984     Changes the current working directory to ⟨dir⟩. A "``~``" symbol
1985     at the beginning of ⟨dir⟩ will be replaced by the contents of the
1986     environment variable ``HOME``. See also the ``:show paths`` command
1987     for showing the current working directory.
1988
1989     Note: changing directories causes all currently loaded modules to be
1990     unloaded. This is because the search path is usually expressed using
1991     relative directories, and changing the search path in the middle of
1992     a session is not supported.
1993
1994 ``:cmd ⟨expr⟩``
1995     .. index::
1996        single: :cmd
1997
1998     Executes ⟨expr⟩ as a computation of type ``IO String``, and then
1999     executes the resulting string as a list of GHCi commands. Multiple
2000     commands are separated by newlines. The ``:cmd`` command is useful
2001     with ``:def`` and ``:set stop``.
2002
2003 ``:complete ⟨type⟩ [⟨n⟩-][⟨m⟩] ⟨string-literal⟩``
2004     .. index::
2005        single: :complete
2006
2007     This command allows to request command completions from GHCi even
2008     when interacting over a pipe instead of a proper terminal and is
2009     designed for integrating GHCi's completion with text editors and
2010     IDEs.
2011
2012     When called, ``:complete`` prints the ⟨n⟩\ :sup:`th` to
2013     ⟨m⟩\ :sup:`th` completion candidates for the partial input
2014     ⟨string-literal⟩ for the completion domain denoted by ⟨type⟩.
2015     Currently, only the ``repl`` domain is supported which denotes the
2016     kind of completion that would be provided interactively by GHCi at
2017     the input prompt.
2018
2019     If omitted, ⟨n⟩ and ⟨m⟩ default to the first or last available
2020     completion candidate respectively. If there are less candidates than
2021     requested via the range argument, ⟨n⟩ and ⟨m⟩ are implicitly capped
2022     to the number of available completition candidates.
2023
2024     The output of ``:complete`` begins with a header line containing
2025     three space-delimited fields:
2026
2027     -  An integer denoting the number ``l`` of printed completions,
2028     -  an integer denoting the total number of completions available,
2029        and finally
2030     -  a string literal denoting a common prefix to be added to the
2031        returned completion candidates.
2032
2033     The header line is followed by ⟨l⟩ lines each containing one
2034     completion candidate encoded as (quoted) string literal. Here are
2035     some example invocations showing the various cases:
2036
2037     ::
2038
2039         Prelude> :complete repl 0 ""
2040         0 470 ""
2041         Prelude> :complete repl 5 "import For"
2042         5 21 "import "
2043         "Foreign"
2044         "Foreign.C"
2045         "Foreign.C.Error"
2046         "Foreign.C.String"
2047         "Foreign.C.Types"
2048         Prelude> :complete repl 5-10 "import For"
2049         6 21 "import "
2050         "Foreign.C.Types"
2051         "Foreign.Concurrent"
2052         "Foreign.ForeignPtr"
2053         "Foreign.ForeignPtr.Safe"
2054         "Foreign.ForeignPtr.Unsafe"
2055         "Foreign.Marshal"
2056         Prelude> :complete repl 20- "import For"
2057         2 21 "import "
2058         "Foreign.StablePtr"
2059         "Foreign.Storable"
2060         Prelude> :complete repl "map"
2061         3 3 ""
2062         "map"
2063         "mapM"
2064         "mapM_"
2065         Prelude> :complete repl 5-10 "map"
2066         0 3 ""
2067
2068 ``:continue``
2069     .. index::
2070        single: :continue
2071
2072     Continue the current evaluation, when stopped at a breakpoint.
2073
2074 ``:ctags [⟨filename⟩]``, ``:etags [⟨filename⟩]``
2075     .. index::
2076        single: :ctags
2077        single: :etags
2078
2079     Generates a “tags” file for Vi-style editors (``:ctags``) or
2080     Emacs-style editors (``:etags``). If no filename is specified, the
2081     default ``tags`` or ``TAGS`` is used, respectively. Tags for all the
2082     functions, constructors and types in the currently loaded modules
2083     are created. All modules must be interpreted for these commands to
2084     work.
2085
2086 ``:def! ⟨name⟩ ⟨expr⟩``
2087     .. index::
2088        single: :def
2089
2090     ``:def`` is used to define new commands, or macros, in GHCi. The
2091     command ``:def`` ⟨name⟩ ⟨expr⟩ defines a new GHCi command ``:name``,
2092     implemented by the Haskell expression ⟨expr⟩, which must have type
2093     ``String -> IO String``. When ``:name args`` is typed at the prompt,
2094     GHCi will run the expression ``(name args)``, take the resulting
2095     ``String``, and feed it back into GHCi as a new sequence of
2096     commands. Separate commands in the result must be separated by
2097     "``\n``".
2098
2099     That's all a little confusing, so here's a few examples. To start
2100     with, here's a new GHCi command which doesn't take any arguments or
2101     produce any results, it just outputs the current date & time:
2102
2103     ::
2104
2105         Prelude> let date _ = Time.getClockTime >>= print >> return ""
2106         Prelude> :def date date
2107         Prelude> :date
2108         Fri Mar 23 15:16:40 GMT 2001
2109
2110     Here's an example of a command that takes an argument. It's a
2111     re-implementation of ``:cd``:
2112
2113     ::
2114
2115         Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
2116         Prelude> :def mycd mycd
2117         Prelude> :mycd ..
2118
2119     Or I could define a simple way to invoke "``ghc --make Main``"
2120     in the current directory:
2121
2122     ::
2123
2124         Prelude> :def make (\_ -> return ":! ghc --make Main")
2125
2126     We can define a command that reads GHCi input from a file. This
2127     might be useful for creating a set of bindings that we want to
2128     repeatedly load into the GHCi session:
2129
2130     ::
2131
2132         Prelude> :def . readFile
2133         Prelude> :. cmds.ghci
2134
2135     Notice that we named the command ``:.``, by analogy with the
2136     "``.``" Unix shell command that does the same thing.
2137
2138     Typing ``:def`` on its own lists the currently-defined macros.
2139     Attempting to redefine an existing command name results in an error
2140     unless the ``:def!`` form is used, in which case the old command
2141     with that name is silently overwritten.
2142
2143 ``:delete * | ⟨num⟩ ...``
2144     .. index::
2145        single: :delete
2146
2147     Delete one or more breakpoints by number (use ``:show breaks`` to
2148     see the number of each breakpoint). The ``*`` form deletes all the
2149     breakpoints.
2150
2151 ``:edit ⟨file⟩``
2152     .. index::
2153        single: :edit
2154
2155     Opens an editor to edit the file ⟨file⟩, or the most recently loaded
2156     module if ⟨file⟩ is omitted. If there were errors during the last
2157     loading, the cursor will be positioned at the line of the first
2158     error. The editor to invoke is taken from the ``EDITOR`` environment
2159     variable, or a default editor on your system if ``EDITOR`` is not
2160     set. You can change the editor using ``:set editor``.
2161
2162 ``:etags``
2163     See ``:ctags``.
2164
2165 ``:force ⟨identifier⟩ ...``
2166     .. index::
2167        single: :force
2168
2169     Prints the value of ⟨identifier⟩ in the same way as ``:print``.
2170     Unlike ``:print``, ``:force`` evaluates each thunk that it
2171     encounters while traversing the value. This may cause exceptions or
2172     infinite loops, or further breakpoints (which are ignored, but
2173     displayed).
2174
2175 ``:forward ⟨n⟩``
2176     .. index::
2177        single: :forward
2178
2179     Move forward ⟨n⟩ steps in the history. ⟨n⟩ is one if omitted. See
2180     :ref:`tracing` for more about GHCi's debugging facilities. See also:
2181     ``:trace``, ``:history``, ``:back``.
2182
2183 ``:help``, ``:?``
2184     .. index::
2185        single: :help
2186        single: :?
2187
2188     Displays a list of the available commands.
2189
2190 ``:``
2191     .. index::
2192        single: :
2193
2194     Repeat the previous command.
2195
2196 ``:history [num]``
2197     .. index::
2198        single: :history
2199
2200     Display the history of evaluation steps. With a number, displays
2201     that many steps (default: 20). For use with ``:trace``; see
2202     :ref:`tracing`. To set the number of history entries stored by GHCi,
2203     use ``-fghci-hist-size=n``.
2204
2205 ``:info[!] ⟨name⟩``
2206     .. index::
2207        single: :info
2208
2209     Displays information about the given name(s). For example, if ⟨name⟩
2210     is a class, then the class methods and their types will be printed;
2211     if ⟨name⟩ is a type constructor, then its definition will be
2212     printed; if ⟨name⟩ is a function, then its type will be printed. If
2213     ⟨name⟩ has been loaded from a source file, then GHCi will also
2214     display the location of its definition in the source.
2215
2216     For types and classes, GHCi also summarises instances that mention
2217     them. To avoid showing irrelevant information, an instance is shown
2218     only if (a) its head mentions ⟨name⟩, and (b) all the other things
2219     mentioned in the instance are in scope (either qualified or
2220     otherwise) as a result of a ``:load`` or ``:module`` commands.
2221
2222     The command ``:info!`` works in a similar fashion but it removes
2223     restriction (b), showing all instances that are in scope and mention
2224     ⟨name⟩ in their head.
2225
2226 ``:issafe [⟨module⟩]``
2227     .. index::
2228        single: :issafe
2229
2230     Displays Safe Haskell information about the given module (or the
2231     current module if omitted). This includes the trust type of the
2232     module and its containing package.
2233
2234 ``:kind[!] ⟨type⟩``
2235     .. index::
2236        single: :kind
2237
2238     Infers and prints the kind of ⟨type⟩. The latter can be an arbitrary
2239     type expression, including a partial application of a type
2240     constructor, such as ``Either Int``. In fact, ``:kind`` even allows
2241     you to write a partial application of a type synonym (usually
2242     disallowed), so that this works:
2243
2244     ::
2245
2246         ghci> type T a b = (a,b,a)
2247         ghci> :k T Int Bool
2248         T Int Bool :: *
2249         ghci> :k T
2250         T :: * -> * -> *
2251         ghci> :k T Int
2252         T Int :: * -> *
2253
2254     If you specify the optional "``!``", GHC will in addition normalise
2255     the type by expanding out type synonyms and evaluating type-function
2256     applications, and display the normalised result.
2257
2258 ``:list ⟨identifier⟩``
2259     .. index::
2260        single: :list
2261
2262     Lists the source code around the definition of ⟨identifier⟩ or the
2263     current breakpoint if not given. This requires that the identifier
2264     be defined in an interpreted module. If your output device supports
2265     it, then GHCi will highlight the active subexpression in bold.
2266
2267 ``:list [⟨module⟩] ⟨line⟩``
2268     .. index::
2269        single: :list
2270
2271     Lists the source code around the given line number of ⟨module⟩. This
2272     requires that the module be interpreted. If your output device
2273     supports it, then GHCi will highlight the active subexpression in
2274     bold.
2275
2276 ``:load[!] [*]⟨module⟩``
2277     .. index::
2278        single: :load
2279
2280     Recursively loads the specified ⟨module⟩s, and all the modules they
2281     depend on. Here, each ⟨module⟩ must be a module name or filename,
2282     but may not be the name of a module in a package.
2283
2284     All previously loaded modules, except package modules, are
2285     forgotten. The new set of modules is known as the target set. Note
2286     that ``:load`` can be used without any arguments to unload all the
2287     currently loaded modules and bindings.
2288
2289     Normally pre-compiled code for a module will be loaded if available,
2290     or otherwise the module will be compiled to byte-code. Using the
2291     ``*`` prefix forces a module to be loaded as byte-code.
2292
2293     Adding the optional "``!``" turns type errors into warnings while
2294     loading. This allows to use the portions of the module that are
2295     correct, even if there are type errors in some definitions.
2296     Effectively, the "-fdefer-type-errors" flag is set before loading
2297     and unset after loading if the flag has not already been set before.
2298     See :ref:`defer-type-errors` for further motivation and details.
2299
2300     After a ``:load`` command, the current context is set to:
2301
2302     -  ⟨module⟩, if it was loaded successfully, or
2303
2304     -  the most recently successfully loaded module, if any other
2305        modules were loaded as a result of the current ``:load``, or
2306
2307     -  ``Prelude`` otherwise.
2308
2309 ``:main ⟨arg1⟩ ... ⟨argn⟩``
2310     .. index::
2311        single: :main
2312
2313     When a program is compiled and executed, it can use the ``getArgs``
2314     function to access the command-line arguments. However, we cannot
2315     simply pass the arguments to the ``main`` function while we are
2316     testing in ghci, as the ``main`` function doesn't take its arguments
2317     directly.
2318
2319     Instead, we can use the ``:main`` command. This runs whatever
2320     ``main`` is in scope, with any arguments being treated the same as
2321     command-line arguments, e.g.:
2322
2323     ::
2324
2325         Prelude> let main = System.Environment.getArgs >>= print
2326         Prelude> :main foo bar
2327         ["foo","bar"]
2328
2329     We can also quote arguments which contains characters like spaces,
2330     and they are treated like Haskell strings, or we can just use
2331     Haskell list syntax:
2332
2333     ::
2334
2335         Prelude> :main foo "bar baz"
2336         ["foo","bar baz"]
2337         Prelude> :main ["foo", "bar baz"]
2338         ["foo","bar baz"]
2339
2340     Finally, other functions can be called, either with the ``-main-is``
2341     flag or the ``:run`` command:
2342
2343     ::
2344
2345         Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
2346         Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
2347         Prelude> :set -main-is foo
2348         Prelude> :main foo "bar baz"
2349         foo
2350         ["foo","bar baz"]
2351         Prelude> :run bar ["foo", "bar baz"]
2352         bar
2353         ["foo","bar baz"]
2354
2355 ``:module +|- [*]⟨mod1⟩ ...``, ``import mod``
2356     .. index::
2357        single: :module
2358
2359     Sets or modifies the current context for statements typed at the
2360     prompt. The form ``import mod`` is equivalent to ``:module +mod``.
2361     See :ref:`ghci-scope` for more details.
2362
2363 ``:print ⟨names⟩``
2364     .. index::
2365        single: :print
2366
2367     Prints a value without forcing its evaluation. ``:print`` may be
2368     used on values whose types are unknown or partially known, which
2369     might be the case for local variables with polymorphic types at a
2370     breakpoint. While inspecting the runtime value, ``:print`` attempts
2371     to reconstruct the type of the value, and will elaborate the type in
2372     GHCi's environment if possible. If any unevaluated components
2373     (thunks) are encountered, then ``:print`` binds a fresh variable
2374     with a name beginning with ``_t`` to each thunk. See
2375     :ref:`breakpoints` for more information. See also the ``:sprint``
2376     command, which works like ``:print`` but does not bind new
2377     variables.
2378
2379 ``:quit``
2380     .. index::
2381        single: :quit
2382
2383     Quits GHCi. You can also quit by typing control-D at the prompt.
2384
2385 ``:reload[!]``
2386     .. index::
2387        single: :reload
2388
2389     Attempts to reload the current target set (see ``:load``) if any of
2390     the modules in the set, or any dependent module, has changed. Note
2391     that this may entail loading new modules, or dropping modules which
2392     are no longer indirectly required by the target.
2393
2394     Adding the optional "``!``" turns type errors into warnings while
2395     loading. This allows to use the portions of the module that are
2396     correct, even if there are type errors in some definitions.
2397     Effectively, the "-fdefer-type-errors" flag is set before loading
2398     and unset after loading if the flag has not already been set before.
2399     See :ref:`defer-type-errors` for further motivation and details.
2400
2401 ``:run``
2402     .. index::
2403        single: :run
2404
2405     See ``:main``.
2406
2407 ``:script [⟨n⟩] ⟨filename⟩``
2408     .. index::
2409        single: :script
2410
2411     Executes the lines of a file as a series of GHCi commands. This
2412     command is compatible with multiline statements as set by
2413     ``:set +m``
2414
2415 ``:set [⟨option⟩ ...]``
2416     .. index::
2417        single: :set
2418
2419     Sets various options. See :ref:`ghci-set` for a list of available
2420     options and :ref:`interactive-mode-options` for a list of
2421     GHCi-specific flags. The ``:set`` command by itself shows which
2422     options are currently set. It also lists the current dynamic flag
2423     settings, with GHCi-specific flags listed separately.
2424
2425 ``:set args ⟨arg⟩``
2426     .. index::
2427        single: :set args
2428        single: getArgs, behavior in GHCi
2429
2430     Sets the list of arguments which are returned when the program calls
2431     ``System.getArgs``.
2432
2433 ``:set editor ⟨cmd⟩``
2434     Sets the command used by ``:edit`` to ⟨cmd⟩.
2435
2436 ``:set prog ⟨prog⟩``
2437     .. index::
2438        single: :set prog
2439        single: getProgName, behavior in GHCi
2440
2441     Sets the string to be returned when the program calls
2442     ``System.getProgName``.
2443
2444 ``:set prompt ⟨prompt⟩``
2445     .. index::
2446        single: GHCi prompt; setting
2447
2448     Sets the string to be used as the prompt in GHCi. Inside ⟨prompt⟩,
2449     the sequence ``%s`` is replaced by the names of the modules
2450     currently in scope, ``%l`` is replaced by the line number (as
2451     referenced in compiler messages) of the current prompt, and ``%%``
2452     is replaced by ``%``. If ⟨prompt⟩ starts with ``"`` then it is parsed as
2453     a Haskell String; otherwise it is treated as a literal string.
2454
2455 ``:set prompt2 ⟨prompt⟩``
2456     Sets the string to be used as the continuation prompt (used when
2457     using the ``:{`` command) in GHCi.
2458
2459 ``:set stop ⟨num⟩ ⟨cmd⟩``
2460     Set a command to be executed when a breakpoint is hit, or a new item
2461     in the history is selected. The most common use of ``:set stop`` is
2462     to display the source code at the current location, e.g.
2463     ``:set stop :list``.
2464
2465     If a number is given before the command, then the commands are run
2466     when the specified breakpoint (only) is hit. This can be quite
2467     useful: for example, ``:set stop 1 :continue`` effectively disables
2468     breakpoint 1, by running ``:continue`` whenever it is hit (although
2469     GHCi will still emit a message to say the breakpoint was hit).
2470     What's more, with cunning use of ``:def`` and ``:cmd`` you can use
2471     ``:set stop`` to implement conditional breakpoints:
2472
2473     ::
2474
2475         *Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
2476         *Main> :set stop 0 :cond (x < 3)
2477
2478     Ignoring breakpoints for a specified number of iterations is also
2479     possible using similar techniques.
2480
2481 ``:seti [⟨option⟩ ...]``
2482     .. index::
2483        single: :seti
2484
2485     Like ``:set``, but options set with ``:seti`` affect only
2486     expressions and commands typed at the prompt, and not modules loaded
2487     with ``:load`` (in contrast, options set with ``:set`` apply
2488     everywhere). See :ref:`ghci-interactive-options`.
2489
2490     Without any arguments, displays the current set of options that are
2491     applied to expressions and commands typed at the prompt.
2492
2493 ``:show bindings``
2494     .. index::
2495        single: :show bindings
2496
2497     Show the bindings made at the prompt and their types.
2498
2499 ``:show breaks``
2500     .. index::
2501        single: :show breaks
2502
2503     List the active breakpoints.
2504
2505 ``:show context``
2506     .. index::
2507        single: :show context
2508
2509     List the active evaluations that are stopped at breakpoints.
2510
2511 ``:show imports``
2512     .. index::
2513        single: :show imports
2514
2515     Show the imports that are currently in force, as created by
2516     ``import`` and ``:module`` commands.
2517
2518 ``:show modules``
2519     .. index::
2520        single: :show modules
2521
2522     Show the list of modules currently loaded.
2523
2524 ``:show packages``
2525     .. index::
2526        single: :show packages
2527
2528     Show the currently active package flags, as well as the list of
2529     packages currently loaded.
2530
2531 ``:show paths``
2532     .. index::
2533        single: :show paths
2534
2535     Show the current working directory (as set via ``:cd`` command), as
2536     well as the list of directories searched for source files (as set by
2537     the ``-i`` option).
2538
2539 ``:show language``
2540     .. index::
2541        single: :show language
2542
2543     Show the currently active language flags for source files.
2544
2545 ``:showi language``
2546     .. index::
2547        single: :showi language
2548
2549     Show the currently active language flags for expressions typed at
2550     the prompt (see also ``:seti``).
2551
2552 ``:show [args|prog|prompt|editor|stop]``
2553     .. index::
2554        single: :show
2555
2556     Displays the specified setting (see ``:set``).
2557
2558 ``:sprint``
2559     .. index::
2560        single: :sprint
2561
2562     Prints a value without forcing its evaluation. ``:sprint`` is
2563     similar to ``:print``, with the difference that unevaluated subterms
2564     are not bound to new variables, they are simply denoted by ‘\_’.
2565
2566 ``:step [⟨expr⟩]``
2567     .. index::
2568        single: :step
2569
2570     Enable all breakpoints and begin evaluating an expression in
2571     single-stepping mode. In this mode evaluation will be stopped after
2572     every reduction, allowing local variables to be inspected. If ⟨expr⟩
2573     is not given, evaluation will resume at the last breakpoint. See
2574     :ref:`single-stepping`.
2575
2576 ``:steplocal``
2577     .. index::
2578        single: :steplocal
2579
2580     Enable only breakpoints in the current top-level binding and resume
2581     evaluation at the last breakpoint.
2582
2583 ``:stepmodule``
2584     .. index::
2585        single: :stepmodule
2586
2587     Enable only breakpoints in the current module and resume evaluation
2588     at the last breakpoint.
2589
2590 ``:trace expr``
2591     .. index::
2592        single: :trace
2593
2594     Evaluates the given expression (or from the last breakpoint if no
2595     expression is given), and additionally logs the evaluation steps for
2596     later inspection using ``:history``. See :ref:`tracing`.
2597
2598 ``:type ⟨expression⟩``
2599     .. index::
2600        single: :type
2601
2602     Infers and prints the type of ⟨expression⟩, including explicit
2603     forall quantifiers for polymorphic types. The monomorphism
2604     restriction is *not* applied to the expression during type
2605     inference.
2606
2607 ``:undef ⟨name⟩``
2608     .. index::
2609        single: :undef
2610
2611     Undefines the user-defined command ⟨name⟩ (see ``:def`` above).
2612
2613 ``:unset ⟨option⟩``
2614     .. index::
2615        single: :unset
2616
2617     Unsets certain options. See :ref:`ghci-set` for a list of available
2618     options.
2619
2620 ``:! ⟨command⟩``
2621     .. index::
2622        single: :!
2623        single: shell commands; in GHCi
2624
2625     Executes the shell command ⟨command⟩.
2626
2627
2628 .. _ghci-set:
2629
2630 The ``:set`` and ``:seti`` commands
2631 -----------------------------------
2632
2633 .. index::
2634    single: :set
2635    single: :seti
2636
2637 The ``:set`` command sets two types of options: GHCi options, which
2638 begin with "``+``", and "command-line" options, which begin with
2639 "``-``".
2640
2641 .. note::
2642     At the moment, the ``:set`` command doesn't support any kind of
2643     quoting in its arguments: quotes will not be removed and cannot be used
2644     to group words together. For example, ``:set -DFOO='BAR BAZ'`` will not
2645     do what you expect.
2646
2647 GHCi options
2648 ~~~~~~~~~~~~
2649
2650 .. index::
2651    single: options; GHCi
2652
2653 GHCi options may be set using ``:set`` and unset using ``:unset``.
2654
2655 The available GHCi options are:
2656
2657 ``+m``
2658     .. index::
2659        single: +m
2660
2661     Enable parsing of multiline commands. A multiline command is
2662     prompted for when the current input line contains open layout
2663     contexts (see :ref:`ghci-multiline`).
2664
2665 ``+r``
2666     .. index::
2667        single: +r
2668        single: CAFs; in GHCi
2669        single: Constant Applicative Form
2670
2671     Normally, any evaluation of top-level expressions (otherwise known
2672     as CAFs or Constant Applicative Forms) in loaded modules is retained
2673     between evaluations. Turning on ``+r`` causes all evaluation of
2674     top-level expressions to be discarded after each evaluation (they
2675     are still retained *during* a single evaluation).
2676
2677     This option may help if the evaluated top-level expressions are
2678     consuming large amounts of space, or if you need repeatable
2679     performance measurements.
2680
2681 ``+s``
2682     .. index::
2683        single: +s
2684
2685     Display some stats after evaluating each expression, including the
2686     elapsed time and number of bytes allocated. NOTE: the allocation
2687     figure is only accurate to the size of the storage manager's
2688     allocation area, because it is calculated at every GC. Hence, you
2689     might see values of zero if no GC has occurred.
2690
2691 ``+t``
2692     .. index::
2693        single: +t
2694
2695     Display the type of each variable bound after a statement is entered
2696     at the prompt. If the statement is a single expression, then the
2697     only variable binding will be for the variable ‘\ ``it``\ ’.
2698
2699 .. _ghci-cmd-line-options:
2700
2701 Setting GHC command-line options in GHCi
2702 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2703
2704 Normal GHC command-line options may also be set using ``:set``. For
2705 example, to turn on ``-fwarn-missing-signatures``, you would say:
2706
2707 ::
2708
2709     Prelude> :set -fwarn-missing-signatures
2710
2711 Any GHC command-line option that is designated as dynamic (see the table
2712 in :ref:`flag-reference`), may be set using ``:set``. To unset an
2713 option, you can set the reverse option:
2714
2715 .. index::
2716    single: dynamic; options
2717
2718 ::
2719
2720     Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses
2721
2722 :ref:`flag-reference` lists the reverse for each option where
2723 applicable.
2724
2725 Certain static options (``-package``, ``-I``, ``-i``, and ``-l`` in
2726 particular) will also work, but some may not take effect until the next
2727 reload.
2728
2729 .. index::
2730    single: static; options
2731
2732 .. _ghci-interactive-options:
2733
2734 Setting options for interactive evaluation only
2735 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2736
2737 GHCi actually maintains *two* sets of options:
2738
2739 -  The *loading options* apply when loading modules
2740
2741 -  The *interactive options* apply when evaluating expressions and
2742    commands typed at the GHCi prompt.
2743
2744 The ``:set`` command modifies both, but there is also a ``:seti``
2745 command (for "set interactive") that affects only the interactive
2746 options set.
2747
2748 It is often useful to change the interactive options, without having
2749 that option apply to loaded modules too. For example
2750
2751 ::
2752
2753     :seti -XMonoLocalBinds
2754
2755 It would be undesirable if ``-XMonoLocalBinds`` were to apply to loaded
2756 modules too: that might cause a compilation error, but more commonly it
2757 will cause extra recompilation, because GHC will think that it needs to
2758 recompile the module because the flags have changed.
2759
2760 If you are setting language options in your ``.ghci`` file, it is good
2761 practice to use ``:seti`` rather than ``:set``, unless you really do
2762 want them to apply to all modules you load in GHCi.
2763
2764 The two sets of options can be inspected using the ``:set`` and
2765 ``:seti`` commands respectively, with no arguments. For example, in a
2766 clean GHCi session we might see something like this:
2767
2768 ::
2769
2770     Prelude> :seti
2771     base language is: Haskell2010
2772     with the following modifiers:
2773       -XNoMonomorphismRestriction
2774       -XNoDatatypeContexts
2775       -XNondecreasingIndentation
2776       -XExtendedDefaultRules
2777     GHCi-specific dynamic flag settings:
2778     other dynamic, non-language, flag settings:
2779       -fimplicit-import-qualified
2780     warning settings:
2781
2782 The two sets of options are initialised as follows. First, both sets of
2783 options are initialised as described in :ref:`ghci-dot-files`. Then the
2784 interactive options are modified as follows:
2785
2786 -  The option ``-XExtendedDefaultRules`` is enabled, in order to apply
2787    special defaulting rules to expressions typed at the prompt (see
2788    :ref:`extended-default-rules`).
2789
2790 -  The Monomorphism Restriction is disabled (see :ref:`monomorphism`).
2791
2792 .. _ghci-dot-files:
2793
2794 The ``.ghci`` and ``.haskeline`` files
2795 --------------------------------------
2796
2797 .. _dot-ghci-files:
2798
2799 The ``.ghci`` files
2800 ~~~~~~~~~~~~~~~~~~~
2801
2802 .. index::
2803    single: .ghci; file
2804    single: startup; files, GHCi
2805
2806 When it starts, unless the ``-ignore-dot-ghci`` flag is given, GHCi
2807 reads and executes commands from the following files, in this order, if
2808 they exist:
2809
2810 1. ``./.ghci``
2811
2812 2. ``appdata/ghc/ghci.conf``, where ⟨appdata⟩ depends on your system,
2813    but is usually something like
2814    ``C:/Documents and Settings/user/Application Data``
2815
2816 3. On Unix: ``$HOME/.ghc/ghci.conf``
2817
2818 4. ``$HOME/.ghci``
2819
2820 The ``ghci.conf`` file is most useful for turning on favourite options
2821 (eg. ``:set +s``), and defining useful macros. Note: when setting
2822 language options in this file it is usually desirable to use ``:seti``
2823 rather than ``:set`` (see :ref:`ghci-interactive-options`).
2824
2825 Placing a ``.ghci`` file in a directory with a Haskell project is a
2826 useful way to set certain project-wide options so you don't have to type
2827 them every time you start GHCi: eg. if your project uses multi-parameter
2828 type classes, scoped type variables, and CPP, and has source files in
2829 three subdirectories A, B and C, you might put the following lines in
2830 ``.ghci``:
2831
2832 ::
2833
2834     :set -XMultiParamTypeClasses -XScopedTypeVariables -cpp
2835     :set -iA:B:C
2836
2837 (Note that strictly speaking the ``-i`` flag is a static one, but in
2838 fact it works to set it using ``:set`` like this. The changes won't take
2839 effect until the next ``:load``, though.)
2840
2841 Once you have a library of GHCi macros, you may want to source them from
2842 separate files, or you may want to source your ``.ghci`` file into your
2843 running GHCi session while debugging it
2844
2845 ::
2846
2847     :def source readFile
2848
2849 With this macro defined in your ``.ghci`` file, you can use
2850 ``:source file`` to read GHCi commands from ``file``. You can find (and
2851 contribute!-) other suggestions for ``.ghci`` files on this Haskell wiki
2852 page: `GHC/GHCi <http://haskell.org/haskellwiki/GHC/GHCi>`__
2853
2854 Additionally, any files specified with ``-ghci-script`` flags will be
2855 read after the standard files, allowing the use of custom .ghci files.
2856
2857 Two command-line options control whether the startup files files are
2858 read:
2859
2860 ``-ignore-dot-ghci``
2861     .. index::
2862        single: -ignore-dot-ghci
2863
2864     Don't read either ``./.ghci`` or the other startup files when
2865     starting up.
2866
2867 ``-ghci-script``
2868     .. index::
2869        single: -ghci-script
2870
2871     Read a specific file after the usual startup files. Maybe be
2872     specified repeatedly for multiple inputs.
2873
2874 When defining GHCi macros, there is some important behavior you should
2875 be aware of when names may conflict with built-in commands, especially
2876 regarding tab completion.
2877
2878 For example, consider if you had a macro named ``:time`` and in the
2879 shell, typed ``:t 3`` - what should happen? The current algorithm we use
2880 for completing commands is:
2881
2882 1. First, look up an exact match on the name from the defined macros.
2883
2884 2. Look for the exact match on the name in the built-in command list.
2885
2886 3. Do a prefix lookup on the list of built-in commands - if a built-in
2887    command matches, but a macro is defined with the same name as the
2888    built-in defined, pick the macro.
2889
2890 4. Do a prefix lookup on the list of built-in commands.
2891
2892 5. Do a prefix lookup on the list of defined macros.
2893
2894 Here are some examples:
2895
2896 1. You have a macro ``:time`` and enter ``:t 3``
2897
2898    You get ``:type 3``
2899
2900 2. You have a macro ``:type`` and enter ``:t 3``
2901
2902    You get ``:type 3`` with your defined macro, not the builtin.
2903
2904 3. You have a macro ``:time`` and a macro ``:type``, and enter ``:t 3``
2905
2906    You get ``:type 3`` with your defined macro.
2907
2908 .. _dot-haskeline-file:
2909
2910 The ``.haskeline`` file
2911 ~~~~~~~~~~~~~~~~~~~~~~~
2912
2913 .. index::
2914    single: .haskeline; file
2915    single: startup; files, GHCi
2916
2917 GHCi uses `Haskeline <https://hackage.haskell.org/package/haskeline>`__ under
2918 the hood. You can configure it to, among other
2919 things, prune duplicates from GHCi history. See:
2920 `Haskeline user preferences <http://trac.haskell.org/haskeline/wiki/UserPrefs>`__.
2921
2922 .. _ghci-obj:
2923
2924 Compiling to object code inside GHCi
2925 ------------------------------------
2926
2927 By default, GHCi compiles Haskell source code into byte-code that is
2928 interpreted by the runtime system. GHCi can also compile Haskell code to
2929 object code: to turn on this feature, use the ``-fobject-code`` flag
2930 either on the command line or with ``:set`` (the option ``-fbyte-code``
2931 restores byte-code compilation again). Compiling to object code takes
2932 longer, but typically the code will execute 10-20 times faster than
2933 byte-code.
2934
2935 Compiling to object code inside GHCi is particularly useful if you are
2936 developing a compiled application, because the ``:reload`` command
2937 typically runs much faster than restarting GHC with ``--make`` from the
2938 command-line, because all the interface files are already cached in
2939 memory.
2940
2941 There are disadvantages to compiling to object-code: you can't set
2942 breakpoints in object-code modules, for example. Only the exports of an
2943 object-code module will be visible in GHCi, rather than all top-level
2944 bindings as in interpreted modules.
2945
2946 .. _ghci-faq:
2947
2948 FAQ and Things To Watch Out For
2949 -------------------------------
2950
2951 The interpreter can't load modules with foreign export declarations!
2952     Unfortunately not. We haven't implemented it yet. Please compile any
2953     offending modules by hand before loading them into GHCi.
2954
2955 ``-O`` doesn't work with GHCi!
2956     .. index::
2957        single: -O
2958
2959     For technical reasons, the bytecode compiler doesn't interact well
2960     with one of the optimisation passes, so we have disabled
2961     optimisation when using the interpreter. This isn't a great loss:
2962     you'll get a much bigger win by compiling the bits of your code that
2963     need to go fast, rather than interpreting them with optimisation
2964     turned on.
2965
2966 Unboxed tuples don't work with GHCi
2967     That's right. You can always compile a module that uses unboxed
2968     tuples and load it into GHCi, however. (Incidentally the previous
2969     point, namely that ``-O`` is incompatible with GHCi, is because the
2970     bytecode compiler can't deal with unboxed tuples).
2971
2972 Concurrent threads don't carry on running when GHCi is waiting for input.
2973     This should work, as long as your GHCi was built with the
2974     ``-threaded`` switch, which is the default. Consult whoever supplied
2975     your GHCi installation.
2976
2977
2978 After using ``getContents``, I can't use ``stdin``, until I do ``:load`` or ``:reload``
2979     This is the defined behaviour of ``getContents``: it puts the stdin
2980     Handle in a state known as semi-closed, wherein any further I/O
2981     operations on it are forbidden. Because I/O state is retained
2982     between computations, the semi-closed state persists until the next
2983     ``:load`` or ``:reload`` command.
2984
2985     You can make ``stdin`` reset itself after every evaluation by giving
2986     GHCi the command ``:set +r``. This works because ``stdin`` is just a
2987     top-level expression that can be reverted to its unevaluated state
2988     in the same way as any other top-level expression (CAF).
2989
2990 I can't use Control-C to interrupt computations in GHCi on Windows.
2991     See :ref:`ghci-windows`.
2992
2993 The default buffering mode is different in GHCi to GHC.
2994     In GHC, the stdout handle is line-buffered by default. However, in
2995     GHCi we turn off the buffering on stdout, because this is normally
2996     what you want in an interpreter: output appears as it is generated.
2997
2998     If you want line-buffered behaviour, as in GHC, you can start your
2999     program thus:
3000
3001     ::
3002
3003         main = do { hSetBuffering stdout LineBuffering; ... }
3004
3005
3006 .. [5]
3007    Note that packages only contain compiled code, so debugging a package
3008    requires finding its source and loading that directly.
3009
3010 .. [6]
3011    We originally provided bindings for all variables in scope, rather
3012    than just the free variables of the expression, but found that this
3013    affected performance considerably, hence the current restriction to
3014    just the free variables.