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