Tracing and Debugging of Calls to Functions

trace

Tracing and Debugging of Calls to Functions

Description

Modifies function definitions to trace the execution of the function.

Usage

trace(what, tracer, exit, at, print, signature,
      where=topenv(parent.frame()), edit=FALSE)
untrace(what, signature=NULL, where=topenv(parent.frame())
.doTrace(expr, msg)
returnValue(default = NULL)

Arguments

what	a character vector. Gives the names of the functions to trace. This can be the unquoted name of a function if there is only one.
tracer	a function or the name of a function or an expression to be called when executing the traced function.
exit	a function or the name of a function or an expression to be called when exiting the traced function.
at	one of more locations inside the body of the traced function at which the tracer is to be inserted. If this is a numeric vector, each element specifies the index of expression in the traced function body. If this is a list, each list element is a numeric vector specifying a series of indices reaching a subexpression within the traced function body. Currently, if at is given, the traced function body must consist of a curly-braces block. If at is not given, the tracing is inserted at the beginning of the traced function body.
print	a logical flag. If TRUE, the tracing code prints a message (for example, "On entry") to identify the location of the trace before calling the tracing function. Usually this is helpful, but you can set the option to FALSE if you want silent tracing.
signature	the signature indicating which S4 method for what should be traced or untraced. Currently unimplemented, and an error is generated if it is specified.
where	the environment containing the function definition to be traced. This can also be a function, in which case environment(where) is used as the environment.
edit	a logical flag. If TRUE, an editor is invoked to edit the function definition. Currently unimplemented, and an error is generated if set to TRUE.
expr	an expression that is evaluated by the utility function .doTrace.
msg	a character string. If this is given, the utility function .doTrace prints this message when it is executed.
default	a character vector that gives the names of the functions or any expression to be evaluated.

Details

Tracing is accomplished by modifying the traced function to add calls to the utility function .doTrace, which can print a message (if print is TRUE) and call the tracer or exit functions or expressions.

The modified function includes the original unmodified definition as an attribute, so untrace simply restores its value.

Tracing is performed only during the current session. Each call to trace for a given function replaces any previous tracing for that function.

Value

trace	returns a character vector of the function names traced.
untrace	returns a character vector of the function names traced.
.doTrace	returns NULL.
returnValue	returns the returned value of function or expression.

See Also

Examples

xx <- function(x) {
  x+1
}
trace(xx, tracer=quote(cat("x =",x,"\n")))
xx(10)
# prints:
#   Tracing xx(10) on entry
#   x = 10
#   [1] 11
untrace(xx)
xx(10)
# prints:
#   [1] 11
returnValue(ts(1))
returnValue(c(ts(1), 3^2))
returnValue(3^3)

Package base version 6.0.0-69
Package Index