From: Simon Marlow Date: Thu, 17 May 2007 11:55:03 +0000 (+0000) Subject: complete documentation of the GHCi debugger X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=01d016a48232ca5932efd7fd19fa4ccdb9623576 complete documentation of the GHCi debugger --- diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index f3a50dc..d8d0a89 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -1672,6 +1672,17 @@ $ ghci -lm + :abandon + :abandon + + + Abandons the current evaluation (only available when stopped at + a breakpoint). + + + + + :add module ... :add @@ -1684,12 +1695,27 @@ $ ghci -lm - :breakpoint list|add|continue|del|stop|step ... - :breakpoint + :back + :back - Permits to add, delete or list the breakpoints in a debugging session. - + 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 . @@ -1740,7 +1766,43 @@ $ ghci -lm :continue :continue - Shortcut to :breakpoint 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 . @@ -1814,6 +1876,18 @@ 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 @@ -1830,6 +1904,34 @@ Prelude> :. cmds.ghci + :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 @@ -1844,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 @@ -1862,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 @@ -1949,39 +2077,19 @@ Prelude> :main foo bar :print - Prints a semievaluated value without forcing its evaluation. - :print works just like :sprint but additionally, - :print binds the unevaluated parts -called - suspensions- - to names which you can play with. For example: - -Prelude> let li = map Just [1..5] -Prelude> :sp li -li - _ -Prelude> :p li -li - (_t1::[Maybe Integer]) -Prelude> head li -Just 1 -Prelude> :sp li -li - Just 1 : _ -Prelude> :p li -li - Just 1 : (_t2::[Maybe Integer]) -Prelude> last li -Just 5 -Prelude> :sp li -li - [Just 1,_,_,_,Just 5] -Prelude> :p li -li - [Just 1,(_t3::Maybe Integer),(_t4::Maybe Integer),(_t5::Maybe Integer),Just 4] -Prelude> _t4 -Just 3 -Prelude> :p li -li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4] - - The example uses :print and :sprint - to help us observe how the li variable is evaluated progressively as we operate - with it. Note for instance how last traverses all the elements of - the list to compute its result, but without evaluating the individual elements. - + 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. @@ -2072,6 +2180,35 @@ li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4] + :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 @@ -2083,6 +2220,26 @@ li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4] + :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 @@ -2090,79 +2247,67 @@ li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4] Show the list of modules currently load. + + + + :show [args|prog|prompt|editor|stop] + :show + + + Displays the specified setting (see + :set). + + + :sprint :sprint - Prints a semievaluated value without forcing its evaluation. - :sprint and its sibling :print - are very useful to observe how lazy evaluation works in your code. For example: - -Prelude> let li = map Just [1..5] -Prelude> :sp li -li - _ -Prelude> head li -Just 1 -Prelude> :sp li -li - Just 1 : _ -Prelude> last li -Just 5 -Prelude> :sp li -li - [Just 1,_,_,_,Just 5] - - The example uses :sprint to help us observe how the li variable is evaluated progressively as we operate - with it. Note for instance how last traverses all the elements of - the list to compute its result, but without evaluating the individual elements. - + 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 ‘_’. + - :ctags filename - :etags filename - :etags - - :etags - - + :step [expr] + :step + - 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 . + Single-step from the last breakpoint. With an expression + argument, begins evaluation of the expression with a + single-step. - :type expression - :type + :trace [expr] + :trace - 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. + 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 + . - :kind type - :kind + :type expression + :type - 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. + 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.