err: Throw an Error, Warning, or Message
In arg: Clean and Simple Argument Checking

View source: R/err.R

err	R Documentation

Throw an Error, Warning, or Message

Description

These functions are similar to stop()/cli::cli_abort(), warning()/cli::cli_warn(), and message()/cli::cli_inform(), throwing an error, warning, and message, respectively. Minor processing is done to capitalize the first letter of the message, add a period at the end (if it makes sense to), and add information about the calling function.

Usage

err(m, .call, .envir = rlang::caller_env())

wrn(m, immediate = TRUE, .envir = rlang::caller_env())

msg(m, .envir = rlang::caller_env())

Arguments

`m`	the message to be displayed, passed to the `message` argument of `rlang::abort()`, `rlang::warn()`, or `rlang::inform()`.
`.call`	the execution environment of a currently running function, e.g. `.call = rlang::current_env()`. The corresponding function call is retrieved and mentioned in error messages as the source of the error. See the `call` argument of `rlang::abort()` for details. Set to `NULL` to omit call information. The default is to search along the call stack for the first user-facing function in another package, if any.
`.envir`	the environment to evaluate the glue expressions in. See `rlang::abort()` for details. Typically this does not need to be changed.
`immediate`	whether to output the warning immediately (`TRUE`, the default) or save all warnings until the end of execution (`FALSE`). See `warning()` for details. Note that the default here differs from that of `warning()`.

Details

These functions are simple wrappers for the corresponding functions in rlang, namely rlang::abort() for err(), rlang::warn() for wrn(), and rlang::inform() for msg(), but which function almost identically to the cli versions. Their main differences are that they additionally process the input (capitalizing the first character of the message and adding a period to the end if needed, unless multiple strings are provided). err() is used inside all ⁠arg_*()⁠ functions in arg.

Value

err() throws an error condition. wrn() throws a warning condition and invisibly returns the formatted warning message as a string. msg() signals a message and invisibly returns NULL.

Examples

f <- function(x) {
  err("this is an error, and {.arg x} is {.type {x}}")
}

try(f(1))

g <- function(x) {
  wrn("this warning displayed last", immediate = FALSE)
  wrn("this warning displayed first")
}

try(g(1))

h <- function() {
  msg("is a period added at the end?")
  msg("not when the message ends in punctuation!")
  msg(c("or when multiple",
        "!" = "messages",
        "v" = "are",
        "*" = "displayed"))
  msg("otherwise yes")
}

h()

arg documentation built on April 9, 2026, 5:09 p.m.