is_installed: Are packages installed in any of the libraries?

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

Are packages installed in any of the libraries?

Description

These functions check that packages are installed with minimal side effects. If installed, the packages will be loaded but not attached.

• is_installed() doesn't interact with the user. It simply returns TRUE or FALSE depending on whether the packages are installed.

• In interactive sessions, check_installed() asks the user whether to install missing packages. If the user accepts, the packages are installed with pak::pkg_install() if available, or utils::install.packages() otherwise. If the session is non interactive or if the user chooses not to install the packages, the current evaluation is aborted.

You can disable the prompt by setting the rlib_restart_package_not_found global option to FALSE. In that case, missing packages always cause an error.

Usage

is_installed(pkg, ..., version = NULL, compare = NULL)

check_installed(
  pkg,
  reason = NULL,
  ...,
  version = NULL,
  compare = NULL,
  action = NULL,
  call = caller_env()
)

Arguments

pkg	The package names. Can include version requirements, e.g. "pkg (>= 1.0.0)".
...	These dots must be empty.
version	Minimum versions for pkg. If supplied, must be the same length as pkg. NA elements stand for any versions.
compare	A character vector of comparison operators to use for version. If supplied, must be the same length as version. If NULL, >= is used as default for all elements. NA elements in compare are also set to >= by default.
reason	Optional string indicating why is pkg needed. Appears in error messages (if non-interactive) and user prompts (if interactive).
action	An optional function taking pkg and ... arguments. It is called by check_installed() when the user chooses to update outdated packages. The function is passed the missing and outdated packages as a character vector of names.
call	The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

Value

is_installed() returns TRUE if all package names provided in pkg are installed, FALSE otherwise. check_installed() either doesn't return or returns NULL.

Handling package not found errors

check_installed() signals error conditions of class rlib_error_package_not_found. The error includes pkg and version fields. They are vectorised and may include several packages.

The error is signalled with a rlib_restart_package_not_found restart on the stack to allow handlers to install the required packages. To do so, add a calling handler for rlib_error_package_not_found, install the required packages, and invoke the restart without arguments. This restarts the check from scratch.

The condition is not signalled in non-interactive sessions, in the restarting case, or if the rlib_restart_package_not_found user option is set to FALSE.

Examples

is_installed("utils")
is_installed(c("base", "ggplot5"))
is_installed(c("base", "ggplot5"), version = c(NA, "5.1.0"))

tidyverse/rlang documentation built on Oct. 31, 2024, 5:35 p.m.