Defuse R expressions

Defusing a function argument prevents its evaluation. When a function argument is defused, R doesn't return its value like it normally would but it returns the R expression describing how to make the value. These defused expressions are like blueprints for computing values. (Defusing is also known as quoting, and is done in base R by quote() and substitute().)

There are two main ways to defuse expressions, to which correspond the two functions expr() and enquo(). Whereas expr() defuses your own expression, enquo() defuses expressions supplied as argument by the user of a function. See section on function arguments for more on this distinction.

The main purpose of preventing evaluation of an expression is to avoid "object not found" errors when the expression involves data-variables that only exist in a data frame. The expression is defused so it can be resumed later on, in a context where the data-variables have been defined.

Defusing prevents the evaluation of R code, but you can still force evaluation inside a defused expression with the forcing operators !! and !!!.

expr(expr)

enexpr(arg)

exprs(..., .named = FALSE, .ignore_empty = c("trailing", "none",
  "all"), .unquote_names = TRUE)

enexprs(..., .named = FALSE, .ignore_empty = c("trailing", "none",
  "all"), .unquote_names = TRUE, .homonyms = c("keep", "first", "last",
  "error"), .check_assign = FALSE)

ensym(arg)

ensyms(..., .named = FALSE, .ignore_empty = c("trailing", "none",
  "all"), .unquote_names = TRUE, .homonyms = c("keep", "first", "last",
  "error"), .check_assign = FALSE)

quo(expr)

enquo(arg)

quos(..., .named = FALSE, .ignore_empty = c("trailing", "none", "all"),
  .unquote_names = TRUE)

enquos(..., .named = FALSE, .ignore_empty = c("trailing", "none",
  "all"), .unquote_names = TRUE, .homonyms = c("keep", "first", "last",
  "error"), .check_assign = FALSE)

Arguments

expr	An expression.
arg	A symbol representing an argument. The expression supplied to that argument will be captured instead of being evaluated.
...	For `enexprs()`, `ensyms()` and `enquos()`, names of arguments to capture without evaluation (including `...`). For `exprs()` and `quos()`, the expressions to capture unevaluated (including expressions contained in `...`).
.named	Whether to ensure all dots are named. Unnamed elements are processed with `quo_name()` to build a default name. See also `quos_auto_name()`.
.ignore_empty	Whether to ignore empty arguments. Can be one of `"trailing"`, `"none"`, `"all"`. If `"trailing"`, only the last argument is ignored if it is empty. Note that `"trailing"` applies only to arguments passed in `...`, not to named arguments. On the other hand, `"all"` also applies to named arguments.
.unquote_names	Whether to treat `:=` as `=`. Unlike `=`, the `:=` syntax supports `!!` unquoting on the LHS.
.homonyms	How to treat arguments with the same name. The default, `"keep"`, preserves these arguments. Set `.homonyms` to `"first"` to only keep the first occurrences, to `"last"` to keep the last occurrences, and to `"error"` to raise an informative error and indicate what arguments have duplicated names.
.check_assign	Whether to check for `<-` calls passed in dots. When `TRUE` and a `<-` call is detected, a warning is issued to advise users to use `=` if they meant to match a function parameter, or wrap the `<-` call in braces otherwise. This ensures assignments are explicit.

Types of defused expressions

Calls, like f(1, 2, 3), 1 + 1, or ..., represent the action of calling a function to compute a new value, such as a vector.
Symbols, like x or df, represent named objects. When the object pointed to by the symbol was defined in a function or in the global environment, we call it an environment-variable. When the object is a column in a data frame, we call it a data-variable.

You can create new call or symbol objects by using the defusing function expr():

# Create a symbol representing objects called `foo`
expr(foo)

# Create a call representing the computation of the mean of `foo`
expr(mean(foo, na.rm = TRUE))

Defusing is not the only way to create defused expressions. You can also assemble them from data:

# Assemble a symbol from a string
var <- "foo"
sym(var)

# Assemble a call from strings, symbols, and other objects
call("mean", sym(var), na.rm = TRUE)

Defusing function arguments

There are two points of view when it comes to defusing an expression:

You can defuse expressions that you supply with expr(). This is one way of creating symbols and calls (see previous section).
You can defuse the expressions supplied by the user of your function with the operators starting with en like ensym(), enquo() and their plural variants. They defuse function arguments .

Defused arguments and quosures

If you inspect the return values of expr() and enquo(), you'll notice that the latter doesn't return a raw expression like the former. Instead it returns a quosure, a wrapper containing an expression and an environment. R needs information about the environment to properly evaluate the argument expression because it comes from a different context than the current function.

See the quosure help topic about tools to work with quosures.

Comparison to base R

The defusing operator expr() is similar to quote(). Like bquote(), it allows forcing evaluation of parts of an expression.
The plural variant exprs() is similar to alist().
The argument-defusing operator enquo() is similar to substitute().

Examples