The R Project SVN R

% File src/library/base/man/trace.Rd

% Part of the R package, https://www.R-project.org

% Copyright (C) 1995-2018 R Core Team

% 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}

\alias{returnValue}

\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 generic function.  Trace code (\code{tracer}) 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)

returnValue(default = NULL)

}

\arguments{

  \item{what}{the name, possibly \code{\link{quote}()}d, 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.  For

    \dQuote{hidden} functions such as S3 methods in a namespace,

    \code{where = *} typically needs to be specified as well.}

  \item{tracer}{either a \link{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 \code{\link{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

    use the version of the function after you edit it.  See the details

    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 functions from a

    package which are \dQuote{hidden} or called from another package.

    The namespace mechanism 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 argument \code{where} to a

    function in the namespace (or that namespace).  The tracing

    computations will then start looking in the environment of that

    function (which will be the namespace of the corresponding package).

    (Yes, it's subtle, but the semantics here are central to how

    namespaces work in \R.)

  }

  \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.

  }

  \item{default}{If \code{returnValue} finds no return value (e.g.

    a function exited because of an error, restart or as a result

    of evaluating a return from a caller function), it will return

    \code{default} instead.

  }

}

\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}.)

  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.

  Using \code{\link{setBreakpoint}} (from package \pkg{utils}) may be an

  alternative, calling \code{trace(...., at, ...)}.

  The \code{exit} argument is called during \code{\link{on.exit}}

  processing.  In an \code{on.exit} expression, the experimental \code{returnValue()}

  function may be called to obtain the value about to be returned by

  the function. Calling this function in other circumstances will give

  undefined results.

  An intrinsic limitation in the \code{exit} argument is that it won't

  work if the function itself uses \code{on.exit} with \code{add=

  FALSE} (the default), 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

  previously edited version is retained.  If you want to throw away

  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 an S4 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{

  Using \code{trace()} is conceptually a generalization of

  \code{\link{debug}}, implemented differently.  Namely by calling

  \code{\link{browser}} via its \code{tracer} or \code{exit} argument.

  %% On the other hand, it sometimes triggers less consistently

  %% ?? lacks features of debug()- (which ??)

  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

  methods namespace, but will not put the methods package on the

  \code{\link{search}} list.

}

\value{

  In the simple version (just the first argument), \code{trace} returns

  an invisible \code{NULL}.

  Otherwise, the traced function(s) name(s).  The relevant consequence is the

  assignment that takes place.

  \code{untrace} returns the function name invisibly.

  \code{tracingState} returns the current global tracing state, and possibly

  changes it.

  When called during \code{on.exit} processing, \code{returnValue} returns

  the value about to be returned by the exiting function.  Behaviour in

  other circumstances is undefined.

}

\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(stats)

##  Very simple use

trace(sum)

hist(rnorm(100)) # shows about 3-4 calls to sum()

untrace(sum)

## Show how pt() is called from inside power.t.test():

if(FALSE)

  trace(pt) ## would show ~20 calls, but we want to see more:

trace(pt, tracer = quote(cat(sprintf("tracing pt(*, ncp = \%.15g)\n", ncp))),

      print = FALSE) # <- not showing typical extra

power.t.test(20, 1, power=0.8, sd=NULL)  ##--> showing the ncp root finding:

untrace(pt)

%% methods is loaded when needed

%% 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

trace("f", quote(browser(skipCalls = 4)),

      exit = quote(browser(skipCalls = 4)))

## 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)

## Enter the browser just before stop() is called.  First, find

## the step numbers

untrace(f) # (as it has changed f's body !)

as.list(body(f))

as.list(body(f)[[3]]) # -> stop(..) is [[4]]

## Now call the browser there

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

\dontrun{

f(-1,2) # --> enters browser just before stop(..)

}

## trace a utility function, with recover so we

## can browse in the calling functions as well.

trace("as.matrix", recover)

## turn off the tracing (that happened above)

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

\dontrun{

## Useful to find how system2() is called in a higher-up function:

trace(base::system2, quote(print(ls.str())))

}

##-------- Tracing hidden functions : need 'where = *'

##

## 'where' can be a function whose environment is meant:

trace(quote(ar.yw.default), where = ar)

a <- ar(rnorm(100)) # "Tracing ..."

untrace(quote(ar.yw.default), where = ar)

## trace() more than one function simultaneously:

##         expression(E1, E2, ...)  here is equivalent to

##          c(quote(E1), quote(E2), quote(.*), ..)

trace(expression(ar.yw, ar.yw.default), where = ar)

a <- ar(rnorm(100)) # --> 2 x "Tracing ..."

# and turn it off:

untrace(expression(ar.yw, ar.yw.default), where = ar)

\dontrun{

## trace calls to the function lm() that come from

## the nlme package.

## (The function nlme is in that package, and the package

## has a namespace, so the where= argument must be used

## to get the right version of lm)

trace(lm, exit = recover, where = asNamespace("nlme"))

}

%%}% only if 'methods'

}

\keyword{programming}

\keyword{debugging}