R: Create a dynamic scope for tidy evaluation

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.

- `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_()`.

### 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]