Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

get_env

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)

rlang

Functions for Base Types and Core R and 'Tidyverse' Features

v0.4.11
MIT + file LICENSE
Authors
Lionel Henry [aut, cre], Hadley Wickham [aut], mikefc [cph] (Hash implementation based on Mike's xxhashlite), Yann Collet [cph] (Author of the embedded xxHash library), RStudio [cph]
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.