rlang (version 0.0.0.9000)

env_scoped: 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

env_scoped(nm)
env_package(pkg)
env_scoped_names()
is_scoped(nm)
env_base()
env_global()

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 env_global() and env_base() respectively.

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

Examples

# List the names of scoped environments:
nms <- env_scoped_names()
nms

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

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

# These two environments have their own shortcuts:
env_global()
env_base()

# Get the scoped environment of a package:
env_package("utils")