search_envs: Search path environments

In rlang: Functions for Base Types and Core R and 'Tidyverse' Features

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.