Skip to contents

Throw an Error, Warning, or Message

Source: R/err.R
err.Rd

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

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.

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.

See also

Examples

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

try(f(1))
#> Error : This is an error, and `x` is a number.

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

try(g(1))
#> Warning: This warning displayed last.
#> Warning: This warning displayed first.

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()
#> Is a period added at the end?
#> Not when the message ends in punctuation!
#> or when multiple
#> ! messages
#> ✔ are
#> • displayed
#> Otherwise yes.