need {suggests}

Declare that packages are needed

Description

Declare that one or more packages are required by subsequent functionality; and if they're missing, either prompt the user to install them, or exit with an informative error message.

Usage

need(
  ...,
  msg = NULL,
  install_cmd = NULL,
  ask = interactive(),
  load = FALSE,
  lib.loc = NULL
)

Arguments

...

Names of required packages, as character strings. You can require a minimum version by appending ⁠>=[version]⁠ to a package name - see Examples.

msg

Custom message to display; if NULL, an informative one will be constructed.

install_cmd

Installation command to run, as a call (i.e. probably wrapped with quote() or substitute()). If NULL, install.packages() will be used for package installation.

ask

Whether to give the user the option of installing the required packages immediately.

load

Whether to make sure packages can be loaded - significantly slower, but gives an extra level of certainty.

lib.loc

Passed to utils::packageVersion().

Value

Invisibly, any package names from ... which were installed.

Examples

## Not run: 
  need("dplyr")
  need("dplyr", "tidyr")

  # All unnamed arguments will be combined into one list of package names
  shared_deps <- c("dplyr", "tidyr")
  need(shared_deps, "stringr") # same as need("dplyr", "tidyr", "stringr")

  # You can require a minimum version for some or all packages
  need("dplyr>=1.0.0", "tidyr")


  # Typically you'll want to use need() within a function
  read_data <- function(path, clean_names = FALSE) {

    # Call need() as early as possible, to avoid wasted work
    if (isTRUE(clean_names))
      suggests::need("janitor")

    output <- utils::read.csv(path)

    if (isTRUE(clean_names))
      output <- janitor::clean_names(output)

    output
  }


  # You can provide a custom message and/or installation command if needed
  need(
    "dplyr",
    msg = "We need the development version of dplyr, for now!",
    install_cmd = quote(remotes::install_github("tidyverse/dplyr"))
  )


## End(Not run)