R: Signal an error, warning, or message

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:

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

### 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. Experimental: Can also be a named character vector, in which case the message is assembled as a list of bullets. See `cnd_message()` to learn how names control the bulleted output.
`.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` | Defunct as of rlang 0.4.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 `.subclass` and are defunct as of rlang 0.4.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:

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

### Lifecycle

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.

### 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 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.4.1 Index]