debug (version 1.0.1)

mtrace: 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())
# Usual: mtrace( fname) or mtrace( fname, tracing=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

Details

mtrace(myfun) modifies the body code of myfun, and also stores debugging information about myfun in tracees$myfun; tracees is stored in the mvb.session.info environment (consult README.mvbutils in the mvbutils package), and is visible from the command line. mtrace does not modify source code (or other) attributes, so myfun will "look" exactly the same afterwards. mtrace(myfun,FALSE) restores myfun to normal. Because mtrace modifies function bodies, 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 Rsession, 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. 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 Rsession 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 lines. 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 situation. 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.

Examples

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