get_env

0th

Percentile

Get or set the environment of an object

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 = caller_env(), default = NULL)

set_env(env, new_env = caller_env())

env_poke_parent(env, new_env)

Arguments
env

An environment or an object bundling an environment, e.g. a formula, quosure or closure.

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. Can be an object handled by get_env().

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.

See Also

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

Aliases
  • get_env
  • set_env
  • env_poke_parent
Examples
library(rlang) # NOT RUN { # Get the environment of frame objects. If no argument is supplied, # the current frame is used: fn <- function() { list( get_env(call_frame()), get_env() ) } fn() # Environment of closure functions: 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), get_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) # }
Documentation reproduced from package rlang, version 0.2.0, License: GPL-3

Community examples

Looks like there are no examples yet.