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()

Arguments

name

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:".

pkg

The name of a package.

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 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().

Examples

# 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" "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: 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] "/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"