Get the ancestral environments of an environment

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.

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.

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)
+-----------------+

Examples

parent_env()
#> <environment: 0x55f413243608>

ns <- getNamespace("stats")
print(ns)
#> <environment: namespace:stats>
parent_env(ns, n = 0)    ## same as 'ns'
#> <environment: namespace:stats>
parent_env(ns, n = 1)    ## default
#> <environment: 0x55f40ddefb30>
#> attr(,"name")
#> [1] "imports:stats"
parent_env(ns, n = 2)
#> <environment: namespace:base>
parent_env(ns, n = 3)
#> <environment: R_GlobalEnv>
parent_env(ns, n = Inf)  ## always emptyenv()
#> <environment: R_EmptyEnv>

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

parent_envs(emptyenv())
#> $R_EmptyEnv
#> <environment: R_EmptyEnv>
#> 
parent_envs(baseenv())
#> $`package:base`
#> <environment: base>
#> 
#> $R_EmptyEnv
#> <environment: R_EmptyEnv>
#> 
parent_envs(globalenv())
#> $R_GlobalEnv
#> <environment: R_GlobalEnv>
#> 
#> $`package:environments`
#> <environment: package:environments>
#> attr(,"name")
#> [1] "package:environments"
#> attr(,"path")
#> [1] "/tmp/hb/Rtmp3egMWL/temp_libpath229fec1e201c7f/environments"
#> 
#> $`package:stats`
#> <environment: package:stats>
#> attr(,"name")
#> [1] "package:stats"
#> attr(,"path")
#> [1] "/home/hb/shared/software/CBI/R-4.2.1-gcc9/lib/R/library/stats"
#> 
#> $`package:graphics`
#> <environment: package:graphics>
#> attr(,"name")
#> [1] "package:graphics"
#> attr(,"path")
#> [1] "/home/hb/shared/software/CBI/R-4.2.1-gcc9/lib/R/library/graphics"
#> 
#> $`package:grDevices`
#> <environment: package:grDevices>
#> attr(,"name")
#> [1] "package:grDevices"
#> attr(,"path")
#> [1] "/home/hb/shared/software/CBI/R-4.2.1-gcc9/lib/R/library/grDevices"
#> 
#> $`package:utils`
#> <environment: package:utils>
#> attr(,"name")
#> [1] "package:utils"
#> attr(,"path")
#> [1] "/home/hb/shared/software/CBI/R-4.2.1-gcc9/lib/R/library/utils"
#> 
#> $`package:datasets`
#> <environment: package:datasets>
#> attr(,"name")
#> [1] "package:datasets"
#> attr(,"path")
#> [1] "/home/hb/shared/software/CBI/R-4.2.1-gcc9/lib/R/library/datasets"
#> 
#> $`package:methods`
#> <environment: package:methods>
#> attr(,"name")
#> [1] "package:methods"
#> attr(,"path")
#> [1] "/home/hb/shared/software/CBI/R-4.2.1-gcc9/lib/R/library/methods"
#> 
#> $Autoloads
#> <environment: 0x55f40d0943e0>
#> attr(,"name")
#> [1] "Autoloads"
#> 
#> $`tools:callr`
#> <environment: 0x55f40de3d090>
#> attr(,"name")
#> [1] "tools:callr"
#> 
#> $`package:base`
#> <environment: base>
#> 
#> $R_EmptyEnv
#> <environment: R_EmptyEnv>
#> 
parent_envs(new.env(parent = baseenv()))
#> $`0x55f4143d0948`
#> <environment: 0x55f4143d0948>
#> 
#> $`package:base`
#> <environment: base>
#> 
#> $R_EmptyEnv
#> <environment: R_EmptyEnv>
#> 

f <- local({
  a <- 42
  local({
    pi <- 3.14
    function() pi * a
  })
})
f_envs <- parent_envs(f, until = environment())
names(f_envs)
#> [1] "0x55f415d7de68" "0x55f415d7b1b8" "0x55f4162252d0"

f_envs <- parent_envs(f, until = environment(), extra = 1L)
names(f_envs)
#> [1] "0x55f415d7de68" "0x55f415d7b1b8" "0x55f4162252d0" "0x55f413243608"

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

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

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