The trace
function operates by constructing a revised version
of the function (or of the method, if signature
is supplied),
and assigning the new object back where the original was found.
If only the what
argument is given, a line of trace printing is
produced for each call to the function (back compatible with the
earlier version of trace
). The object constructed by trace
is from a class that extends
"function"
and which contains the original, untraced version.
A call to untrace
re-assigns this version.
If the argument tracer
or 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 browser
and 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 tracer
or exit
argument can also be an unevaluated
expression (such as returned by a call to quote
or
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 print = FALSE
in the call
to trace
also).
When the 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 { ...}
. In
this case tracer
is not called on entry, but instead
just before evaluating each of the steps listed in at
. (Hint:
you don't want to try to count the steps in the printed version of a
function; instead, look at as.list(body(f))
to get the numbers
associated with the steps in function f
.)
The 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, 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 setBreakpoint
(from package utils) may be an
alternative, calling trace(...., at, ...)
.
The exit
argument is called during on.exit
processing. In an on.exit
expression, the experimental 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 exit
argument is that it won't
work if the function itself uses on.exit
with add=
FALSE
(the default), since the existing calls will override the one
supplied by trace
.
Tracing does not nest. Any call to trace
replaces previously
traced versions of that function or method (except for edited
versions as discussed below), and untrace
always
restores an untraced version. (Allowing nested tracing has too many
potentials for confusion and for accidentally leaving traced versions
behind.)
When the edit
argument is used repeatedly with no call to
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 untrace
before the next
call to trace
. Editing may be combined with automatic
tracing; just supply the other arguments such as tracer
, and
the edit
argument as well. The edit = TRUE
argument
uses the default editor (see 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 ... (only). You can get a bit
of information out, but not much. A warning message is issued when
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, if the traced function is saved in the
session image. (In the next session, 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
setMethod
rather than by direct assignment, and so is
the untraced version after a call to untrace
.
The version of trace
described here is largely compatible with
the version in S-Plus, although the two work by entirely different
mechanisms. The S-Plus 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 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 destructive browser for R.)