| 27442 |
ripley |
1 |
\name{debugger}
|
|
|
2 |
\alias{debugger}
|
|
|
3 |
\alias{dump.frames}
|
|
|
4 |
\title{Post-Mortem Debugging}
|
|
|
5 |
\description{
|
|
|
6 |
Functions to dump the evaluation environments (frames) and to examine
|
|
|
7 |
dumped frames.
|
|
|
8 |
}
|
|
|
9 |
\usage{
|
|
|
10 |
dump.frames(dumpto = "last.dump", to.file = FALSE)
|
|
|
11 |
debugger(dump = last.dump)
|
|
|
12 |
}
|
|
|
13 |
\arguments{
|
|
|
14 |
\item{dumpto}{a character string. The name of the object or file to
|
|
|
15 |
dump to.}
|
|
|
16 |
\item{to.file}{logical. Should the dump be to an \R object or to a
|
|
|
17 |
file?}
|
|
|
18 |
\item{dump}{An \R dump object created by \code{dump.frames}.}
|
|
|
19 |
}
|
|
|
20 |
\details{
|
|
|
21 |
To use post-mortem debugging, set the option \code{error} to be a call
|
|
|
22 |
to \code{dump.frames}. By default this dumps to an \R object
|
|
|
23 |
\code{"last.dump"} in the workspace, but it can be set to dump to a
|
|
|
24 |
file (as dump of the object produced by a call to \code{\link{save}}).
|
|
|
25 |
The dumped object contain the call stack, the active environments and
|
|
|
26 |
the last error message as returned by \code{\link{geterrmessage}}.
|
|
|
27 |
|
|
|
28 |
When dumping to file, \code{dumpto} gives the name of the dumped
|
|
|
29 |
object and the file name has \code{.rda} appended.
|
|
|
30 |
|
|
|
31 |
A dump object of class \code{"dump.frames"} can be examined
|
|
|
32 |
by calling \code{debugger}. This will give the error message and a
|
|
|
33 |
list of environments from which to select repeatedly. When an
|
|
|
34 |
environment is selected, it is copied and the \code{browser} called
|
|
|
35 |
from within the copy.
|
|
|
36 |
|
|
|
37 |
If \code{dump.frames} is installed as the error handler, execution
|
|
|
38 |
will continue even in non-interactive sessions. See the examples for
|
|
|
39 |
how to dump and then quit.
|
|
|
40 |
}
|
|
|
41 |
\value{
|
|
|
42 |
None.
|
|
|
43 |
}
|
|
|
44 |
\note{
|
|
|
45 |
Functions such as \code{\link{sys.parent}} and
|
|
|
46 |
\code{\link{environment}} applied to closures will not work correctly
|
|
|
47 |
inside \code{debugger}.
|
|
|
48 |
|
|
|
49 |
Of course post-mortem debugging will not work if \R is too damaged to
|
|
|
50 |
produce and save the dump, for example if it has run out of workspace.
|
|
|
51 |
}
|
|
|
52 |
\references{
|
|
|
53 |
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
|
|
|
54 |
\emph{The New S Language}.
|
|
|
55 |
Wadsworth \& Brooks/Cole.
|
|
|
56 |
}
|
|
|
57 |
\seealso{
|
|
|
58 |
\code{\link{options}} for setting \code{error} options;
|
|
|
59 |
\code{\link{recover}} is an interactive debugger working similarly to
|
|
|
60 |
\code{debugger} but directly after the error occurs.
|
|
|
61 |
}
|
|
|
62 |
\examples{
|
|
|
63 |
\dontrun{
|
|
|
64 |
options(error=quote(dump.frames("testdump", TRUE)))
|
|
|
65 |
|
|
|
66 |
f <- function() {
|
|
|
67 |
g <- function() stop("test dump.frames")
|
|
|
68 |
g()
|
|
|
69 |
}
|
|
|
70 |
f() # will generate a dump on file "testdump.rda"
|
|
|
71 |
options(error=NULL)
|
|
|
72 |
|
|
|
73 |
## possibly in another R session
|
|
|
74 |
load("testdump.rda")
|
|
|
75 |
debugger(testdump)
|
|
|
76 |
Available environments had calls:
|
|
|
77 |
1: f()
|
|
|
78 |
2: g()
|
|
|
79 |
3: stop("test dump.frames")
|
|
|
80 |
|
|
|
81 |
Enter an environment number, or 0 to exit
|
|
|
82 |
Selection: 1
|
|
|
83 |
Browsing in the environment with call:
|
|
|
84 |
f()
|
|
|
85 |
Called from: debugger.look(ind)
|
|
|
86 |
Browse[1]> ls()
|
|
|
87 |
[1] "g"
|
|
|
88 |
Browse[1]> g
|
|
|
89 |
function() stop("test dump.frames")
|
|
|
90 |
<environment: 759818>
|
|
|
91 |
Browse[1]>
|
|
|
92 |
Available environments had calls:
|
|
|
93 |
1: f()
|
|
|
94 |
2: g()
|
|
|
95 |
3: stop("test dump.frames")
|
|
|
96 |
|
|
|
97 |
Enter an environment number, or 0 to exit
|
|
|
98 |
Selection: 0
|
|
|
99 |
|
|
|
100 |
## A possible setting for non-interactive sessions
|
|
|
101 |
options(error=quote({dump.frames(to.file=TRUE); q()}))
|
|
|
102 |
}}
|
|
|
103 |
\keyword{utilities}
|
|
|
104 |
\keyword{error}
|
The R Project SVN
R