EVOLUTION-MANAGER

Edit File: env.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Create a new environment</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for env {rlang}"><tr><td>env {rlang}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Create a new environment</h2>

<h3>Description</h3>

<p>These functions create new environments.
</p>

<ul>
<li> <p><code>env()</code> creates a child of the current environment by default
and takes a variable number of named objects to populate it.
</p>
</li>
<li> <p><code>new_environment()</code> creates a child of the empty environment by
default and takes a named list of objects to populate it.
</p>
</li></ul>

<h3>Usage</h3>

<pre>
env(...)

child_env(.parent, ...)

new_environment(data = list(), parent = empty_env())
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>..., data</code></td>
<td>
<p>&lt;<a href="dyn-dots.html">dynamic</a>&gt; Named values. You can
supply one unnamed to specify a custom parent, otherwise it
defaults to the current environment.</p>
</td></tr>
<tr valign="top"><td><code>.parent, parent</code></td>
<td>
<p>A parent environment.</p>
</td></tr>
</table>

<h3>Environments as objects</h3>

<p>Environments are containers of uniquely named objects. Their most
common use is to provide a scope for the evaluation of R
expressions. Not all languages have first class environments,
i.e. can manipulate scope as regular objects. Reification of scope
is one of the most powerful features of R as it allows you to change
what objects a function or expression sees when it is evaluated.
</p>
<p>Environments also constitute a data structure in their own
right. They are a collection of uniquely named objects, subsettable
by name and modifiable by reference. This latter property (see
section on reference semantics) is especially useful for creating
mutable OO systems (cf the <a href="https://github.com/r-lib/R6">R6 package</a>
and the <a href="https://ggplot2.tidyverse.org/articles/extending-ggplot2.html">ggproto system</a>
for extending ggplot2).
</p>

<h3>Inheritance</h3>

<p>All R environments (except the <a href="empty_env.html">empty environment</a>) are
defined with a parent environment. An environment and its
grandparents thus form a linear hierarchy that is the basis for
<a href="https://en.wikipedia.org/wiki/Scope_(computer_science)">lexical scoping</a> in
R. When R evaluates an expression, it looks up symbols in a given
environment. If it cannot find these symbols there, it keeps
looking them up in parent environments. This way, objects defined
in child environments have precedence over objects defined in
parent environments.
</p>
<p>The ability of overriding specific definitions is used in the
tidyeval framework to create powerful domain-specific grammars. A
common use of masking is to put data frame columns in scope. See
for example <code><a href="as_data_mask.html">as_data_mask()</a></code>.
</p>

<h3>Reference semantics</h3>

<p>Unlike regular objects such as vectors, environments are an
<a href="is_copyable.html">uncopyable</a> object type. This means that if you
have multiple references to a given environment (by assigning the
environment to another symbol with <code style="white-space: pre;">&lt;-</code> or passing the environment
as argument to a function), modifying the bindings of one of those
references changes all other references as well.
</p>

<h3>Life cycle</h3>

<ul>
<li> <p><code>child_env()</code> is in the questioning stage. It is redundant now
that <code>env()</code> accepts parent environments.
</p>
</li></ul>

<h3>Examples</h3>

<pre>
# env() creates a new environment which has the current environment
# as parent
env &lt;- env(a = 1, b = "foo")
env$b
identical(env_parent(env), current_env())

# Supply one unnamed argument to override the default:
env &lt;- env(base_env(), a = 1, b = "foo")
identical(env_parent(env), base_env())

# child_env() lets you specify a parent:
child &lt;- child_env(env, c = "bar")
identical(env_parent(child), env)

# This child environment owns `c` but inherits `a` and `b` from `env`:
env_has(child, c("a", "b", "c", "d"))
env_has(child, c("a", "b", "c", "d"), inherit = TRUE)

# `parent` is passed to as_environment() to provide handy
# shortcuts. Pass a string to create a child of a package
# environment:
child_env("rlang")
env_parent(child_env("rlang"))

# Or `NULL` to create a child of the empty environment:
child_env(NULL)
env_parent(child_env(NULL))

# The base package environment is often a good default choice for a
# parent environment because it contains all standard base
# functions. Also note that it will never inherit from other loaded
# package environments since R keeps the base package at the tail
# of the search path:
base_child &lt;- child_env("base")
env_has(base_child, c("lapply", "("), inherit = TRUE)

# On the other hand, a child of the empty environment doesn't even
# see a definition for `(`
empty_child &lt;- child_env(NULL)
env_has(empty_child, c("lapply", "("), inherit = TRUE)

# Note that all other package environments inherit from base_env()
# as well:
rlang_child &lt;- child_env("rlang")
env_has(rlang_child, "env", inherit = TRUE)     # rlang function
env_has(rlang_child, "lapply", inherit = TRUE)  # base function

# Both env() and child_env() support tidy dots features:
objs &lt;- list(b = "foo", c = "bar")
env &lt;- env(a = 1, !!! objs)
env$c

# You can also unquote names with the definition operator `:=`
var &lt;- "a"
env &lt;- env(!!var := "A")
env$a

# Use new_environment() to create containers with the empty
# environment as parent:
env &lt;- new_environment()
env_parent(env)

# Like other new_ constructors, it takes an object rather than dots:
new_environment(list(a = "foo", b = "bar"))
</pre>

<hr /><div style="text-align: center;">[Package <em>rlang</em> version 1.0.6 <a href="00Index.html">Index</a>]</div>
</body></html>