X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=82ee33054d6bdbeda1f1b04cc26730a7abfac83f;hb=9c6bd70dc4f1a51a487790c7218d9648783c4e70;hp=7a3c77a74d2ce556e15e9829cf31b01130911593;hpb=b0d80aa3d908a6b9991920a5ac7fd1b437ecafd3;p=ghc-hetmet.git
diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 7a3c77a..82ee330 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1106,10 +1106,12 @@ right :: [a]
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:
+ bug. GHCi offers two variants of stepping. Use
+ :step to enable all the
+ breakpoints in the program, and execute until the next breakpoint is
+ reached. Use :stepover to step over function
+ applications, which of course are executed all the same.
+ For example:
*Main> :step main
@@ -1118,13 +1120,53 @@ _result :: IO ()
The command :step
- expr begins the evaluation of
+ expr begins the evaluation of
expr in single-stepping mode. If
expr is ommitted, then it single-steps from
- the current breakpoint.
-
+ the current breakpoint. :stepover
+ works similarly.
+
+ In the current version of the debugger, :stepover
+ is limited to work locally in the lexical sense, that is in the context
+ of the current expression body.
+ When you run to the end of the expression, :stepover
+ stops working and switches to behave like regular :step.
+ This means
+ that it will fail to step over the last function application. As a result,
+ currently :stepover works great for monadic code, but
+ interacts less perfectly with pure code. For example, if stopped at the
+ line 2, on the entire expression
+ qsort left ++ [a] ++ qsort right:
+
+... [qsort2.hs:2:15-46] *Main> :step
+Stopped at qsort2.hs:2:15-46
+
+... [qsort2.hs:2:15-46] *Main> :list
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+
+
+ The first :stepover will step over the first
+ qsort recursive call, as expected. The second one
+ will step over the evaluation of [a], again as
+ expected. However, the third one has lexically run out
+ of the current expression, and will behave like regular
+ :step, performing one step of lazy evaluation and
+ stopping at the next breakpoint. In this case it is indeed the second
+ recursive application of qsort.
+
+[qsort2.hs:2:36-46] *Main> :stepover
+Warning: no more breakpoints in this function body, switching to :step
+Stopped at qsort2.hs:(1,0)-(3,55)
+
+[qsort2.hs:2:36-46] *Main> :list
+_result :: [a]
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+
The :list command is particularly useful when
- single-stepping, to see where you currently are:
+ single-stepping, to see where you currently are, as just shown
+ in the above example.
[qsort.hs:5:7-47] *Main> :list
@@ -1486,6 +1528,10 @@ Just 20
CAF (e.g. main), stop at a breakpoint, and ask for the value of the
CAF at the prompt again.
+ :stepover only works lexically locally, in the
+ body of the current expression. As a result, it can be rather impredictable
+ when used in pure functional code, as opposed to monadic code.
+
Implicit parameters (see ) are only available
at the scope of a breakpoint if there is an explicit type signature.
@@ -1925,7 +1971,7 @@ Prelude> :. cmds.ghci
the location of its definition in the source.
For types and classes, GHCi also summarises instances that
mention them. To avoid showing irrelevant information, an instance
- is shown only if (a) its head mentions name,
+ is shown only if (a) its head mentions name,
and (b) all the other things mentioned in the instance
are in scope (either qualified or otherwise) as a result of
a :load or :module commands.