X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=b27781c332b3310416d5022c6c6fa7c1628a4c26;hb=d7df1559b3f44603e78062e9eed5c13a453aa7f4;hp=26efdee4f74a06f60ff1a11074670284405b4b67;hpb=8eb677bc6758080886aa8b21340cc3470b249b75;p=ghc-hetmet.git
diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 26efdee..b27781c 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -14,11 +14,13 @@
, then you'll be right at home with GHCi. However, GHCi
also has support for interactively loading compiled code, as well as
supporting allexcept foreign export, at the moment
- the language extensions that GHC provides.
+ the language extensions that GHC provides.
FFIGHCi support
- Foreign Function InterfaceGHCi support
+ Foreign Function
+ InterfaceGHCi support.
+ GHCi also includes an interactive debugger (see )..
-
+ Introduction to GHCiLet's start with an example GHCi session. You can fire up
@@ -49,6 +51,8 @@ Prelude>
:browse [*]<module> display the names defined by <module>
:cd <dir> change directory to <dir>
:def <cmd> <expr> define a command :<cmd>
+ :edit <file> edit file
+ :edit edit last module
:help, :? display this list of commands
:info [<name> ...] display information about the given names
:load <filename> ... load module(s) and their dependents
@@ -60,12 +64,13 @@ Prelude>
:set args <arg> ... set the arguments returned by System.getArgs
:set prog <progname> set the value returned by System.getProgName
:set prompt <prompt> set the prompt used in GHCi
+ :set editor <cmd> set the command used for :edit
:show modules show the currently loaded modules
:show bindings show the current bindings made at the prompt
:ctags [<file>] create tags file for Vi (default: "tags")
- :etags [<file>] create tags file for Emacs (defauilt: "TAGS")
+ :etags [<file>] create tags file for Emacs (default: "TAGS")
:type <expr> show the type of <expr>
:kind <type> show the kind of <type>
:undef <cmd> undefine user-defined command :<cmd>
@@ -103,7 +108,7 @@ Prelude>
enter, GHCi will attempt to evaluate it.
-
+ Loading source filesSuppose we have the following Haskell source code, which we
@@ -360,7 +365,7 @@ Ok, modules loaded: A, B, C, D.
-
+ Interactive evaluation at the promptWhen you type an expression at the prompt, GHCi immediately
@@ -402,7 +407,7 @@ hello
-
+ Using do-notation at the promptdo-notationin GHCistatementsin GHCi
@@ -444,7 +449,13 @@ Prelude>
Show
-
+ The automatic printing of binding results can be supressed with
+ (this does not
+ supress printing the result of non-binding statements).
+ .
+ You might want to do this to prevent the result of binding
+ statements from being fully evaluated by the act of printing
+ them, for example.
Of course, you can also bind normal non-IO expressions
using the let-statement:
@@ -566,7 +577,9 @@ hello
Prelude IO>
- (Note: :module can be shortened to
+ (Note: you can use import M as an
+ alternative to :module +M, and
+ :module can also be shortened to
:m). The full syntax of the
:module command is:
@@ -604,6 +617,12 @@ Prelude IO>
behaves in the same way for expressions typed at the
prompt.
+
+ Hint: GHCi will tab-complete names that are in scope; for
+ example, if you run GHCi and type J<tab>
+ then GHCi will expand it to Just .
+
+
Qualified names
@@ -732,25 +751,803 @@ it <- e
standard rules take each group of constraints (C1 a, C2 a, ..., Cn
a) for each type variable a, and defaults the
type variable if
-
- The type variable a
- appears in no other constraints
- All the classes Ci are standard.
- At least one of the classes Ci is
- numeric.
+
+
+
+ The type variable a appears in no
+ other constraints
+
+
+
+
+ All the classes Ci are standard.
+
+
+
+
+ At least one of the classes Ci is
+ numeric.
+
+
+
+ At the GHCi prompt, or with GHC if the
+ -fextended-default-rules flag is given,
+ the following additional differences apply:
+
+
+
+ Rule 2 above is relaxed thus:
+ All of the classes
+ Ci are single-parameter type classes.
+
+
+
+
+ Rule 3 above is relaxed this:
+ At least one of the classes Ci is
+ numeric, or is Show,
+ Eq, or
+ Ord.
+
+
+
+
+ The unit type () is added to the
+ start of the standard list of types which are tried when
+ doing type defaulting.
+
+
+
+ The last point means that, for example, this program:
+
+main :: IO ()
+main = print def
+
+instance Num ()
+
+def :: (Num a, Enum a) => a
+def = toEnum 0
+
+ prints () rather than 0 as the
+ type is defaulted to () rather than
+ Integer.
+
+
+ The motivation for the change is that it means IO a
+ actions default to IO (), which in turn means that
+ ghci won't try to print a result when running them. This is
+ particularly important for printf, which has an
+ instance that returns IO a.
+ However, it is only able to return
+ undefined
+ (the reason for the instance having this type is to not require
+ extensions to the class system), so if the type defaults to
+ Integer then ghci gives an error when running a
+ printf.
+
+
+
+
+
+ The GHCi Debugger
+ debuggerin GHCi
+
+
+ GHCi contains a simple imperative-style debugger in which you can
+ stop a running computation in order to examine the values of
+ variables. The debugger is integrated into GHCi, and is turned on by
+ default: no flags are required to enable the debugging facilities. There
+ is one major restriction: breakpoints and single-stepping are only
+ available in interpreted modules; compiled code is
+ invisible to the debugger.
+
+ The debugger provides the following:
+
+
+ The abilty to set a breakpoint on a
+ function definition or expression in the program. When the function
+ is called, or the expression evaluated, GHCi suspends
+ execution and returns to the prompt, where you can inspect the
+ values of local variables before continuing with the
+ execution.
+
+
+ Execution can be single-stepped: the
+ evaluator will suspend execution approximately after every
+ reduction, allowing local variables to be inspected. This is
+ equivalent to setting a breakpoint at every point in the
+ program.
+
+
+ Execution can take place in tracing
+ mode, in which the evaluator remembers each
+ evaluation step as it happens, but doesn't suspend execution until
+ an actual breakpoint is reached. When this happens, the history of
+ evaluation steps can be inspected.
+
+
+ Exceptions (e.g. pattern matching failure and
+ error) can be treated as breakpoints, to help
+ locate the source of an exception in the program.
+
- At the GHCi prompt, the second and third rules are relaxed as follows
- (differences italicised):
-
- All of the classes
- Ci are single-parameter type classes.
- At least one of the classes Ci is
- numeric, or is Show,
- Eq, or Ord.
+
+
+ There is currently no support for obtaining a “stack
+ trace”, but the tracing and history features provide a useful
+ second-best, which will often be enough to establish the context of an
+ error.
+
+
+ Breakpoints and inspecting variables
+
+ Let's use quicksort as a running example. Here's the code:
+
+
+qsort [] = []
+qsort (a:as) = qsort left ++ [a] ++ qsort right
+ where (left,right) = (filter (<=a) as, filter (>a) as)
+
+main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+
+
+ First, load the module into GHCi:
+
+
+Prelude> :l qsort.hs
+[1 of 1] Compiling Main ( qsort.hs, interpreted )
+Ok, modules loaded: Main.
+*Main>
+
+
+ Now, let's set a breakpoint on the right-hand-side of the second
+ equation of qsort:
+
+
+*Main> :break 2
+Breakpoint 0 activated at qsort.hs:2:15-46
+*Main>
+
+
+ The command :break 2 sets a breakpoint on line
+ 2 of the most recently-loaded module, in this case
+ qsort.hs. Specifically, it picks the
+ leftmost complete subexpression on that line on which to set the
+ breakpoint, which in this case is the expression
+ (qsort left ++ [a] ++ qsort right).
+
+ Now, we run the program:
+
+
+*Main> main
+Stopped at qsort.hs:2:15-46
+_result :: [a]
+a :: a
+left :: [a]
+right :: [a]
+[qsort.hs:2:15-46] *Main>
+
+
+ Execution has stopped at the breakpoint. The prompt has changed to
+ indicate that we are currently stopped at a breakpoint, and the location:
+ [qsort.hs:2:15-46]. To further clarify the
+ location, we can use the :list command:
+
+
+[qsort.hs:2:15-46] *Main> :list
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+
+
+ The :list command lists the source code around
+ the current breakpoint. If your output device supports it, then GHCi
+ will highlight the active subexpression in bold.
+
+ GHCi has provided bindings for the free variablesWe
+ originally provided bindings for all variables in scope, rather
+ than just
+ the free variables of the expression, but found that this affected
+ performance considerably, hence the current restriction to just the
+ free variables.
+ of the expression
+ on which the
+ breakpoint was placed (a, left,
+ right), and additionally a binding for the result of
+ the expression (_result). These variables are just
+ like other variables that you might define in GHCi; you
+ can use them in expressions that you type at the prompt, you can ask
+ for their types with :type, and so on. There is one
+ important difference though: these variables may only have partial
+ types. For example, if we try to display the value of
+ left:
+
+
+[qsort.hs:2:15-46] *Main> left
+
+<interactive>:1:0:
+ Ambiguous type variable `a' in the constraint:
+ `Show a' arising from a use of `print' at <interactive>:1:0-3
+ Cannot resolve unknown runtime types: a
+ Use :print or :force to determine these types
+
+
+ This is because qsort is a polymorphic function,
+ and because GHCi does not carry type information at runtime, it cannot
+ determine the runtime types of free variables that involve type
+ variables. Hence, when you ask to display left at
+ the prompt, GHCi can't figure out which instance of
+ Show to use, so it emits the type error above.
+
+ Fortunately, the debugger includes a generic printing command,
+ :print, which can inspect the actual runtime value of a
+ variable and attempt to reconstruct its type. If we try it on
+ left:
+
+
+[qsort.hs:2:15-46] *Main> :print left
+left = (_t1::[a])
+
+
+ This isn't particularly enlightening. What happened is that
+ left is bound to an unevaluated computation (a
+ suspension, or thunk), and
+ :print does not force any evaluation. The idea is
+ that :print can be used to inspect values at a
+ breakpoint without any unfortunate side effects. It won't force any
+ evaluation, which could cause the program to give a different answer
+ than it would normally, and hence it won't cause any exceptions to be
+ raised, infinite loops, or further breakpoints to be triggered (see
+ ).
+ Rather than forcing thunks, :print
+ binds each thunk to a fresh variable beginning with an
+ underscore, in this case
+ _t1.
+
+ If we aren't concerned about preserving the evaluatedness of a
+ variable, we can use :force instead of
+ :print. The :force command
+ behaves exactly like :print, except that it forces
+ the evaluation of any thunks it encounters:
+
+
+[qsort.hs:2:15-46] *Main> :force left
+left = [4,0,3,1]
+
+
+ Now, since :force has inspected the runtime
+ value of left, it has reconstructed its type. We
+ can see the results of this type reconstruction:
+
+
+[qsort.hs:2:15-46] *Main> :show bindings
+_result :: [Integer]
+a :: Integer
+left :: [Integer]
+right :: [Integer]
+_t1 :: [Integer]
+
+
+ Not only do we now know the type of left, but
+ all the other partial types have also been resolved. So we can ask
+ for the value of a, for example:
+
+
+[qsort.hs:2:15-46] *Main> a
+8
+
+
+ You might find it useful to use Haskell's
+ seq function to evaluate individual thunks rather
+ than evaluating the whole expression with :force.
+ For example:
+
+
+[qsort.hs:2:15-46] *Main> :print right
+right = (_t1::[Integer])
+[qsort.hs:2:15-46] *Main> seq _t1 ()
+()
+[qsort.hs:2:15-46] *Main> :print right
+right = 23 : (_t2::[Integer])
+
+
+ We evaluated only the _t1 thunk, revealing the
+ head of the list, and the tail is another thunk now bound to
+ _t2. The seq function is a
+ little inconvenient to use here, so you might want to use
+ :def to make a nicer interface (left as an exercise
+ for the reader!).
+
+ Finally, we can continue the current execution:
+
+
+[qsort.hs:2:15-46] *Main> :continue
+Stopped at qsort.hs:2:15-46
+_result :: [a]
+a :: a
+left :: [a]
+right :: [a]
+[qsort.hs:2:15-46] *Main>
+
+
+ The execution continued at the point it previously stopped, and has
+ now stopped at the breakpoint for a second time.
+
+
+ Setting breakpoints
+
+ Breakpoints can be set in various ways. Perhaps the easiest way to
+ set a breakpoint is to name a top-level function:
+
+
+ :break identifier
+
+
+ Where identifier names any top-level
+ function in an interpreted module currently loaded into GHCi (qualified
+ names may be used). The breakpoint will be set on the body of the
+ function, when it is fully applied but before any pattern matching has
+ taken place.
+
+ Breakpoints can also be set by line (and optionally column)
+ number:
+
+
+ :break line
+ :break linecolumn
+ :break moduleline
+ :break modulelinecolumn
+
+
+ When a breakpoint is set on a particular line, GHCi sets the
+ breakpoint on the
+ leftmost subexpression that begins and ends on that line. If two
+ complete subexpressions start at the same
+ column, the longest one is picked. If there is no complete
+ subexpression on the line, then the leftmost expression starting on
+ the line is picked, and failing that the rightmost expression that
+ partially or completely covers the line.
+
+ When a breakpoint is set on a particular line and column, GHCi
+ picks the smallest subexpression that encloses that location on which
+ to set the breakpoint. Note: GHC considers the TAB character to have a
+ width of 1, wherever it occurs; in other words it counts
+ characters, rather than columns. This matches what some editors do,
+ and doesn't match others. The best advice is to avoid tab
+ characters in your source code altogether (see
+ in ).
+
+ If the module is omitted, then the most recently-loaded module is
+ used.
+
+ Not all subexpressions are potential breakpoint locations. Single
+ variables are typically not considered to be breakpoint locations
+ (unless the variable is the right-hand-side of a function definition,
+ lambda, or case alternative). The rule of thumb is that all redexes
+ are breakpoint locations, together with the bodies of functions,
+ lambdas, case alternatives and binding statements. There is normally
+ no breakpoint on a let expression, but there will always be a
+ breakpoint on its body, because we are usually interested in inspecting
+ the values of the variables bound by the let.
+
+
+
+ Listing and deleting breakpoints
+
+ The list of breakpoints currently enabled can be displayed using
+ :show breaks:
+
+*Main> :show breaks
+[0] Main qsort.hs:1:11-12
+[1] Main qsort.hs:2:15-46
+
+
+ To delete a breakpoint, use the :delete
+ command with the number given in the output from :show breaks:
+
+
+*Main> :delete 0
+*Main> :show breaks
+[1] Main qsort.hs:2:15-46
+
+
+ To delete all breakpoints at once, use :delete *.
+
+
+
+
+
+ Single-stepping
+
+ Single-stepping is a great way to visualise the execution of your
+ program, and it is also a useful tool for identifying the source of a
+ bug. The concept is simple: single-stepping enables all the
+ breakpoints in the program and executes until the next breakpoint is
+ reached, at which point you can single-step again, or continue
+ normally. For example:
+
+
+*Main> :step main
+Stopped at qsort.hs:5:7-47
+_result :: IO ()
+
+
+ The command :step
+ expr begins the evaluation of
+ expr in single-stepping mode. If
+ expr is ommitted, then it single-steps from
+ the current breakpoint.
+
+ The :list command is particularly useful when
+ single-stepping, to see where you currently are:
+
+
+[qsort.hs:5:7-47] *Main> :list
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:7-47] *Main>
+
+
+ In fact, GHCi provides a way to run a command when a breakpoint is
+ hit, so we can make it automatically do
+ :list:
+
+
+[qsort.hs:5:7-47] *Main> :set stop :list
+[qsort.hs:5:7-47] *Main> :step
+Stopped at qsort.hs:5:14-46
+_result :: [Integer]
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:14-46] *Main>
+
+
+
+
+ Nested breakpoints
+ When GHCi is stopped at a breakpoint, and an expression entered at
+ the prompt triggers a
+ second breakpoint, the new breakpoint becomes the “current”
+ one, and the old one is saved on a stack. An arbitrary number of
+ breakpoint contexts can be built up in this way. For example:
+
+
+[qsort.hs:2:15-46] *Main> :st qsort [1,3]
+Stopped at qsort.hs:(1,0)-(3,55)
+_result :: [a]
+... [qsort.hs:(1,0)-(3,55)] *Main>
+
+
+ While stopped at the breakpoint on line 2 that we set earlier, we
+ started a new evaluation with :step qsort [1,3].
+ This new evaluation stopped after one step (at the definition of
+ qsort). The prompt has changed, now prefixed with
+ ..., to indicate that there are saved breakpoints
+ beyond the current one. To see the stack of contexts, use
+ :show context:
+
+
+... [qsort.hs:(1,0)-(3,55)] *Main> :show context
+--> main
+ Stopped at qsort.hs:2:15-46
+--> qsort [1,3]
+ Stopped at qsort.hs:(1,0)-(3,55)
+... [qsort.hs:(1,0)-(3,55)] *Main>
+
+
+ To abandon the current evaluation, use
+ :abandon:
+
+
+... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
+[qsort.hs:2:15-46] *Main> :abandon
+*Main>
+
+
+
+
+ The _result variable
+ When stopped at a breakpoint or single-step, GHCi binds the
+ variable _result to the value of the currently
+ active expression. The value of _result is
+ presumably not available yet, because we stopped its evaluation, but it
+ can be forced: if the type is known and showable, then just entering
+ _result at the prompt will show it. However,
+ there's one caveat to doing this: evaluating _result
+ will be likely to trigger further breakpoints, starting with the
+ breakpoint we are currently stopped at (if we stopped at a real
+ breakpoint, rather than due to :step). So it will
+ probably be necessary to issue a :continue
+ immediately when evaluating _result. Alternatively,
+ you can use :force which ignores breakpoints.
+
+
+
+ Tracing and history
+
+ A question that we often want to ask when debugging a program is
+ “how did I get here?”. Traditional imperative debuggers
+ usually provide some kind of stack-tracing feature that lets you see
+ the stack of active function calls (sometimes called the “lexical
+ call stack”), describing a path through the code
+ to the current location. Unfortunately this is hard to provide in
+ Haskell, because execution proceeds on a demand-driven basis, rather
+ than a depth-first basis as in strict languages. The
+ “stack“ in GHC's execution engine bears little
+ resemblance to the lexical call stack. Ideally GHCi would maintain a
+ separate lexical call stack in addition to the dynamic call stack, and
+ in fact this is exactly
+ what our profiling system does (), and what
+ some other Haskell debuggers do. For the time being, however, GHCi
+ doesn't maintain a lexical call stack (there are some technical
+ challenges to be overcome). Instead, we provide a way to backtrack from a
+ breakpoint to previous evaluation steps: essentially this is like
+ single-stepping backwards, and should in many cases provide enough
+ information to answer the “how did I get here?”
+ question.
+
+ To use tracing, evaluate an expression with the
+ :trace command. For example, if we set a breakpoint
+ on the base case of qsort:
+
+
+*Main> :list qsort
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+4
+*Main> :b 1
+Breakpoint 1 activated at qsort.hs:1:11-12
+*Main>
+
+
+ and then run a small qsort with
+ tracing:
+
+
+*Main> :trace qsort [3,2,1]
+Stopped at qsort.hs:1:11-12
+_result :: [a]
+[qsort.hs:1:11-12] *Main>
+
+
+ We can now inspect the history of evaluation steps:
+
+
+[qsort.hs:1:11-12] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:3:24-38
+-7 : qsort.hs:3:23-55
+-8 : qsort.hs:(1,0)-(3,55)
+-9 : qsort.hs:2:15-24
+-10 : qsort.hs:2:15-46
+-11 : qsort.hs:3:24-38
+-12 : qsort.hs:3:23-55
+-13 : qsort.hs:(1,0)-(3,55)
+-14 : qsort.hs:2:15-24
+-15 : qsort.hs:2:15-46
+-16 : qsort.hs:(1,0)-(3,55)
+<end of history>
+
+
+ To examine one of the steps in the history, use
+ :back:
+
+
+[qsort.hs:1:11-12] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main>
+
+
+ Note that the local variables at each step in the history have been
+ preserved, and can be examined as usual. Also note that the prompt has
+ changed to indicate that we're currently examining the first step in
+ the history: -1. The command
+ :forward can be used to traverse forward in the
+ history.
+
+ The :trace command can be used with or without
+ an expression. When used without an expression, tracing begins from
+ the current breakpoint, just like :step.
+
+ The history is only available when
+ using :trace; the reason for this is we found that
+ logging each breakpoint in the history cuts performance by a factor of
+ 2 or more. GHCi remembers the last 50 steps in the history (perhaps in
+ the future we'll make this configurable).
+
+
+
+ Debugging exceptions
+ Another common question that comes up when debugging is
+ “where did this exception come from?”. Exceptions such as
+ those raised by error or head []
+ have no context information attached to them. Finding which
+ particular call to head in your program resulted in
+ the error can be a painstaking process, usually involving
+ Debug.Trace.trace, or compiling with
+ profiling and using +RTS -xc (see ).
+
+ The GHCi debugger offers a way to hopefully shed some light on
+ these errors quickly and without modifying or recompiling the source
+ code. One way would be to set a breakpoint on the location in the
+ source code that throws the exception, and then use
+ :trace and :history to establish
+ the context. However, head is in a library and
+ we can't set a breakpoint on it directly. For this reason, GHCi
+ provides the flag -fbreak-on-exception which causes
+ the evaluator to stop when an exception is thrown, just as it does when
+ a breakpoint is hit. This is only really useful in conjunction with
+ :trace, in order to log the steps leading up to the
+ exception. For example:
+
+
+*Main> :set -fbreak-on-exception
+*Main> :trace qsort ("abc" ++ undefined)
+"Stopped at <exception thrown>
+_exception :: e
+[<exception thrown>] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:(1,0)-(3,55)
+<end of history>
+[<exception thrown>] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main> :force as
+*** Exception: Prelude.undefined
+[-1: qsort.hs:3:24-38] *Main> :print as
+as = 'b' : 'c' : (_t1::[Char])
+
+
+ The exception itself is bound to a new variable,
+ _exception.
+
+ Breaking on exceptions is particularly useful for finding out what
+ your program was doing when it was in an infinite loop. Just hit
+ Control-C, and examine the history to find out what was going
+ on.
+
+
+ Example: inspecting functions
+
+ It is possible to use the debugger to examine function values.
+ When we are at a breakpoint and a function is in scope, the debugger
+ cannot show
+ you the source code for it; however, it is possible to get some
+ information by applying it to some arguments and observing the result.
+
+
+
+ The process is slightly complicated when the binding is polymorphic.
+ We show the process by means of an example.
+ To keep things simple, we will use the well known map function:
+
+import Prelude hiding (map)
+
+map :: (a->b) -> a -> b
+map f [] = []
+map f (x:xs) = f x : map f xs
+
+
+
+
+ We set a breakpoint on map, and call it.
+
+*Main> :break 5
+Breakpoint 0 activated at map.hs:5:15-28
+*Main> map Just [1..5]
+Stopped at map.hs:(4,0)-(5,12)
+_result :: [b]
+x :: a
+f :: a -> b
+xs :: [a]
+
+ GHCi tells us that, among other bindings, f is in scope.
+ However, its type is not fully known yet,
+ and thus it is not possible to apply it to any
+ arguments. Nevertheless, observe that the type of its first argument is the
+ same as the type of x, and its result type is shared
+ with _result.
+
+
+
+ As we demonstrated earlier (), the
+ debugger has some intelligence built-in to update the type of
+ f whenever the types of x or
+ _result are discovered. So what we do in this
+ scenario is
+ force x a bit, in order to recover both its type
+ and the argument part of f.
+
+*Main> seq x ()
+*Main> :print x
+x = 1
+
+
+
+ We can check now that as expected, the type of x
+ has been reconstructed, and with it the
+ type of f has been too:
+
+*Main> :t x
+x :: Integer
+*Main> :t f
+f :: Integer -> b
+
+
+ From here, we can apply f to any argument of type Integer and observe
+ the results.
+ let b = f 10
+*Main> :t b
+b :: b
+*Main> b
+:1:0:
+ Ambiguous type variable `b' in the constraint:
+ `Show b' arising from a use of `print' at :1:0
+*Main> :p b
+b = (_t2::a)
+*Main> seq b ()
+()
+*Main> :t b
+b :: a
+*Main> :p b
+b = Just 10
+*Main> :t b
+b :: Maybe Integer
+*Main> :t f
+f :: Integer -> Maybe Integer
+*Main> f 20
+Just 20
+*Main> map f [1..5]
+[Just 1, Just 2, Just 3, Just 4, Just 5]
+]]>
+ In the first application of f, we had to do
+ some more type reconstruction
+ in order to recover the result type of f.
+ But after that, we are free to use
+ f normally.
+
+
+
+ Limitations
+
+
+ When stopped at a breakpoint, if you try to evaluate a variable
+ that is already under evaluation, the second evaluation will hang.
+ The reason is
+ that GHC knows the variable is under evaluation, so the new
+ evaluation just waits for the result before continuing, but of
+ course this isn't going to happen because the first evaluation is
+ stopped at a breakpoint. Control-C can interrupt the hung
+ evaluation and return to the prompt.
+ The most common way this can happen is when you're evaluating a
+ CAF (e.g. main), stop at a breakpoint, and ask for the value of the
+ CAF at the prompt again.
+
+
+ Implicit parameters (see ) are only available
+ at the scope of a breakpoint if there is a explicit type signature.
+
+
- The same type-default behaviour can be enabled in an ordinary Haskell
- module, using the flag -fextended-default-rules.
-
@@ -765,7 +1562,7 @@ it <- e
instructs GHCi to load the specified modules or filenames (and all
the modules they depend on), just as if you had said
:load modules at the
- GHCi prompt (see ). For example, to
+ GHCi prompt (see ). For example, to
start GHCi and load the program whose topmost module is in the
file Main.hs, we could say:
@@ -788,7 +1585,7 @@ $ ghci Main.hs
they will be automatically loaded the first time they are
needed.
- For non-auto packages, however, you need to request the
+ For hidden packages, however, you need to request the
package be loaded by using the -package flag:
@@ -879,6 +1676,17 @@ $ ghci -lm
+ :abandon
+ :abandon
+
+
+ Abandons the current evaluation (only available when stopped at
+ a breakpoint).
+
+
+
+
+ :addmodule ...
:add
@@ -891,6 +1699,32 @@ $ ghci -lm
+ :back
+ :back
+
+
+ Travel back one step in the history. See . See also:
+ :trace, :history,
+ :forward.
+
+
+
+
+
+ :break [identifier |
+ [module] line
+ [column]]
+
+ :break
+
+ Set a breakpoint on the specified function or line and
+ column. See .
+
+
+
+
+ :browse*module ...
:browse
@@ -933,6 +1767,51 @@ $ ghci -lm
+ :continue
+ :continue
+
+ Continue the current evaluation, when stopped at a
+ breakpoint.
+
+
+
+
+
+ :cmdexpr
+ :cmd
+
+
+ Executes expr as a computation of
+ type IO String, and then executes the resulting
+ string as a list of GHCi commands. Multiple commands are separated
+ by newlines. The :cmd command is useful with
+ :def and :set stop.
+
+
+
+
+
+ :ctagsfilename
+ :etagsfilename
+ :etags
+
+ :etags
+
+
+
+ Generates a “tags” file for Vi-style editors
+ (:ctags) or Emacs-style editors (etags). If
+ no filename is specified, the defaulit tags or
+ TAGS is
+ used, respectively. Tags for all the functions, constructors and
+ types in the currently loaded modules are created. All modules must
+ be interpreted for these commands to work.
+ See also .
+
+
+
+
+ :defnameexpr:def
@@ -1001,6 +1880,62 @@ Prelude> :. cmds.ghci
+ :delete * | num ...
+ :delete
+
+
+ Delete one or more breakpoints by number (use :show
+ breaks to see the number of each breakpoint). The
+ * form deletes all the breakpoints.
+
+
+
+
+
+ :edit file
+ :edit
+
+
+ Opens an editor to edit the file
+ file, or the most recently loaded
+ module if file is omitted. The
+ editor to invoke is taken from the EDITOR
+ environment variable, or a default editor on your system if
+ EDITOR is not set. You can change the
+ editor using :set editor.
+
+
+
+
+
+ :force identifier ...
+ :force
+
+
+ Prints the value of identifier in
+ the same way as :print. Unlike
+ :print, :force evaluates each
+ thunk that it encounters while traversing the value. This may
+ cause exceptions or infinite loops, or further breakpoints (which
+ are ignored, but displayed).
+
+
+
+
+
+ :forward
+ :forward
+
+
+ Move forward in the history. See . See also:
+ :trace, :history,
+ :back.
+
+
+
+
+ :help:help
@@ -1015,6 +1950,19 @@ Prelude> :. cmds.ghci
+ :history [num]
+ :history
+
+
+ Display the history of evaluation steps. With a number,
+ displays that many steps (default: 20). For use with
+ :trace; see .
+
+
+
+
+ :infoname ...
:info
@@ -1033,6 +1981,19 @@ Prelude> :. cmds.ghci
+ :kindtype
+ :kind
+
+
+ Infers and prints the kind of
+ type. The latter can be an arbitrary
+ type expression, including a partial application of a type constructor,
+ such as Either Int.
+
+
+
+
+ :loadmodule ...
:load
@@ -1072,18 +2033,78 @@ Prelude> :. cmds.ghci
+ :main arg1 ... argn
+ :main
+
+
+
+ When a program is compiled and executed, it can use the
+ getArgs function to access the
+ command-line arguments.
+ However, we cannot simply pass the arguments to the
+ main function while we are testing in ghci,
+ as the main function doesn't take its
+ directly.
+
+
+
+ Instead, we can use the :main command.
+ This runs whatever main is in scope, with
+ any arguments being treated the same as command-line arguments,
+ e.g.:
+
+
+
+Prelude> let main = System.Environment.getArgs >>= print
+Prelude> :main foo bar
+["foo","bar"]
+
+
+
+
+
+
+ :module +|-*mod1 ... *modn:module
+
+ import mod
+ Sets or modifies the current context for statements
- typed at the prompt. See for
+ typed at the prompt. The form import
+ mod is equivalent to
+ :module +mod.
+ See for
more details.
+ :print names ...
+ :print
+
+
+ Prints a value without forcing its evaluation.
+ :print may be used on values whose types are
+ unkonwn or partially known, which might be the case for local
+ variables with polymorphic types at a breakpoint. While inspecting
+ the runtime value, :print attempts to
+ reconstruct the type of the value, and will elaborate the type in
+ GHCi's environment if possible. If any unevaluated components
+ (thunks) are encountered, then :print binds
+ a fresh variable with a name beginning with _t
+ to each thunk. See for more
+ information. See also the :sprint command,
+ which works like :print but does not bind new
+ variables.
+
+
+
+
+ :quit:quit
@@ -1134,6 +2155,16 @@ Prelude> :. cmds.ghci
+ :seteditorcmd
+
+
+ Sets the command used by :edit to
+ cmd.
+
+
+
+
+ :setprogprog:set prog
@@ -1159,6 +2190,35 @@ Prelude> :. cmds.ghci
+ :setstop
+ [num] cmd
+
+
+ Set a command to be executed when a breakpoint is hit, or a new
+ item in the history is selected. The most common use of
+ :set stop is to display the source code at the
+ current location, e.g. :set stop :list.
+
+ If a number is given before the command, then the commands are
+ run when the specified breakpoint (only) is hit. This can be quite
+ useful: for example, :set stop 1 :continue
+ effectively disables breakpoint 1, by running
+ :continue whenever it is hit (although GHCi will
+ still emit a message to say the breakpoint was hit). What's more,
+ with cunning use of :def and
+ :cmd you can use :set stop to
+ implement conditional breakpoints:
+
+*Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
+*Main> :set stop 0 :cond (x < 3)
+
+ Ignoring breakpoints for a specified number of iterations is
+ also possible using similar techniques.
+
+
+
+
+ :show bindings:show bindings
@@ -1170,6 +2230,26 @@ Prelude> :. cmds.ghci
+ :show breaks
+ :show breaks
+
+
+ List the active breakpoints.
+
+
+
+
+
+ :show context
+ :show context
+
+
+ List the active evaluations that are stopped at breakpoints.
+
+
+
+
+ :show modules:show modules
@@ -1180,49 +2260,64 @@ Prelude> :. cmds.ghci
- :ctagsfilename
- :etagsfilename
- :etags
-
- :etags
-
-
+ :show [args|prog|prompt|editor|stop]
+ :show
+
- Generates a “tags” file for Vi-style editors
- (:ctags) or Emacs-style editors (etags). If
- no filename is specified, the defaulit tags or
- TAGS is
- used, respectively. Tags for all the functions, constructors and
- types in the currently loaded modules are created. All modules must
- be interpreted for these commands to work.
- See also .
+ Displays the specified setting (see
+ :set).
- :typeexpression
- :type
+ :sprint
+ :sprint
- Infers and prints the type of
- expression, including explicit
- forall quantifiers for polymorphic types. The monomorphism
- restriction is not applied to the
- expression during type inference.
+ Prints a value without forcing its evaluation.
+ :sprint is similar to :print,
+ with the difference that unevaluated subterms are not bound to new
+ variables, they are simply denoted by ‘_’.
- :kindtype
- :kind
+ :step [expr]
+ :step
- Infers and prints the kind of
- type. The latter can be an arbitrary
- type expression, including a partial application of a type constructor,
- such as Either Int.
+ Single-step from the last breakpoint. With an expression
+ argument, begins evaluation of the expression with a
+ single-step.
+
+
+
+
+
+ :trace [expr]
+ :trace
+
+
+ Evaluates the given expression (or from the last breakpoint if
+ no expression is given), and additionally logs the evaluation
+ steps for later inspection using :history. See
+ .
+
+
+
+
+
+ :typeexpression
+ :type
+
+
+ Infers and prints the type of
+ expression, including explicit
+ forall quantifiers for polymorphic types. The monomorphism
+ restriction is not applied to the
+ expression during type inference.
@@ -1375,7 +2470,6 @@ Prelude> :set -fno-glasgow-exts
staticoptions
-
The .ghci file.ghcifile
@@ -1438,7 +2532,33 @@ Prelude> :set -fno-glasgow-exts
-
+
+ Compiling to object code inside GHCi
+
+ By default, GHCi compiles Haskell source code into byte-code
+ that is interpreted by the runtime system. GHCi can also compile
+ Haskell code to object code: to turn on this feature, use the
+ flag either on the command line or
+ with :set (the option
+ restores byte-code compilation
+ again). Compiling to object code takes longer, but typically the
+ code will execute 10-20 times faster than byte-code.
+
+ Compiling to object code inside GHCi is particularly useful
+ if you are developing a compiled application, because the
+ :reload command typically runs much faster than
+ restarting GHC with from the command-line,
+ because all the interface files are already cached in
+ memory.
+
+ There are disadvantages to compiling to object-code: you
+ can't set breakpoints in object-code modules, for example. Only
+ the exports of an object-code module will be visible in GHCi,
+ rather than all top-level bindings as in interpreted
+ modules.
+
+
+ FAQ and Things To Watch Out For
@@ -1483,10 +2603,9 @@ Prelude> :set -fno-glasgow-exts
Concurrent threads don't carry on running when GHCi is
waiting for input.
- No, they don't. This is because the Haskell binding
- to the GNU readline library doesn't support reading from the
- terminal in a non-blocking way, which is required to work
- properly with GHC's concurrency model.
+ This should work, as long as your GHCi was built with
+ the switch, which is the default.
+ Consult whoever supplied your GHCi installation.
@@ -1513,6 +2632,13 @@ Prelude> :set -fno-glasgow-exts
+
+ I can't use Control-C to interrupt computations in
+ GHCi on Windows.
+
+ See
+
+