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