R: Search path environments

search_envs {rlang} | R 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"))`.

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

    # 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")

[Package rlang version 0.4.5 Index]