rlang (version 0.0.0.9000)

env: Get an environment.

Description

Environments are objects that create a scope for evaluation of R code. Reification of scope is one of the most powerful feature of the R language: it allows you to change what objects a function or expression sees when it is evaluated. In R, scope is hierarchical: each environment is defined with a parent environment. An environment and its grandparents form together a linear hierarchy. All objects within the grandparents are in scope unless they are eclipsed by synonyms (other bindings with the same names) in child environments.

Usage

env(env = caller_env())
"env"(env = caller_env())
"env"(env = caller_env())
"env"(env = caller_env())
"env"(env = caller_env())
"env"(env = caller_env())
"env"(env = caller_env())
new_env(parent = NULL, data = list())
env_parent(env = caller_env(), n = 1)
env_tail(env = caller_env())

Arguments

env

An environment or an object with a S3 method for env(). If missing, the environment of the current evaluation frame is returned.

parent

A parent environment. Can be an object with a S3 method for as_env().

data

A vector with unique names which defines bindings (pairs of name and value). See is_dictionary().

n

The number of generations to go through.

Details

env() is a S3 generic. Methods are provided for functions, formulas and frames. If called with a missing argument, the environment of the current evaluation frame (see eval_stack()) is returned. If you call env() with an environment, it acts as the identity function and the environment is simply returned (this helps simplifying code when writing generic functions).

new_env() creates a new environment. env_parent() returns the parent environment of env if called with n = 1, the grandparent with n = 2, etc. env_tail() searches through the parents and returns the one which has empty_env() as parent.

See Also

scoped_env, env_has(), env_assign().

Examples

# Get the environment of frame objects. If no argument is supplied,
# the current frame is used:
fn <- function() {
  list(
    env(call_frame()),
    env()
  )
}
fn()

# Environment of closure functions:
env(fn)

# There is also an assignment operator:
env(fn) <- base_env()
env(fn)


# new_env() creates by default an environment whose parent is the
# empty environment. Here we return a new environment that has
# the evaluation environment (or frame environment) of a function
# as parent:
fn <- function() {
  my_object <- "A"
  new_env(env())
}
frame_env <- fn()

# The new environment is empty:
env_has(frame_env, "my_object")

# But sees objects defined inside fn() by inheriting from its
# parent:
env_has(frame_env, "my_object", inherit = TRUE)


# Create a new environment with a particular scope by setting a
# parent. When inheriting from the empty environment (the default),
# the environment will have no object in scope at all:
env <- new_env()
env_has(env, "lapply", inherit = TRUE)

# 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:
env <- new_env(base_env())
env_has(env, "lapply", inherit = TRUE)

# Note that all other package environments inherit from base_env()
# as well:
env <- new_env(pkg_env("rlang"))
env_has(env, "env_has", inherit = TRUE)
env_has(env, "lapply", inherit = TRUE)


# The parent argument of new_env() is passed to as_env() to provide
# handy shortcuts:
env <- new_env("rlang")
identical(env_parent(env), pkg_env("rlang"))


# Get the parent environment with env_parent():
env_parent(global_env())

# Or the tail environment with env_tail():
env_tail(global_env())


# By default, env_parent() returns the parent environment of the
# current evaluation frame. If called at top-level (the global
# frame), the following two expressions are equivalent:
env_parent()
env_parent(global_env())

# This default is more handy when called within a function. In this
# case, the enclosure environment of the function is returned
# (since it is the parent of the evaluation frame):
enclos_env <- new_env(pkg_env("rlang"))
fn <- with_env(enclos_env, function() env_parent())
identical(enclos_env, fn())