X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=d8d0a897414c0dac106faf08b0c23fad098caea6;hb=01d016a48232ca5932efd7fd19fa4ccdb9623576;hp=9ec07c355e0ab68f1bae0f660e33a9f5ab23ee73;hpb=1b001bb3b84b9279b568b50e5330b35be33b5ac1;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 9ec07c3..d8d0a89 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 GHCi Let'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 files Suppose we have the following Haskell source code, which we @@ -360,7 +365,7 @@ Ok, modules loaded: A, B, C, D. - + Interactive evaluation at the prompt When you type an expression at the prompt, GHCi immediately @@ -402,7 +407,7 @@ hello - + Using <literal>do-</literal>notation at the prompt do-notationin GHCi statementsin 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: @@ -738,25 +749,801 @@ 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 line column + :break module line + :break module line column + + + 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 <literal>_result</literal> 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. + + 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. - @@ -771,7 +1558,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: @@ -794,7 +1581,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: @@ -885,6 +1672,17 @@ $ ghci -lm + :abandon + :abandon + + + Abandons the current evaluation (only available when stopped at + a breakpoint). + + + + + :add module ... :add @@ -897,6 +1695,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 @@ -939,6 +1763,51 @@ $ ghci -lm + :continue + :continue + + Continue the current evaluation, when stopped at a + breakpoint. + + + + + + :cmd expr + :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. + + + + + + :ctags filename + :etags filename + :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 . + + + + + :def name expr :def @@ -1007,6 +1876,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 @@ -1021,6 +1946,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 . + + + + + :info name ... :info @@ -1039,6 +1977,19 @@ Prelude> :. cmds.ghci + :kind type + :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. + + + + + :load module ... :load @@ -1122,6 +2073,28 @@ Prelude> :main foo bar + :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 @@ -1172,6 +2145,16 @@ Prelude> :main foo bar + :set editor cmd + + + Sets the command used by :edit to + cmd. + + + + + :set prog prog :set prog @@ -1197,6 +2180,35 @@ Prelude> :main foo bar + :set stop + [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 @@ -1208,6 +2220,26 @@ Prelude> :main foo bar + :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 @@ -1218,49 +2250,64 @@ Prelude> :main foo bar - :ctags filename - :etags filename - :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). - :type expression - :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 ‘_’. - :kind type - :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 + . + + + + + + :type expression + :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. @@ -1413,7 +2460,6 @@ Prelude> :set -fno-glasgow-exts staticoptions - The <filename>.ghci</filename> file .ghcifile @@ -1476,7 +2522,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 @@ -1521,10 +2593,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. @@ -1551,6 +2622,13 @@ Prelude> :set -fno-glasgow-exts + + I can't use Control-C to interrupt computations in + GHCi on Windows. + + See + +