debugger                package:utils                R Documentation

_P_o_s_t-_M_o_r_t_e_m _D_e_b_u_g_g_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     Functions to dump the evaluation environments (frames) and to
     examine dumped frames.

_U_s_a_g_e:

     dump.frames(dumpto = "last.dump", to.file = FALSE)
     debugger(dump = last.dump)

_A_r_g_u_m_e_n_t_s:

  dumpto: a character string. The name of the object or file to dump
          to.

 to.file: logical. Should the dump be to an R object or to a file?

    dump: An R dump object created by 'dump.frames'.

_D_e_t_a_i_l_s:

     To use post-mortem debugging, set the option 'error' to be a call
     to 'dump.frames'.  By default this dumps to an R object
     '"last.dump"' in the workspace, but it can be set to dump to a
     file (a dump of the object produced by a call to 'save'). The
     dumped object contain the call stack, the active environments and
     the last error message as returned by 'geterrmessage'.

     When dumping to file, 'dumpto' gives the name of the dumped object
     and the file name has '.rda' appended.

     A dump object of class '"dump.frames"' can be examined by calling
     'debugger'. This will give the error message and a list of
     environments from which to select repeatedly. When an environment
     is selected, it is copied and the 'browser' called from within the
     copy.

     If 'dump.frames' is installed as the error handler, execution will
     continue even in non-interactive sessions. See the examples for
     how to dump and then quit.

_V_a_l_u_e:

     Invisible 'NULL'.

_N_o_t_e:

     Functions such as 'sys.parent' and 'environment' applied to
     closures will not work correctly inside 'debugger'.

     If the error occurred when computing the default value of a formal
     argument the debugger will report "recursive default argument
     reference" when trying to examine that environment. 

     Of course post-mortem debugging will not work if R is too damaged
     to produce and save the dump, for example if it has run out of
     workspace.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'options' for setting 'error' options; 'recover' is an interactive
     debugger working similarly to 'debugger' but directly after the
     error occurs.

_E_x_a_m_p_l_e_s:

     ## Not run: 
     options(error=quote(dump.frames("testdump", TRUE)))

     f <- function() {
         g <- function() stop("test dump.frames")
         g()
     }
     f()   # will generate a dump on file "testdump.rda"
     options(error=NULL)

     ## possibly in another R session
     load("testdump.rda")
     debugger(testdump)
     Available environments had calls:
     1: f()
     2: g()
     3: stop("test dump.frames")

     Enter an environment number, or 0 to exit
     Selection: 1
     Browsing in the environment with call:
     f()
     Called from: debugger.look(ind)
     Browse[1]> ls()
     [1] "g"
     Browse[1]> g
     function() stop("test dump.frames")
     <environment: 759818>
     Browse[1]> 
     Available environments had calls:
     1: f()
     2: g()
     3: stop("test dump.frames")

     Enter an environment number, or 0 to exit
     Selection: 0

     ## A possible setting for non-interactive sessions
     options(error=quote({dump.frames(to.file=TRUE); q()}))
     ## End(Not run)