rlang (version 0.0.0.9000)

scoped_env: Scope environments

Description

Scope environments are named environments which form a parent-child hierarchy called the search path. They define what objects you can see (are in scope) from your workspace. They typically are package environments, i.e. special environments containing all exported functions from a package (and whose parent environment is the package namespace, which also contains unexported functions). Package environments are attached to the search path with library(). Note however that any environment can be attached to the search path, for example with the unrecommended attach() base function which transforms vectors to scoped environments.

Usage

scoped_env(nm)
pkg_env(pkg)
pkg_env_name(pkg)
scoped_names()
is_scoped(nm)
base_env()
global_env()

Arguments

nm
The name of an environment attached to the search path. Call search() to see what is currently on the path.
pkg
The name of a package.

Details

Scope environments form a chain with newly attached environments as the childs of earlier ones. However, the global environment, where everything you define at top-level ends up, is pinned as the head of the linked list. Likewise, the base package environment is always the tail of the chain. You can obtain those environments with global_env() and base_env() respectively. The global environment is always the environment of the very first evaluation frame on the stack, see global_frame() and eval_stack().

You can list all scoped environments with scoped_names(). With is_scoped() you can check whether a named environment is on the search path. pkg_env() returns the scope environment of packages if they are attached to the search path, and throws an error otherwise.

Examples

Run this code
# List the names of scoped environments:
nms <- scoped_names()
nms

# The global environment is always the first in the chain:
scoped_env(nms[[1]])

# And the scoped environment of the base package is always the last:
scoped_env(nms[[length(nms)]])

# These two environments have their own shortcuts:
global_env()
base_env()

# Packages appear in the search path with a special name. Use
# pkg_env_name() to create that name:
pkg_env_name("rlang")
scoped_env(pkg_env_name("rlang"))

# Alternatively, get the scoped environment of a package with
# pkg_env():
pkg_env("utils")

Run the code above in your browser using DataCamp Workspace