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