R: Quosure getters, setters and predicates

quosure-tools {rlang} | R Documentation

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

[Package rlang version 1.0.2 Index]