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()
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. |
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/2021-11-29/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"