global_entrace: Entrace unexpected errors

In rlang: Functions for Base Types and Core R and 'Tidyverse' Features

Entrace unexpected errors

Description

global_entrace() enriches base errors, warnings, and messages with rlang features.

• They are assigned a backtrace. You can configure whether to display a backtrace on error with the rlang_backtrace_on_error global option.

• They are recorded in last_error(), last_warnings(), or last_messages(). You can inspect backtraces at any time by calling these functions.

Set global entracing in your RProfile with:

rlang::global_entrace()

Usage

global_entrace(enable = TRUE, class = c("error", "warning", "message"))

Arguments

enable	Whether to enable or disable global handling.
class	A character vector of one or several classes of conditions to be entraced.

Inside RMarkdown documents

Call global_entrace() inside an RMarkdown document to cause errors and warnings to be promoted to rlang conditions that include a backtrace. This needs to be done in a separate setup chunk before the first error or warning.

This is useful in conjunction with rlang_backtrace_on_error_report and rlang_backtrace_on_warning_report. To get full entracing in an Rmd document, include this in a setup chunk before the first error or warning is signalled.

```{r setup}
rlang::global_entrace()
options(rlang_backtrace_on_warning_report = "full")
options(rlang_backtrace_on_error_report = "full")
```

Under the hood

On R 4.0 and newer, global_entrace() installs a global handler with globalCallingHandlers(). On older R versions, entrace() is set as an option(error = ) handler. The latter method has the disadvantage that only one handler can be set at a time. This means that you need to manually switch between entrace() and other handlers like recover(). Also this causes a conflict with IDE handlers (e.g. in RStudio).

rlang documentation built on June 22, 2024, 9:31 a.m.