sys.parent               package:base               R Documentation

_F_u_n_c_t_i_o_n_s _t_o _A_c_c_e_s_s _t_h_e _F_u_n_c_t_i_o_n _C_a_l_l _S_t_a_c_k

_D_e_s_c_r_i_p_t_i_o_n:

     These functions provide access to `environment's (``frames'' in S
     terminology) associated with functions further up the calling
     stack.

_U_s_a_g_e:

     sys.call(which=<<see below>>)
     sys.frame(which=<<see below>>)
     sys.nframe()
     sys.function(n=<<see below>>)
     sys.parent(n=1)

     sys.calls()
     sys.frames()
     sys.parents()
     sys.on.exit()
     sys.status()
     parent.frame(n=1)

_A_r_g_u_m_e_n_t_s:

   which: the frame number.

       n: the number of frame generations to go back.

_D_e_t_a_i_l_s:

     `.GlobalEnv' is given number 0 in the list of frames. Each
     subsequent function evaluation increases the frame stack by 1 and
     the environment for evaluation of that function is returned by
     `sys.frame' with the appropriate index.

     The parent of a function evaluation is the environment in which
     the function was called. It is not necessarily one less than the
     frame number of the current evaluation, nor the environment from
     which it is called.  `sys.parent' returns the number of the parent
     frame if `n' is 1 (the default), the grandparent if `n' is 2, and
     so forth. `sys.frame' returns the environment associated with a
     given frame number.

     `sys.call' and `sys.frame' both accept either positive or negative
     values for the argument `which'.  Positive values of `which' are
     normal frame numbers whereas negative values are counted back from
     the frame number of the current evaluation.

     Notice that even though the `sys.'xxx functions are interpreted,
     their contexts are not counted nor are they reported. There is no
     access to them.

     `sys.status()' returns a list with components `sys.calls',
     `sys.parents' and `sys.frames'.

     `sys.on.exit()' retrieves the expression stored for use by
     `on.exit' in the function currently being evaluated. (Note that
     this differs from S, which returns a list of expressions for the
     current frame and its parents.)

     `parent.frame(n)' is a convenient shorthand for
     `sys.frame(sys.parent(n))'.

_S_e_e _A_l_s_o:

     `eval' for the usage of `sys.frame'.

_E_x_a_m_p_l_e_s:

     ff <- function(x) gg(x)
     gg <- function(y) sys.status()
     str(ff(1))

     t1 <- function() {
       aa <- "here"
       t2 <- function() {
         ## in frame 2 here
         cat("current frame is", sys.nframe(), "\n")
         str(sys.calls()) ## list with two components t1() and t2()
         cat("parents are frame nos", sys.parents(), "\n") ## 0 1
         print(ls(envir=sys.frame(-1))) ## [1] "aa" "t2"
         invisible()
       }
       t2()
     }
     t1()

     test.sys.on.exit <- function() {
       on.exit(print(1))
       ex <- sys.on.exit()
       str(ex)
       cat("exiting...\n")
     }
     test.sys.on.exit()
     ## gives `language print(1)', prints 1 on exit

