The R Project SVN R

Rev

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