rlang (version 1.1.0)

quosure-tools: Quosure getters, setters and predicates

Description

These tools inspect and modify quosures, a type of defused expression that includes a reference to the context where it was created. A quosure is guaranteed to evaluate in its original environment and can refer to local objects safely.

• You can access the quosure components with quo_get_expr() and quo_get_env().

• The quo_ prefixed predicates test the expression of a quosure, quo_is_missing(), quo_is_symbol(), etc.

All quo_ prefixed functions expect a quosure and will fail if supplied another type of object. Make sure the input is a quosure with is_quosure().

Usage

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

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.

Empty quosures and missing arguments

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.

Use quo_is_missing() to test for a missing argument defused with enquo().

See Also

• quo() for creating quosures by argument defusal.

• new_quosure() and as_quosure() for assembling quosures from components.

• What are quosures and when are they needed? for an overview.

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())