X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=b27781c332b3310416d5022c6c6fa7c1628a4c26;hb=0e2c7147358aca96e5a4245c3c4ead848d472fb9;hp=f3a50dc248fc9f8ec82dc0a0d28f119b5cf707ce;hpb=79fb37d4fe333f5c3dd7f08a6df102aed05394d9;p=ghc-hetmet.git
diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index f3a50dc..b27781c 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -577,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:
@@ -1373,7 +1375,9 @@ a :: a
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.
+ 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
@@ -1672,6 +1676,17 @@ $ ghci -lm
+ :abandon
+ :abandon
+
+
+ Abandons the current evaluation (only available when stopped at
+ a breakpoint).
+
+
+
+
+
:add module ...
:add
@@ -1684,12 +1699,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 +1770,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 +1880,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 +1908,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 +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 .
+
+
+
+
+
:info name ...
:info
@@ -1862,6 +1981,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
@@ -1936,9 +2068,15 @@ Prelude> :main 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.
@@ -1949,39 +2087,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 +2190,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 +2230,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 +2257,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.