Imagine that you want to call glue()
repeatedly inside
your own code (e.g. in your own package) with a non-default value for
one or more arguments. For example, maybe you anticipate producing R
code where {
and }
have specific syntactic
meaning. Therefore, you’d prefer to use <<
and
>>
as the opening and closing delimiters for
expressions in glue()
.
Spoiler alert: here’s the correct way to write such a wrapper:
my_glue <- function(..., .envir = parent.frame()) {
glue(..., .open = "<<", .close = ">>", .envir = .envir)
}
This is the key move:
Include
.envir = parent.frame()
as an argument of the wrapper function and pass this.envir
to the.envir
argument ofglue()
.
If you’d like to know why this is the way, keep reading. It pays off
to understand this, because the technique applies more broadly than
glue. Once you recognize this setup, you’ll see it in many functions in
the withr, cli, and rlang packages (e.g. withr::defer()
,
cli::cli_abort()
, rlang::abort()
).
Here’s an abbreviated excerpt of the roxygen comment that generates
the documentation for the starwars dataset in dplyr
(?dplyr::starwars
):
#' \describe{
#' \item{name}{Name of the character}
#' \item{height}{Height (cm)}
#' \item{mass}{Weight (kg)}
#' \item{species}{Name of species}
#' \item{films}{List of films the character appeared in}
#' }
To produce such text programmatically, the first step might be to
generate the \item{}{}
lines from a named list of column
names and descriptions. Notice that {
and }
are important to the \describe{...}
and
\item{}{}
syntax, so this is an example where it is nice
for glue to use different delimiters for expressions.
Put the metadata in a suitable list:
sw_meta <- list(
name = "Name of the character",
height = "Height (cm)",
mass = "Weight (kg)",
species = "Name of species",
films = "List of films the character appeared in"
)
Define a custom glue wrapper and use it inside another helper that
generates \item
entries1:
my_glue = function(...) {
glue(..., .open = "<<", .close = ">>", .envir = parent.frame())
}
named_list_to_items <- function(x) {
my_glue("\\item{<<names(x)>>}{<<x>>}")
}
Apply named_list_to_items()
to starwars metadata:
named_list_to_items(sw_meta)
#> \item{name}{Name of the character}
#> \item{height}{Height (cm)}
#> \item{mass}{Weight (kg)}
#> \item{species}{Name of species}
#> \item{films}{List of films the character appeared in}
Here’s how this would fail if we did not handle
.envir
correctly in our wrapper function:
my_glue_WRONG <- function(...) {
glue(..., .open = "<<", .close = ">>")
}
named_list_to_items_WRONG <- function(x) {
my_glue_WRONG("\\item{<<names(x)>>}{<<x>>}")
}
named_list_to_items_WRONG(sw_meta)
It can be hard to understand why x
can’t be found, when
it is clearly available inside named_list_to_items_WRONG()
.
Why isn’t x
available to my_glue_WRONG()
?
glue()
evaluate code?What’s going on? It’s time to look at the (redacted) signature of
glue()
:
The expressions inside a glue string are evaluated with respect to
.envir
, which defaults to the environment where
glue()
is called from.
Everything is simple when evaluating glue()
in the
global environment:
Now we wrap glue()
in our own simple function,
my_glue1()
. Notice that my_glue1()
does not
capture its caller environment and pass that along.
When we execute my_glue1()
in the global environment,
there’s no obvious problem.
The value of x
is found in the execution environment of
my_glue1()
. The values of y
and z
are found in the global environment. Importantly, this is because that
is the environment where my_glue1()
is defined, not because
that is where my_glue1()
is called.
However, if we call our my_glue1()
inside another
function, we see that all is not well.
Why do x
and y
not have the value 2?
Because my_glue1()
and its eventual call to
glue()
have no access to the execution environment of
my_glue2()
, which is the caller environment of
my_glue1()
.
If you want your glue wrapper to behave like glue()
itself and to work as expected inside other functions, make sure it
captures its caller environment and passes that along to
glue()
.
Note that delimiters <<
and
>>
have special meaning in knitr (they are used for a
templating feature in knitr itself). So in code chunks inside RMarkdown
or Quarto documents, you may need to use different delimiters.↩︎