rlang: entrace – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

entrace

Add backtrace from error handler

Description

entrace() interrupts an error throw to add an rlang backtrace to the error. The error throw is immediately resumed. cnd_entrace() adds a backtrace to a condition object, without any other effect. Both functions should be called directly from an error handler.

Set the error global option to rlang::entrace to transform base errors to rlang errors. These enriched errors include a backtrace. The RProfile is a good place to set the handler. See rlang_backtrace_on_error for details.

entrace() also works as a calling handler, though it is often more practical to use the higher-level function with_abort().

Usage

entrace(cnd, ..., top = NULL, bottom = NULL)

cnd_entrace(cnd, ..., top = NULL, bottom = NULL)

Arguments

`cnd`	When `entrace()` is used as a calling handler, `cnd` is the condition to handle.
`...`	Unused. These dots are for future extensions.
`top`	The first frame environment to be included in the backtrace. This becomes the top of the backtrace tree and represents the oldest call in the backtrace. This is needed in particular when you call `trace_back()` indirectly or from a larger context, for example in tests or inside an RMarkdown document where you don't want all of the knitr evaluation mechanisms to appear in the backtrace.
`bottom`	The last frame environment to be included in the backtrace. This becomes the rightmost leaf of the backtrace tree and represents the youngest call in the backtrace. Set this when you would like to capture a backtrace without the capture context. Can also be an integer that will be passed to `caller_env()`.

Examples

if (FALSE) {  # Not run

# Set the error handler in your RProfile like this:
if (requireNamespace("rlang", quietly = TRUE)) {
  options(error = rlang::entrace)
}

}

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