Make language extensions their own category in the documentation
[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 .. extension:: ExtendedDefaultRules
1027     :shortdesc: Use GHCi's extended default rules in a normal module.
1028
1029     :since: 6.8.1
1030
1031     Allow defaulting to take place for more than just numeric classes.
1032
1033 Consider this GHCi session:
1034
1035 .. code-block:: none
1036
1037       ghci> reverse []
1038
1039 What should GHCi do? Strictly speaking, the program is ambiguous.
1040 ``show (reverse [])`` (which is what GHCi computes here) has type
1041 ``Show a => String`` and how that displays depends on the type ``a``.
1042 For example:
1043
1044 .. code-block:: none
1045
1046       ghci> reverse ([] :: String)
1047       ""
1048       ghci> reverse ([] :: [Int])
1049       []
1050
1051 However, it is tiresome for the user to have to specify the type, so
1052 GHCi extends Haskell's type-defaulting rules (Section 4.3.4 of the
1053 Haskell 2010 Report) as follows. The standard rules take each group of
1054 constraints ``(C1 a, C2 a, ..., Cn a)`` for each type variable ``a``,
1055 and defaults the type variable if
1056
1057 1. The type variable ``a`` appears in no other constraints
1058
1059 2. All the classes ``Ci`` are standard.
1060
1061 3. At least one of the classes ``Ci`` is numeric.
1062
1063 At the GHCi prompt, or with GHC if the :extension:`ExtendedDefaultRules` flag
1064 is given, the types are instead resolved with the following method:
1065
1066 Find all the unsolved constraints. Then:
1067
1068 -  Find those that are of form ``(C a)`` where ``a`` is a type variable, and
1069    partition those constraints into groups that share a common type variable ``a``.
1070
1071 -  Keep only the groups in which at least one of the classes is an
1072    **interactive class** (defined below).
1073
1074 -  Now, for each remaining group G, try each type ``ty`` from the default-type list
1075    in turn; if setting ``a = ty`` would allow the constraints in G to be completely
1076    solved. If so, default ``a`` to ``ty``.
1077
1078 -  The unit type ``()`` and the list type ``[]`` are added to the start of
1079    the standard list of types which are tried when doing type defaulting.
1080
1081 Note that any multi-parameter constraints ``(D a b)`` or ``(D [a] Int)`` do not
1082 participate in the process (either to help or to hinder); but they must of course
1083 be soluble once the defaulting process is complete.
1084
1085 The last point means that, for example, this program: ::
1086
1087     main :: IO ()
1088     main = print def
1089
1090     instance Num ()
1091
1092     def :: (Num a, Enum a) => a
1093     def = toEnum 0
1094
1095 prints ``()`` rather than ``0`` as the type is defaulted to ``()``
1096 rather than ``Integer``.
1097
1098 The motivation for the change is that it means ``IO a`` actions default
1099 to ``IO ()``, which in turn means that ghci won't try to print a result
1100 when running them. This is particularly important for ``printf``, which
1101 has an instance that returns ``IO a``. However, it is only able to
1102 return ``undefined`` (the reason for the instance having this type is so
1103 that printf doesn't require extensions to the class system), so if the
1104 type defaults to ``Integer`` then ghci gives an error when running a
1105 printf.
1106
1107 See also :ref:`actions-at-prompt` for how the monad of a computational
1108 expression defaults to ``IO`` if possible.
1109
1110 Interactive classes
1111 ^^^^^^^^^^^^^^^^^^^
1112
1113 .. index::
1114    single: Interactive classes
1115
1116 The interactive classes (only relevant when :extension:`ExtendedDefaultRules`
1117 is in effect) are: any numeric class, ``Show``, ``Eq``, ``Ord``,
1118 ``Foldable`` or ``Traversable``.
1119
1120 As long as a type variable is constrained by one of these classes, defaulting
1121 will occur, as outlined above.
1122
1123 Extended rules around ``default`` declarations
1124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1125
1126 .. index::
1127    single: default declarations
1128
1129 Since the rules for defaulting are relaxed under
1130 :extension:`ExtendedDefaultRules`, the rules for ``default`` declarations
1131 are also relaxed. According to Section 4.3.4 of the Haskell 2010 Report,
1132 a ``default`` declaration looks like ``default (t1, ..., tn)`` where, for
1133 each ``ti``, ``Num ti`` must hold. This is relaxed to say that for each
1134 ``ti``, there must exist an interactive class ``C`` such that ``C ti`` holds.
1135 This means that type *constructors* can be allowed in these lists.
1136 For example, the following works if you wish your ``Foldable`` constraints
1137 to default to ``Maybe`` but your ``Num`` constraints to still default
1138 to ``Integer`` or ``Double``: ::
1139
1140     default (Maybe, Integer, Double)
1141
1142 .. _ghci-interactive-print:
1143
1144 Using a custom interactive printing function
1145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1146
1147 .. index::
1148    single: Custom printing function; in GHCi
1149
1150 Since GHC 7.6.1, GHCi prints the result of expressions typed at the prompt
1151 using the function ``System.IO.print``. Its type signature is ``Show a => a ->
1152 IO ()``, and it works by converting the value to ``String`` using ``show``.
1153
1154 This is not ideal in certain cases, like when the output is long, or
1155 contains strings with non-ascii characters.
1156
1157 The :ghc-flag:`-interactive-print ⟨expr⟩` flag allows to specify any function
1158 of type ``C a => a -> IO ()``, for some constraint ``C``, as the function for
1159 printing evaluated expressions. The function can reside in any loaded module or
1160 any registered package, but only when it resides in a registered package will
1161 it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`,
1162 :ghci-cmd:`:reload` or, :ghci-cmd:`:set`.
1163
1164 .. ghc-flag:: -interactive-print ⟨expr⟩
1165     :shortdesc: :ref:`Select the function to use for printing evaluated
1166         expressions in GHCi <ghci-interactive-print>`
1167     :type: dynamic
1168     :category:
1169
1170     Set the function used by GHCi to print evaluation results. Expression
1171     must be of type ``C a => a -> IO ()``.
1172
1173 As an example, suppose we have following special printing module: ::
1174
1175     module SpecPrinter where
1176     import System.IO
1177
1178     sprint a = putStrLn $ show a ++ "!"
1179
1180 The ``sprint`` function adds an exclamation mark at the end of any
1181 printed value. Running GHCi with the command:
1182
1183 .. code-block:: none
1184
1185     ghci -interactive-print=SpecPrinter.sprint SpecPrinter
1186
1187 will start an interactive session where values with be printed using
1188 ``sprint``:
1189
1190 .. code-block:: none
1191
1192     *SpecPrinter> [1,2,3]
1193     [1,2,3]!
1194     *SpecPrinter> 42
1195     42!
1196
1197 A custom pretty printing function can be used, for example, to format
1198 tree-like and nested structures in a more readable way.
1199
1200 The :ghc-flag:`-interactive-print ⟨expr⟩` flag can also be used when running
1201 GHC in ``-e mode``:
1202
1203 .. code-block:: none
1204
1205     % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter
1206     [1,2,3]!
1207
1208 .. _ghci-stack-traces:
1209
1210 Stack Traces in GHCi
1211 ~~~~~~~~~~~~~~~~~~~~
1212
1213 .. index::
1214   simple: stack trace; in GHCi
1215
1216 [ This is an experimental feature enabled by the new
1217 ``-fexternal-interpreter`` flag that was introduced in GHC 8.0.1.  It
1218 is currently not supported on Windows.]
1219
1220 GHCi can use the profiling system to collect stack trace information
1221 when running interpreted code.  To gain access to stack traces, start
1222 GHCi like this:
1223
1224 .. code-block:: none
1225
1226     ghci -fexternal-interpreter -prof
1227
1228 This runs the interpreted code in a separate process (see
1229 :ref:`external-interpreter`) and runs it in profiling mode to collect
1230 call stack information.  Note that because we're running the
1231 interpreted code in profiling mode, all packages that you use must be
1232 compiled for profiling.  The ``-prof`` flag to GHCi only works in
1233 conjunction with ``-fexternal-interpreter``.
1234
1235 There are three ways to get access to the current call stack.
1236
1237 - ``error`` and ``undefined`` automatically attach the current stack
1238   to the error message.  This often complements the ``HasCallStack``
1239   stack (see :ref:`hascallstack`), so both call stacks are
1240   shown.
1241
1242 - ``Debug.Trace.traceStack`` is a version of ``Debug.Trace.trace``
1243   that also prints the current call stack.
1244
1245 - Functions in the module ``GHC.Stack`` can be used to get the current
1246   stack and render it.
1247
1248 You don't need to use ``-fprof-auto`` for interpreted modules,
1249 annotations are automatically added at a granularity fine enough to
1250 distinguish individual call sites.  However, you won't see any call
1251 stack information for compiled code unless it was compiled with
1252 ``-fprof-auto`` or has explicit ``SCC`` annotations (see
1253 :ref:`scc-pragma`).
1254
1255 .. _ghci-debugger:
1256
1257 The GHCi Debugger
1258 -----------------
1259
1260 .. index::
1261    single: debugger; in GHCi
1262
1263 GHCi contains a simple imperative-style debugger in which you can stop a
1264 running computation in order to examine the values of variables. The
1265 debugger is integrated into GHCi, and is turned on by default: no flags
1266 are required to enable the debugging facilities. There is one major
1267 restriction: breakpoints and single-stepping are only available in
1268 interpreted modules; compiled code is invisible to the debugger [5]_.
1269
1270 The debugger provides the following:
1271
1272 -  The ability to set a breakpoint on a function definition or
1273    expression in the program. When the function is called, or the
1274    expression evaluated, GHCi suspends execution and returns to the
1275    prompt, where you can inspect the values of local variables before
1276    continuing with the execution.
1277
1278 -  Execution can be single-stepped: the evaluator will suspend execution
1279    approximately after every reduction, allowing local variables to be
1280    inspected. This is equivalent to setting a breakpoint at every point
1281    in the program.
1282
1283 -  Execution can take place in tracing mode, in which the evaluator
1284    remembers each evaluation step as it happens, but doesn't suspend
1285    execution until an actual breakpoint is reached. When this happens,
1286    the history of evaluation steps can be inspected.
1287
1288 -  Exceptions (e.g. pattern matching failure and ``error``) can be
1289    treated as breakpoints, to help locate the source of an exception in
1290    the program.
1291
1292 There is currently no support for obtaining a “stack trace”, but the
1293 tracing and history features provide a useful second-best, which will
1294 often be enough to establish the context of an error. For instance, it
1295 is possible to break automatically when an exception is thrown, even if
1296 it is thrown from within compiled code (see
1297 :ref:`ghci-debugger-exceptions`).
1298
1299 .. _breakpoints:
1300
1301 Breakpoints and inspecting variables
1302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1303
1304 Let's use quicksort as a running example. Here's the code: ::
1305
1306     qsort [] = []
1307     qsort (a:as) = qsort left ++ [a] ++ qsort right
1308       where (left,right) = (filter (<=a) as, filter (>a) as)
1309
1310     main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1311
1312 First, load the module into GHCi:
1313
1314 .. code-block:: none
1315
1316     Prelude> :l qsort.hs
1317     [1 of 1] Compiling Main             ( qsort.hs, interpreted )
1318     Ok, modules loaded: Main.
1319     *Main>
1320
1321 Now, let's set a breakpoint on the right-hand-side of the second
1322 equation of qsort:
1323
1324 .. code-block:: none
1325
1326     *Main> :break 2
1327     Breakpoint 0 activated at qsort.hs:2:15-46
1328     *Main>
1329
1330 The command ``:break 2`` sets a breakpoint on line 2 of the most
1331 recently-loaded module, in this case ``qsort.hs``. Specifically, it
1332 picks the leftmost complete subexpression on that line on which to set
1333 the breakpoint, which in this case is the expression
1334 ``(qsort left ++ [a] ++ qsort right)``.
1335
1336 Now, we run the program:
1337
1338 .. code-block:: none
1339
1340     *Main> main
1341     Stopped at qsort.hs:2:15-46
1342     _result :: [a]
1343     a :: a
1344     left :: [a]
1345     right :: [a]
1346     [qsort.hs:2:15-46] *Main>
1347
1348 Execution has stopped at the breakpoint. The prompt has changed to
1349 indicate that we are currently stopped at a breakpoint, and the
1350 location: ``[qsort.hs:2:15-46]``. To further clarify the location, we
1351 can use the :ghci-cmd:`:list` command:
1352
1353 .. code-block:: none
1354
1355     [qsort.hs:2:15-46] *Main> :list
1356     1  qsort [] = []
1357     2  qsort (a:as) = qsort left ++ [a] ++ qsort right
1358     3    where (left,right) = (filter (<=a) as, filter (>a) as)
1359
1360 The :ghci-cmd:`:list` command lists the source code around the current
1361 breakpoint. If your output device supports it, then GHCi will highlight
1362 the active subexpression in bold.
1363
1364 GHCi has provided bindings for the free variables [6]_ of the expression
1365 on which the breakpoint was placed (``a``, ``left``, ``right``), and
1366 additionally a binding for the result of the expression (``_result``).
1367 These variables are just like other variables that you might define in
1368 GHCi; you can use them in expressions that you type at the prompt, you
1369 can ask for their types with :ghci-cmd:`:type`, and so on. There is one
1370 important difference though: these variables may only have partial
1371 types. For example, if we try to display the value of ``left``:
1372
1373 .. code-block:: none
1374
1375     [qsort.hs:2:15-46] *Main> left
1376
1377     <interactive>:1:0:
1378         Ambiguous type variable `a' in the constraint:
1379           `Show a' arising from a use of `print' at <interactive>:1:0-3
1380         Cannot resolve unknown runtime types: a
1381         Use :print or :force to determine these types
1382
1383 This is because ``qsort`` is a polymorphic function, and because GHCi
1384 does not carry type information at runtime, it cannot determine the
1385 runtime types of free variables that involve type variables. Hence, when
1386 you ask to display ``left`` at the prompt, GHCi can't figure out which
1387 instance of ``Show`` to use, so it emits the type error above.
1388
1389 Fortunately, the debugger includes a generic printing command,
1390 :ghci-cmd:`:print`, which can inspect the actual runtime value of a variable and
1391 attempt to reconstruct its type. If we try it on ``left``:
1392
1393 .. code-block:: none
1394
1395     [qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show
1396     [qsort.hs:2:15-46] *Main> :print left
1397     left = (_t1::[a])
1398
1399 This isn't particularly enlightening. What happened is that ``left`` is
1400 bound to an unevaluated computation (a suspension, or thunk), and
1401 :ghci-cmd:`:print` does not force any evaluation. The idea is that
1402 :ghci-cmd:`:print` can be used to inspect values at a breakpoint without any
1403 unfortunate side effects. It won't force any evaluation, which could cause the
1404 program to give a different answer than it would normally, and hence it won't
1405 cause any exceptions to be raised, infinite loops, or further breakpoints to be
1406 triggered (see :ref:`nested-breakpoints`). Rather than forcing thunks,
1407 :ghci-cmd:`:print` binds each thunk to a fresh variable beginning with an
1408 underscore, in this case ``_t1``.
1409
1410 The flag :ghc-flag:`-fprint-evld-with-show` instructs :ghci-cmd:`:print` to reuse
1411 available ``Show`` instances when possible. This happens only when the
1412 contents of the variable being inspected are completely evaluated.
1413
1414 If we aren't concerned about preserving the evaluatedness of a variable, we can
1415 use :ghci-cmd:`:force` instead of :ghci-cmd:`:print`. The :ghci-cmd:`:force`
1416 command behaves exactly like :ghci-cmd:`:print`, except that it forces the
1417 evaluation of any thunks it encounters:
1418
1419 .. code-block:: none
1420
1421     [qsort.hs:2:15-46] *Main> :force left
1422     left = [4,0,3,1]
1423
1424 Now, since :ghci-cmd:`:force` has inspected the runtime value of ``left``, it
1425 has reconstructed its type. We can see the results of this type
1426 reconstruction:
1427
1428 .. code-block:: none
1429
1430     [qsort.hs:2:15-46] *Main> :show bindings
1431     _result :: [Integer]
1432     a :: Integer
1433     left :: [Integer]
1434     right :: [Integer]
1435     _t1 :: [Integer]
1436
1437 Not only do we now know the type of ``left``, but all the other partial
1438 types have also been resolved. So we can ask for the value of ``a``, for
1439 example:
1440
1441 .. code-block:: none
1442
1443     [qsort.hs:2:15-46] *Main> a
1444     8
1445
1446 You might find it useful to use Haskell's ``seq`` function to evaluate
1447 individual thunks rather than evaluating the whole expression with
1448 :ghci-cmd:`:force`. For example:
1449
1450 .. code-block:: none
1451
1452     [qsort.hs:2:15-46] *Main> :print right
1453     right = (_t1::[Integer])
1454     [qsort.hs:2:15-46] *Main> seq _t1 ()
1455     ()
1456     [qsort.hs:2:15-46] *Main> :print right
1457     right = 23 : (_t2::[Integer])
1458
1459 We evaluated only the ``_t1`` thunk, revealing the head of the list, and
1460 the tail is another thunk now bound to ``_t2``. The ``seq`` function is
1461 a little inconvenient to use here, so you might want to use :ghci-cmd:`:def` to
1462 make a nicer interface (left as an exercise for the reader!).
1463
1464 Finally, we can continue the current execution:
1465
1466 .. code-block:: none
1467
1468     [qsort.hs:2:15-46] *Main> :continue
1469     Stopped at qsort.hs:2:15-46
1470     _result :: [a]
1471     a :: a
1472     left :: [a]
1473     right :: [a]
1474     [qsort.hs:2:15-46] *Main>
1475
1476 The execution continued at the point it previously stopped, and has now
1477 stopped at the breakpoint for a second time.
1478
1479 .. _setting-breakpoints:
1480
1481 Setting breakpoints
1482 ^^^^^^^^^^^^^^^^^^^
1483
1484 Breakpoints can be set in various ways. Perhaps the easiest way to set a
1485 breakpoint is to name a top-level function:
1486
1487 .. code-block:: none
1488
1489        :break identifier
1490
1491 Where ⟨identifier⟩ names any top-level function in an interpreted module
1492 currently loaded into GHCi (qualified names may be used). The breakpoint
1493 will be set on the body of the function, when it is fully applied but
1494 before any pattern matching has taken place.
1495
1496 Breakpoints can also be set by line (and optionally column) number:
1497
1498 .. code-block:: none
1499
1500        :break line
1501        :break line column
1502        :break module line
1503        :break module line column
1504
1505 When a breakpoint is set on a particular line, GHCi sets the breakpoint
1506 on the leftmost subexpression that begins and ends on that line. If two
1507 complete subexpressions start at the same column, the longest one is
1508 picked. If there is no complete subexpression on the line, then the
1509 leftmost expression starting on the line is picked, and failing that the
1510 rightmost expression that partially or completely covers the line.
1511
1512 When a breakpoint is set on a particular line and column, GHCi picks the
1513 smallest subexpression that encloses that location on which to set the
1514 breakpoint. Note: GHC considers the TAB character to have a width of 1,
1515 wherever it occurs; in other words it counts characters, rather than
1516 columns. This matches what some editors do, and doesn't match others.
1517 The best advice is to avoid tab characters in your source code
1518 altogether (see :ghc-flag:`-Wtabs` in :ref:`options-sanity`).
1519
1520 If the module is omitted, then the most recently-loaded module is used.
1521
1522 Not all subexpressions are potential breakpoint locations. Single
1523 variables are typically not considered to be breakpoint locations
1524 (unless the variable is the right-hand-side of a function definition,
1525 lambda, or case alternative). The rule of thumb is that all redexes are
1526 breakpoint locations, together with the bodies of functions, lambdas,
1527 case alternatives and binding statements. There is normally no
1528 breakpoint on a let expression, but there will always be a breakpoint on
1529 its body, because we are usually interested in inspecting the values of
1530 the variables bound by the let.
1531
1532 Listing and deleting breakpoints
1533 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1534
1535 The list of breakpoints currently enabled can be displayed using
1536 :ghci-cmd:`:show breaks`:
1537
1538 .. code-block:: none
1539
1540     *Main> :show breaks
1541     [0] Main qsort.hs:1:11-12
1542     [1] Main qsort.hs:2:15-46
1543
1544 To delete a breakpoint, use the :ghci-cmd:`:delete` command with the number
1545 given in the output from :ghci-cmd:`:show breaks`:
1546
1547 .. code-block:: none
1548
1549     *Main> :delete 0
1550     *Main> :show breaks
1551     [1] Main qsort.hs:2:15-46
1552
1553 To delete all breakpoints at once, use ``:delete *``.
1554
1555 .. _single-stepping:
1556
1557 Single-stepping
1558 ~~~~~~~~~~~~~~~
1559
1560 Single-stepping is a great way to visualise the execution of your
1561 program, and it is also a useful tool for identifying the source of a
1562 bug. GHCi offers two variants of stepping. Use :ghci-cmd:`:step` to enable all
1563 the breakpoints in the program, and execute until the next breakpoint is
1564 reached. Use :ghci-cmd:`:steplocal` to limit the set of enabled breakpoints to
1565 those in the current top level function. Similarly, use :ghci-cmd:`:stepmodule`
1566 to single step only on breakpoints contained in the current module. For
1567 example:
1568
1569 .. code-block:: none
1570
1571     *Main> :step main
1572     Stopped at qsort.hs:5:7-47
1573     _result :: IO ()
1574
1575 The command :ghci-cmd:`:step expr <:step>` begins the evaluation of ⟨expr⟩ in
1576 single-stepping mode. If ⟨expr⟩ is omitted, then it single-steps from
1577 the current breakpoint. :ghci-cmd:`:steplocal` and :ghci-cmd:`:stepmodule`
1578 commands work similarly.
1579
1580 The :ghci-cmd:`:list` command is particularly useful when single-stepping, to
1581 see where you currently are:
1582
1583 .. code-block:: none
1584
1585     [qsort.hs:5:7-47] *Main> :list
1586     4
1587     5  main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1588     6
1589     [qsort.hs:5:7-47] *Main>
1590
1591 In fact, GHCi provides a way to run a command when a breakpoint is hit,
1592 so we can make it automatically do :ghci-cmd:`:list`:
1593
1594 .. code-block:: none
1595
1596     [qsort.hs:5:7-47] *Main> :set stop :list
1597     [qsort.hs:5:7-47] *Main> :step
1598     Stopped at qsort.hs:5:14-46
1599     _result :: [Integer]
1600     4
1601     5  main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
1602     6
1603     [qsort.hs:5:14-46] *Main>
1604
1605 .. _nested-breakpoints:
1606
1607 Nested breakpoints
1608 ~~~~~~~~~~~~~~~~~~
1609
1610 When GHCi is stopped at a breakpoint, and an expression entered at the
1611 prompt triggers a second breakpoint, the new breakpoint becomes the
1612 "current" one, and the old one is saved on a stack. An arbitrary number
1613 of breakpoint contexts can be built up in this way. For example:
1614
1615 .. code-block:: none
1616
1617     [qsort.hs:2:15-46] *Main> :st qsort [1,3]
1618     Stopped at qsort.hs:(1,0)-(3,55)
1619     _result :: [a]
1620     ... [qsort.hs:(1,0)-(3,55)] *Main>
1621
1622 While stopped at the breakpoint on line 2 that we set earlier, we
1623 started a new evaluation with ``:step qsort [1,3]``. This new evaluation
1624 stopped after one step (at the definition of ``qsort``). The prompt has
1625 changed, now prefixed with ``...``, to indicate that there are saved
1626 breakpoints beyond the current one. To see the stack of contexts, use
1627 :ghci-cmd:`:show context`:
1628
1629 .. code-block:: none
1630
1631     ... [qsort.hs:(1,0)-(3,55)] *Main> :show context
1632     --> main
1633       Stopped at qsort.hs:2:15-46
1634     --> qsort [1,3]
1635       Stopped at qsort.hs:(1,0)-(3,55)
1636     ... [qsort.hs:(1,0)-(3,55)] *Main>
1637
1638 To abandon the current evaluation, use :ghci-cmd:`:abandon`:
1639
1640 .. code-block:: none
1641
1642     ... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
1643     [qsort.hs:2:15-46] *Main> :abandon
1644     *Main>
1645
1646 .. _ghci-debugger-result:
1647
1648 The ``_result`` variable
1649 ~~~~~~~~~~~~~~~~~~~~~~~~
1650
1651 When stopped at a breakpoint or single-step, GHCi binds the variable
1652 ``_result`` to the value of the currently active expression. The value
1653 of ``_result`` is presumably not available yet, because we stopped its
1654 evaluation, but it can be forced: if the type is known and showable,
1655 then just entering ``_result`` at the prompt will show it. However,
1656 there's one caveat to doing this: evaluating ``_result`` will be likely
1657 to trigger further breakpoints, starting with the breakpoint we are
1658 currently stopped at (if we stopped at a real breakpoint, rather than
1659 due to :ghci-cmd:`:step`). So it will probably be necessary to issue a
1660 :ghci-cmd:`:continue` immediately when evaluating ``_result``. Alternatively,
1661 you can use :ghci-cmd:`:force` which ignores breakpoints.
1662
1663 .. _tracing:
1664
1665 Tracing and history
1666 ~~~~~~~~~~~~~~~~~~~
1667
1668 A question that we often want to ask when debugging a program is “how
1669 did I get here?”. Traditional imperative debuggers usually provide some
1670 kind of stack-tracing feature that lets you see the stack of active
1671 function calls (sometimes called the “lexical call stack”), describing a
1672 path through the code to the current location. Unfortunately this is
1673 hard to provide in Haskell, because execution proceeds on a
1674 demand-driven basis, rather than a depth-first basis as in strict
1675 languages. The “stack“ in GHC's execution engine bears little
1676 resemblance to the lexical call stack. Ideally GHCi would maintain a
1677 separate lexical call stack in addition to the dynamic call stack, and
1678 in fact this is exactly what our profiling system does
1679 (:ref:`profiling`), and what some other Haskell debuggers do. For the
1680 time being, however, GHCi doesn't maintain a lexical call stack (there
1681 are some technical challenges to be overcome). Instead, we provide a way
1682 to backtrack from a breakpoint to previous evaluation steps: essentially
1683 this is like single-stepping backwards, and should in many cases provide
1684 enough information to answer the "how did I get here?" question.
1685
1686 To use tracing, evaluate an expression with the :ghci-cmd:`:trace` command. For
1687 example, if we set a breakpoint on the base case of ``qsort``:
1688
1689 .. code-block:: none
1690
1691     *Main> :list qsort
1692     1  qsort [] = []
1693     2  qsort (a:as) = qsort left ++ [a] ++ qsort right
1694     3    where (left,right) = (filter (<=a) as, filter (>a) as)
1695     4
1696     *Main> :b 1
1697     Breakpoint 1 activated at qsort.hs:1:11-12
1698     *Main>
1699
1700 and then run a small ``qsort`` with tracing:
1701
1702 .. code-block:: none
1703
1704     *Main> :trace qsort [3,2,1]
1705     Stopped at qsort.hs:1:11-12
1706     _result :: [a]
1707     [qsort.hs:1:11-12] *Main>
1708
1709 We can now inspect the history of evaluation steps:
1710
1711 .. code-block:: none
1712
1713     [qsort.hs:1:11-12] *Main> :hist
1714     -1  : qsort.hs:3:24-38
1715     -2  : qsort.hs:3:23-55
1716     -3  : qsort.hs:(1,0)-(3,55)
1717     -4  : qsort.hs:2:15-24
1718     -5  : qsort.hs:2:15-46
1719     -6  : qsort.hs:3:24-38
1720     -7  : qsort.hs:3:23-55
1721     -8  : qsort.hs:(1,0)-(3,55)
1722     -9  : qsort.hs:2:15-24
1723     -10 : qsort.hs:2:15-46
1724     -11 : qsort.hs:3:24-38
1725     -12 : qsort.hs:3:23-55
1726     -13 : qsort.hs:(1,0)-(3,55)
1727     -14 : qsort.hs:2:15-24
1728     -15 : qsort.hs:2:15-46
1729     -16 : qsort.hs:(1,0)-(3,55)
1730     <end of history>
1731
1732 To examine one of the steps in the history, use :ghci-cmd:`:back`:
1733
1734 .. code-block:: none
1735
1736     [qsort.hs:1:11-12] *Main> :back
1737     Logged breakpoint at qsort.hs:3:24-38
1738     _result :: [a]
1739     as :: [a]
1740     a :: a
1741     [-1: qsort.hs:3:24-38] *Main>
1742
1743 Note that the local variables at each step in the history have been
1744 preserved, and can be examined as usual. Also note that the prompt has
1745 changed to indicate that we're currently examining the first step in the
1746 history: ``-1``. The command :ghci-cmd:`:forward` can be used to traverse
1747 forward in the history.
1748
1749 The :ghci-cmd:`:trace` command can be used with or without an expression. When
1750 used without an expression, tracing begins from the current breakpoint,
1751 just like :ghci-cmd:`:step`.
1752
1753 The history is only available when using :ghci-cmd:`:trace`; the reason for this
1754 is we found that logging each breakpoint in the history cuts performance
1755 by a factor of 2 or more.
1756
1757 .. ghc-flag:: -fghci-hist-size=⟨n⟩
1758     :shortdesc: Set the number of entries GHCi keeps for ``:history``.
1759         See :ref:`ghci-debugger`.
1760     :type: dynamic
1761     :category:
1762
1763     :default: 50
1764
1765     Modify the depth of the evaluation history tracked by GHCi.
1766
1767 .. _ghci-debugger-exceptions:
1768
1769 Debugging exceptions
1770 ~~~~~~~~~~~~~~~~~~~~
1771
1772 Another common question that comes up when debugging is "where did this
1773 exception come from?". Exceptions such as those raised by ``error`` or
1774 ``head []`` have no context information attached to them. Finding which
1775 particular call to ``head`` in your program resulted in the error can be
1776 a painstaking process, usually involving ``Debug.Trace.trace``, or
1777 compiling with profiling and using ``Debug.Trace.traceStack`` or
1778 ``+RTS -xc`` (see :rts-flag:`-xc`).
1779
1780 The GHCi debugger offers a way to hopefully shed some light on these
1781 errors quickly and without modifying or recompiling the source code. One
1782 way would be to set a breakpoint on the location in the source code that
1783 throws the exception, and then use :ghci-cmd:`:trace` and :ghci-cmd:`:history` to
1784 establish the context. However, ``head`` is in a library and we can't
1785 set a breakpoint on it directly. For this reason, GHCi provides the
1786 flags :ghc-flag:`-fbreak-on-exception` which causes the evaluator to stop when
1787 an exception is thrown, and :ghc-flag:`-fbreak-on-error`, which works similarly
1788 but stops only on uncaught exceptions. When stopping at an exception,
1789 GHCi will act just as it does when a breakpoint is hit, with the
1790 deviation that it will not show you any source code location. Due to
1791 this, these commands are only really useful in conjunction with
1792 :ghci-cmd:`:trace`, in order to log the steps leading up to the exception. For
1793 example:
1794
1795 .. code-block:: none
1796
1797     *Main> :set -fbreak-on-exception
1798     *Main> :trace qsort ("abc" ++ undefined)
1799     “Stopped at <exception thrown>
1800     _exception :: e
1801     [<exception thrown>] *Main> :hist
1802     -1  : qsort.hs:3:24-38
1803     -2  : qsort.hs:3:23-55
1804     -3  : qsort.hs:(1,0)-(3,55)
1805     -4  : qsort.hs:2:15-24
1806     -5  : qsort.hs:2:15-46
1807     -6  : qsort.hs:(1,0)-(3,55)
1808     <end of history>
1809     [<exception thrown>] *Main> :back
1810     Logged breakpoint at qsort.hs:3:24-38
1811     _result :: [a]
1812     as :: [a]
1813     a :: a
1814     [-1: qsort.hs:3:24-38] *Main> :force as
1815     *** Exception: Prelude.undefined
1816     [-1: qsort.hs:3:24-38] *Main> :print as
1817     as = 'b' : 'c' : (_t1::[Char])
1818
1819 The exception itself is bound to a new variable, ``_exception``.
1820
1821 Breaking on exceptions is particularly useful for finding out what your
1822 program was doing when it was in an infinite loop. Just hit Control-C,
1823 and examine the history to find out what was going on.
1824
1825 .. ghc-flag:: -fbreak-on-exception
1826     :shortdesc: :ref:`Break on any exception thrown <ghci-debugger-exceptions>`
1827     :type: dynamic
1828     :reverse: -fno-break-on-exception
1829     :category:
1830
1831     Causes GHCi to halt evaluation and return to the interactive prompt
1832     in the event of an exception. :ghc-flag:`-fbreak-on-exception` breaks
1833     on all exceptions.
1834
1835 .. ghc-flag:: -fbreak-on-error
1836     :shortdesc: :ref:`Break on uncaught exceptions and errors
1837         <ghci-debugger-exceptions>`
1838     :type: dynamic
1839     :reverse: -fno-break-on-error
1840     :category:
1841
1842     Causes GHCi to halt evaluation and return to the interactive prompt in the
1843     event of an exception.  :ghc-flag:`-fbreak-on-error` breaks on only those
1844     exceptions which would otherwise be uncaught.
1845
1846
1847 Example: inspecting functions
1848 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1849
1850 It is possible to use the debugger to examine function values. When we
1851 are at a breakpoint and a function is in scope, the debugger cannot show
1852 you the source code for it; however, it is possible to get some
1853 information by applying it to some arguments and observing the result.
1854
1855 The process is slightly complicated when the binding is polymorphic. We
1856 show the process by means of an example. To keep things simple, we will
1857 use the well known ``map`` function:
1858
1859 ::
1860
1861     import Prelude hiding (map)
1862
1863     map :: (a->b) -> [a] -> [b]
1864     map f [] = []
1865     map f (x:xs) = f x : map f xs
1866
1867 We set a breakpoint on ``map``, and call it.
1868
1869 .. code-block:: none
1870
1871     *Main> :break 5
1872     Breakpoint 0 activated at  map.hs:5:15-28
1873     *Main> map Just [1..5]
1874     Stopped at map.hs:(4,0)-(5,12)
1875     _result :: [b]
1876     x :: a
1877     f :: a -> b
1878     xs :: [a]
1879
1880 GHCi tells us that, among other bindings, ``f`` is in scope. However,
1881 its type is not fully known yet, and thus it is not possible to apply it
1882 to any arguments. Nevertheless, observe that the type of its first
1883 argument is the same as the type of ``x``, and its result type is shared
1884 with ``_result``.
1885
1886 As we demonstrated earlier (:ref:`breakpoints`), the debugger has some
1887 intelligence built-in to update the type of ``f`` whenever the types of
1888 ``x`` or ``_result`` are discovered. So what we do in this scenario is
1889 force ``x`` a bit, in order to recover both its type and the argument
1890 part of ``f``.
1891
1892 .. code-block:: none
1893
1894     *Main> seq x ()
1895     *Main> :print x
1896     x = 1
1897
1898 We can check now that as expected, the type of ``x`` has been
1899 reconstructed, and with it the type of ``f`` has been too:
1900
1901 .. code-block:: none
1902
1903     *Main> :t x
1904     x :: Integer
1905     *Main> :t f
1906     f :: Integer -> b
1907
1908 From here, we can apply f to any argument of type Integer and observe
1909 the results.
1910
1911 .. code-block:: none
1912
1913     *Main> let b = f 10
1914     *Main> :t b
1915     b :: b
1916     *Main> b
1917     <interactive>:1:0:
1918         Ambiguous type variable `b' in the constraint:
1919           `Show b' arising from a use of `print' at <interactive>:1:0
1920     *Main> :p b
1921     b = (_t2::a)
1922     *Main> seq b ()
1923     ()
1924     *Main> :t b
1925     b :: a
1926     *Main> :p b
1927     b = Just 10
1928     *Main> :t b
1929     b :: Maybe Integer
1930     *Main> :t f
1931     f :: Integer -> Maybe Integer
1932     *Main> f 20
1933     Just 20
1934     *Main> map f [1..5]
1935     [Just 1, Just 2, Just 3, Just 4, Just 5]
1936
1937 In the first application of ``f``, we had to do some more type
1938 reconstruction in order to recover the result type of ``f``. But after
1939 that, we are free to use ``f`` normally.
1940
1941 Limitations
1942 ~~~~~~~~~~~
1943
1944 -  When stopped at a breakpoint, if you try to evaluate a variable that
1945    is already under evaluation, the second evaluation will hang. The
1946    reason is that GHC knows the variable is under evaluation, so the new
1947    evaluation just waits for the result before continuing, but of course
1948    this isn't going to happen because the first evaluation is stopped at
1949    a breakpoint. Control-C can interrupt the hung evaluation and return
1950    to the prompt.
1951
1952    The most common way this can happen is when you're evaluating a CAF
1953    (e.g. main), stop at a breakpoint, and ask for the value of the CAF
1954    at the prompt again.
1955
1956 -  Implicit parameters (see :ref:`implicit-parameters`) are only
1957    available at the scope of a breakpoint if there is an explicit type
1958    signature.
1959
1960 .. _ghci-invocation:
1961
1962 Invoking GHCi
1963 -------------
1964
1965 .. index::
1966    single: invoking; GHCi
1967    single: --interactive
1968
1969 GHCi is invoked with the command ``ghci`` or ``ghc --interactive``. One
1970 or more modules or filenames can also be specified on the command line;
1971 this instructs GHCi to load the specified modules or filenames (and all
1972 the modules they depend on), just as if you had said ``:load modules``
1973 at the GHCi prompt (see :ref:`ghci-commands`). For example, to start
1974 GHCi and load the program whose topmost module is in the file
1975 ``Main.hs``, we could say:
1976
1977 .. code-block:: none
1978
1979     $ ghci Main.hs
1980
1981 Most of the command-line options accepted by GHC (see :ref:`using-ghc`)
1982 also make sense in interactive mode. The ones that don't make sense are
1983 mostly obvious.
1984
1985 .. ghc-flag:: -flocal-ghci-history
1986     :shortdesc: Use current directory for the GHCi command history
1987         file ``.ghci-history``.
1988     :type: dynamic
1989     :reverse: -fno-local-ghci-history
1990     :category:
1991
1992     By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or
1993     ``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.:
1994
1995     .. code-block:: none
1996
1997         $ ghci -flocal-ghci-history
1998
1999     It will create ``.ghci-history`` in current folder where GHCi is launched.
2000
2001 Packages
2002 ~~~~~~~~
2003
2004 .. index::
2005    single: packages; with GHCi
2006
2007 Most packages (see :ref:`using-packages`) are available without needing
2008 to specify any extra flags at all: they will be automatically loaded the
2009 first time they are needed.
2010
2011 For hidden packages, however, you need to request the package be loaded
2012 by using the :ghc-flag:`-package ⟨pkg⟩` flag:
2013
2014 .. code-block:: none
2015
2016     $ ghci -package readline
2017     GHCi, version 8.y.z: http://www.haskell.org/ghc/  :? for help
2018     Loading package base ... linking ... done.
2019     Loading package readline-1.0 ... linking ... done.
2020     Prelude>
2021
2022 The following command works to load new packages into a running GHCi:
2023
2024 .. code-block:: none
2025
2026     Prelude> :set -package name
2027
2028 But note that doing this will cause all currently loaded modules to be
2029 unloaded, and you'll be dumped back into the ``Prelude``.
2030
2031 Extra libraries
2032 ~~~~~~~~~~~~~~~
2033
2034 .. index::
2035    single: libraries; with GHCi
2036
2037 Extra libraries may be specified on the command line using the normal
2038 ``-llib`` option. (The term *library* here refers to libraries of
2039 foreign object code; for using libraries of Haskell source code, see
2040 :ref:`ghci-modules-filenames`.) For example, to load the “m” library:
2041
2042 .. code-block:: none
2043
2044     $ ghci -lm
2045
2046 On systems with ``.so``-style shared libraries, the actual library
2047 loaded will the ``liblib.so``. GHCi searches the following places for
2048 libraries, in this order:
2049
2050 -  Paths specified using the :ghc-flag:`-L ⟨dir⟩` command-line option,
2051
2052 -  the standard library search path for your system, which on some
2053    systems may be overridden by setting the :envvar:`LD_LIBRARY_PATH`
2054    environment variable.
2055
2056 On systems with ``.dll``-style shared libraries, the actual library
2057 loaded will be ``lib.dll``. Again, GHCi will signal an error if it can't
2058 find the library.
2059
2060 GHCi can also load plain object files (``.o`` or ``.obj`` depending on
2061 your platform) from the command-line. Just add the name the object file
2062 to the command line.
2063
2064 Ordering of ``-l`` options matters: a library should be mentioned
2065 *before* the libraries it depends on (see :ref:`options-linker`).
2066
2067 .. _ghci-commands:
2068
2069 GHCi commands
2070 -------------
2071
2072 GHCi commands all begin with "``:``" and consist of a single command
2073 name followed by zero or more parameters. The command name may be
2074 abbreviated, with ambiguities being resolved in favour of the more
2075 commonly used commands.
2076
2077 .. comment
2078
2079     This section makes use of the GHC-specific :directive:`ghci-cmd` directive
2080     defined in :file:`conf.py`. This is used to describe and cross-reference GHCi
2081     commands.
2082
2083
2084 .. ghci-cmd:: :abandon
2085
2086     Abandons the current evaluation (only available when stopped at a
2087     breakpoint).
2088
2089 .. ghci-cmd:: :add;[*] ⟨module⟩
2090
2091     Add ⟨module⟩(s) to the current target set, and perform a reload.
2092     Normally pre-compiled code for the module will be loaded if
2093     available, or otherwise the module will be compiled to byte-code.
2094     Using the ``*`` prefix forces the module to be loaded as byte-code.
2095
2096     ⟨module⟩ may be a file path. A "``~``" symbol at the beginning of
2097     ⟨module⟩  will be replaced by the contents of the environment variable
2098     :envvar:`HOME`.
2099
2100 .. ghci-cmd:: :all-types
2101
2102     List all types collected for expressions and (local) bindings
2103     currently loaded (while :ghci-cmd:`:set +c` was active) with their respective
2104     source-code span, e.g. ::
2105
2106        GhciTypes> :all-types
2107        GhciTypes.hs:(38,13)-(38,24): Maybe Id
2108        GhciTypes.hs:(45,10)-(45,29): Outputable SpanInfo
2109        GhciTypes.hs:(45,10)-(45,29): (Rational -> SpanInfo -> SDoc) -> Outputable SpanInfo
2110
2111 .. ghci-cmd:: :back; ⟨n⟩
2112
2113     Travel back ⟨n⟩ steps in the history. ⟨n⟩ is one if omitted. See
2114     :ref:`tracing` for more about GHCi's debugging facilities. See also:
2115     :ghci-cmd:`:trace`, :ghci-cmd:`:history`, :ghci-cmd:`:forward`.
2116
2117 .. ghci-cmd:: :break; [⟨identifier⟩ | [⟨module⟩] ⟨line⟩ [⟨column⟩]]
2118
2119     Set a breakpoint on the specified function or line and column. See
2120     :ref:`setting-breakpoints`.
2121
2122 .. ghci-cmd:: :browse;[!] [[*] ⟨module⟩]
2123
2124     Displays the identifiers exported by the module ⟨module⟩, which must
2125     be either loaded into GHCi or be a member of a package. If ⟨module⟩
2126     is omitted, the most recently-loaded module is used.
2127
2128     Like all other GHCi commands, the output is always displayed in the
2129     current GHCi scope (:ref:`ghci-scope`).
2130
2131     There are two variants of the browse command:
2132
2133     -  If the ``*`` symbol is placed before the module name, then *all*
2134        the identifiers in scope in ⟨module⟩ (rather that just its
2135        exports) are shown.
2136
2137        The ``*``-form is only available for modules which are
2138        interpreted; for compiled modules (including modules from
2139        packages) only the non-\ ``*`` form of :ghci-cmd:`:browse` is available.
2140
2141     -  Data constructors and class methods are usually displayed in the
2142        context of their data type or class declaration. However, if the
2143        ``!`` symbol is appended to the command, thus ``:browse!``, they
2144        are listed individually. The ``!``-form also annotates the
2145        listing with comments giving possible imports for each group of
2146        entries. Here is an example: ::
2147
2148            Prelude> :browse! Data.Maybe
2149            -- not currently imported
2150            Data.Maybe.catMaybes :: [Maybe a] -> [a]
2151            Data.Maybe.fromJust :: Maybe a -> a
2152            Data.Maybe.fromMaybe :: a -> Maybe a -> a
2153            Data.Maybe.isJust :: Maybe a -> Bool
2154            Data.Maybe.isNothing :: Maybe a -> Bool
2155            Data.Maybe.listToMaybe :: [a] -> Maybe a
2156            Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
2157            Data.Maybe.maybeToList :: Maybe a -> [a]
2158            -- imported via Prelude
2159            Just :: a -> Maybe a
2160            data Maybe a = Nothing | Just a
2161            Nothing :: Maybe a
2162            maybe :: b -> (a -> b) -> Maybe a -> b
2163
2164        This output shows that, in the context of the current session (ie
2165        in the scope of ``Prelude``), the first group of items from
2166        ``Data.Maybe`` are not in scope (althought they are available in
2167        fully qualified form in the GHCi session - see
2168        :ref:`ghci-scope`), whereas the second group of items are in
2169        scope (via ``Prelude``) and are therefore available either
2170        unqualified, or with a ``Prelude.`` qualifier.
2171
2172 .. ghci-cmd:: :cd; ⟨dir⟩
2173
2174     Changes the current working directory to ⟨dir⟩. A "``~``" symbol
2175     at the beginning of ⟨dir⟩ will be replaced by the contents of the
2176     environment variable :envvar:`HOME`. See also the :ghci-cmd:`:show paths`
2177     command for showing the current working directory.
2178
2179     Note: changing directories causes all currently loaded modules to be
2180     unloaded. This is because the search path is usually expressed using
2181     relative directories, and changing the search path in the middle of
2182     a session is not supported.
2183
2184 .. ghci-cmd:: :cmd; ⟨expr⟩
2185
2186     Executes ⟨expr⟩ as a computation of type ``IO String``, and then
2187     executes the resulting string as a list of GHCi commands. Multiple
2188     commands are separated by newlines. The :ghci-cmd:`:cmd` command is useful
2189     with :ghci-cmd:`:def` and :ghci-cmd:`:set stop`.
2190
2191 .. ghci-cmd:: :complete; ⟨type⟩ [⟨n⟩-][⟨m⟩] ⟨string-literal⟩
2192
2193     This command allows to request command completions from GHCi even
2194     when interacting over a pipe instead of a proper terminal and is
2195     designed for integrating GHCi's completion with text editors and
2196     IDEs.
2197
2198     When called, :ghci-cmd:`:complete` prints the ⟨n⟩\ :sup:`th` to
2199     ⟨m⟩\ :sup:`th` completion candidates for the partial input
2200     ⟨string-literal⟩ for the completion domain denoted by ⟨type⟩.
2201     Currently, only the ``repl`` domain is supported which denotes the
2202     kind of completion that would be provided interactively by GHCi at
2203     the input prompt.
2204
2205     If omitted, ⟨n⟩ and ⟨m⟩ default to the first or last available
2206     completion candidate respectively. If there are less candidates than
2207     requested via the range argument, ⟨n⟩ and ⟨m⟩ are implicitly capped
2208     to the number of available completion candidates.
2209
2210     The output of :ghci-cmd:`:complete` begins with a header line containing
2211     three space-delimited fields:
2212
2213     -  An integer denoting the number ``l`` of printed completions,
2214     -  an integer denoting the total number of completions available,
2215        and finally
2216     -  a string literal denoting a common prefix to be added to the
2217        returned completion candidates.
2218
2219     The header line is followed by ⟨l⟩ lines each containing one
2220     completion candidate encoded as (quoted) string literal. Here are
2221     some example invocations showing the various cases:
2222
2223     .. code-block:: none
2224
2225         Prelude> :complete repl 0 ""
2226         0 470 ""
2227         Prelude> :complete repl 5 "import For"
2228         5 21 "import "
2229         "Foreign"
2230         "Foreign.C"
2231         "Foreign.C.Error"
2232         "Foreign.C.String"
2233         "Foreign.C.Types"
2234         Prelude> :complete repl 5-10 "import For"
2235         6 21 "import "
2236         "Foreign.C.Types"
2237         "Foreign.Concurrent"
2238         "Foreign.ForeignPtr"
2239         "Foreign.ForeignPtr.Safe"
2240         "Foreign.ForeignPtr.Unsafe"
2241         "Foreign.Marshal"
2242         Prelude> :complete repl 20- "import For"
2243         2 21 "import "
2244         "Foreign.StablePtr"
2245         "Foreign.Storable"
2246         Prelude> :complete repl "map"
2247         3 3 ""
2248         "map"
2249         "mapM"
2250         "mapM_"
2251         Prelude> :complete repl 5-10 "map"
2252         0 3 ""
2253
2254 .. ghci-cmd:: :continue
2255
2256     Continue the current evaluation, when stopped at a breakpoint.
2257
2258 .. ghci-cmd:: :ctags; [⟨filename⟩]
2259
2260     Generates a "tags" file for Vi-style editors (:ghci-cmd:`:ctags`) or
2261     Emacs-style editors (:ghci-cmd:`:etags`). If no filename is specified, the
2262     default ``tags`` or ``TAGS`` is used, respectively. Tags for all the
2263     functions, constructors and types in the currently loaded modules
2264     are created. All modules must be interpreted for these commands to
2265     work.
2266
2267 .. ghci-cmd:: :def;[!] ⟨name⟩ ⟨expr⟩
2268
2269     :ghci-cmd:`:def` is used to define new commands, or macros, in GHCi. The
2270     command ``:def ⟨name⟩ ⟨expr⟩`` defines a new GHCi command ``:name``,
2271     implemented by the Haskell expression ⟨expr⟩, which must have type
2272     ``String -> IO String``. When ``:name args`` is typed at the prompt,
2273     GHCi will run the expression ``(name args)``, take the resulting
2274     ``String``, and feed it back into GHCi as a new sequence of
2275     commands. Separate commands in the result must be separated by
2276     "``\n``".
2277
2278     That's all a little confusing, so here's a few examples. To start
2279     with, here's a new GHCi command which doesn't take any arguments or
2280     produce any results, it just outputs the current date and time:
2281
2282     .. code-block:: none
2283
2284         Prelude> let date _ = Data.Time.getZonedTime >>= print >> return ""
2285         Prelude> :def date date
2286         Prelude> :date
2287         2017-04-10 12:34:56.93213581 UTC
2288
2289     Here's an example of a command that takes an argument. It's a
2290     re-implementation of :ghci-cmd:`:cd`:
2291
2292     .. code-block:: none
2293
2294         Prelude> let mycd d = System.Directory.setCurrentDirectory d >> return ""
2295         Prelude> :def mycd mycd
2296         Prelude> :mycd ..
2297
2298     Or I could define a simple way to invoke "``ghc --make Main``"
2299     in the current directory:
2300
2301     .. code-block:: none
2302
2303         Prelude> :def make (\_ -> return ":! ghc --make Main")
2304
2305     We can define a command that reads GHCi input from a file. This
2306     might be useful for creating a set of bindings that we want to
2307     repeatedly load into the GHCi session:
2308
2309     .. code-block:: none
2310
2311         Prelude> :def . readFile
2312         Prelude> :. cmds.ghci
2313
2314     Notice that we named the command ``:.``, by analogy with the
2315     "``.``" Unix shell command that does the same thing.
2316
2317     Typing ``:def`` on its own lists the currently-defined macros.
2318     Attempting to redefine an existing command name results in an error
2319     unless the ``:def!`` form is used, in which case the old command
2320     with that name is silently overwritten.
2321
2322 .. ghci-cmd:: :delete; * | ⟨num⟩ ...
2323
2324     Delete one or more breakpoints by number (use :ghci-cmd:`:show breaks` to
2325     see the number of each breakpoint). The ``*`` form deletes all the
2326     breakpoints.
2327
2328 .. ghci-cmd:: :edit; ⟨file⟩
2329
2330     Opens an editor to edit the file ⟨file⟩, or the most recently loaded
2331     module if ⟨file⟩ is omitted. If there were errors during the last
2332     loading, the cursor will be positioned at the line of the first
2333     error. The editor to invoke is taken from the :envvar:`EDITOR` environment
2334     variable, or a default editor on your system if :envvar:`EDITOR` is not
2335     set. You can change the editor using :ghci-cmd:`:set editor`.
2336
2337 .. ghci-cmd:: :etags
2338
2339     See :ghci-cmd:`:ctags`.
2340
2341 .. ghci-cmd:: :force; ⟨identifier⟩ ...
2342
2343     Prints the value of ⟨identifier⟩ in the same way as :ghci-cmd:`:print`.
2344     Unlike :ghci-cmd:`:print`, :ghci-cmd:`:force` evaluates each thunk that it
2345     encounters while traversing the value. This may cause exceptions or
2346     infinite loops, or further breakpoints (which are ignored, but
2347     displayed).
2348
2349 .. ghci-cmd:: :forward; ⟨n⟩
2350
2351     Move forward ⟨n⟩ steps in the history. ⟨n⟩ is one if omitted. See
2352     :ref:`tracing` for more about GHCi's debugging facilities. See also:
2353     :ghci-cmd:`:trace`, :ghci-cmd:`:history`, :ghci-cmd:`:back`.
2354
2355 .. ghci-cmd:: :help
2356               :?
2357
2358     Displays a list of the available commands.
2359
2360 .. ghci-cmd:: :
2361
2362     .. index::
2363        pair: Repeating last command; in GHCi
2364
2365     Repeat the previous command.
2366
2367 .. ghci-cmd:: :history; [num]
2368
2369     Display the history of evaluation steps. With a number, displays
2370     that many steps (default: 20). For use with :ghci-cmd:`:trace`; see
2371     :ref:`tracing`. To set the number of history entries stored by GHCi,
2372     use the :ghc-flag:`-fghci-hist-size=⟨n⟩` flag.
2373
2374 .. ghci-cmd:: :info;[!] ⟨name⟩
2375
2376     Displays information about the given name(s). For example, if ⟨name⟩
2377     is a class, then the class methods and their types will be printed;
2378     if ⟨name⟩ is a type constructor, then its definition will be
2379     printed; if ⟨name⟩ is a function, then its type will be printed. If
2380     ⟨name⟩ has been loaded from a source file, then GHCi will also
2381     display the location of its definition in the source.
2382
2383     For types and classes, GHCi also summarises instances that mention
2384     them. To avoid showing irrelevant information, an instance is shown
2385     only if (a) its head mentions ⟨name⟩, and (b) all the other things
2386     mentioned in the instance are in scope (either qualified or
2387     otherwise) as a result of a :ghci-cmd:`:load` or :ghci-cmd:`:module`
2388     commands.
2389
2390     The command ``:info!`` works in a similar fashion but it removes
2391     restriction (b), showing all instances that are in scope and mention
2392     ⟨name⟩ in their head.
2393
2394 .. ghci-cmd:: :issafe; [⟨module⟩]
2395
2396     Displays Safe Haskell information about the given module (or the
2397     current module if omitted). This includes the trust type of the
2398     module and its containing package.
2399
2400 .. ghci-cmd:: :kind;[!] ⟨type⟩
2401
2402     Infers and prints the kind of ⟨type⟩. The latter can be an arbitrary
2403     type expression, including a partial application of a type
2404     constructor, such as ``Either Int``. In fact, :ghci-cmd:`:kind` even allows
2405     you to write a partial application of a type synonym (usually
2406     disallowed), so that this works:
2407
2408     .. code-block:: none
2409
2410         ghci> type T a b = (a,b,a)
2411         ghci> :k T Int Bool
2412         T Int Bool :: *
2413         ghci> :k T
2414         T :: * -> * -> *
2415         ghci> :k T Int
2416         T Int :: * -> *
2417
2418     If you specify the optional "``!``", GHC will in addition normalise
2419     the type by expanding out type synonyms and evaluating type-function
2420     applications, and display the normalised result.
2421
2422 .. ghci-cmd:: :list; ⟨identifier⟩
2423
2424     Lists the source code around the definition of ⟨identifier⟩ or the
2425     current breakpoint if not given. This requires that the identifier
2426     be defined in an interpreted module. If your output device supports
2427     it, then GHCi will highlight the active subexpression in bold.
2428
2429 .. ghci-cmd:: :list [⟨module⟩]; ⟨line⟩
2430
2431     Lists the source code around the given line number of ⟨module⟩. This
2432     requires that the module be interpreted. If your output device
2433     supports it, then GHCi will highlight the active subexpression in
2434     bold.
2435
2436 .. ghci-cmd:: :load;[!] [*]⟨module⟩
2437
2438     Recursively loads the specified ⟨module⟩s, and all the modules they
2439     depend on. Here, each ⟨module⟩ must be a module name or filename,
2440     but may not be the name of a module in a package.
2441
2442     All previously loaded modules, except package modules, are
2443     forgotten. The new set of modules is known as the target set. Note
2444     that :ghci-cmd:`:load` can be used without any arguments to unload all the
2445     currently loaded modules and bindings.
2446
2447     Normally pre-compiled code for a module will be loaded if available,
2448     or otherwise the module will be compiled to byte-code. Using the
2449     ``*`` prefix forces a module to be loaded as byte-code.
2450
2451     Adding the optional "``!``" turns type errors into warnings while
2452     loading. This allows to use the portions of the module that are
2453     correct, even if there are type errors in some definitions.
2454     Effectively, the "-fdefer-type-errors" flag is set before loading
2455     and unset after loading if the flag has not already been set before.
2456     See :ref:`defer-type-errors` for further motivation and details.
2457
2458     After a :ghci-cmd:`:load` command, the current context is set to:
2459
2460     -  ⟨module⟩, if it was loaded successfully, or
2461
2462     -  the most recently successfully loaded module, if any other
2463        modules were loaded as a result of the current :ghci-cmd:`:load`, or
2464
2465     -  ``Prelude`` otherwise.
2466
2467 .. ghci-cmd:: :loc-at; ⟨module⟩ ⟨line⟩ ⟨col⟩ ⟨end-line⟩ ⟨end-col⟩ [⟨name⟩]
2468
2469     Tries to find the definition site of the name at the given
2470     source-code span, e.g.:
2471
2472     .. code-block:: none
2473
2474         X> :loc-at X.hs 6 14 6 16 mu
2475         X.hs:(8,7)-(8,9)
2476
2477     This command is useful when integrating GHCi with text editors and
2478     IDEs for providing a goto-definition facility.
2479
2480     The ``:loc-at`` command requires :ghci-cmd:`:set +c` to be set.
2481
2482 .. ghci-cmd:: :main; ⟨arg1⟩ ... ⟨argn⟩
2483
2484     When a program is compiled and executed, it can use the ``getArgs``
2485     function to access the command-line arguments. However, we cannot
2486     simply pass the arguments to the ``main`` function while we are
2487     testing in ghci, as the ``main`` function doesn't take its arguments
2488     directly.
2489
2490     Instead, we can use the :ghci-cmd:`:main` command. This runs whatever
2491     ``main`` is in scope, with any arguments being treated the same as
2492     command-line arguments, e.g.:
2493
2494     .. code-block:: none
2495
2496         Prelude> main = System.Environment.getArgs >>= print
2497         Prelude> :main foo bar
2498         ["foo","bar"]
2499
2500     We can also quote arguments which contains characters like spaces,
2501     and they are treated like Haskell strings, or we can just use
2502     Haskell list syntax:
2503
2504     .. code-block:: none
2505
2506         Prelude> :main foo "bar baz"
2507         ["foo","bar baz"]
2508         Prelude> :main ["foo", "bar baz"]
2509         ["foo","bar baz"]
2510
2511     Finally, other functions can be called, either with the ``-main-is``
2512     flag or the :ghci-cmd:`:run` command:
2513
2514     .. code-block:: none
2515
2516         Prelude> foo = putStrLn "foo" >> System.Environment.getArgs >>= print
2517         Prelude> bar = putStrLn "bar" >> System.Environment.getArgs >>= print
2518         Prelude> :set -main-is foo
2519         Prelude> :main foo "bar baz"
2520         foo
2521         ["foo","bar baz"]
2522         Prelude> :run bar ["foo", "bar baz"]
2523         bar
2524         ["foo","bar baz"]
2525
2526 .. ghci-cmd:: :module; +|- [*]⟨mod1⟩ ...
2527 .. ghci-cmd:: import; ⟨mod⟩
2528
2529     Sets or modifies the current context for statements typed at the
2530     prompt. The form ``import mod`` is equivalent to ``:module +mod``.
2531     See :ref:`ghci-scope` for more details.
2532
2533 .. ghci-cmd:: :print; ⟨names⟩
2534
2535     Prints a value without forcing its evaluation. :ghci-cmd:`:print` may be
2536     used on values whose types are unknown or partially known, which
2537     might be the case for local variables with polymorphic types at a
2538     breakpoint. While inspecting the runtime value, :ghci-cmd:`:print` attempts
2539     to reconstruct the type of the value, and will elaborate the type in
2540     GHCi's environment if possible. If any unevaluated components
2541     (thunks) are encountered, then :ghci-cmd:`:print` binds a fresh variable
2542     with a name beginning with ``_t`` to each thunk. See
2543     :ref:`breakpoints` for more information. See also the :ghci-cmd:`:sprint`
2544     command, which works like :ghci-cmd:`:print` but does not bind new
2545     variables.
2546
2547 .. ghci-cmd:: :quit
2548
2549     Quits GHCi. You can also quit by typing :kbd:`Control-D` at the prompt.
2550
2551 .. ghci-cmd:: :reload;[!]
2552
2553     Attempts to reload the current target set (see :ghci-cmd:`:load`) if any of
2554     the modules in the set, or any dependent module, has changed. Note
2555     that this may entail loading new modules, or dropping modules which
2556     are no longer indirectly required by the target.
2557
2558     Adding the optional "``!``" turns type errors into warnings while
2559     loading. This allows to use the portions of the module that are
2560     correct, even if there are type errors in some definitions.
2561     Effectively, the "-fdefer-type-errors" flag is set before loading
2562     and unset after loading if the flag has not already been set before.
2563     See :ref:`defer-type-errors` for further motivation and details.
2564
2565 .. ghci-cmd:: :run
2566
2567     See :ghci-cmd:`:main`.
2568
2569 .. ghci-cmd:: :script; [⟨n⟩] ⟨filename⟩
2570
2571     Executes the lines of a file as a series of GHCi commands. This
2572     command is compatible with multiline statements as set by
2573     :ghci-cmd:`:set +m`
2574
2575 .. ghci-cmd:: :set; [⟨option⟩ ...]
2576
2577     Sets various options. See :ref:`ghci-set` for a list of available
2578     options and :ref:`interactive-mode-options` for a list of
2579     GHCi-specific flags. The :ghci-cmd:`:set` command by itself shows which
2580     options are currently set. It also lists the current dynamic flag
2581     settings, with GHCi-specific flags listed separately.
2582
2583 .. ghci-cmd:: :set args; ⟨arg⟩
2584
2585     .. index::
2586        single: getArgs, behavior in GHCi
2587
2588     Sets the list of arguments which are returned when the program calls
2589     ``System.getArgs``.
2590
2591 .. ghci-cmd:: :set editor; ⟨cmd⟩
2592
2593     Sets the command used by :ghci-cmd:`:edit` to ⟨cmd⟩.
2594
2595 .. ghci-cmd:: :set prog; ⟨prog⟩
2596
2597     .. index::
2598        single: getProgName, behavior in GHCi
2599
2600     Sets the string to be returned when the program calls
2601     ``System.getProgName``.
2602
2603 .. ghci-cmd:: :set prompt; ⟨prompt⟩
2604
2605     .. index::
2606        single: GHCi prompt; setting
2607
2608     Sets the string to be used as the prompt in GHCi. Inside ⟨prompt⟩,
2609     the next sequences are replaced:
2610
2611     - ``%s`` by the names of the modules currently in scope.
2612     - ``%l`` by the line number (as referenced in compiler messages) of the
2613       current prompt.
2614     - ``%d`` by the date in "Weekday Month Date" format (e.g., "Tue May 26") .
2615     - ``%t`` by the current time in 24-hour HH:MM:SS format.
2616     - ``%T`` by the current time in 12-hour HH:MM:SS format.
2617     - ``%@`` by the current time in 12-hour am/pm format.
2618     - ``%A`` by the current time in 24-hour HH:MM format.
2619     - ``%u`` by the username of the current user.
2620     - ``%w`` by the current working directory.
2621     - ``%o`` by the operating system.
2622     - ``%a`` by the machine architecture.
2623     - ``%N`` by the compiler name.
2624     - ``%V`` by the compiler version.
2625     - ``%call(cmd [args])`` by the result of calling ``cmd args``.
2626     - ``%%`` by ``%``.
2627
2628     If ⟨prompt⟩ starts with ``"`` then it is parsed as a Haskell String;
2629     otherwise it is treated as a literal string.
2630
2631 .. ghci-cmd:: :set prompt-cont; ⟨prompt⟩
2632
2633     Sets the string to be used as the continuation prompt (used when
2634     using the :ghci-cmd:`:{` command) in GHCi.
2635
2636 .. ghci-cmd:: :set prompt-function; ⟨prompt-function⟩
2637
2638     .. index::
2639        single: GHCi prompt function; setting
2640
2641     Sets the function to be used for the prompt displaying in GHCi. The
2642     function should be of the type ``[String] -> Int -> IO String``. This
2643     function is called each time the prompt is being made. The first argument
2644     stands for the names of the modules currently in scope(the name of the
2645     "topmost" module  will begin with a ``*``; see  :ref:`ghci-scope` for
2646     more information). The second arguments is the line number (as referenced
2647     in compiler  messages) of the current prompt.
2648
2649 .. ghci-cmd:: :set prompt-cont-function; ⟨prompt-function⟩
2650
2651    Sets the function to be used for the continuation prompt (used when
2652    using the :ghci-cmd:`:{` command) displaying in GHCi.
2653
2654 .. ghci-cmd:: :set stop; ⟨num⟩ ⟨cmd⟩
2655
2656     Set a command to be executed when a breakpoint is hit, or a new item
2657     in the history is selected. The most common use of :ghci-cmd:`:set stop` is
2658     to display the source code at the current location, e.g.
2659     ``:set stop :list``.
2660
2661     If a number is given before the command, then the commands are run
2662     when the specified breakpoint (only) is hit. This can be quite
2663     useful: for example, ``:set stop 1 :continue`` effectively disables
2664     breakpoint 1, by running :ghci-cmd:`:continue` whenever it is hit (although
2665     GHCi will still emit a message to say the breakpoint was hit). What's more,
2666     with cunning use of :ghci-cmd:`:def` and :ghci-cmd:`:cmd` you can use
2667     :ghci-cmd:`:set stop` to implement conditional breakpoints:
2668
2669     .. code-block:: none
2670
2671         *Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
2672         *Main> :set stop 0 :cond (x < 3)
2673
2674     Ignoring breakpoints for a specified number of iterations is also
2675     possible using similar techniques.
2676
2677 .. ghci-cmd:: :seti; [⟨option⟩ ...]
2678
2679     Like :ghci-cmd:`:set`, but options set with :ghci-cmd:`:seti` affect only
2680     expressions and commands typed at the prompt, and not modules loaded
2681     with :ghci-cmd:`:load` (in contrast, options set with :ghci-cmd:`:set` apply
2682     everywhere). See :ref:`ghci-interactive-options`.
2683
2684     Without any arguments, displays the current set of options that are
2685     applied to expressions and commands typed at the prompt.
2686
2687 .. ghci-cmd:: :show bindings
2688
2689     Show the bindings made at the prompt and their types.
2690
2691 .. ghci-cmd:: :show breaks
2692
2693     List the active breakpoints.
2694
2695 .. ghci-cmd:: :show context
2696
2697     List the active evaluations that are stopped at breakpoints.
2698
2699 .. ghci-cmd:: :show imports
2700
2701     Show the imports that are currently in force, as created by
2702     ``import`` and :ghci-cmd:`:module` commands.
2703
2704 .. ghci-cmd:: :show modules
2705
2706     Show the list of modules currently loaded.
2707
2708 .. ghci-cmd:: :show packages
2709
2710     Show the currently active package flags, as well as the list of
2711     packages currently loaded.
2712
2713 .. ghci-cmd:: :show paths
2714
2715     Show the current working directory (as set via :ghci-cmd:`:cd` command), as
2716     well as the list of directories searched for source files (as set by the
2717     ``-i`` option).
2718
2719 .. ghci-cmd:: :show language
2720
2721     Show the currently active language flags for source files.
2722
2723 .. ghci-cmd:: :showi language
2724
2725     Show the currently active language flags for expressions typed at
2726     the prompt (see also :ghci-cmd:`:seti`).
2727
2728 .. ghci-cmd:: :show; [args|prog|prompt|editor|stop]
2729
2730     Displays the specified setting (see :ghci-cmd:`:set`).
2731
2732 .. ghci-cmd:: :sprint; ⟨expr⟩
2733
2734     Prints a value without forcing its evaluation. :ghci-cmd:`:sprint` is
2735     similar to :ghci-cmd:`:print`, with the difference that unevaluated subterms
2736     are not bound to new variables, they are simply denoted by ``_``.
2737
2738 .. ghci-cmd:: :step; [⟨expr⟩]
2739
2740     Enable all breakpoints and begin evaluating an expression in
2741     single-stepping mode. In this mode evaluation will be stopped after
2742     every reduction, allowing local variables to be inspected. If ⟨expr⟩
2743     is not given, evaluation will resume at the last breakpoint. See
2744     :ref:`single-stepping`.
2745
2746 .. ghci-cmd:: :steplocal
2747
2748     Enable only breakpoints in the current top-level binding and resume
2749     evaluation at the last breakpoint.
2750
2751 .. ghci-cmd:: :stepmodule
2752
2753     Enable only breakpoints in the current module and resume evaluation
2754     at the last breakpoint.
2755
2756 .. ghci-cmd:: :trace; ⟨expr⟩
2757
2758     Evaluates the given expression (or from the last breakpoint if no
2759     expression is given), and additionally logs the evaluation steps for
2760     later inspection using :ghci-cmd:`:history`. See :ref:`tracing`.
2761
2762 .. ghci-cmd:: :type; ⟨expression⟩
2763
2764     Infers and prints the type of ⟨expression⟩, including explicit
2765     forall quantifiers for polymorphic types.
2766     The type reported is the type that would be inferred
2767     for a variable assigned to the expression, but without the
2768     monomorphism restriction applied.
2769
2770     .. code-block:: none
2771
2772         *X> :type length
2773         length :: Foldable t => t a -> Int
2774
2775 .. ghci-cmd:: :type +v; ⟨expression⟩
2776
2777     Infers and prints the type of ⟨expression⟩, but without fiddling
2778     with type variables or class constraints. This is useful when you
2779     are using :extension:`TypeApplications` and care about the distinction
2780     between specified type variables (available for type application)
2781     and inferred type variables (not available). This mode sometimes prints
2782     constraints (such as ``Show Int``) that could readily be solved, but
2783     solving these constraints may affect the type variables, so GHC refrains.
2784
2785     .. code-block:: none
2786
2787         *X> :set -fprint-explicit-foralls
2788         *X> :type +v length
2789         length :: forall (t :: * -> *). Foldable t => forall a. t a -> Int
2790
2791 .. ghci-cmd:: :type +d; ⟨expression⟩
2792
2793     Infers and prints the type of ⟨expression⟩, defaulting type variables
2794     if possible. In this mode, if the inferred type is constrained by
2795     any interactive class (``Num``, ``Show``, ``Eq``, ``Ord``, ``Foldable``,
2796     or ``Traversable``), the constrained type variable(s) are defaulted
2797     according to the rules described under :extension:`ExtendedDefaultRules`.
2798     This mode is quite useful when the inferred type is quite general (such
2799     as for ``foldr``) and it may be helpful to see a more concrete
2800     instantiation.
2801
2802     .. code-block:: none
2803
2804         *X> :type +d length
2805         length :: [a] -> Int
2806
2807 .. ghci-cmd:: :type-at; ⟨module⟩ ⟨line⟩ ⟨col⟩ ⟨end-line⟩ ⟨end-col⟩ [⟨name⟩]
2808
2809     Reports the inferred type at the given span/position in the module, e.g.:
2810
2811     .. code-block:: none
2812
2813        *X> :type-at X.hs 6 6 6 7 f
2814        Int -> Int
2815
2816     This command is useful when integrating GHCi with text editors and
2817     IDEs for providing a show-type-under-point facility.
2818
2819     The last string parameter is useful for when the span is out of
2820     date, i.e. the file changed and the code has moved. In which case
2821     :ghci-cmd:`:type-at` falls back to a general :ghci-cmd:`:type` like lookup.
2822
2823     The :ghci-cmd:`:type-at` command requires :ghci-cmd:`:set +c` to be set.
2824
2825 .. ghci-cmd:: :undef; ⟨name⟩
2826
2827     Undefines the user-defined command ⟨name⟩ (see :ghci-cmd:`:def` above).
2828
2829 .. ghci-cmd:: :unset; ⟨option⟩
2830
2831     Unsets certain options. See :ref:`ghci-set` for a list of available
2832     options.
2833
2834 .. ghci-cmd:: :uses; ⟨module⟩ ⟨line⟩ ⟨col⟩ ⟨end-line⟩ ⟨end-col⟩ [⟨name⟩]
2835
2836     Reports all module-local uses of the thing at the given position
2837     in the module, e.g.:
2838
2839     .. code-block:: none
2840
2841        :uses GhciFind.hs 53 66 53 70 name
2842        GhciFind.hs:(46,25)-(46,29)
2843        GhciFind.hs:(47,37)-(47,41)
2844        GhciFind.hs:(53,66)-(53,70)
2845        GhciFind.hs:(57,62)-(57,66)
2846
2847     This command is useful for highlighting and navigating all uses of
2848     an identifier in editors and IDEs.
2849
2850     The :ghci-cmd:`:uses` command requires :ghci-cmd:`:set +c` to be set.
2851
2852 .. ghci-cmd:: :! ⟨command⟩
2853
2854     .. index::
2855        single: shell commands; in GHCi
2856
2857     Executes the shell command ⟨command⟩.
2858
2859
2860 .. _ghci-set:
2861
2862 The ``:set`` and ``:seti`` commands
2863 -----------------------------------
2864
2865 .. index::
2866    single: :set; command in GHCi
2867    single: :seti
2868
2869 The :ghci-cmd:`:set` command sets two types of options: GHCi options, which
2870 begin with "``+``", and "command-line" options, which begin with "``-``".
2871
2872 .. note::
2873     At the moment, the :ghci-cmd:`:set` command doesn't support any kind of
2874     quoting in its arguments: quotes will not be removed and cannot be used
2875     to group words together. For example, ``:set -DFOO='BAR BAZ'`` will not
2876     do what you expect.
2877
2878 GHCi options
2879 ~~~~~~~~~~~~
2880
2881 .. index::
2882    single: options; GHCi
2883
2884 GHCi options may be set using :ghci-cmd:`:set` and unset using :ghci-cmd:`:unset`.
2885
2886 The available GHCi options are:
2887
2888 .. ghci-cmd:: :set +c
2889
2890     Collect type and location information after loading modules.
2891     The commands :ghci-cmd:`:all-types`, :ghci-cmd:`:loc-at`,
2892     :ghci-cmd:`:type-at`, and :ghci-cmd:`:uses` require ``+c`` to be active.
2893
2894 .. ghci-cmd:: :set +m
2895
2896     .. index::
2897        single: multiline input; in GHCi
2898
2899     Enable parsing of multiline commands. A multiline command is
2900     prompted for when the current input line contains open layout
2901     contexts (see :ref:`ghci-multiline`).
2902
2903 .. ghci-cmd:: :set +r
2904
2905     .. index::
2906        single: CAFs; in GHCi
2907        single: Constant Applicative Form
2908
2909     Normally, any evaluation of top-level expressions (otherwise known
2910     as CAFs or Constant Applicative Forms) in loaded modules is retained
2911     between evaluations. Turning on ``+r`` causes all evaluation of
2912     top-level expressions to be discarded after each evaluation (they
2913     are still retained *during* a single evaluation).
2914
2915     This option may help if the evaluated top-level expressions are
2916     consuming large amounts of space, or if you need repeatable
2917     performance measurements.
2918
2919 .. ghci-cmd:: :set +s
2920
2921     Display some stats after evaluating each expression, including the
2922     elapsed time and number of bytes allocated. NOTE: the allocation
2923     figure is only accurate to the size of the storage manager's
2924     allocation area, because it is calculated at every GC. Hence, you
2925     might see values of zero if no GC has occurred.
2926
2927 .. ghci-cmd:: :set +t
2928
2929     .. index::
2930        single: displaying type; in GHCi
2931
2932     Display the type of each variable bound after a statement is entered
2933     at the prompt. If the statement is a single expression, then the
2934     only variable binding will be for the variable ``it``.
2935
2936 .. _ghci-cmd-line-options:
2937
2938 Setting GHC command-line options in GHCi
2939 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2940
2941 Normal GHC command-line options may also be set using :ghci-cmd:`:set`. For
2942 example, to turn on :ghc-flag:`-Wmissing-signatures`, you would say:
2943
2944 .. code-block:: none
2945
2946     Prelude> :set -Wmissing-signatures
2947
2948 Any GHC command-line option that is designated as dynamic (see the table
2949 in :ref:`flag-reference`), may be set using :ghci-cmd:`:set`. To unset an
2950 option, you can set the reverse option:
2951
2952 .. index::
2953    single: dynamic; options
2954
2955 .. code-block:: none
2956
2957     Prelude> :set -Wno-incomplete-patterns -XNoMultiParamTypeClasses
2958
2959 :ref:`flag-reference` lists the reverse for each option where
2960 applicable.
2961
2962 Certain static options (:ghc-flag:`-package ⟨pkg⟩`, :ghc-flag:`-I⟨dir⟩`,
2963 :ghc-flag:`-i⟨dir⟩[:⟨dir⟩]*`, and :ghc-flag:`-l ⟨lib⟩` in particular) will also
2964 work, but some may not take effect until the next reload.
2965
2966 .. index::
2967    single: static; options
2968
2969 .. _ghci-interactive-options:
2970
2971 Setting options for interactive evaluation only
2972 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2973
2974 GHCi actually maintains *two* sets of options:
2975
2976 -  The *loading options* apply when loading modules
2977
2978 -  The *interactive options* apply when evaluating expressions and
2979    commands typed at the GHCi prompt.
2980
2981 The :ghci-cmd:`:set` command modifies both, but there is also a
2982 :ghci-cmd:`:seti` command (for "set interactive") that affects only the
2983 interactive options set.
2984
2985 It is often useful to change the interactive options, without having
2986 that option apply to loaded modules too. For example
2987
2988 .. code-block:: none
2989
2990     :seti -XMonoLocalBinds
2991
2992 It would be undesirable if :extension:`MonoLocalBinds` were to apply to loaded
2993 modules too: that might cause a compilation error, but more commonly it
2994 will cause extra recompilation, because GHC will think that it needs to
2995 recompile the module because the flags have changed.
2996
2997 If you are setting language options in your ``.ghci`` file, it is good
2998 practice to use :ghci-cmd:`:seti` rather than :ghci-cmd:`:set`, unless you
2999 really do want them to apply to all modules you load in GHCi.
3000
3001 The two sets of options can be inspected using the :ghci-cmd:`:set` and
3002 :ghci-cmd:`:seti` commands respectively, with no arguments. For example, in a
3003 clean GHCi session we might see something like this:
3004
3005 .. code-block:: none
3006
3007     Prelude> :seti
3008     base language is: Haskell2010
3009     with the following modifiers:
3010       -XNoMonomorphismRestriction
3011       -XNoDatatypeContexts
3012       -XNondecreasingIndentation
3013       -XExtendedDefaultRules
3014     GHCi-specific dynamic flag settings:
3015     other dynamic, non-language, flag settings:
3016       -fimplicit-import-qualified
3017     warning settings:
3018
3019 The two sets of options are initialised as follows. First, both sets of
3020 options are initialised as described in :ref:`ghci-dot-files`. Then the
3021 interactive options are modified as follows:
3022
3023 -  The option ``-XExtendedDefaultRules`` is enabled, in order to apply
3024    special defaulting rules to expressions typed at the prompt (see
3025    :ref:`extended-default-rules`).
3026
3027 -  The Monomorphism Restriction is disabled (see :ref:`monomorphism`).
3028
3029 .. _ghci-dot-files:
3030
3031 The ``.ghci`` and ``.haskeline`` files
3032 --------------------------------------
3033
3034 .. _dot-ghci-files:
3035
3036 The ``.ghci`` files
3037 ~~~~~~~~~~~~~~~~~~~
3038
3039 .. index::
3040    single: .ghci; file
3041    single: startup; files, GHCi
3042
3043 When it starts, unless the :ghc-flag:`-ignore-dot-ghci` flag is given, GHCi
3044 reads and executes commands from the following files, in this order, if
3045 they exist:
3046
3047 1. :file:`./.ghci`
3048
3049 2. :file:`{appdata}/ghc/ghci.conf`, where ⟨appdata⟩ depends on your system,
3050    but is usually something like
3051    :file:`C:/Documents and Settings/user/Application Data`
3052
3053 3. On Unix: :file:`$HOME/.ghc/ghci.conf`
3054
3055 4. :file:`$HOME/.ghci`
3056
3057 The :file:`ghci.conf` file is most useful for turning on favourite options
3058 (e.g. ``:set +s``), and defining useful macros.
3059
3060 .. note::
3061     When setting language options in this file it is usually desirable to use
3062     :ghci-cmd:`:seti` rather than :ghci-cmd:`:set` (see :ref:`ghci-interactive-options`).
3063
3064 Placing a :file:`.ghci` file in a directory with a Haskell project is a
3065 useful way to set certain project-wide options so you don't have to type
3066 them every time you start GHCi: eg. if your project uses multi-parameter
3067 type classes, scoped type variables, and CPP, and has source files in
3068 three subdirectories A, B and C, you might put the following lines in
3069 :file:`.ghci`:
3070
3071 .. code-block:: none
3072
3073     :set -XMultiParamTypeClasses -XScopedTypeVariables -cpp
3074     :set -iA:B:C
3075
3076 (Note that strictly speaking the :ghc-flag:`-i` flag is a static one, but in
3077 fact it works to set it using :ghci-cmd:`:set` like this. The changes won't take
3078 effect until the next :ghci-cmd:`:load`, though.)
3079
3080 Once you have a library of GHCi macros, you may want to source them from
3081 separate files, or you may want to source your ``.ghci`` file into your
3082 running GHCi session while debugging it
3083
3084 .. code-block:: none
3085
3086     :def source readFile
3087
3088 With this macro defined in your ``.ghci`` file, you can use
3089 ``:source file`` to read GHCi commands from ``file``. You can find (and
3090 contribute!-) other suggestions for ``.ghci`` files on this Haskell wiki
3091 page: `GHC/GHCi <http://haskell.org/haskellwiki/GHC/GHCi>`__
3092
3093 Additionally, any files specified with :ghc-flag:`-ghci-script` flags will be
3094 read after the standard files, allowing the use of custom .ghci files.
3095
3096 Two command-line options control whether the startup files files are
3097 read:
3098
3099 .. ghc-flag:: -ignore-dot-ghci
3100     :shortdesc: Disable reading of ``.ghci`` files
3101     :type: dynamic
3102     :category:
3103
3104     Don't read either :file:`./.ghci` or the other startup files when
3105     starting up.
3106
3107 .. ghc-flag:: -ghci-script
3108     :shortdesc: Read additional ``.ghci`` files
3109     :type: dynamic
3110     :category:
3111
3112     Read a specific file after the usual startup files. Maybe be
3113     specified repeatedly for multiple inputs.
3114
3115 When defining GHCi macros, there is some important behavior you should
3116 be aware of when names may conflict with built-in commands, especially
3117 regarding tab completion.
3118
3119 For example, consider if you had a macro named ``:time`` and in the
3120 shell, typed ``:t 3`` — what should happen? The current algorithm we use
3121 for completing commands is:
3122
3123 1. First, look up an exact match on the name from the defined macros.
3124
3125 2. Look for the exact match on the name in the built-in command list.
3126
3127 3. Do a prefix lookup on the list of built-in commands - if a built-in
3128    command matches, but a macro is defined with the same name as the
3129    built-in defined, pick the macro.
3130
3131 4. Do a prefix lookup on the list of built-in commands.
3132
3133 5. Do a prefix lookup on the list of defined macros.
3134
3135 Here are some examples:
3136
3137 1. You have a macro ``:time`` and enter ``:t 3``
3138
3139    You get ``:type 3``
3140
3141 2. You have a macro ``:type`` and enter ``:t 3``
3142
3143    You get ``:type 3`` with your defined macro, not the builtin.
3144
3145 3. You have a macro ``:time`` and a macro ``:type``, and enter ``:t 3``
3146
3147    You get ``:type 3`` with your defined macro.
3148
3149 .. _dot-haskeline-file:
3150
3151 The ``.haskeline`` file
3152 ~~~~~~~~~~~~~~~~~~~~~~~
3153
3154 .. index::
3155    single: .haskeline; file
3156    single: startup; files, GHCi
3157
3158 GHCi uses `Haskeline <https://hackage.haskell.org/package/haskeline>`__ under
3159 the hood. You can configure it to, among other
3160 things, prune duplicates from GHCi history. See:
3161 `Haskeline user preferences <http://trac.haskell.org/haskeline/wiki/UserPrefs>`__.
3162
3163 .. _ghci-obj:
3164
3165 Compiling to object code inside GHCi
3166 ------------------------------------
3167
3168 By default, GHCi compiles Haskell source code into byte-code that is
3169 interpreted by the runtime system. GHCi can also compile Haskell code to
3170 object code: to turn on this feature, use the :ghc-flag:`-fobject-code` flag
3171 either on the command line or with :ghci-cmd:`:set` (the option :ghc-flag:`-fbyte-code`
3172 restores byte-code compilation again). Compiling to object code takes
3173 longer, but typically the code will execute 10-20 times faster than
3174 byte-code.
3175
3176 Compiling to object code inside GHCi is particularly useful if you are
3177 developing a compiled application, because the :ghci-cmd:`:reload` command
3178 typically runs much faster than restarting GHC with :ghc-flag:`--make` from the
3179 command-line, because all the interface files are already cached in
3180 memory.
3181
3182 There are disadvantages to compiling to object-code: you can't set
3183 breakpoints in object-code modules, for example. Only the exports of an
3184 object-code module will be visible in GHCi, rather than all top-level
3185 bindings as in interpreted modules.
3186
3187 .. _external-interpreter:
3188
3189 Running the interpreter in a separate process
3190 ---------------------------------------------
3191
3192 Normally GHCi runs the interpreted code in the same process as GHC
3193 itself, on top of the same RTS and sharing the same heap.  However, if
3194 the flag :ghc-flag:`-fexternal-interpreter` is given, then GHC will spawn a
3195 separate process for running interpreted code, and communicate with it
3196 using messages over a pipe.
3197
3198 .. ghc-flag:: -fexternal-interpreter
3199     :shortdesc: Run interpreted code in a separate process
3200     :type: dynamic
3201     :category: misc
3202
3203     :since: 8.0.1
3204
3205     Run interpreted code (for GHCi, Template Haskell, Quasi-quoting,
3206     or Annotations) in a separate process.  The interpreter will run
3207     in profiling mode if :ghc-flag:`-prof` is in effect, and in
3208     dynamically-linked mode if :ghc-flag:`-dynamic` is in effect.
3209
3210     There are a couple of caveats that will hopefully be removed in
3211     the future: this option is currently not implemented on Windows
3212     (it is a no-op), and the external interpreter does not support the
3213     GHCi debugger, so breakpoints and single-stepping don't work with
3214     :ghc-flag:`-fexternal-interpreter`.
3215
3216     See also the :ghc-flag:`-pgmi ⟨cmd⟩` (:ref:`replacing-phases`) and
3217     :ghc-flag:`-opti ⟨option⟩` (:ref:`forcing-options-through`) flags.
3218
3219 Why might we want to do this?  The main reason is that the RTS running
3220 the interpreted code can be a different flavour (profiling or
3221 dynamically-linked) from GHC itself.  So for example:
3222
3223 - We can use the profiler to collect stack traces when using GHCi (see
3224   :ref:`ghci-stack-traces`).
3225
3226 - When compiling Template Haskell code with :ghc-flag:`-prof` we don't need to
3227   compile the modules without :ghc-flag:`-prof` first (see :ref:`th-profiling`)
3228   because we can run the profiled object code in the interpreter.
3229
3230 This feature is experimental in GHC 8.0.x, but it may become the
3231 default in future releases.
3232
3233 .. _ghci-faq:
3234
3235 FAQ and Things To Watch Out For
3236 -------------------------------
3237
3238 The interpreter can't load modules with foreign export declarations!
3239     Unfortunately not. We haven't implemented it yet. Please compile any
3240     offending modules by hand before loading them into GHCi.
3241
3242 :ghc-flag:`-O` doesn't work with GHCi!
3243
3244     .. index::
3245        single: optimization; and GHCi
3246
3247     For technical reasons, the bytecode compiler doesn't interact well
3248     with one of the optimisation passes, so we have disabled
3249     optimisation when using the interpreter. This isn't a great loss:
3250     you'll get a much bigger win by compiling the bits of your code that
3251     need to go fast, rather than interpreting them with optimisation
3252     turned on.
3253
3254 Unboxed tuples don't work with GHCi
3255     That's right. You can always compile a module that uses unboxed
3256     tuples and load it into GHCi, however. (Incidentally the previous
3257     point, namely that :ghc-flag:`-O` is incompatible with GHCi, is because the
3258     bytecode compiler can't deal with unboxed tuples).
3259
3260 Concurrent threads don't carry on running when GHCi is waiting for input.
3261     This should work, as long as your GHCi was built with the
3262     :ghc-flag:`-threaded` switch, which is the default. Consult whoever supplied
3263     your GHCi installation.
3264
3265
3266 After using ``getContents``, I can't use ``stdin``, until I do ``:load`` or ``:reload``
3267     This is the defined behaviour of ``getContents``: it puts the stdin
3268     Handle in a state known as semi-closed, wherein any further I/O
3269     operations on it are forbidden. Because I/O state is retained
3270     between computations, the semi-closed state persists until the next
3271     :ghci-cmd:`:load` or :ghci-cmd:`:reload` command.
3272
3273     You can make ``stdin`` reset itself after every evaluation by giving
3274     GHCi the command ``:set +r``. This works because ``stdin`` is just a
3275     top-level expression that can be reverted to its unevaluated state
3276     in the same way as any other top-level expression (CAF).
3277
3278 I can't use :kbd:`Control-C` to interrupt computations in GHCi on Windows.
3279     See :ref:`ghci-windows`.
3280
3281 The default buffering mode is different in GHCi to GHC.
3282     In GHC, the stdout handle is line-buffered by default. However, in
3283     GHCi we turn off the buffering on stdout, because this is normally
3284     what you want in an interpreter: output appears as it is generated.
3285
3286     If you want line-buffered behaviour, as in GHC, you can start your
3287     program thus: ::
3288
3289         main = do { hSetBuffering stdout LineBuffering; ... }
3290
3291
3292 .. [5]
3293    Note that packages only contain compiled code, so debugging a package
3294    requires finding its source and loading that directly.
3295
3296 .. [6]
3297    We originally provided bindings for all variables in scope, rather
3298    than just the free variables of the expression, but found that this
3299    affected performance considerably, hence the current restriction to
3300    just the free variables.