\HeaderA{debug}{Debug a Function}{debug}
\aliasA{undebug}{debug}{undebug}
\keyword{programming}{debug}
\keyword{environment}{debug}
\begin{Description}\relax
Set or unset the debugging flag on a function.
\end{Description}
\begin{Usage}
\begin{verbatim}
debug(fun)
undebug(fun)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{fun}] any interpreted \R{} function.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
When a function flagged for debugging is entered, normal execution
is suspended and the body of function is executed one statement at a
time.  A new browser context is initiated for each step (and the
previous one destroyed).

At the debug prompt the user can enter commands or \R{} expressions.
The commands are

\describe{
\item[\code{n}] (or just return).  Advance to the next step.
\item[\code{c}] continue to the end of the current context: e.g. to the
end of the loop if within a loop or to the end of the function.
\item[\code{cont}] synonym for \code{c}.
\item[\code{where}] print a stack trace of all active function calls.
\item[\code{Q}] exit the browser and the current evaluation and
return to the top-level prompt.
}

Anything else entered at the debug prompt is interpreted as an
\R{} expression to be evaluated in the calling environment: in
particular typing an object name will cause the object to be printed,
and \code{ls()} lists the objects in the calling frame.  (If you want
to look at an object with a name such as \code{n}, print it explicitly.)

If a function is defined inside a function, single-step though to the
end of its definition, and then call \code{debug} on its name.

In order to debug S4 methods (see \code{\LinkA{Methods}{Methods}}), you
need to use \code{\LinkA{trace}{trace}}, typically calling \code{\LinkA{browser}{browser}},
e.g., as \\
\code{trace("plot", browser, exit=browser, signature = c("track", "missing"))}
\end{Details}
\begin{SeeAlso}\relax
\code{\LinkA{browser}{browser}}, \code{\LinkA{trace}{trace}};
\code{\LinkA{traceback}{traceback}} to see the stack after an \code{Error: ...}
message; \code{\LinkA{recover}{recover}} for another debugging approach.
\end{SeeAlso}

