parent_envs: Get the ancestral environments of an environment

In HenrikBengtsson/environments: Working with Environments and Closures in R

Get the ancestral environments of an environment

Description

Get the ancestral environments of an environment

Usage

parent_env(envir = parent.frame(), n = 1L)

parent_envs(envir = parent.frame(), until = emptyenv(), extra = 0L)

top_env(envir, until = globalenv())

Arguments

envir	An environment or an object with an environment, e.g. a function or a formula.
n	The generation of parent environment to get. If n = 0, then envir is returned. If n = 1 (default), then parent.env(envir) is returned. If n = 2, then parent.env(parent.env(envir)) is returned, and so on, until emptyenv() is returned.
until	An environment to consider the last parent environment. If until is not one of the parent environments, then emptyenv() is the last one. It is also possible to specify a list of alternative environments.
extra	Maximum number of additional parent environments to include after a matching "until" environment was identified.

Details

Consider the following R script evaluated in the global environment:

cargo <- rnorm(1e6)
a <- 2
f <- local({
  pi <- 3.14
  function() {
    n <- 4
    a * pi / n
  }
})

The environment of function f() is the local environment that contains the pi object, i.e. environment(f)$pi exists. The parent environment of this environment is parent.envir(environment(f)), which can also be obtained as parent_env(f). This environment contains objects a and cargo, i.e. parent_env(f)$a and parent_env(f)$cargo exist. If we sourced the script in the global environment, then parent_env(f) is the global environment.

We can retrieve these two "ancestral" environments of f() using parent_envs(f), which can be represented visually as:

+-----------------+
| parent_env(f):  | == parent_envs(f)[[2]]
| cargo = { 1e6 } | == parent_env(f, n = 1L)
| a = 2           | == top_env(f)
| f               | == globalenv()
+-----------------+
        ^
        |
+-----------------+
| environment(f): | == parent_envs(f)[[1]]
| pi = 3.14       | == parent_env(f, n = 0L)
+-----------------+

Value

parent_env() returns an environment.

parent_envs() returns a named list of environments, where the names correspond to environment_name() of each environment. The first element is always envir. If extra = 0L (default), the last is until or emptyenv(), which equals top_env().

top_env() returns the top parent environment, which is either the until environment or the empty environment.

Examples

parent_env()

ns <- getNamespace("stats")
print(ns)
parent_env(ns, n = 0)    ## same as 'ns'
parent_env(ns, n = 1)    ## default
parent_env(ns, n = 2)
parent_env(ns, n = 3)
parent_env(ns, n = Inf)  ## always emptyenv()

f <- local({
  a <- 42
  local({
    pi <- 3.14
    function() pi * a
  })
})
environment(f)
parent_env(f, n = 0)     ## same as environment(f)
parent_env(f, n = 1)
parent_env(f, n = 2)
parent_env(f, n = 3)

parent_envs(emptyenv())
parent_envs(baseenv())
parent_envs(globalenv())
parent_envs(new.env(parent = baseenv()))

f <- local({
  a <- 42
  local({
    pi <- 3.14
    function() pi * a
  })
})
f_envs <- parent_envs(f, until = environment())
names(f_envs)

f_envs <- parent_envs(f, until = environment(), extra = 1L)
names(f_envs)

a <- 42
pi <- 3.14
f <- function() pi * a
env <- top_env(f)
print(env)
#stopifnot(identical(env, environment()))

f <- local({
  a <- 42
  local({
    pi <- 3.14
    function() pi * a
  })
})
env <- top_env(f)
print(env)
#stopifnot(identical(env, environment()))

make_fcn <- function() {
  a <- 42
  pi <- 3.14
  function() pi * a
}
f <- make_fcn()
env <- top_env(f)
print(env)
#stopifnot(identical(env, environment()))

HenrikBengtsson/environments documentation built on Jan. 15, 2025, 12:58 a.m.