abort {rlang}R Documentation

Signal an error, warning, or message

Description

These functions are equivalent to base functions base::stop(), base::warning() and base::message(), but make it easy to supply condition metadata:

interrupt() allows R code to simulate a user interrupt of the kind that is signalled with Ctrl-C. It is currently not possible to create custom interrupt condition objects.

Usage

abort(message, .subclass = NULL, ..., trace = NULL, call = NULL,
  parent = NULL, msg, type)

warn(message, .subclass = NULL, ..., call = NULL, msg, type)

inform(message, .subclass = NULL, ..., call = NULL, msg, type)

signal(message, .subclass, ...)

interrupt()

Arguments

message

The message to display.

.subclass

Subclass of the condition. This allows your users to selectively handle the conditions signalled by your functions.

...

Additional data to be stored in the condition object.

trace

A trace object created by trace_back().

call

Deprecated as of rlang 0.3.0. Storing the full backtrace is now preferred to storing a simple call.

parent

A parent condition object created by abort().

msg, type

These arguments were renamed to message and .type and are deprecated as of rlang 0.3.0.

Backtrace

Unlike stop() and warning(), these functions don't include call information by default. This saves you from typing call. = FALSE and produces cleaner error messages.

A backtrace is always saved into error objects. You can print a simplified backtrace of the last error by calling last_error() and a full backtrace with summary(last_error()).

You can also display a backtrace with the error message by setting the option rlang_backtrace_on_error. It supports the following values:

Mufflable conditions

Signalling a condition with inform() or warn() causes a message to be displayed in the console. These messages can be muffled with base::suppressMessages() or base::suppressWarnings().

On recent R versions (>= R 3.5.0), interrupts are typically signalled with a "resume" restart. This is however not guaranteed.

Lifecycle

These functions were changed in rlang 0.3.0 to take condition metadata with .... Consequently:

See Also

with_abort() to convert all errors to rlang errors.

Examples

# These examples are guarded to avoid throwing errors
if (FALSE) {

# Signal an error with a message just like stop():
abort("Something bad happened")

# Give a class to the error:
abort("Something bad happened", "somepkg_bad_error")

# This will allow your users to handle the error selectively
tryCatch(
  somepkg_function(),
  somepkg_bad_error = function(err) {
    warn(err$message) # Demote the error to a warning
    NA                # Return an alternative value
  }
)

# You can also specify metadata that will be stored in the condition:
abort("Something bad happened", "somepkg_bad_error", data = 1:10)

# This data can then be consulted by user handlers:
tryCatch(
  somepkg_function(),
  somepkg_bad_error = function(err) {
    # Compute an alternative return value with the data:
    recover_error(err$data)
  }
)

# If you call low-level APIs it is good practice to catch technical
# errors and rethrow them with a more meaningful message. Pass on
# the caught error as `parent` to get a nice decomposition of
# errors and backtraces:
file <- "http://foo.bar/baz"
tryCatch(
  download(file),
  error = function(err) {
    msg <- sprintf("Can't download `%s`", file)
    abort(msg, parent = err)
})

# Unhandled errors are saved automatically by `abort()` and can be
# retrieved with `last_error()`. The error prints with a simplified
# backtrace:
abort("Saved error?")
last_error()

# Use `summary()` to print the full backtrace and the condition fields:
summary(last_error())

}

[Package rlang version 0.3.4 Index]