Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

abort

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:

  • 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.

Usage

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

Arguments

message

The message to display. Character vectors are formatted with format_error_bullets(). The first element defines a message header and the rest of the vector defines bullets. Bullets named i and x define info and error bullets respectively, with special Unicode and colour formatting applied if possible.

If a message is not supplied, it is expected that the message is generated lazily through conditionMessage(). In that case, class must be supplied. Only inform() allows empty messages as it is occasionally useful to build user output incrementally.

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 trace object created by trace_back().

parent

A parent condition object created by abort().

.subclass

This argument was renamed to class in rlang 0.4.2. It will be deprecated in the next major version. This is for consistency with our conventions for class constructors documented in https://adv-r.hadley.nz/s3.html#s3-subclassing.

.frequency

How frequently should the warning or message be displayed? By default ("always") it is displayed at each time. If "regularly", it is displayed once every 8 hours. If "once", it is displayed once per session.

.frequency_id

A unique identifier for the warning or message. This is used when .frequency is supplied to recognise recurring conditions. This argument must be supplied if .frequency is not set to "always".

.file

Where the message is printed. This should be a connection or character string which will be passed to cat().

By default, inform() prints to standard output in interactive sessions and standard error otherwise. This way IDEs can treat messages distinctly from warnings and errors, and R scripts can still filter out the messages easily by redirecting stderr. If a sink is active, either on output or on messages, messages are printed to stderr. This ensures consistency of behaviour in interactive and non-interactive sessions.

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:

  • "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.

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.

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

}

rlang

Functions for Base Types and Core R and 'Tidyverse' Features

v0.4.11
MIT + file LICENSE
Authors
Lionel Henry [aut, cre], Hadley Wickham [aut], mikefc [cph] (Hash implementation based on Mike's xxhashlite), Yann Collet [cph] (Author of the embedded xxHash library), RStudio [cph]
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.