R: Evaluate an expression with quosures and pronoun support

eval_tidy {rlang} | R Documentation

## Evaluate an expression with quosures and pronoun support

### Description

`eval_tidy()` is a variant of `base::eval()` that powers the tidy evaluation framework. Like `eval()` it accepts user data as argument. If supplied, it evaluates its input `expr` in a data mask. In additon `eval_tidy()` supports:

- Quosures. The expression wrapped in the quosure evaluates in its original context (masked by `data` if supplied).

- Pronouns. If `data` is supplied, the `.env` and `.data` pronouns are installed in the data mask. `.env` is a reference to the calling environment and `.data` refers to the `data` argument. These pronouns lets you be explicit about where to find values and throw errors if you try to access non-existent values.

### Usage

    eval_tidy(expr, data = NULL, env = caller_env())

### Arguments

`expr` | An expression to evaluate.
`data` | A data frame, or named list or vector. Alternatively, a data mask created with `as_data_mask()` or `new_data_mask()`.
`env` | The environment in which to evaluate `expr`. This environment is always ignored when evaluating quosures. Quosures are evaluated in their own environment.

### Life cycle

`eval_tidy()` is stable.

### See Also

quasiquotation for the second leg of the tidy evaluation framework.

### Examples

    # With simple quoted expressions eval_tidy() works the same way as
    # eval():
    apple <- "apple"
    kiwi <- "kiwi"
    expr <- quote(paste(apple, kiwi))
    expr

    eval(expr)
    eval_tidy(expr)

    # Both accept a data mask as argument:
    data <- list(apple = "CARROT", kiwi = "TOMATO")
    eval(expr, data)
    eval_tidy(expr, data)

    # In addition eval_tidy() has support for quosures:
    with_data <- function(data, expr) {
      quo <- enquo(expr)
      eval_tidy(quo, data)
    }
    with_data(NULL, apple)
    with_data(data, apple)
    with_data(data, list(apple, kiwi))

    # Secondly eval_tidy() installs handy pronouns that allows users to
    # be explicit about where to find symbols:
    with_data(data, .data$apple)
    with_data(data, .env$apple)

    # Note that instead of using `.env` it is often equivalent and may
    # be preferred to unquote a value. There are two differences. First
    # unquoting happens earlier, when the quosure is created. Secondly,
    # subsetting `.env` with the `$` operator may be brittle because
    # `$` does not look through the parents of the environment.
    #
    # For instance using `.env$name` in a magrittr pipeline is an
    # instance where this poses problem, because the magrittr pipe
    # currently (as of v1.5.0) evaluates its operands in a *child* of
    # the current environment (this child environment is where it
    # defines the pronoun `.`).
    ## Not run:
      data %>% with_data(!!kiwi)     # "kiwi"
      data %>% with_data(.env$kiwi)  # NULL

    ## End(Not run)

[Package rlang version 0.2.2 Index]