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