rlang: quosure – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

quosure

Quosure getters, setters and testers

Description

A quosure is a type of quoted expression that includes a reference to the context where it was created. A quosure is thus guaranteed to evaluate in its original environment and can refer to local objects.

You can access the quosure components (its expression and its environment) with:

get_expr() and get_env(). These getters also support other kinds of objects such as formulas.
quo_get_expr() and quo_get_env(). These getters only work with quosures and throw an error with other types of input.

Test if an object is a quosure with is_quosure(). If you know an object is a quosure, use the quo_ prefixed predicates to check its contents, quo_is_missing(), quo_is_symbol(), etc.

Usage

is_quosure(x)

quo_is_missing(quo)

quo_is_symbol(quo, name = NULL)

quo_is_call(quo, name = NULL, n = NULL, ns = NULL)

quo_is_symbolic(quo)

quo_is_null(quo)

quo_get_expr(quo)

quo_get_env(quo)

quo_set_expr(quo, expr)

quo_set_env(quo, env)

Arguments

`x`	An object to test.
`quo`	A quosure to test.
`name`	The name of the symbol or function call. If `NULL` the name is not tested.
`n`	An optional number of arguments that the call should match.
`ns`	The namespace of the call. If `NULL`, the namespace doesn't participate in the pattern-matching. If an empty string `""` and `x` is a namespaced call, `is_call()` returns `FALSE`. If any other string, `is_call()` checks that `x` is namespaced within `ns`. Can be a character vector of namespaces, in which case the call has to match at least one of them, otherwise `is_call()` returns `FALSE`.
`expr`	A new expression for the quosure.
`env`	A new environment for the quosure.

Quosured constants

A quosure usually does not carry environments for constant objects like strings or numbers. quo() and enquo() only capture an environment for symbolic expressions. For instance, all of these return the empty environment:

quo_get_env(quo("constant"))
quo_get_env(quo(100))
quo_get_env(quo(NA))

On the other hand, quosures capture the environment of symbolic expressions, i.e. expressions whose meaning depends on the environment in which they are evaluated and what objects are defined there:

quo_get_env(quo(some_object))
quo_get_env(quo(some_function()))

Empty quosures

When missing arguments are captured as quosures, either through enquo() or quos(), they are returned as an empty quosure. These quosures contain the missing argument and typically have the empty environment as enclosure.

Life cycle

is_quosure() is stable.
quo_get_expr() and quo_get_env() are stable.

Examples

quo <- quo(my_quosure)
quo


# Access and set the components of a quosure:
quo_get_expr(quo)
quo_get_env(quo)

quo <- quo_set_expr(quo, quote(baz))
quo <- quo_set_env(quo, empty_env())
quo

# Test wether an object is a quosure:
is_quosure(quo)

# If it is a quosure, you can use the specialised type predicates
# to check what is inside it:
quo_is_symbol(quo)
quo_is_call(quo)
quo_is_null(quo)

# quo_is_missing() checks for a special kind of quosure, the one
# that contains the missing argument:
quo()
quo_is_missing(quo())

fn <- function(arg) enquo(arg)
fn()
quo_is_missing(fn())

rlang

Functions for Base Types and Core R and 'Tidyverse' Features

v0.4.11

MIT + file LICENSE

Authors

Lionel Henry [aut, cre], Hadley Wickham [aut], mikefc [cph] (Hash implementation based on Mike's xxhashlite), Yann Collet [cph] (Author of the embedded xxHash library), RStudio [cph]

Initial release