EVOLUTION-MANAGER
Edit File: as_data_mask.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: Create a data mask</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 as_data_mask {rlang}"><tr><td>as_data_mask {rlang}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Create a data mask</h2> <h3>Description</h3> <p>A <a href="topic-data-mask.html">data mask</a> is an environment (or possibly multiple environments forming an ancestry) containing user-supplied objects. Objects in the mask have precedence over objects in the environment (i.e. they mask those objects). Many R functions evaluate quoted expressions in a data mask so these expressions can refer to objects within the user data. </p> <p>These functions let you construct a tidy eval data mask manually. They are meant for developers of tidy eval interfaces rather than for end users. </p> <h3>Usage</h3> <pre> as_data_mask(data) as_data_pronoun(data) new_data_mask(bottom, top = bottom) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>data</code></td> <td> <p>A data frame or named vector of masking data.</p> </td></tr> <tr valign="top"><td><code>bottom</code></td> <td> <p>The environment containing masking objects if the data mask is one environment deep. The bottom environment if the data mask comprises multiple environment. </p> <p>If you haven't supplied <code>top</code>, this <strong>must</strong> be an environment that you own, i.e. that you have created yourself.</p> </td></tr> <tr valign="top"><td><code>top</code></td> <td> <p>The last environment of the data mask. If the data mask is only one environment deep, <code>top</code> should be the same as <code>bottom</code>. </p> <p>This <strong>must</strong> be an environment that you own, i.e. that you have created yourself. The parent of <code>top</code> will be changed by the tidy eval engine and should be considered undetermined. Never make assumption about the parent of <code>top</code>.</p> </td></tr> </table> <h3>Value</h3> <p>A data mask that you can supply to <code><a href="eval_tidy.html">eval_tidy()</a></code>. </p> <h3>Why build a data mask?</h3> <p>Most of the time you can just call <code><a href="eval_tidy.html">eval_tidy()</a></code> with a list or a data frame and the data mask will be constructed automatically. There are three main use cases for manual creation of data masks: </p> <ul> <li><p> When <code><a href="eval_tidy.html">eval_tidy()</a></code> is called with the same data in a tight loop. Because there is some overhead to creating tidy eval data masks, constructing the mask once and reusing it for subsequent evaluations may improve performance. </p> </li> <li><p> When several expressions should be evaluated in the exact same environment because a quoted expression might create new objects that can be referred in other quoted expressions evaluated at a later time. One example of this is <code>tibble::lst()</code> where new columns can refer to previous ones. </p> </li> <li><p> When your data mask requires special features. For instance the data frame columns in dplyr data masks are implemented with <a href="../../base/html/delayedAssign.html">active bindings</a>. </p> </li></ul> <h3>Building your own data mask</h3> <p>Unlike <code><a href="../../base/html/eval.html">base::eval()</a></code> which takes any kind of environments as data mask, <code><a href="eval_tidy.html">eval_tidy()</a></code> has specific requirements in order to support <a href="topic-defuse.html">quosures</a>. For this reason you can't supply bare environments. </p> <p>There are two ways of constructing an rlang data mask manually: </p> <ul> <li> <p><code>as_data_mask()</code> transforms a list or data frame to a data mask. It automatically installs the data pronoun <code><a href="dot-data.html">.data</a></code>. </p> </li> <li> <p><code>new_data_mask()</code> is a bare bones data mask constructor for environments. You can supply a bottom and a top environment in case your data mask comprises multiple environments (see section below). </p> <p>Unlike <code>as_data_mask()</code> it does not install the <code>.data</code> pronoun so you need to provide one yourself. You can provide a pronoun constructed with <code>as_data_pronoun()</code> or your own pronoun class. </p> <p><code>as_data_pronoun()</code> will create a pronoun from a list, an environment, or an rlang data mask. In the latter case, the whole ancestry is looked up from the bottom to the top of the mask. Functions stored in the mask are bypassed by the pronoun. </p> </li></ul> <p>Once you have built a data mask, simply pass it to <code><a href="eval_tidy.html">eval_tidy()</a></code> as the <code>data</code> argument. You can repeat this as many times as needed. Note that any objects created there (perhaps because of a call to <code style="white-space: pre;"><-</code>) will persist in subsequent evaluations. </p> <h3>Top and bottom of data mask</h3> <p>In some cases you'll need several levels in your data mask. One good reason is when you include functions in the mask. It's a good idea to keep data objects one level lower than function objects, so that the former cannot override the definitions of the latter (see examples). </p> <p>In that case, set up all your environments and keep track of the bottom child and the top parent. You'll need to pass both to <code>new_data_mask()</code>. </p> <p>Note that the parent of the top environment is completely undetermined, you shouldn't expect it to remain the same at all times. This parent is replaced during evaluation by <code><a href="eval_tidy.html">eval_tidy()</a></code> to one of the following environments: </p> <ul> <li><p> The default environment passed as the <code>env</code> argument of <code>eval_tidy()</code>. </p> </li> <li><p> The environment of the current quosure being evaluated, if applicable. </p> </li></ul> <p>Consequently, all masking data should be contained between the bottom and top environment of the data mask. </p> <h3>Examples</h3> <pre> # Evaluating in a tidy evaluation environment enables all tidy # features: mask <- as_data_mask(mtcars) eval_tidy(quo(letters), mask) # You can install new pronouns in the mask: mask$.pronoun <- as_data_pronoun(list(foo = "bar", baz = "bam")) eval_tidy(quo(.pronoun$foo), mask) # In some cases the data mask can leak to the user, for example if # a function or formula is created in the data mask environment: cyl <- "user variable from the context" fn <- eval_tidy(quote(function() cyl), mask) fn() # If new objects are created in the mask, they persist in the # subsequent calls: eval_tidy(quote(new <- cyl + am), mask) eval_tidy(quote(new * 2), mask) # In some cases your data mask is a whole chain of environments # rather than a single environment. You'll have to use # `new_data_mask()` and let it know about the bottom of the mask # (the last child of the environment chain) and the topmost parent. # A common situation where you'll want a multiple-environment mask # is when you include functions in your mask. In that case you'll # put functions in the top environment and data in the bottom. This # will prevent the data from overwriting the functions. top <- new_environment(list(`+` = base::paste, c = base::paste)) # Let's add a middle environment just for sport: middle <- env(top) # And finally the bottom environment containing data: bottom <- env(middle, a = "a", b = "b", c = "c") # We can now create a mask by supplying the top and bottom # environments: mask <- new_data_mask(bottom, top = top) # This data mask can be passed to eval_tidy() instead of a list or # data frame: eval_tidy(quote(a + b + c), data = mask) # Note how the function `c()` and the object `c` are looked up # properly because of the multi-level structure: eval_tidy(quote(c(a, b, c)), data = mask) # new_data_mask() does not create data pronouns, but # data pronouns can be added manually: mask$.fns <- as_data_pronoun(top) # The `.data` pronoun should generally be created from the # mask. This will ensure data is looked up throughout the whole # ancestry. Only non-function objects are looked up from this # pronoun: mask$.data <- as_data_pronoun(mask) mask$.data$c # Now we can reference values with the pronouns: eval_tidy(quote(c(.data$a, .data$b, .data$c)), data = mask) </pre> <hr /><div style="text-align: center;">[Package <em>rlang</em> version 1.0.6 <a href="00Index.html">Index</a>]</div> </body></html>