EVOLUTION-MANAGER

Edit File: eval_bare.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: Evaluate an expression in an 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 eval_bare {rlang}"><tr><td>eval_bare {rlang}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Evaluate an expression in an environment</h2>

<h3>Description</h3>

<p><code>eval_bare()</code> is a lower-level version of function <code><a href="../../base/html/eval.html">base::eval()</a></code>.
Technically, it is a simple wrapper around the C function
<code>Rf_eval()</code>. You generally don't need to use <code>eval_bare()</code> instead
of <code>eval()</code>. Its main advantage is that it handles stack-sensitive
calls (such as <code>return()</code>, <code>on.exit()</code> or <code>parent.frame()</code>) more
consistently when you pass an enviroment of a frame on the call
stack.
</p>

<h3>Usage</h3>

<pre>
eval_bare(expr, env = parent.frame())
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>expr</code></td>
<td>
<p>An expression to evaluate.</p>
</td></tr>
<tr valign="top"><td><code>env</code></td>
<td>
<p>The environment in which to evaluate the expression.</p>
</td></tr>
</table>

<h3>Details</h3>

<p>These semantics are possible because <code>eval_bare()</code> creates only one
frame on the call stack whereas <code>eval()</code> creates two frames, the
second of which has the user-supplied environment as frame
environment. When you supply an existing frame environment to
<code>base::eval()</code> there will be two frames on the stack with the same
frame environment. Stack-sensitive functions only detect the
topmost of these frames. We call these evaluation semantics
&quot;stack inconsistent&quot;.
</p>
<p>Evaluating expressions in the actual frame environment has useful
practical implications for <code>eval_bare()</code>:
</p>

<ul>
<li> <p><code>return()</code> calls are evaluated in frame environments that might
be burried deep in the call stack. This causes a long return that
unwinds multiple frames (triggering the <code>on.exit()</code> event for
each frame). By contrast <code>eval()</code> only returns from the <code>eval()</code>
call, one level up.
</p>
</li>
<li> <p><code>on.exit()</code>, <code>parent.frame()</code>, <code>sys.call()</code>, and generally all
the stack inspection functions <code>sys.xxx()</code> are evaluated in the
correct frame environment. This is similar to how this type of
calls can be evaluated deep in the call stack because of lazy
evaluation, when you force an argument that has been passed
around several times.
</p>
</li></ul>

<p>The flip side of the semantics of <code>eval_bare()</code> is that it can't
evaluate <code>break</code> or <code>next</code> expressions even if called within a
loop.
</p>

<p><code><a href="eval_tidy.html">eval_tidy()</a></code> for evaluation with data mask and quosure
support.
</p>

<h3>Examples</h3>

<pre>
# eval_bare() works just like base::eval() but you have to create
# the evaluation environment yourself:
eval_bare(quote(foo), env(foo = "bar"))

# eval() has different evaluation semantics than eval_bare(). It
# can return from the supplied environment even if its an
# environment that is not on the call stack (i.e. because you've
# created it yourself). The following would trigger an error with
# eval_bare():
ret &lt;- quote(return("foo"))
eval(ret, env())
# eval_bare(ret, env())  # "no function to return from" error

# Another feature of eval() is that you can control surround loops:
bail &lt;- quote(break)
while (TRUE) {
  eval(bail)
  # eval_bare(bail)  # "no loop for break/next" error
}

# To explore the consequences of stack inconsistent semantics, let's
# create a function that evaluates `parent.frame()` deep in the call
# stack, in an environment corresponding to a frame in the middle of
# the stack. For consistency with R's lazy evaluation semantics, we'd
# expect to get the caller of that frame as result:
fn &lt;- function(eval_fn) {
  list(
    returned_env = middle(eval_fn),
    actual_env = current_env()
  )
}
middle &lt;- function(eval_fn) {
  deep(eval_fn, current_env())
}
deep &lt;- function(eval_fn, eval_env) {
  expr &lt;- quote(parent.frame())
  eval_fn(expr, eval_env)
}

# With eval_bare(), we do get the expected environment:
fn(rlang::eval_bare)

# But that's not the case with base::eval():
fn(base::eval)
</pre>

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