Skip to contents

jinjar is a templating engine for R, inspired by the Jinja Python package and powered by the inja C++ library.

Installation

You can install the released version of jinjar from CRAN with:

Or you can install the development version from GitHub:

# install.packages("remotes")
remotes::install_github("davidchall/jinjar")

Usage

library(jinjar)

render("Hello {{ name }}!", name = "world")
#> [1] "Hello world!"

Here’s a more advanced example using loops and conditional statements. The full list of supported syntax is described in vignette("template-syntax").

template <- 'Humans of A New Hope

{% for person in people -%}
{% if "A New Hope" in person.films and default(person.species, "Unknown") == "Human" -%}
* {{ person.name }} ({{ person.homeworld }})
{% endif -%}
{% endfor -%}
'

template |>
  render(people = dplyr::starwars) |>
  writeLines()
#> Humans of A New Hope
#> 
#> * Luke Skywalker (Tatooine)
#> * Darth Vader (Tatooine)
#> * Leia Organa (Alderaan)
#> * Owen Lars (Tatooine)
#> * Beru Whitesun lars (Tatooine)
#> * Biggs Darklighter (Tatooine)
#> * Obi-Wan Kenobi (Stewjon)
#> * Wilhuff Tarkin (Eriadu)
#> * Han Solo (Corellia)
#> * Wedge Antilles (Corellia)
#> * Jek Tono Porkins (Bestine IV)
#> * Raymus Antilles (Alderaan)

An important characteristic of a templating engine is how much logic is supported. This spectrum ranges from logic-less templates (i.e. only variable substitution is supported) to arbitrary code execution. Generally speaking, logic-less templates are easier to maintain because their functionality is so restricted. But often the data doesn’t align with how it should be rendered – templating logic offers the flexibility to bridge this gap.

Fortunately, we already have very popular R packages that fall on opposite ends of this spectrum:

  • whisker – Implements the Mustache templating syntax. This is nearly logic-less, though some simple control flow is supported. Mustache templates are language agnostic (i.e. can be rendered by other Mustache implementations).
  • knitr and rmarkdown – Allows arbitrary code execution to be knitted together with Markdown text content. It even supports multiple language engines (e.g. R, Python, C++, SQL).

In contrast, jinjar strikes a balance inspired by the Jinja Python package. It supports more complex logic than whisker, but without the arbitrary code execution of knitr.