quosure: Create and manipulate quosures easily

quosureR Documentation

Create and manipulate quosures easily

Description

Quosures are defined in rlang package as part of the tidy evaluation of non-standard expressions (see quo()). Here, we provide an alternate mechanism using -~expr as a synonym of quo(expr). Also, +quo_obj is equivalent to !!quo_obj in rlang, and ++quo_obj both unquotes and evaluates it in the right environment. Quosures are keystone objects in the tidy evaluation mechanism. So, they deserve a special, clean and concise syntax to create and manipulate them.

The as_xxx() and is_xxx() further ease the manipulation of quosures or related objects.

Usage

## S3 method for class 'formula'
e1 - e2

## S3 method for class 'formula'
e1 + e2

## S3 method for class 'quosure'
e1 ^ e2

## S3 method for class 'quosure'
e1 + e2

## S3 method for class 'unquoted'
e1 + e2

## S3 method for class 'unquoted'
print(x, ...)

as.quosure(x, env = caller_env())

is.quosure(x)

is.formula(x)

is.bare_formula(x)

`!!`(x)

Arguments

e1

Unary operator member, or first member of a binary operator.

e2

Second member of a binary operator (not used here, except for ^).

x

An expression

...

Further arguments passed to the print() method (not used yet).

env

An environment specified for scoping of the quosure.

Details

- is defined as an unary minus operator for formula objects (which is not defined in base R, hence, not supposed to be used otherwise). Thus, -~expr just converts a formula build using the base ~expr instruction into a quosure. as.quosure() does the same, when the expression is provided directly, and allows also to define the enclosing environment (by default, it is the environment where the code is evaluated, and it is also the case when using -~expr).

Similarly, the unary + operator is defined for quosure in order to easily "reverse" the mechanism of quoting an expression with a logical complementary operator. It does something similar to ⁠!!⁠ in rlang, but it can be used outside of tidy eval expressions. Since unary + has higher syntax precedence than ! in R, it is less susceptible to require parentheses (only ^ for exponentiation, indexing/subsetting operators like $ or [, and namespace operators :: and ::: have higher precedence). A specific ^ operator for quosures solves the precedence issue. :: or ::: are very unlikely used in the context.

++quosure is indeed a two-steps operation (+(+quosure)). It first unquotes the quosure, returning an unquoted object. Then, the second + evaluates the unquoted object. This allows for fine-graded manipulation of quosures: you can unquote at one place, and evaluate the unquoted object elsewhere (and, of course, the contained expression is always evaluated in the right environment, despite all these manipulations).

⁠!!⁠ and just evaluates its argument and passes the result. It is only useful inside a quasi-quoted argument, see quasiquotation.

Value

These functions build or manipulated quosures and return such objects. +quosure creates an unquoted object. The + unary operator applied to unquoted objects evaluate the expression contained in the quosure in the right environment.

See Also

quos_underscore, %>_%

Examples

x <- 1:10
# Create a quosure (same as quo(x))
x_quo <- -~x
x_quo
# Unquote it (same as !!x, but usable everywhere)
+x_quo
# Unquote and evaluate the quosure
++x_quo
# Syntax precedence issues (^ has higher precedence than unary +)
# is solved by redefining ^ for unquoted objects:
++x_quo^2
# acts like if ++ had higher precedence than ^, thus like if it was
(++x_quo)^2

# Assign the unquoted expression
x_unquo <- +x_quo
# ... and use x_unquo in a different context
foo <- function(x) +x
foo(x_unquo)

SciViews/flow documentation built on Sept. 9, 2023, 10:22 a.m.