abort {rlang} | R Documentation |
These functions are equivalent to base functions base::stop()
,
base::warning()
and base::message()
, but make it easy to supply
condition metadata:
Supply .subclass
to create a classed condition. Typed
conditions can be captured or handled selectively, allowing for
finer-grained error handling.
Supply metadata with named ...
arguments. This data will be
stored in the condition object and can be examined by handlers.
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.
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()
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 |
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 |
msg, type |
These arguments were renamed to |
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:
"reminder"
: Invite users to call rlang::last_error()
to see a
backtrace.
"branch"
: Display a simplified backtrace.
"collapse"
: Display a collapsed backtrace tree.
"full"
: Display a full backtrace tree.
"none"
: Display nothing.
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.
These functions were changed in rlang 0.3.0 to take condition
metadata with ...
. Consequently:
All arguments were renamed to be prefixed with a dot, except for
type
which was renamed to .subclass
.
.call
(previously call
) can no longer be passed positionally.
with_abort()
to convert all errors to rlang errors.
# 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()) }