| 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 class 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 = NULL,
class = NULL,
...,
trace = NULL,
parent = NULL,
.subclass = deprecated()
)
warn(
message = NULL,
class = NULL,
...,
.frequency = c("always", "regularly", "once"),
.frequency_id = NULL,
.subclass = deprecated()
)
inform(
message = NULL,
class = NULL,
...,
.file = NULL,
.frequency = c("always", "regularly", "once"),
.frequency_id = NULL,
.subclass = deprecated()
)
signal(message, class, ..., .subclass = deprecated())
interrupt()
message |
The message to display. Character vectors are
formatted with If a message is not supplied, it is expected that the message is
generated lazily through conditionMessage(). In
that case, |
class |
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 |
parent |
A parent condition object created by |
.subclass |
This argument was renamed to |
.frequency |
How frequently should the warning or message be
displayed? By default ( |
.frequency_id |
A unique identifier for the warning or
message. This is used when |
.file |
Where the message is printed. This should be a
connection or character string which will be passed to By default, |
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.
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(conditionMessage(err)) # 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 handle
# technical errors and rethrow them with a more meaningful
# message. Always prefer doing this from `withCallinghandlers()`
# rather than `tryCatch()` because the former preserves the stack
# on error and makes it possible for users to use `recover()`.
file <- "http://foo.bar/baz"
try(withCallinghandlers(
download(file),
error = function(err) {
msg <- sprintf("Can't download `%s`", file)
abort(msg, parent = err)
}))
# Note how we supplied the parent error to `abort()` as `parent` to
# get a decomposition of error messages across error contexts.
# 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())
}