EVOLUTION-MANAGER
Edit File: rlang_backtrace_on_error.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Display backtrace on error</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for rlang_backtrace_on_error {rlang}"><tr><td>rlang_backtrace_on_error {rlang}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Display backtrace on error</h2> <h3>Description</h3> <p>rlang errors carry a backtrace that can be inspected by calling <code><a href="last_error.html">last_error()</a></code>. You can also control the default display of the backtrace by setting the option <code>rlang_backtrace_on_error</code> to one of the following values: </p> <ul> <li> <p><code>"none"</code> show nothing. </p> </li> <li> <p><code>"reminder"</code>, the default in interactive sessions, displays a reminder that you can see the backtrace with <code><a href="last_error.html">last_error()</a></code>. </p> </li> <li> <p><code>"branch"</code> displays a simplified backtrace. </p> </li> <li> <p><code>"full"</code>, the default in non-interactive sessions, displays the full tree. </p> </li></ul> <p>rlang errors are normally thrown with <code><a href="abort.html">abort()</a></code>. If you promote base errors to rlang errors with <code><a href="global_entrace.html">global_entrace()</a></code>, <code>rlang_backtrace_on_error</code> applies to all errors. </p> <h3>Promote base errors to rlang errors</h3> <p>You can use <code>options(error = rlang::entrace)</code> to promote base errors to rlang errors. This does two things: </p> <ul> <li><p> It saves the base error as an rlang object so you can call <code><a href="last_error.html">last_error()</a></code> to print the backtrace or inspect its data. </p> </li> <li><p> It prints the backtrace for the current error according to the <code>rlang_backtrace_on_error</code> option. </p> </li></ul> <h3>Errors in RMarkdown</h3> <p>The display of errors depends on whether they're expected (i.e. chunk option <code>error = TRUE</code>) or unexpected: </p> <ul> <li><p> Expected errors are controlled by the global option <code>"rlang_backtrace_on_error_report"</code> (note the <code style="white-space: pre;">_report</code> suffix). The default is <code>"none"</code> so that your expected errors don't include a reminder to run <code>rlang::last_error()</code>. Customise this option if you want to demonstrate what the error backtrace will look like. </p> <p>You can also use <code><a href="last_error.html">last_error()</a></code> to display the trace like you would in your session, but it currently only works in the next chunk. </p> </li> <li><p> Unexpected errors are controlled by the global option <code>"rlang_backtrace_on_error"</code>. The default is <code>"branch"</code> so you'll see a simplified backtrace in the knitr output to help you figure out what went wrong. </p> </li></ul> <p>When knitr is running (as determined by the <code>knitr.in.progress</code> global option), the default top environment for backtraces is set to the chunk environment <code>knitr::knit_global()</code>. This ensures that the part of the call stack belonging to knitr does not end up in backtraces. If needed, you can override this by setting the <code>rlang_trace_top_env</code> global option. </p> <h3>Examples</h3> <pre> # Display a simplified backtrace on error for both base and rlang # errors: # options( # rlang_backtrace_on_error = "branch", # error = rlang::entrace # ) # stop("foo") </pre> <hr /><div style="text-align: center;">[Package <em>rlang</em> version 1.0.6 <a href="00Index.html">Index</a>]</div> </body></html>