Functions to Access the Function Call Stack

Description

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

Usage

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)

Arguments

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

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

See Also

eval for the usage of sys.frame.

Examples

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