---
title: "Custom knitr language engines"
vignette: >
  %\VignetteIndexEntry{Custom knitr language engines}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    echo: true
---

```{r}
#| label: setup
#| include: false
library(glue)
```

Glue provides a few [custom language engines](https://yihui.org/rmarkdown-cookbook/custom-engine.html) for knitr, which allows you to use glue directly in knitr chunks.

## `glue` engine

The first engine is the `glue` engine, which evaluates the chunk contents as a glue template.

````markdown
```{{glue}}
1 + 1 = {1 + 1}
```
````

```{glue}
#| echo: false
1 + 1 = {1 + 1}
```

Here's one of the best uses of the `glue` engine:
Set the knitr option `results` to the value `'asis'` and output markdown or HTML directly into the document.
Because glue is vectorized, this is a concise way to generate a dynamic list or other repeated Markdown structure, which is difficult with inline R code.

````markdown
```{{glue}}
#| results: asis
#| echo: false
- **{month.abb}** is short for {month.name}
```
````

```{glue}
#| results: asis
#| echo: false
- **{month.abb}** is short for {month.name}
```

If you want to pass additional arguments into the glue call, simply include them as chunk options.

````markdown
```{{glue}}
#| .open: "<<"
#| .close: ">>"
#| results: asis
#| echo: false
The **median waiting time** between eruptions is <<median(faithful$waiting)>>.
```
````

```{glue}
#| .open: "<<"
#| .close: ">>"
#| results: asis
#| echo: false
The **median waiting time** between eruptions is <<median(faithful$waiting)>>.
```

## `glue_sql` engine

The second engine is `glue_sql`, which will use `glue::glue_sql()` to generate a SQL query and then run the query using the [sql engine](https://yihui.org/rmarkdown/language-engines.html).

First we create a new connection to an in-memory SQLite database, and write a new table to it.

```{r}
con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
mtcars$model <- rownames(mtcars)
DBI::dbWriteTable(con, "mtcars", mtcars)
```

Next define some variables we that we can use with glue to interpolate.

```{r}
var <- "mpg"
tbl <- "mtcars"
num <- 150
```

Then we can use `glue_sql` to construct and run a query using those variables into that database. *Note* you need to provide the connection object as a `connection` chunk option.

In this example there are two type of quotes. The first is a bare backtick, these are passed directly to the SQL engine unchanged.
The second is backticks inside of braces, which are specially interpreted to do the proper quoting for the given SQL engine by glue.
In this example we use the `sqlite` engine, which uses backticks for quoting, but you would use the same backticks inside brace syntax for postgreSQL, and `glue_sql()` would automatically use double quotes for quoting instead.

````markdown
```{{glue_sql}}
#| connection: con
SELECT `model`, `hp`, {`var`}
FROM {`tbl`}
WHERE {`tbl`}.`hp` > {num}
```
````

```{glue_sql}
#| connection: con
SELECT `model`, `hp`, {`var`}
  FROM {`tbl`}
  WHERE {`tbl`}.`hp` > {num}
```