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. |
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" "devtools_shims" "package:rlang" #> [4] "package:testthat" "package:stats" "package:graphics" #> [7] "package:grDevices" "package:utils" "package:datasets" #> [10] "package:methods" "Autoloads" "tools:callr" #> [13] "package:base"# Get the corresponding environments: search_envs()#> [[1]] $ <env: global> #> [[2]] $ <env: devtools_shims> #> [[3]] $ <env: package:rlang> #> [[4]] $ <env: package:testthat> #> [[5]] $ <env: package:stats> #> [[6]] $ <env: package:graphics> #> [[7]] $ <env: package:grDevices> #> [[8]] $ <env: package:utils> #> [[9]] $ <env: package:datasets> #> [[10]] $ <env: package:methods> #> [[11]] $ <env: Autoloads> #> [[12]] $ <env: tools:callr> #> [[13]] $ <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] "/home/travis/build/r-lib/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] "/home/travis/R-bin/lib/R/library/utils"