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")).
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() (technically, it finishes with the empty_env()
which the base package environment inherits from).
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>#> <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/deployment/2020-03-30/renv/library/R-3.6/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/3.6.2/lib/R/library/utils"