defusing-advanced {rlang} | R Documentation |
Advanced defusal operators
Description
These advanced operators defuse R expressions.
expr()
, enquo()
, and enquos()
are sufficient for most
purposes but rlang provides these other operations, either for
completeness or because they are useful to experts.
-
exprs()
is the plural variant ofexpr()
. It returns a list of expressions. It is likebase::alist()
but with injection support. -
quo()
andquos()
are likeexpr()
andexprs()
but return quosures instead of naked expressions. When you are defusing your own local expressions (by opposition to function arguments where non-local expressions are supplied by your users), there is generally no need to attach the current environment in a quosure. See What are quosures and when are they needed?. -
enexpr()
andenexprs()
are likeenquo()
andenquos()
but return naked expressions instead of quosures. These operators should very rarely be used because they lose track of the environment of defused arguments. -
ensym()
andensyms()
are likeenexpr()
andenexprs()
but they throw an error when the defused expressions are not simple symbols. They also support strings which are interpreted as symbols. These functions are modelled on the behaviour of the left-hand side of=
and<-
where you can supply symbols and strings interchangeably."foo" <- NULL list("foo" = NULL)
-
enquo0
andenquos0()
are likeenquo()
andenquos()
but without injection support. The injection operators!!
,!!!
, and{{
are not processed, instead they are preserved in the defused expression. This makes it possible to defuse expressions that potentially contain injection operators meant for later use. The trade off is that it makes it harder for users to inject expressions in your function. They have to enable injection explicitly withinject()
.None of the features of dynamic dots are available when defusing with
enquos0()
. For instance, trailing empty arguments are not automatically trimmed.
Usage
enexpr(arg)
exprs(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE
)
enexprs(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.ignore_null = c("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"),
.ignore_null = c("none", "all"),
.unquote_names = TRUE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
quo(expr)
quos(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE
)
enquo0(arg)
enquos0(...)
Arguments
arg |
An unquoted argument name. The expression supplied to that argument is defused and returned. |
... |
For |
.named |
If |
.ignore_empty |
Whether to ignore empty arguments. Can be one
of |
.unquote_names |
Whether to treat |
.ignore_null |
Whether to ignore unnamed null arguments. Can be
|
.homonyms |
How to treat arguments with the same name. The
default, |
.check_assign |
Whether to check for |
expr |
An expression to defuse. |
Examples
# `exprs()` is the plural variant of `expr()`
exprs(foo, bar, bar)
# `quo()` and `quos()` are the quosure variants of `expr()` and `exprs()`
quo(foo)
quos(foo, bar)
# `enexpr()` and `enexprs()` are the naked variants of `enquo()` and `enquos()`
my_function1 <- function(arg) enexpr(arg)
my_function2 <- function(arg, ...) enexprs(arg, ...)
my_function1(1 + 1)
my_function2(1 + 1, 10 * 2)
# `ensym()` and `ensyms()` are symbol variants of `enexpr()` and `enexprs()`
my_function3 <- function(arg) ensym(arg)
my_function4 <- function(arg, ...) ensyms(arg, ...)
# The user must supply symbols
my_function3(foo)
my_function4(foo, bar)
# Complex expressions are an error
try(my_function3(1 + 1))
try(my_function4(1 + 1, 10 * 2))
# `enquo0()` and `enquos0()` disable injection operators
automatic_injection <- function(x) enquo(x)
no_injection <- function(x) enquo0(x)
automatic_injection(foo(!!!1:3))
no_injection(foo(!!!1:3))
# Injection can still be done explicitly
inject(no_injection(foo(!!!1:3)))