| env_bind {rlang} | R Documentation |
These functions create bindings in an environment. The bindings are
supplied through ... as pairs of names and values or expressions.
env_bind() is equivalent to evaluating a <- expression within
the given environment. This function should take care of the
majority of use cases but the other variants can be useful for
specific problems.
env_bind() takes named values which are bound in .env.
env_bind() is equivalent to base::assign().
env_bind_fns() takes named functions and creates active
bindings in .env. This is equivalent to
base::makeActiveBinding(). An active binding executes a
function each time it is evaluated. env_bind_fns() takes dots
with implicit splicing, so that you can supply
both named functions and named lists of functions.
If these functions are closures they are lexically
scoped in the environment that they bundle. These functions can
thus refer to symbols from this enclosure that are not actually
in scope in the dynamic environment where the active bindings are
invoked. This allows creative solutions to difficult problems
(see the implementations of dplyr::do() methods for an
example).
env_bind_exprs() takes named expressions. This is equivalent
to base::delayedAssign(). The arguments are captured with
exprs() (and thus support call-splicing and unquoting) and
assigned to symbols in .env. These expressions are not
evaluated immediately but lazily. Once a symbol is evaluated, the
corresponding expression is evaluated in turn and its value is
bound to the symbol (the expressions are thus evaluated only
once, if at all).
env_bind(.env, ...)
.env |
An environment or an object bundling an environment,
e.g. a formula, quosure or closure.
This argument is passed to |
... |
Pairs of names and expressions, values or functions. These dots support tidy dots features. |
The input object .env, with its associated environment
modified in place, invisibly.
Since environments have reference semantics (see relevant section
in env() documentation), modifying the bindings of an environment
produces effects in all other references to that environment. In
other words, env_bind() and its variants have side effects.
As they are called primarily for their side effects, these functions follow the convention of returning their input invisibly.
# env_bind() is a programmatic way of assigning values to symbols
# with `<-`. We can add bindings in the current environment:
env_bind(get_env(), foo = "bar")
foo
# Or modify those bindings:
bar <- "bar"
env_bind(get_env(), bar = "BAR")
bar
# It is most useful to change other environments:
my_env <- env()
env_bind(my_env, foo = "foo")
my_env$foo
# A useful feature is to splice lists of named values:
vals <- list(a = 10, b = 20)
env_bind(my_env, !!! vals, c = 30)
my_env$b
my_env$c
# You can also unquote a variable referring to a symbol or a string
# as binding name:
var <- "baz"
env_bind(my_env, !!var := "BAZ")
my_env$baz
# env_bind() and its variants are generic over formulas, quosures
# and closures. To illustrate this, let's create a closure function
# referring to undefined bindings:
fn <- function() list(a, b)
fn <- set_env(fn, child_env("base"))
# This would fail if run since `a` etc are not defined in the
# enclosure of fn() (a child of the base environment):
# fn()
# Let's define those symbols:
env_bind(fn, a = "a", b = "b")
# fn() now sees the objects:
fn()