1% File src/library/base/man/debug.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2019 R Core Team
4% Distributed under GPL 2 or later
5
6\name{debug}
7\title{Debug a Function}
8\alias{debug}
9\alias{debugonce}
10\alias{undebug}
11\alias{isdebugged}
12\alias{debuggingState}
13\usage{
14debug(fun, text = "", condition = NULL, signature = NULL)
15debugonce(fun, text = "", condition = NULL, signature = NULL)
16undebug(fun, signature = NULL)
17isdebugged(fun, signature = NULL)
18debuggingState(on = NULL)
19}
20\arguments{
21  \item{fun}{any interpreted \R function.}
22  \item{text}{a text string that can be retrieved when the browser is entered.}
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.}
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 ??
34}
35\description{
36  Set, unset or query the debugging flag on a function.
37  The \code{text} and \code{condition} arguments are the same as those
38  that can be supplied via a call to \code{\link{browser}}.  They can be retrieved
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.
41}
42\details{
43  When a function flagged for debugging is entered, normal execution
44  is suspended and the body of function is executed one statement at a
45  time.  A new \code{\link{browser}} context is initiated for each step
46  (and the previous one destroyed).
47
48  At the debug prompt the user can enter commands or \R expressions,
49  followed by a newline.  The commands are described in the
50  \code{\link{browser}} help topic.
51
52  To debug a function which is defined inside another function,
53  single-step through to the end of its definition, and then call
54  \code{debug} on its name.
55
56  If you want to debug a function not starting at the very beginning,
57  use \code{\link{trace}(..., at = *)} or \code{\link{setBreakpoint}}.
58
59  Using \code{debug} is persistent, and unless debugging is turned off
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).
62  Use \code{debugonce()} to enter the debugger only the next time the
63  function is invoked.
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:RMethodUtils]{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
81  The number of lines printed for the deparsed call when a function is
82  entered for debugging can be limited by setting
83  \code{\link{options}(deparse.max.lines)}.
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.
88}
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
93
94  marked for debugging, and \code{FALSE} otherwise.
95}
96\seealso{
97  \code{\link{debugcall}} for conveniently debugging methods,
98  \code{\link{browser}} notably for its \sQuote{\emph{commands}}, \code{\link{trace}};
99  \code{\link{traceback}} to see the stack after an \code{Error: \dots}
100  message; \code{\link{recover}} for another debugging approach.
101}
102
103\examples{
104\dontrun{
105debug(library)
106library(methods)
107}
108\dontrun{
109debugonce(sample)
110## only the first call will be debugged
111sampe(10, 1)
112sample(10, 1)
113}
114}
115\keyword{programming}
116\keyword{environment}
117