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.

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)