search_envs: Search path environments

View source: R/env-special.R

search_envsR Documentation

Search path environments

Description

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.

Usage

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.

x

An environment or a search name.

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

Examples

# List the search names of environments attached to the search path:
search()

# Get the corresponding environments:
search_envs()

# The global environment and the base package are always first and
# last in the chain, respectively:
envs <- search_envs()
envs[[1]]
envs[[length(envs)]]

# These two environments have their own shortcuts:
global_env()
base_env()

# Packages appear in the search path with a special name. Use
# pkg_env_name() to create that name:
pkg_env_name("rlang")
search_env(pkg_env_name("rlang"))

# Alternatively, get the scoped environment of a package with
# pkg_env():
pkg_env("utils")

rlang documentation built on June 22, 2024, 9:31 a.m.