R: Quosure getters, setters and testers

quosure {rlang} | R Documentation

## 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.

### See Also

`quo()` for creating quosures by quotation; `as_quosure()` and `new_quosure()` for constructing quosures manually.

### 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 0.4.5 Index]