The R Project SVN R

Rev

Rev 70405 | Rev 86827 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
42333 ripley 1 
% File src/library/base/man/debug.Rd
68948 ripley 2 
% Part of the R package, https://www.R-project.org
76678 maechler 3 
% Copyright 1995-2019 R Core Team
42333 ripley 4 
% Distributed under GPL 2 or later
5 
 
2 r 6 
\name{debug}
37213 ripley 7 
\title{Debug a Function}
66751 maechler 8 
\alias{debug}
9 
\alias{debugonce}
10 
\alias{undebug}
11 
\alias{isdebugged}
12 
\alias{debuggingState}
2 r 13 
\usage{
70405 lawrence 14 
debug(fun, text = "", condition = NULL, signature = NULL)
15 
debugonce(fun, text = "", condition = NULL, signature = NULL)
16 
undebug(fun, signature = NULL)
17 
isdebugged(fun, signature = NULL)
66751 maechler 18 
debuggingState(on = NULL)
2 r 19 
}
20 
\arguments{
66751 maechler 21 
  \item{fun}{any interpreted \R function.}
22 
  \item{text}{a text string that can be retrieved when the browser is entered.}
70405 lawrence 23 
  \item{condition}{a condition that can be retrieved when the browser is
24 
    entered.}
25 
  \item{signature}{an optional method signature. If specified, the
26 
    method is debugged, rather than its generic.}
66751 maechler 27 
  \item{on}{logical; a call to the support function
28 
    \code{debuggingState} returns \code{TRUE} if debugging is globally
29 
    turned on, \code{FALSE} otherwise.  An argument of one or the other
30 
    of those values sets the state.  If the debugging state is
31 
    \code{FALSE}, none of the debugging actions will occur (but explicit
32 
    \code{\link{browser}} calls in functions will continue to work).}
33 
  %% can we describe what happens when it is turned off *inside* debugging ??
2 r 34 
}
35 
\description{
47969 rgentlem 36 
  Set, unset or query the debugging flag on a function.
53966 ripley 37 
  The \code{text} and \code{condition} arguments are the same as those
76678 maechler 38 
  that can be supplied via a call to \code{\link{browser}}.  They can be retrieved
53966 ripley 39 
  by the user once the browser has been entered, and provide a mechanism to
40 
  allow users to identify which breakpoint has been activated.
7081 pd 41 
}
42 
\details{
43 
  When a function flagged for debugging is entered, normal execution
37213 ripley 44 
  is suspended and the body of function is executed one statement at a
76678 maechler 45 
  time.  A new \code{\link{browser}} context is initiated for each step
46 
  (and the previous one destroyed).
35081 maechler 47 
 
53966 ripley 48 
  At the debug prompt the user can enter commands or \R expressions,
66865 ripley 49 
  followed by a newline.  The commands are described in the
50 
  \code{\link{browser}} help topic.
37213 ripley 51 
 
66865 ripley 52 
  To debug a function which is defined inside another function,
76678 maechler 53 
  single-step through to the end of its definition, and then call
66865 ripley 54 
  \code{debug} on its name.
48288 rgentlem 55 
 
52692 maechler 56 
  If you want to debug a function not starting at the very beginning,
56340 ripley 57 
  use \code{\link{trace}(..., at = *)} or \code{\link{setBreakpoint}}.
52692 maechler 58 
 
48869 murdoch 59 
  Using \code{debug} is persistent, and unless debugging is turned off
48288 rgentlem 60 
  the debugger will be entered on every invocation (note that if the
61 
  function is removed and replaced the debug state is not preserved).
76678 maechler 62 
  Use \code{debugonce()} to enter the debugger only the next time the
48288 rgentlem 63 
  function is invoked.
70405 lawrence 64 
 
65 
  To debug an S4 method by explicit signature, use
66 
  \code{signature}. When specified, signature indicates the method of
67 
  \code{fun} to be debugged. Note that debugging is implemented slightly
68 
  differently for this case, as it uses the trace machinery, rather than
69 
  the debugging bit. As such, \code{text} and \code{condition} cannot be
70 
  specified in combination with a non-null \code{signature}. For methods
71 
  which implement the \code{.local} rematching mechanism, the
72 
  \code{.local} closure itself is the one that will be ultimately
73 
  debugged (see \code{\link[methods]{isRematched}}).
74 
 
75 
  \code{isdebugged} returns \code{TRUE} if a) \code{signature} is \code{NULL}
76 
  and the closure \code{fun} has been debugged, or b) \code{signature} is not
77 
  \code{NULL}, \code{fun} is an S4 generic, and the method of \code{fun}
78 
  for that signature has been debugged. In all other cases, it returns
79 
  \code{FALSE}.
80 
 
50809 ripley 81 
  The number of lines printed for the deparsed call when a function is
82 
  entered for debugging can be limited by setting
52692 maechler 83 
  \code{\link{options}(deparse.max.lines)}.
58795 luke 84 
 
85 
  When debugging is enabled on a byte compiled function then the
86 
  interpreted version of the function will be used until debugging is
87 
  disabled.
2 r 88 
}
70405 lawrence 89 
\value{
90 
  \code{debug} and \code{undebug} invisibly return \code{NULL}.
91 
 
92 
  \code{isdebugged} returns \code{TRUE} if the function or method is
76678 maechler 93 
 
70405 lawrence 94 
  marked for debugging, and \code{FALSE} otherwise.
95 
}
2 r 96 
\seealso{
70405 lawrence 97 
  \code{\link{debugcall}} for conveniently debugging methods,
76678 maechler 98 
  \code{\link{browser}} notably for its \sQuote{\emph{commands}}, \code{\link{trace}};
35081 maechler 99 
  \code{\link{traceback}} to see the stack after an \code{Error: \dots}
100 
  message; \code{\link{recover}} for another debugging approach.
2 r 101 
}
70405 lawrence 102 
 
103 
\examples{
104 
\dontrun{
105 
debug(library)
106 
library(methods)
107 
}
108 
\dontrun{
109 
debugonce(sample)
110 
## only the first call will be debugged
111 
sampe(10, 1)
112 
sample(10, 1)
113 
}
114 
}
286 maechler 115 
\keyword{programming}
116 
\keyword{environment}