Init an article about wrapping glue

vignettes/wrappers.Rmd

@@ -0,0 +1,172 @@
+---
+title: "How to write a function that wraps glue"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{How to write a function that wraps glue}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(glue)
+```
+
+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:
+
+```{r}
+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 of `glue()`.
+
+If you'd like to understand why this is the way, keep reading.
+
+## Working example
+
+Here's an abbreviated excerpt of the roxygen comment that generates the documentation for the starwars dataset in dplyr:
+
+```r
+#' \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{...}` 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:
+
+```{r}
+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` entries[^1]:
+
+[^1]: We're using `<@` and `@>` as the delimiters because this vignette is authored using R Markdown and knitr. The delimiters `<<` and ``>>` actually have special meaning in knitr, so it was easiest to use something else.
+
+```{r}
+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:
+
+```{r}
+named_list_to_items(sw_meta)
+```
+
+Here's how this would fail if we did *not* handle `.envir` correctly in our wrapper function:
+
+```{r, error = TRUE}
+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()`?
+
+## Where does `glue()` evaluate code?
+
+What's going on?
+It's time to look at the (redacted) signature of `glue()`:
+
+```{r, eval = FALSE}
+glue(..., .envir = parent.frame(), ...)
+```
+
+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.
+
+```{r}
+x <- 0
+y <- 0
+z <- 0
+
+glue("{x} {y} {z}")
+```
+
+Now we wrap `glue()` in our own simple function, `myglue1()`.
+Notice that `myglue()` doesn't capture its caller environment and pass that along.
+
+When we execute `myglue1()` in the global environment, there's no obvious problem.
+
+```{r}
+myglue1 <- function(...) {
+  x <- 1
+  glue(...)
+}
+
+myglue1("{x} {y} {z}")
+```
+
+However, if we call our `myglue1()` inside another function, we see that all is not well.
+
+```{r}
+myglue2 <- function(...) {
+  x <- 2
+  y <- 2
+  myglue1(...)
+}
+
+myglue2("{x} {y} {z}")
+```
+
+Why do `x` and `y` not have the value 2?
+Because `myglue1()` and its eventual call to `glue()` have no access to the execution environment of `myglue2()`.
+
+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()`.
+
+```{r}
+myglue3 <- function(..., .envir = parent.frame()) {
+  x <- 3
+  glue(..., .envir = .envir)
+}
+
+myglue3("{x} {y} {z}")
+
+myglue4 <- function(...) {
+  x <- 4
+  y <- 4
+  myglue3(...)
+}
+
+myglue4("{x} {y} {z}")
+```