as_overscope {rlang}R Documentation

Create a dynamic scope for tidy evaluation

Description

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.

Usage

as_overscope(quo, data = NULL)

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

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

overscope_clean(overscope)

Arguments

quo

A quosure.

data

Additional data to put in scope.

bottom

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.

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.

enclosure

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

overscope

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

env

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

Details

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.

Value

An overscope environment.

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

Examples

# 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)
fn()

overscope_clean(overscope)
fn()

[Package rlang version 0.1.6 Index]