search_envs {rlang} | R Documentation |
Search path environments
Description
The search path is a chain of environments containing exported functions of attached packages.
The API includes:
-
base::search()
to get the names of environments attached to the search path. -
search_envs()
returns the environments on the search path as a list. -
pkg_env_name()
takes a bare package name and prefixes it with"package:"
. Attached package environments have search names of the formpackage:name
. -
pkg_env()
takes a bare package name and returns the scoped environment of packages if they are attached to the search path, and throws an error otherwise. It is a shortcut forsearch_env(pkg_env_name("pkgname"))
. -
global_env()
andbase_env()
(simple aliases forglobalenv()
andbaseenv()
). These are respectively the first and last environments of the search path. -
is_attached()
returnsTRUE
when its argument (a search name or a package environment) is attached to the search path.
Usage
search_envs()
search_env(name)
pkg_env(pkg)
pkg_env_name(pkg)
is_attached(x)
base_env()
global_env()
Arguments
name |
The name of an environment attached to the search
path. Call |
pkg |
The name of a package. |
x |
An environment or a search name. |
The search path
This chain of environments determines what objects are visible from the global workspace. It contains the following elements:
The chain always starts with
global_env()
and finishes withbase_env()
which inherits from the terminal environmentempty_env()
.Each
base::library()
call attaches a new package environment to the search path. Attached packages are associated with a search name.In addition, any list, data frame, or environment can be attached to the search path with
base::attach()
.
Examples
# List the search names of environments attached to the search path:
search()
# Get the corresponding environments:
search_envs()
# The global environment and the base package are always first and
# last in the chain, respectively:
envs <- search_envs()
envs[[1]]
envs[[length(envs)]]
# 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")
search_env(pkg_env_name("rlang"))
# Alternatively, get the scoped environment of a package with
# pkg_env():
pkg_env("utils")