EVOLUTION-MANAGER

Edit File: local_error_call.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: Set local error call in an execution environment</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 local_error_call {rlang}"><tr><td>local_error_call {rlang}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Set local error call in an execution environment</h2>

<h3>Description</h3>

<p><code>local_error_call()</code> is an alternative to explicitly passing a
<code>call</code> argument to <code><a href="abort.html">abort()</a></code>. It sets the call (or a value that
indicates where to find the call, see below) in a local binding
that is automatically picked up by <code><a href="abort.html">abort()</a></code>.
</p>

<h3>Usage</h3>

<pre>
local_error_call(call, frame = caller_env())
</pre>

<h3>Arguments</h3>

<ul>
<li><p> A call to be used as context for an error thrown in that
execution environment.
</p>
</li>
<li><p> The <code>NULL</code> value to show no context.
</p>
</li>
<li><p> An execution environment, e.g. as returned by <code><a href="stack.html">caller_env()</a></code>.
The <code><a href="../../base/html/sys.parent.html">sys.call()</a></code> for that environment is taken as context.
</p>
</li></ul>
</td></tr>
<tr valign="top"><td><code>frame</code></td>
<td>
<p>The execution environment in which to set the local
error call.</p>
</td></tr>
</table>

<h3>Motivation for setting local error calls</h3>

<p>By default <code><a href="abort.html">abort()</a></code> uses the function call of its caller as
context in error messages:
</p>
<div class="sourceCode"><pre>foo &lt;- function() abort("Uh oh.")
foo()
#&gt; Error in `foo()`: Uh oh.
</pre></div>
<p>This is not always appropriate. For example a function that checks
an input on the behalf of another function should reference the
latter, not the former:
</p>
<div class="sourceCode"><pre>arg_check &lt;- function(arg,
                      error_arg = as_string(substitute(arg))) {
  abort(cli::format_error("{.arg {error_arg}} is failing."))
}

foo &lt;- function(x) arg_check(x)
foo()
#&gt; Error in `arg_check()`: `x` is failing.
</pre></div>
<p>The mismatch is clear in the example above. <code>arg_check()</code> does not
have any <code>x</code> argument and so it is confusing to present
<code>arg_check()</code> as being the relevant context for the failure of the
<code>x</code> argument.
</p>
<p>One way around this is to take a <code>call</code> or <code>error_call</code> argument
and pass it to <code>abort()</code>. Here we name this argument <code>error_call</code>
for consistency with <code>error_arg</code> which is prefixed because there is
an existing <code>arg</code> argument. In other situations, taking <code>arg</code> and
<code>call</code> arguments might be appropriate.
</p>
<div class="sourceCode"><pre>arg_check &lt;- function(arg,
                      error_arg = as_string(substitute(arg)),
                      error_call = caller_env()) {
  abort(
    cli::format_error("{.arg {error_arg}} is failing."),
    call = error_call
  )
}

foo &lt;- function(x) arg_check(x)
foo()
#&gt; Error in `foo()`: `x` is failing.
</pre></div>
<p>This is the generally recommended pattern for argument checking
functions. If you mention an argument in an error message, provide
your callers a way to supply a different argument name and a
different error call. <code>abort()</code> stores the error call in the <code>call</code>
condition field which is then used to generate the &quot;in&quot; part of
error messages.
</p>
<p>In more complex cases it's often burdensome to pass the relevant
call around, for instance if your checking and throwing code is
structured into many different functions. In this case, use
<code>local_error_call()</code> to set the call locally or instruct <code>abort()</code>
to climb the call stack one level to find the relevant call. In the
following example, the complexity is not so important that sparing
the argument passing makes a big difference. However this
illustrates the pattern:
</p>
<div class="sourceCode"><pre>arg_check &lt;- function(arg,
                      error_arg = caller_arg(arg),
                      error_call = caller_env()) {
  # Set the local error call
  local_error_call(error_call)

my_classed_stop(
    cli::format_error("{.arg {error_arg}} is failing.")
  )
}

my_classed_stop &lt;- function(message) {
  # Forward the local error call to the caller's
  local_error_call(caller_env())

abort(message, class = "my_class")
}

foo &lt;- function(x) arg_check(x)
foo()
#&gt; Error in `foo()`: `x` is failing.
</pre></div>

<h3>Error call flags in performance-critical functions</h3>

<p>The <code>call</code> argument can also be the string <code>"caller"</code>. This is
equivalent to <code>caller_env()</code> or <code>parent.frame()</code> but has a lower
overhead because call stack introspection is only performed when an
error is triggered. Note that eagerly calling <code>caller_env()</code> is
fast enough in almost all cases.
</p>
<p>If your function needs to be really fast, assign the error call
flag directly instead of calling <code>local_error_call()</code>:
</p>
<div class="sourceCode"><pre>.__error_call__. &lt;- "caller"
</pre></div>

<h3>Examples</h3>

<pre>
# Set a context for error messages
function() {
  local_error_call(quote(foo()))
  local_error_call(sys.call())
}

# Disable the context
function() {
  local_error_call(NULL)
}

# Use the caller's context
function() {
  local_error_call(caller_env())
}
</pre>

<hr /><div style="text-align: center;">[Package <em>rlang</em> version 1.0.6 <a href="00Index.html">Index</a>]</div>
</body></html>