Learn R Programming

rlang (version 1.1.4)

englue: Defuse function arguments with glue

Description

englue() creates a string with the glue operators { and {{. These operators are normally used to inject names within dynamic dots. englue() makes them available anywhere within a function.

englue() must be used inside a function. englue("{{ var }}") defuses the argument var and transforms it to a string using the default name operation.

Usage

englue(x, env = caller_env(), error_call = current_env(), error_arg = "x")

Arguments

x

A string to interpolate with glue operators.

env

User environment where the interpolation data lives in case you're wrapping englue() in another function.

error_call

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

error_arg

An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.

Wrapping <code>englue()</code>

You can provide englue semantics to a user provided string by supplying env. In this example we create a variant of englue() that supports a special .qux pronoun by:

  • Creating an environment masked_env that inherits from the user env, the one where their data lives.

  • Overriding the error_arg and error_call arguments to point to our own argument name and call environment. This pattern is slightly different from usual error context passing because englue() is a backend function that uses its own error context by default (and not a checking function that uses your error context by default).

my_englue <- function(text) {
  masked_env <- env(caller_env(), .qux = "QUX")

englue( text, env = masked_env, error_arg = "text", error_call = current_env() ) }

# Users can then use your wrapper as they would use `englue()`: fn <- function(x) { foo <- "FOO" my_englue("{{ x }}_{.qux}_{foo}") }

fn(bar) #> [1] "bar_QUX_FOO"

If you are creating a low level package on top of englue(), you should also consider exposing env, error_arg and error_call in your englue() wrapper so users can wrap your wrapper.

Details

englue("{{ var }}") is equivalent to as_label(enquo(var)). It defuses arg and transforms the expression to a string with as_label().

In dynamic dots, using only { is allowed. In englue() you must use {{ at least once. Use glue::glue() for simple interpolation.

Before using englue() in a package, first ensure that glue is installed by adding it to your Imports: section.

usethis::use_package("glue", "Imports")

See Also

  • Injecting with !!, !!!, and glue syntax

Examples

Run this code
g <- function(var) englue("{{ var }}")
g(cyl)
g(1 + 1)
g(!!letters)

# These are equivalent to
as_label(quote(cyl))
as_label(quote(1 + 1))
as_label(letters)

Run the code above in your browser using DataLab