mtrace                 package:debug                 R Documentation

_I_n_t_e_r_a_c_t_i_v_e _d_e_b_u_g_g_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

   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

_D_e_t_a_i_l_s:

     '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 'mtrace'd 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 'mtrace'd
     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
     'mtrace'd, but only in one directory. By contrast,
     'names(tracees)' will return all functions that are currently
     known to be 'mtrace'd. However, unlike 'check.for.tracees',
     'names(tracees)' won't show functions that were saved during a
     previous R session in an 'mtrace'd 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 'mtrace'd '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 'mtrace'd 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 'mtrace'd.

_E_x_a_m_p_l_e_s:

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

