Create a dynamic scope for tidy evaluation

Tidy evaluation works by rescoping a set of symbols (column names of a data frame for example) to custom bindings. While doing this, it is important to keep the original environment of captured expressions in scope. The gist of tidy evaluation is to create a dynamic scope containing custom bindings that should have precedence when expressions are evaluated, and chain this scope (set of linked environments) to the lexical enclosure of formulas under evaluation. During tidy evaluation, formulas are transformed into formula-promises and will self-evaluate their RHS as soon as they are called. The main trick of tidyeval is to consistently rechain the dynamic scope to the lexical enclosure of each tidy quote under evaluation.

as_overscope(quo, data = NULL)

new_overscope(bottom, top = NULL, enclosure = base_env())

overscope_eval_next(overscope, quo, env = base_env())



A quosure.


Additional data to put in scope.


This is the environment (or the bottom of a set of environments) containing definitions for overscoped symbols. The bottom environment typically contains pronouns (like .data) while its direct parents contain the overscoping bindings. The last one of these parents is the top.


The top environment of the overscope. During tidy evaluation, this environment is chained and rechained to lexical enclosures of self-evaluating formulas (or quosures). This is the mechanism that ensures hygienic scoping: the bindings in the overscope have precedence, but the bindings in the dynamic environment where the tidy quotes were created in the first place are in scope as well.


The default enclosure. After a quosure is done self-evaluating, the overscope is rechained to the default enclosure.


A valid overscope containing bindings for ~, .top_env and _F and whose parents contain overscoped bindings for tidy evaluation.


The lexical enclosure in case quo is not a validly scoped quosure. This is the base environment by default.


These functions are useful for embedding the tidy evaluation framework in your own DSLs with your own evaluating function. They let you create a custom dynamic scope. That is, a set of chained environments whose bottom serves as evaluation environment and whose top is rechained to the current lexical enclosure. But most of the time, you can just use eval_tidy_() as it will take care of installing the tidyeval components in your custom dynamic scope.

  • as_overscope() is the function that powers eval_tidy(). It could be useful if you cannot use eval_tidy() for some reason, but serves mostly as an example of how to build a dynamic scope for tidy evaluation. In this case, it creates pronouns .data and .env and buries all dynamic bindings from the supplied data in new environments.

  • new_overscope() is called by as_overscope() and eval_tidy_(). It installs the definitions for making formulas self-evaluate and for formula-guards. It also installs the pronoun .top_env that helps keeping track of the boundary of the dynamic scope. If you evaluate a tidy quote with eval_tidy_(), you don't need to use this.

  • eval_tidy_() is useful when you have several quosures to evaluate in a same dynamic scope. That's a simple wrapper around eval_bare() that updates the .env pronoun and rechains the dynamic scope to the new formula enclosure to evaluate.

  • Once an expression has been evaluated in the tidy environment, it's a good idea to clean up the definitions that make self-evaluation of formulas possible overscope_clean(). Otherwise your users may face unexpected results in specific corner cases (e.g. when the evaluation environment is leaked, see examples). Note that this function is automatically called by eval_tidy_().


An overscope environment.

A valid overscope: a child environment of bottom containing the definitions enabling tidy evaluation (self-evaluating quosures, formula-unguarding, ...).

  • as_overscope
  • new_overscope
  • overscope_eval_next
  • overscope_clean
# Evaluating in a tidy evaluation environment enables all tidy
# features:
expr <- quote(list(.data$cyl, ~letters))
f <- as_quosure(expr)
overscope <- as_overscope(f, data = mtcars)
overscope_eval_next(overscope, f)

# However you need to cleanup the environment after evaluation.
# Otherwise the leftover definitions for self-evaluation of
# formulas might cause unexpected results:
fn <- overscope_eval_next(overscope, ~function() ~letters)

# }
Documentation reproduced from package rlang, version 0.1.1, License: GPL-3

Community examples

Looks like there are no examples yet.