R: Get or set the environment of an object

get_env {rlang} | R Documentation

## Get or set the environment of an object

### Description

These functions dispatch internally with methods for functions, formulas and frames. If called with a missing argument, the environment of the current evaluation frame (see `ctxt_stack()`) is returned. If you call `get_env()` with an environment, it acts as the identity function and the environment is simply returned (this helps simplifying code when writing generic functions for environments).

### Usage

    get_env(env, default = NULL)

    set_env(env, new_env = caller_env())

    env_poke_parent(env, new_env)

### Arguments

`env` | An environment.
`default` | The default environment in case `env` does not wrap an environment. If `NULL` and no environment could be extracted, an error is issued.
`new_env` | An environment to replace `env` with.

### Details

While `set_env()` returns a modified copy and does not have side effects, `env_poke_parent()` operates changes the environment by side effect. This is because environments are uncopyable. Be careful not to change environments that you don't own, e.g. a parent environment of a function from a package.

### Life cycle

- Using `get_env()` without supplying `env` is deprecated as of rlang 0.3.0. Please use `current_env()` to retrieve the current environment.

- Passing environment wrappers like formulas or functions instead of bare environments is deprecated as of rlang 0.3.0. This internal genericity was causing confusion (see issue #427). You should now extract the environment separately before calling these functions.

### See Also

`quo_get_env()` and `quo_set_env()` for versions of `get_env()` and `set_env()` that only work on quosures.

### Examples

    # Environment of closure functions:
    fn <- function() "foo"
    get_env(fn)

    # Or of quosures or formulas:
    get_env(~foo)
    get_env(quo(foo))

    # Provide a default in case the object doesn't bundle an environment.
    # Let's create an unevaluated formula:
    f <- quote(~foo)

    # The following line would fail if run because unevaluated formulas
    # don't bundle an environment (they didn't have the chance to
    # record one yet):
    # get_env(f)

    # It is often useful to provide a default when you're writing
    # functions accepting formulas as input:
    default <- env()
    identical(get_env(f, default), default)

    # set_env() can be used to set the enclosure of functions and
    # formulas. Let's create a function with a particular environment:
    env <- child_env("base")
    fn <- set_env(function() NULL, env)

    # That function now has `env` as enclosure:
    identical(get_env(fn), env)
    identical(get_env(fn), current_env())

    # set_env() does not work by side effect. Setting a new environment
    # for fn has no effect on the original function:
    other_env <- child_env(NULL)
    set_env(fn, other_env)
    identical(get_env(fn), other_env)

    # Since set_env() returns a new function with a different
    # environment, you'll need to reassign the result:
    fn <- set_env(fn, other_env)
    identical(get_env(fn), other_env)

[Package rlang version 0.4.3 Index]