sys.parent               package:base               R Documentation

Functions to Access the Function Call Stack

Description:

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

Usage:

     sys.call(which = 0)
     sys.frame(which = 0)
     sys.nframe()
     sys.function(n = 0)
     sys.parent(n = 1)

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

Arguments:

   which: the frame number if non-negative, the number of generations
          to go back if negative. (See the Details section.)

       n: the number of frame generations to go back.

Details:

     `.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 numbered one less
     than the frame number of the current evaluation, nor is it the
     environment within which the function was defined.  `sys.parent'
     returns the number of the parent frame if `n' is 1 (the default),
     the grandparent if `n' is 2, and so on. `sys.frame' returns the
     environment associated with a given frame number.

     `sys.call' and `sys.frame' both accept integer values for the
     argument `which'.  Non-negative values of `which' are normal frame
     numbers whereas negative values are counted back from the frame
     number of the current evaluation.

     `sys.nframe' returns the number of the current frame in that list.
     `sys.function' gives the definition of the function curently being
     evaluated in the frame `n' generations back.

     `sys.frames' gives a list of all the active frames and
     `sys.parents' gives the indices of the parent frames of each of
     the frames.

     Notice that even though the `sys.'xxx functions (except
     `sys.status') 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))' (implemented slightly more
     efficiently).

See Also:

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

Examples:

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

     gg <- function(y) {
         ggg <- function() {
             cat("current frame is", sys.nframe(), "\n")
             cat("parents are", sys.parents(), "\n")
             print(sys.function(0)) # ggg
             print(sys.function(2)) # gg
         }
         if(y > 0) gg(y-1) else ggg()
     }
     gg(3)

     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

