nseval (version 0.4)

caller: Find the caller of a given environment.

Description

Given an environment that is currently on the stack, caller determines the calling environment.

Usage

caller(env = caller(environment()),
  ifnotfound = stop("caller: environment not found on stack"))

Arguments

env

The environment whose caller to find. The default is caller's caller; that is, caller() should return the the same value as caller(environment()).)

ifnotfound

What to return in case the caller cannot be determined. By default an error is raised.

Value

The environment which called env into being. If that environment cannot be determined, ifnotfound is returned.

Details

For example, in the code:

X <- environment()
F <- function() {
  Y <- environment()
  caller(Y)
}
F()

the environment called Y was created by calling F(), and that call occurs in the environment called X. In this case X is the calling environment of Y, so F() returns the same environment as X().

caller is intended as a replacement for parent.frame, which returns the next environment up the calling stack -- which is sometimes the same value, but differs in some cases such as when lazy evaluation re-activates an environment. parent.frame() can return different things depending on the order in which arguments are evaluated, and without warning. caller will by default throw an error if the caller cannot be determined.

In addition, caller tries to do the right thing when the environment was instantiated by means of do.call, eval or do rather than an ordinary function call.

Examples

# NOT RUN {
E <- environment()
F <- function() {
 Y <- environment()
 caller(Y)
}
identical(F(), E) ## TRUE
# }