trace.Rd 11.9 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/trace.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2010 R Core Team
Radford Neal's avatar
Radford Neal committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
% Distributed under GPL 2 or later

\name{trace}
\title{Interactive Tracing and Debugging of Calls to a Function or Method}
\alias{trace}
\alias{untrace}
\alias{tracingState}
\alias{.doTrace}
\description{
  A call to \code{trace} allows you to insert debugging code (e.g., a
  call to \code{\link{browser}} or \code{\link{recover}}) at chosen
  places in any function.  A call to \code{untrace} cancels the tracing.
  Specified methods can be traced the same way, without tracing all
  calls to the function.  Trace code can be any \R expression.  Tracing
  can be temporarily turned on or off globally by calling \code{tracingState}.
}
\usage{
trace(what, tracer, exit, at, print, signature,
      where = topenv(parent.frame()), edit = FALSE)
untrace(what, signature = NULL, where = topenv(parent.frame()))

tracingState(on = NULL)
.doTrace(expr, msg)
}
\arguments{
  \item{what}{The name (quoted or not) of a function to be traced or
    untraced.  For \code{untrace} or for \code{trace} with more than one
    argument, more than one name can be given in the quoted form, and
    the same action will be applied to each one.}
  \item{tracer}{Either a function or an unevaluated expression.  The
    function will be called or the expression will be evaluated either
    at the beginning of the call, or before those steps in the call
    specified by the argument \code{at}.
    See the details section.}
  \item{exit}{ Either a function or an unevaluated expression.  The
    function will be called or the expression will be evaluated on
    exiting the function.
    See the details section.}
  \item{at}{optional numeric vector or list.  If supplied, \code{tracer}
    will be called just before the corresponding step in the body of the
    function.
    See the details section. }
  \item{print}{If \code{TRUE} (as per default), a descriptive line is
    printed before any trace expression is evaluated.}
  \item{signature}{ If this argument is supplied, it should be a
    signature for a method for function \code{what}.  In this case, the
    method, and \emph{not} the function itself, is traced.}
  \item{edit}{ For complicated tracing, such as tracing within a loop
    inside the function, you will need to insert the desired calls by
    editing the body of the function.  If so, supply the \code{edit}
    argument either as \code{TRUE}, or as the name of the editor you
    want to use.  Then \code{trace()} will call \code{\link{edit}} and
Radford Neal's avatar
Radford Neal committed
56
    use the version of the function after you edit it.  See the details
Radford Neal's avatar
Radford Neal committed
57 58 59 60 61 62 63
    section for additional information.
    }
  \item{where}{where to look for the function to be
    traced; by default, the top-level environment of the call to
    \code{trace}.

    An important use of this argument is to trace a function when it
Radford Neal's avatar
Radford Neal committed
64
  is called from a package with a namespace.  The current namespace mechanism
Radford Neal's avatar
Radford Neal committed
65 66 67 68 69
  imports the functions to be called (with the exception of functions
  in the base package).  The functions being called are \emph{not} the
  same objects seen from the top-level (in general, the imported
  packages may not even be attached).  Therefore, you must ensure that
  the correct versions are being traced.  The way to do this is to set
Radford Neal's avatar
Radford Neal committed
70
  argument \code{where} to a function in the namespace.  The tracing
Radford Neal's avatar
Radford Neal committed
71
  computations will then start looking in the environment of that
Radford Neal's avatar
Radford Neal committed
72
  function (which will be the namespace of the corresponding package).
Radford Neal's avatar
Radford Neal committed
73
  (Yes, it's subtle, but the semantics here are central to how
Radford Neal's avatar
Radford Neal committed
74
  namespaces work in R.)
Radford Neal's avatar
Radford Neal committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
  }
  \item{on}{logical; a call to  the support function \code{tracingState} returns \code{TRUE}
    if tracing is globally turned on, \code{FALSE} otherwise.  An
    argument of one or the other of those values sets the state.  If the
    tracing state is \code{FALSE}, none of the trace actions will
    actually occur (used, for example, by debugging functions to shut
    off tracing during debugging).}
  \item{expr, msg}{arguments to the support function \code{.doTrace}, calls to
    which are inserted into the modified function or method:
    \code{expr} is the tracing action (such as a call to
    \code{browser()}, and \code{msg} is a string identifying the
    place where the trace action occurs.
  }
}
\details{
  The \code{trace} function operates by constructing a revised version
  of the function (or of the method, if \code{signature} is supplied),
  and assigning the new object back where the original was found.
  If only the \code{what} argument is given, a line of trace printing is
  produced for each call to the function (back compatible with the
  earlier version of \code{trace}).

  The object constructed by \code{trace} is from a class that extends
  \code{"function"} and which contains the original, untraced version.
  A call to \code{untrace} re-assigns this version.

  If the argument \code{tracer} or \code{exit} is the name of a
  function, the tracing expression will be a call to that function, with
  no arguments.  This is the easiest and most common case, with the
  functions \code{\link{browser}} and \code{\link{recover}} the
  likeliest candidates; the former browses in the frame of the function
  being traced, and the latter allows browsing in any of the currently
  active calls.

  The \code{tracer} or \code{exit} argument can also be an unevaluated
  expression (such as returned by a call to \code{\link{quote}} or
  \code{\link{substitute}}).  This expression itself is inserted in the
  traced function, so it will typically involve arguments or local
  objects in the traced function.  An expression of this form is useful
  if you only want to interact when certain conditions apply (and in
  this case you probably want to supply \code{print=FALSE} in the call
  to \code{trace} also).

  When the \code{at} argument is supplied, it can be a vector of
  integers referring to the substeps of the body of the function (this
  only works if the body of the function is enclosed in \code{{ ...}}.  In
  this case \code{tracer} is \emph{not} called on entry, but instead
  just before evaluating each of the steps listed in \code{at}.  (Hint:
  you don't want to try to count the steps in the printed version of a
  function; instead, look at \code{as.list(body(f))} to get the numbers
  associated with the steps in function \code{f}.)
Radford Neal's avatar
Radford Neal committed
126

Radford Neal's avatar
Radford Neal committed
127 128 129 130 131 132
  The \code{at} argument can also be a list of integer vectors.  In
  this case, each vector refers to a step nested within another step of
  the function.  For example, \code{at = list(c(3,4))}
  will call the tracer just before the fourth step of the third step
  of the function.  See the example below.

Radford Neal's avatar
Radford Neal committed
133 134
  Using \code{\link{setBreakpoint}} (from package \pkg{utils}) may be an
  alternative, calling \code{trace(...., at, ...)}.
Radford Neal's avatar
Radford Neal committed
135

Radford Neal's avatar
Radford Neal committed
136 137 138 139 140 141 142 143 144 145 146 147 148
  An intrinsic limitation in the \code{exit} argument is that it won't
  work if the function itself uses \code{on.exit}, since the existing
  calls will override the one supplied by \code{trace}.

  Tracing does not nest.  Any call to \code{trace} replaces previously
  traced versions of that function or method (except for edited
  versions as discussed below), and \code{untrace} always
  restores an untraced version.  (Allowing nested tracing has too many
  potentials for confusion and for accidentally leaving traced versions
  behind.)

  When the \code{edit} argument is used repeatedly with no call to
  \code{untrace} on the same function or method in between, the
Radford Neal's avatar
Radford Neal committed
149
  previously edited version is retained.  If you want to throw away
Radford Neal's avatar
Radford Neal committed
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
  all the previous tracing and then edit, call \code{untrace} before the next
  call to \code{trace}.  Editing may be combined with automatic
  tracing; just supply the other arguments such as \code{tracer}, and
  the \code{edit} argument as well.  The \code{edit=TRUE} argument
  uses the default editor (see \code{\link{edit}}).

  Tracing primitive functions (builtins and specials) from the base
  package works, but only by a special mechanism and not very
  informatively.  Tracing a primitive causes the primitive to be
  replaced by a function with argument \dots (only).  You can get a bit
  of information out, but not much.  A warning message is issued when
  \code{trace} is used on a primitive.

  The practice of saving the traced version of the function back where
  the function came from means that tracing carries over from one
  session to another, \emph{if} the traced function is saved in the
  session image.  (In the next session, \code{untrace} will remove the
  tracing.)  On the other hand, functions that were in a package, not in
  the global environment, are not saved in the image, so tracing expires
  with the session for such functions.

  Tracing a method is basically just like tracing a function, with the
  exception that the traced version is stored by a call to
  \code{\link{setMethod}} rather than by direct assignment, and so is
  the untraced version after a call to \code{untrace}.

  The version of \code{trace} described here is largely compatible with
  the version in S-Plus, although the two work by entirely different
  mechanisms.  The S-Plus \code{trace} uses the session frame, with the
  result that tracing never carries over from one session to another (\R
  does not have a session frame).  Another relevant distinction has
  nothing directly to do with \code{trace}:  The browser in S-Plus
  allows changes to be made to the frame being browsed, and the changes
  will persist after exiting the browser.  The \R browser allows changes,
  but they disappear when the browser exits.  This may be relevant in
  that the S-Plus version allows you to experiment with code changes
  interactively, but the \R version does not.  (A future revision may
  include a \sQuote{destructive} browser for \R.)
}
\note{
  The version of function tracing that includes any of the arguments
  except for the function name requires the \pkg{methods} package
  (because it uses special classes of objects to store and restore
  versions of the traced functions).

  If methods dispatch is not currently on, \code{trace} will load the
Radford Neal's avatar
Radford Neal committed
196
  methods namespace, but will not put the methods package on the search
Radford Neal's avatar
Radford Neal committed
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
  list.
}
\value{
  In the simple version (just the first argument), invisible \code{NULL}.
  Otherwise, the traced function(s) name(s).  The relevant consequence is the
  assignment that takes place.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{browser}} and \code{\link{recover}}, the likeliest
  tracing functions;
  also, \code{\link{quote}} and \code{\link{substitute}} for
  constructing general expressions.
}
\examples{
require(graphics)

##  Very simple use
trace(sum)
hist(stats::rnorm(100)) # shows about 3-4 calls to sum()
untrace(sum)

if(.isMethodsDispatchOn()) { # non-simple use needs 'methods' package

f <- function(x, y) {
    y <- pmax(y, 0.001)
    if (x > 0) x ^ y else stop("x must be positive")
}

## arrange to call the browser on entering and exiting
## function f
Radford Neal's avatar
Radford Neal committed
232 233
trace("f", quote(browser(skipCalls=4)),
      exit = quote(browser(skipCalls=4)))
Radford Neal's avatar
Radford Neal committed
234 235 236 237 238 239 240

## instead, conditionally assign some data, and then browse
## on exit, but only then.  Don't bother me otherwise

trace("f", quote(if(any(y < 0)) yOrig <- y),
      exit = quote(if(exists("yOrig")) browser(skipCalls=4)),
      print = FALSE)
Radford Neal's avatar
Radford Neal committed
241

Radford Neal's avatar
Radford Neal committed
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
## Enter the browser just before stop() is called.  First, find
## the step numbers

as.list(body(f))
as.list(body(f)[[3]])

## Now call the browser there

trace("f", quote(browser(skipCalls=4)), at=list(c(3,4)))

## trace a utility function, with recover so we
## can browse in the calling functions as well.

trace("as.matrix", recover)

## turn off the tracing

untrace(c("f", "as.matrix"))

\dontrun{
## trace calls to the function lm() that come from
## the nlme package.
## (The function nlme is in that package, and the package
Radford Neal's avatar
Radford Neal committed
265
## has a namespace, so the where= argument must be used
Radford Neal's avatar
Radford Neal committed
266 267 268 269 270 271 272 273
## to get the right version of lm)

trace(lm, exit = recover, where = nlme)
}
}
}
\keyword{programming}
\keyword{debugging}