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 form package: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 for
search_env(pkg_env_name("pkgname"))
.
global_env()
and base_env()
(simple aliases for globalenv()
and baseenv()
). These are respectively the first and last
environments of the search path.
is_attached()
returns TRUE
when its argument (a search name
or a package environment) is attached to the search path.
search_envs()
search_env(name)
pkg_env(pkg)
pkg_env_name(pkg)
is_attached(x)
base_env()
global_env()
The name of an environment attached to the search
path. Call base::search()
to get the names of environments
currently attached to the search path. Note that the search name
of a package environment is prefixed with "package:"
.
The name of a package.
An environment or a search name.
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 with
base_env()
which inherits from the terminal environment
empty_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()
.
# List the search names of environments attached to the search path:
search()
#> [1] ".GlobalEnv" "package:rlang" "package:stats"
#> [4] "package:graphics" "package:grDevices" "package:datasets"
#> [7] "renv:shims" "package:utils" "package:methods"
#> [10] "Autoloads" "tools:callr" "package:base"
# Get the corresponding environments:
search_envs()
#> [[1]] $ <env: global>
#> [[2]] $ <env: package:rlang>
#> [[3]] $ <env: package:stats>
#> [[4]] $ <env: package:graphics>
#> [[5]] $ <env: package:grDevices>
#> [[6]] $ <env: package:datasets>
#> [[7]] $ <env: renv:shims>
#> [[8]] $ <env: package:utils>
#> [[9]] $ <env: package:methods>
#> [[10]] $ <env: Autoloads>
#> [[11]] $ <env: tools:callr>
#> [[12]] $ <env: package:base>
# The global environment and the base package are always first and
# last in the chain, respectively:
envs <- search_envs()
envs[[1]]
#> <environment: R_GlobalEnv>
envs[[length(envs)]]
#> <environment: base>
# These two environments have their own shortcuts:
global_env()
#> <environment: R_GlobalEnv>
base_env()
#> <environment: base>
# Packages appear in the search path with a special name. Use
# pkg_env_name() to create that name:
pkg_env_name("rlang")
#> [1] "package:rlang"
search_env(pkg_env_name("rlang"))
#> <environment: package:rlang>
#> attr(,"name")
#> [1] "package:rlang"
#> attr(,"path")
#> [1] "/data/GHE/deployment/deployments/2022-03-22/renv/library/R-4.1/x86_64-pc-linux-gnu/rlang"
# Alternatively, get the scoped environment of a package with
# pkg_env():
pkg_env("utils")
#> <environment: package:utils>
#> attr(,"name")
#> [1] "package:utils"
#> attr(,"path")
#> [1] "/opt/R/4.1.1/lib/R/library/utils"