mtrace {debug}R Documentation

Interactive debugging

Description

mtrace sets or clears debugging mode for a function; mtrace.off clears debugging mode for all functions; check.for.tracees shows which functions are in debugging mode.

Usage

mtrace( fname, tracing=TRUE, char.fname, from=mvb.sys.parent(), update.tracees=TRUE, return.envs=FALSE)
# Usual: mtrace( fname) or mtrace( fname, tracing=FALSE, return.envs=FALSE)
mtrace.off()
check.for.tracees( where=1)

Arguments

fname quoted or unquoted function name
tracing TRUE to turn tracing on, FALSE to turn it off
char.fname (rarely used) if your function name is stored in a character object x, use char.fname=x
from where to start looking for fname (not usually needed)
where (character or integer) position in search path
update.tracees don't set this parameter! It's only for use by other functions
return.envs if TRUE, this will return a list of the environments where the function has been replaced by the mtraced version

Details

mtrace(myfun) modifies the body code of myfun, and also stores debugging information about myfun in tracees$myfun. Next time the function is invoked, the modified debug-ready version will be called instead of the orginal. mtrace does not modify source code (or other) attributes, so myfun will "look" exactly the same afterwards. mtrace(myfun,FALSE) restores myfun to normal. mtrace.off unmtraces all mtraced functions (see below for exceptions).

Because mtrace modifies function bodies (possibly in several places, if namespaced packages are involved), calling save.image or save while functions are still mtraced is probably not a good idea– if the saved image is reloaded in a new R session, the debugger won't know how to handle the previously mtraced functions, and an error message will be given if they are invoked. The Save and Save.pos functions in package mvbutils will get round this without your having to manually untrace and retrace functions.

If you do see a "maybe saved before being un-mtraced?" error message when myfun is invoked, all is not lost; you can restore myfun to health via mtrace(myfun,F), or put it properly into debugging mode via mtrace(myfun). mtrace.off won't work in such cases, because myfun isn't included in tracees.

mtrace looks for a function in the following places: first in the frame stack (unless from has been set– see below), then in the search path, then in all namespaces, then in all S3 methods tables. If several copies of a function are found, all will get modified (mtraced) to the same code; ditto when unmtracing.

mtrace etc doesn't (currently) handle S4 methods. However, I doubt there's any fundamental problem there (hopefully I will never have to find out)– the first issue, though, is that S4 methods have mangled names. If you can work out what the mangled name is, then you can mtrace the "real" version and all may work.

check.for.tracees checks for functions which have been mtraced, but only in one directory. By contrast, names(tracees) will return all functions that are currently known to be mtraced. However, unlike check.for.tracees, names(tracees) won't show functions that were saved during a previous R session in an mtraced state.

mtrace.off will untrace all functions returned by names( tracees) and/or check.for.tracees( 1).

mtrace puts a breakpoint (see bp) at line 1, but clears all other breakpoints.

mtrace can handle mlocal functions, but not (yet) do.in.envir functions– the latter appear as monolithic statements in the code window. See package mvbutils for more details.

If you use fixr to edit functions, mtrace will automatically be re-applied when an updated function file is sourced back in. Otherwise, you'll need to call mtrace manually after updating a function.

The from argument is only used in the following situations. The first is to mtrace an S4 method that lives somewhere. Suppose there is a function f which first defines functions g and h, then calls g. Now suppose you have mtraced g and that g is running, with the code window displayed. If you want to mtrace(h), the problem is that h is not visible from the frame of g. To tell mtrace where to find g, call mtrace( h, from=sys.parent()). [You can also replace sys.parent() with the absolute frame number of f, if f has been mtraced and its code window is visible.] mtrace will then look through the enclosing environments of from until it finds a definition of h.

If myfun has been defined in a namespaced package, then there may be several copies of myfun in the system, different ones being used at different times. mtrace will change them all; see fun.locator if you really want to know more.

If mtrace(bar) is called while function foo is being debugged (mtrace(foo) having previously been called), and bar has been redefined within foo or a parent environment of foo, then only the redefined copy of bar will be mtraced.

Value

Not normally used. mtrace by default returns an invisible copy of the modified function body. If you set return.envs=TRUE, it will instead return a list of the environments in which the function has been modified. This is only intended for "internal use".

Examples

## Not run: 
mtrace(glm) # turns tracing on
names( tracees) # "glm"
check.for.tracees( "package:base") # "glm"
glm(stupid.args) # voila le debugger
qqq() # back to command prompt
mtrace( glm, FALSE)
mtrace.off() # turns it off for all functions
## End(Not run)

[Package debug version 1.2.0 Index]