Why a command-line interface for R?

A command-line interface (CLI) lets you run programs from a terminal, without opening an IDE or starting an interactive R session. This is useful when you want to:

• automate tasks via cron jobs, scheduled tasks, or CI/CD pipelines
• chain R scripts together with other tools in data pipelines
• let others run your R code without needing to know R
• package reusable tools that feel native to the terminal
• expose specific actions through a clean interface that LLM agents can invoke

There are several established packages for building CLIs in R, including argparse, optparse, and docopt, where you explicitly parse and handle command-line arguments in code. Rapp takes a different approach: it derives the CLI surface from the structure of your R script and injects values at runtime, so you never need to handle CLI arguments manually.

How Rapp works

At its core, Rapp is an alternative front-end to R: a drop-in replacement for Rscript that automatically turns common R expression patterns into command-line options, switches, positional arguments, and subcommands. You write normal R code and Rapp handles the CLI surface.

Rapp also uses special #| comments (similar to Quarto’s YAML-in-comments syntax) to add metadata such as help descriptions and short aliases.

A tiny example

Here’s a complete Rapp script (from the package examples), a coin flipper:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

#!/usr/bin/env Rapp
#| name: flip-coin
#| description: |
#|   Flip a coin.

#| description: Number of coin flips
#| short: 'n'
flips <- 1L

sep <- " "
wrap <- TRUE

seed <- NA_integer_
if (!is.na(seed)) {
  set.seed(seed)
}

cat(sample(c("heads", "tails"), flips, TRUE), sep = sep, fill = wrap)

Let’s break down how Rapp interprets this script:

The #| short: 'n' comment adds -n as a short alias for --flips. The #!/usr/bin/env Rapp line (called a “shebang”) lets you run the script directly on macOS and Linux without typing Rapp first.

Running the script

With Rapp installed and flip-coin available on your PATH (see Get started below), you can run the app from the terminal:

1
2
3
4
5

flip-coin -n 3
#> heads tails heads

flip-coin --seed 42 -n 5
#> tails heads tails tails heads

Auto-generated help

Rapp generates --help from your script (and --help-yaml if you want a machine-readable spec):

1

flip-coin --help

1
2
3
4
5
6
7
8
9

Usage: flip-coin [OPTIONS]

Flip a coin.

Options:
  -n, --flips <FLIPS>  Number of coin flips [default: 1] [type: integer]
  --sep <SEP>          [default: " "] [type: string]
  --wrap / --no-wrap   [default: true] Disable with `--no-wrap`.
  --seed <SEED>        [default: NA] [type: integer]

1
2
3
4
5
6

# Before 0.3.0: this positional was optional
name <- NULL

# In 0.3.0+: add this comment to keep it optional
#| required: false
name <- NULL

Highlights in 0.3.0

Rapp will be new to most readers, so rather than listing every change, here are the main ideas (and what’s improved in 0.3.0).

Options, switches, and repeatable flags from plain R

Rapp recognizes a small set of “declarative” patterns at the top level of your script:

• Scalar literals like flips <- 1L become options like --flips 10.
• Logical defaults like wrap <- TRUE become toggles like --wrap / --no-wrap.
• #| short: n adds a short alias like -n (new in 0.3.0).
• c() and list() defaults declare repeatable options (new in 0.3.0): callers can supply the same flag multiple times and values are appended.

Subcommands with switch()

Rapp can now turn a switch() block into subcommands (and you can nest switch() blocks for nested commands). Here’s a small sketch of a todo-style app:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#!/usr/bin/env Rapp
#| name: todo
#| description: Manage a simple todo list.

#| description: Path to the todo list file.
#| short: s
store <- ".todo.yml"

switch(
  command <- "",

  #| description: Display the todos
  list = {
    limit <- 30L
    # ...
  },

  #| description: Add a new todo
  add = {
    task <- NULL
    # ...
  }
)

Help is scoped to the command you’re asking about, so todo --help lists the commands, and todo list --help shows just the options/arguments for list (plus any parent/global options).

Installable launchers for package CLIs

A big part of sharing CLI tools is making them easy to run after installation. In 0.3.0, install_pkg_cli_apps() installs lightweight launchers for scripts in a package’s exec/ directory that use either #!/usr/bin/env Rapp or #!/usr/bin/env Rscript:

1

Rapp::install_pkg_cli_apps("mypackage")

(There’s also uninstall_pkg_cli_apps() to remove a package’s launchers.)

Get started

Here’s the quickest path to your first Rapp script:

1
2

# 1. Install the package
install.packages("Rapp")

1
2

# 2. Install the command-line launcher
Rapp::install_pkg_cli_apps("Rapp")

Then create a script (e.g., hello.R):

1
2
3
4
5
6

#!/usr/bin/env Rapp
#| name: hello
#| description: Say hello

name <- "world"
cat("Hello,", name, "\n")

And run it:

1
2

Rapp hello.R --name "R users"
#> Hello, R users

Learn more

To dig deeper into Rapp:

• browse examples in the package: system.file("examples", package = "Rapp")
• read the full documentation: https://github.com/r-lib/Rapp
• note that Rapp requires R ≥ 4.1.0

If you try Rapp, we’d love feedback! We especially want to hear about your experiences with edge cases in argument parsing, help output, and how commands should feel. Issues and ideas are welcome at https://github.com/r-lib/Rapp/issues .

With this release, it bridges the gap between your laptop and enterprise infrastructure – the same code you prototype locally now deploys to Posit Workbench or any cloud HTTP API, with a single function call.

You can install it from CRAN with:

1

install.packages("mirai")

The flagship feature for this release is the HTTP launcher for deploying daemons to cloud and enterprise platforms. This release also brings a C-level dispatcher for minimal task dispatch overhead, race_mirai() for process-as-completed patterns, synchronous mode for debugging, and daemon synchronization for remote deployments. You can see a full list of changes in the release notes .

How mirai works

If you’ve ever waited for a loop to finish fitting models, processing files, or calling APIs, mirai can help. Any task that’s repeated independently across items is a candidate for parallel execution.

The previous release post covered mirai’s design philosophy in detail. Here’s a brief overview for readers encountering mirai for the first time.

library(mirai)
# Set up 4 background processes
daemons(4)

# Send work -- non-blocking, returns immediately
m <- mirai({
  Sys.sleep(1)
  100 + 42
})
m
#> < mirai [] >

# Collect the result when ready
m[]
#> [1] 142

# Shut down
daemons(0)

That’s mirai in a nutshell: daemons() to set up workers, mirai() to send work, [] to collect results. Everything else builds on this.

In mirai’s hub architecture, the host session listens at a URL and daemons – background R processes that do the actual work – connect to it. You send tasks with mirai() , and the dispatcher routes them to available daemons in first-in, first-out (FIFO) order.

This design enables dynamic scaling: daemons can connect and disconnect at any time without disrupting the host. Add capacity when you need it, release it when you don’t.

A single compute profile can mix daemons launched by different methods, and you can run multiple profiles simultaneously to direct different tasks to different resources. The basic syntax for each deployment method:

Change one line and your local prototype runs on a Slurm cluster. Change it again and it runs on Posit Workbench. Your analysis code stays identical.

The async foundation for the modern R stack

mirai has become the convergence point for asynchronous and parallel computing across the R ecosystem.

It is the recommended async backend for Shiny – if you’re building production Shiny apps, you should be using mirai. It is the only async backend for the next-generation plumber2 – if you’re building APIs with plumber2, you’re already using mirai.

It is the parallel backend for purrr – if you use map(), mirai is how you make it parallel. Wrap your function in in_parallel() , set up daemons, and your map calls run across all of them:

1
2
3
4
5

library(purrr)
daemons(4)
models <- split(mtcars, mtcars$cyl) |>
  map(in_parallel(\(x) lm(mpg ~ wt + hp, data = x)))
daemons(0)

It powers targets – the pipeline orchestration tool for reproducible analysis. And most recently, ragnar – the Tidyverse package for retrieval-augmented generation (RAG) – adopted mirai for its parallel processing.

As an official alternative communications backend for R’s parallel package, mirai underpins workflows from interactive web applications to pipeline orchestration to AI-powered document processing.

Learn mirai, and you’ve learned the async primitive that powers the modern R stack. The same two concepts – daemons() to set up workers, mirai() to send work – are all you need to keep a Shiny app responsive or run async tasks in production.

HTTP launcher

This release extends the “deploy everywhere” principle with http_config() , a new remote launch configuration that deploys daemons via HTTP API calls – any platform with an HTTP API for launching jobs.

Posit Workbench

Many organizations use Posit Workbench to run research and data science at scale. mirai now integrates directly with it.¹ Call http_config() with no arguments and it auto-configures using the Workbench environment:

1

daemons(n = 4, url = host_url(), remote = http_config())

That’s it. Four daemons launch as Workbench jobs, connect back to your session, and you can start sending work to them.

Here’s what that looks like in practice: you’re developing a model in your Workbench session. Fitting it locally is slow. Add that line, and those fits fan out across four Workbench-managed compute jobs. When you’re done, daemons(0) releases them. No YAML, no job scripts, no leaving your R session – resource allocation, access control, and job lifecycle are all handled by the platform.

If you’ve been bitten by expired tokens in long-running sessions, http_config() is designed to prevent that. Under the hood, it stores functions rather than static values for credentials and endpoint URLs. These functions are called at the moment daemons actually launch, so session cookies and API tokens are always fresh – even if you created the configuration hours earlier.

See the mirai vignette for troubleshooting remote launches.

Custom APIs

The HTTP launcher works with any HTTP API, not just Workbench. Supply your own endpoint, authentication, and request body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

daemons(
  n = 2,
  url = host_url(),
  remote = http_config(
    url = "https://api.example.com/launch",
    method = "POST",
    token = function() Sys.getenv("MY_API_KEY"),
    data = '{"command": "%s"}'
  )
)

The "%s" placeholder in data is where mirai inserts the daemon launch command at launch time. Each argument can be a plain value or a function – use functions for anything that changes between launches (tokens, cookies, dynamic URLs).

This opens up a wide range of deployment targets: Kubernetes job APIs, other cloud container services, or any internal job scheduler with an HTTP interface. If you can launch a process with an HTTP call, mirai can use it.

C-level dispatcher

The overhead of distributing your tasks is now negligible. In a mirai_map() over thousands of items, what you measure is the time of your actual computation, not the framework – per-task dispatch overhead is now in the tens of microseconds, where existing R parallelism solutions typically operate in the millisecond range.

Under the hood, the dispatcher – the process that sits between your session and the daemons, routing tasks to available workers – has been re-implemented entirely in C code within nanonext . This eliminates the R interpreter overhead that remained, while the dispatcher continues to be event-driven and consume zero CPU when idle.

This also removes the bottleneck when coordinating large numbers of daemons, which matters directly for the kind of scaled-out deployments that the HTTP launcher enables – dozens of Workbench jobs or cloud instances all connecting to a single dispatcher. The two features are designed to work together: deploy broadly, dispatch efficiently. mirai is built to scale from 2 cores on your laptop to 200 across a cluster, without the framework slowing you down.

race_mirai()

race_mirai() lets you process results as they arrive, rather than waiting for the slowest task. Suppose you’re fitting 10 models with different hyperparameters in parallel – some converge quickly, others take much longer. Without race_mirai() , you wait for the slowest fit to complete before seeing any results. With it, you can inspect or save each model the instant it finishes – updating a progress display, freeing memory, or deciding whether to continue the remaining fits at all.

race_mirai() returns the integer index of the first resolved mirai. This makes the “process as completed” pattern clean and efficient:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

daemons(4)

# Launch 10 model fits in parallel
fits <- lapply(param_grid, function(p) mirai(fit_model(data, p), data = data, p = p))

# Process each result as soon as it's ready
remaining <- fits
while (length(remaining) > 0) {
  idx <- race_mirai(remaining)
  cat("Finished model with params:", remaining[[idx]]$data$p, "\n")
  remaining <- remaining[-idx]
}

daemons(0)

Send off a batch of tasks, then process results in the order they finish – no polling, no wasted time waiting on the slowest one. If any mirai is already resolved when you call race_mirai() , it returns immediately. This pattern applies whenever tasks have variable completion times – parallel model fits, API calls, simulations, or any batch where you want to stream results as they land.

Synchronous mode

When tasks don’t behave as expected, you need a way to inspect them interactively.

Without synchronous mode, errors in a mirai return as miraiError objects – you can see that something went wrong, but you can’t step through the code to find out why. The task ran in a separate process, and by the time you see the error, that process has moved on.

daemons(sync = TRUE), introduced in 2.5.1, solves this. It runs everything in the current process – no background processes, no networking – just sequential execution. You can use browser() and other interactive debugging tools directly:

1
2
3
4
5
6
7
8

daemons(sync = TRUE)
mirai(
  {
    browser()
    mypkg::some_complex_function(x)
  },
  x = my_data
)

You can scope synchronous mode to a specific compute profile, isolating the problematic task for inspection while the rest of your pipeline keeps running in parallel.

Daemon synchronization with everywhere()

everywhere() runs setup operations on all daemons – loading packages, sourcing scripts, or preparing datasets – so they’re ready before you send work.

When launching remote daemons – via SSH, HPC schedulers, or the new HTTP launcher – there’s an inherent delay between requesting a daemon and that daemon being ready to accept work. The new .min argument ensures that setup has completed on at least that many daemons before returning:

1
2
3
4
5
6
7

daemons(n = 8, url = host_url(), remote = http_config())

# Wait until all 8 daemons are connected before continuing
everywhere(library(mypackage), .min = 8)

# Now send work once all daemons are ready
mp <- mirai_map(tasks, process)

This creates a synchronization point, ensuring your pipeline doesn’t start sending work before all daemons are ready. It’s especially useful for remote deployments where connection times are unpredictable.

Minor improvements and fixes

• miraiError objects now have conditionCall() and conditionMessage() methods, making them easier to use with R’s standard condition handling.
• The default exit behavior for daemons has been updated with a 200ms grace period before forceful termination, which allows OpenTelemetry disconnection events to be traced.
• OpenTelemetry span names and attributes have been revised to better follow semantic conventions.
• daemons() now properly validates that url is a character value where supplied.
• Fixed a bug where repeated mirai cancellation could sometimes cause a daemon to exit prematurely.

Try it now

1
2
3
4
5
6
7
8

install.packages("mirai")
library(mirai)

daemons(4)
system.time(mirai_map(1:4, \(x) Sys.sleep(1))[])
#>    user  system elapsed
#>   0.000   0.001   1.003
daemons(0)

Four one-second tasks, one second of wall time. If those were four model fits that each took a minute, you’d go from four minutes down to one – and if you needed more power, switching to Workbench or a Slurm cluster is a one-line change. Visit mirai.r-lib.org for the full documentation.

Acknowledgements

A big thank you to all the folks who helped make this release happen:

@agilly , @aimundo , @barnabasharris , @beevabeeva , @boshek , @eliocamp , @jan-swissre , @jeroenjanssens , @kentqin-cve , @mcol , @michaelmayer2 , @pmac0451 , @r2evans , @shikokuchuo , @t-kalinowski , @VincentGuyader , @wlandau , and @xwanner .

When we introduced nanonext last year, we showed how it connects R directly to Python, Go, Rust, and other languages through NNG’s messaging protocols. We hinted at its web capabilities – but that was just the beginning.

R already has excellent web infrastructure. Shiny and plumber2 are the go-to tools for building interactive applications and REST APIs in R. They are both powered by httpuv . nanonext adds a complementary option at the httpuv level of the stack – a low-level streaming HTTP and WebSocket server built on NNG, giving developers fine-grained control over connections, streaming, and static file serving over TLS. nanonext is for when you need lower-level control – custom protocols, infrastructure endpoints, or embedding a server alongside an existing Shiny or plumber2 application.

You can install it from CRAN with:

1

install.packages("nanonext")

You can see a full list of changes in the release notes .

Streaming HTTP/WebSocket server

The flagship feature of this release is http_server() , a streaming HTTP and WebSocket server with full TLS support. Built on NNG’s HTTP server architecture, it brings the same performance that powers nanonext’s messaging layer to web serving.

One server, one port – HTTP endpoints, WebSocket connections, and streaming all coexist. Static files bypass R entirely, served natively by NNG. WebSocket and streaming connections run callbacks on R’s main thread via the later package. Mbed TLS is built in for HTTPS/WSS, and there’s no need to run separate processes or bind additional ports.

Because it shares the same event loop that Shiny uses, http_server() can run alongside a Shiny app in the same R process. You could spin up a nanonext server to handle health checks, serve static assets, or stream real-time events – while Shiny or plumber2 handles the application logic. They’re designed to work together.

As part of our investment in expanding what’s possible with R, we’re already using nanonext at Posit to explore new real-time capabilities, and we’re excited to see what the community builds with it.

Basic HTTP server

Where frameworks like plumber2 give you a full-featured API layer with routing, serialization, and documentation out of the box, http_server() gives you direct control over requests and responses – the kind of direct access you’d reach for when building custom infrastructure or embedding a server inside a larger system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

library(nanonext)

server <- http_server(
  url = "http://127.0.0.1:8080",
  handlers = list(
    handler("/", function(req) {
      list(status = 200L, body = "Hello from nanonext!")
    }),
    handler("/api/data", function(req) {
      list(
        status = 200L,
        headers = c("Content-Type" = "application/json"),
        body = '{"value": 42}'
      )
    }, method = "GET")
  )
)
server$start()

Handlers receive a request and return a response list. You can freely mix handler types in a single server:

Specifying port 0 in the URL lets the operating system assign an available port. The actual port is reflected in server$url after $start(), so you can set up test servers without worrying about port conflicts.

Static file serving

Static handlers bypass R entirely – NNG serves content directly and efficiently:

1
2
3
4
5
6
7

handler_directory("/static", "www/assets")  # serve a folder
handler_file("/favicon.ico", "favicon.ico") # serve a single file
handler_inline(
  "/robots.txt",
  "User-agent: *\nDisallow:",
  content_type = "text/plain"
) # serve in-memory content

For example, you can serve a rendered Quarto website with a single handler:

1
2
3
4
5
6
7

server <- http_server(
  url = "http://127.0.0.1:0",
  handlers = handler_directory("/", "_site")
)
server$start()
server$url
# Browse to the URL to see your Quarto site

WebSocket server

WebSockets provide full bidirectional communication – the server can push messages to the client, and the client can send messages back. WebSocket and HTTP handlers share the same server and port, so a browser can load a page over HTTP and open a WebSocket to the same origin – no cross-origin configuration needed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

server <- http_server(
  url = "http://127.0.0.1:8080",
  handlers = list(
    handler("/", function(req) list(status = 200L, body = "<html>...</html>")),
    handler_ws("/ws",
      on_message = function(ws, data) ws$send(data),
      on_open = function(ws) cat("connected:", ws$id, "\n"),
      on_close = function(ws) cat("disconnected:", ws$id, "\n")
    )
  )
)

This makes it easy to build lightweight real-time services – monitoring endpoints or live-updating feeds that push results to the browser as they arrive.

HTTP streaming and Server-Sent Events

When you only need to push data in one direction – server to client – streaming is a lighter-weight alternative to WebSockets. It works over plain HTTP, so any client that speaks HTTP can consume the stream without needing a WebSocket library. handler_stream() enables chunked transfer encoding for streaming responses:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

conns <- list()

handler_stream("/events",
  on_request = function(conn, req) {
    conn$set_header("Content-Type", "text/event-stream")
    conn$set_header("Cache-Control", "no-cache")
    conns[[as.character(conn$id)]] <<- conn
    conn$send(format_sse(data = "connected", id = "1"))
  },
  on_close = function(conn) {
    conns[[as.character(conn$id)]] <<- NULL
  }
)

The format_sse() helper formats messages per the SSE specification. On the browser side, updates arrive automatically as they happen – no page refreshes or repeated requests needed. Streaming also supports NDJSON and custom formats – useful for streaming model training progress, sensor readings, monitoring endpoints, or pipeline notifications.

TLS/SSL support

For HTTPS, pass a TLS configuration. nanonext bundles Mbed TLS, so there’s nothing extra to install:

1
2
3
4
5
6

cert <- write_cert(cn = "127.0.0.1")
server <- http_server(
  url = "https://127.0.0.1:0",
  handlers = handler("/", function(req) list(status = 200L, body = "Secure!")),
  tls = tls_config(server = cert$server)
)

Full response headers for HTTP client

ncurl() now accepts response = TRUE to return all response headers:

resp <- ncurl("https://postman-echo.com/get", response = TRUE)
resp$headers |> names()
#>  [1] "Date"                          "Content-Type"                 
#>  [3] "Content-Length"                "Connection"                   
#>  [5] "CF-RAY"                        "etag"                         
#>  [7] "vary"                          "Set-Cookie"                   
#>  [9] "x-envoy-upstream-service-time" "cf-cache-status"              
#> [11] "Server"

Previously you could only request specific headers by name. Now you can retrieve the complete set – useful for inspecting rate limits, caching directives, and other metadata from REST APIs.

Async HTTP with Shiny

If your Shiny app calls a REST API, a slow or unresponsive endpoint will block the R process and freeze the app for all users, not just the one who triggered the request. ncurl_aio() avoids this – it performs the HTTP call on a background thread and returns a promise, so the R process stays free to serve other sessions. It works anywhere that accepts a promise, including Shiny’s ExtendedTask:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

library(shiny)
library(bslib)
library(nanonext)

ui <- page_fluid(
  p("The time is ", textOutput("current_time", inline = TRUE)),
  hr(),
  input_task_button("btn", "Fetch data"),
  verbatimTextOutput("result")
)

server <- function(input, output, session) {
  output$current_time <- renderText({
    invalidateLater(1000)
    format(Sys.time(), "%H:%M:%S %p")
  })

  task <- ExtendedTask$new(
    function() ncurl_aio("https://postman-echo.com/get", response = TRUE)
  ) |> bind_task_button("btn")

  observeEvent(input$btn, task$invoke())
  output$result <- renderPrint(task$result()$headers)
}

shinyApp(ui, server)

New documentation

The package documentation has been reorganized into focused, self-contained guides:

Whether you need a quick API cheatsheet or a deep dive into WebSocket chat servers, the new vignettes are designed to get you up and running fast.

Bug fixes and improvements

A new race_aio() function returns the index of the first resolved async operation in a list – useful when waiting on multiple concurrent operations and you want to act on whichever completes first.

This release also fixes two critical issues – one affecting TLS operations in fresh sessions with newer system versions of Mbed TLS, another when custom serialization hooks threw errors. Error handling is now more graceful throughout, with closed streams returning error values instead of throwing. Under the hood, serialization, streaming, and async sends are all faster, and the bundled Mbed TLS is updated to 3.6.5 LTS. Building from source no longer requires xz.

Looking ahead

nanonext gives R a new building block for web infrastructure – one that complements httpuv. We see it as part of a broader investment in making R a first-class platform for real-time, connected applications. If you want to dig deeper, visit the package website or explore the source on GitHub .

Acknowledgements

A big thank you to everyone who contributed to this release:

@jeroenjanssens and @shikokuchuo .

Today we’re announcing two new packages for parsing and emitting YAML 1.2: yaml12 for R and py-yaml12 for Python.

Both packages are implemented in Rust and built on the excellent saphyr crate. They share the same design goals: predictable YAML 1.2 typing, explicit control over tag interpretation via handlers, and clean round-tripping of unhandled tags.

Before we get into the details, a quick note on how this relates to the existing R yaml package. The R yaml package is now in r-lib , and we’ve taken over maintenance after years of stewardship by its original author, Jeremy Stephens, and later by Shawn Garbett.

If yaml already works for you, there’s no need to switch. yaml12 is an experiment providing consistent R and Python bindings to a new Rust library specifically for YAML 1.2, which, as we’ll see below, has some particular advantages.

Install

Install the R package from CRAN:

install.packages("yaml12")

Install the Python package from PyPI:

1

pip install py-yaml12

Quick start (R)

library(yaml12)

yaml <- "
title: A modern YAML parser and emitter written in Rust
properties: [fast, correct, safe, simple]
"

doc <- parse_yaml(yaml)
str(doc)
#> List of 2
#>  $ title     : chr "A modern YAML parser and emitter written in Rust"
#>  $ properties: chr [1:4] "fast" "correct" "safe" "simple"

Round-trip back to YAML:

obj <- list(
  seq = 1:2,
  map = list(key = "value"),
  tagged = structure("1 + 1", yaml_tag = "!expr")
)
write_yaml(obj)
#> ---
#> seq:
#>   - 1
#>   - 2
#> map:
#>   key: value
#> tagged: !expr 1 + 1
#> ...

identical(obj, parse_yaml(format_yaml(obj)))
#> [1] TRUE

Quick start (Python)

# Install from PyPI:
#   python -m pip install py-yaml12
from yaml12 import parse_yaml, format_yaml, Yaml

yaml_text = """
title: A modern YAML parser and emitter written in Rust
properties: [fast, correct, safe, simple]
"""

doc = parse_yaml(yaml_text)

assert doc == {
  "title": "A modern YAML parser and emitter written in Rust",
  "properties": ["fast", "correct", "safe", "simple"]
}

assert doc == parse_yaml(format_yaml(doc))

# Tagged values
tagged = parse_yaml("!expr 1 + 1")
assert tagged == Yaml(value="1 + 1", tag="!expr")

Why YAML 1.2?

YAML 1.2 tightened up a number of ambiguous implicit conversions. In particular, plain scalars like on/off/yes/no/y/n are strings in the 1.2 core schema, and YAML 1.2 removed sexagesimal (base-60) parsing, so values like 1:2 are not treated as numbers.

YAML 1.2 also removed !!timestamp, !!binary, and !!omap from the set of core types, which further reduces implicit coercions (for example, getting a date/time object when you expected a string). If you want to interpret those values, you can do so explicitly via tags and handlers.

That makes YAML a better default for configuration files, front matter, and data interchange. You get fewer surprises and fewer “why did this become a boolean?” moments (or “why did this become a date?”).

Highlights

A consistent API in R and Python

The two packages intentionally share the same high-level functions:

• parse_yaml() : Parse YAML from a string
• read_yaml() : Read YAML from a file
• format_yaml() : Format values as YAML (to a string)
• write_yaml() : Write YAML to a file (or stdout)

Tags and handlers (opt-in, meaning, safe defaults)

In YAML, tags are explicit annotations like !expr or !!timestamp that attach type and meaning to a value.

Tags are preserved by default:

• In R, tags are kept in a yaml_tag attribute.
• In Python, tags are kept by wrapping values in a Yaml() object.

Handlers let you opt into custom behavior for tags (including tags on mapping keys) while keeping parsing as a data-only operation by default.

If you used R yaml’s !expr tag to evaluate expressions, you can recreate that behavior by registering a handler, but it’s only recommended when parsing trusted YAML, since evaluating arbitrary code is a security risk. For untrusted input, the default behavior is safer because it keeps !expr as data and does not execute code.

R example:

# by default, tags are kept as data
dput(parse_yaml("!expr 1 + 1"))
#> structure("1 + 1", yaml_tag = "!expr")

# Add a handler to process tagged nodes (like the {yaml} package does)
handlers <- list("!expr" = \(x) eval(str2expression(x), globalenv()))
parse_yaml("!expr 1 + 1", handlers = handlers)
#> [1] 2

Python example:

from yaml12 import parse_yaml

handlers = {"!expr": eval}  # use with trusted input only
parse_yaml("!expr 1 + 1", handlers=handlers)

#> 2

Simplification and missing values (R)

In R, parse_yaml() can simplify homogeneous sequences to vectors. When it does, YAML null becomes the appropriate NA type:

parse_yaml("[1, 2, 3, null]")
#> [1]  1  2  3 NA

str(parse_yaml("[1, 2, 3, null]", simplify = FALSE))
#> List of 4
#>  $ : int 1
#>  $ : int 2
#>  $ : int 3
#>  $ : NULL

Non-string mapping keys

YAML allows mapping keys that aren’t plain strings (numbers, booleans, tagged scalars, even sequences and mappings). Both packages preserve these safely:

• In R, you’ll get a regular named list plus a yaml_keys attribute when needed.
• In Python, unhashable keys (like lists/dicts) are wrapped in Yaml so they can still be used as dict keys and round-trip correctly.

R example:

dput(parse_yaml("{a: b}: c"))
#> structure(list("c"), names = "", yaml_keys = list(list(a = "b")))

Python example:

from yaml12 import parse_yaml, Yaml

doc = parse_yaml("{a: b}: c")
assert doc == {Yaml({'a': 'b'}): 'c'}

Mapping order is preserved

YAML mappings are ordered. yaml12 preserves mapping/dictionary order when parsing and formatting, so the order you see in a YAML file (or emit) round-trips in both R and Python.

Document streams and front matter

Both packages support multi-document YAML streams with multi = TRUE. When multi = FALSE (the default), parsing stops after the first document, which is handy for extracting YAML front matter from text that continues with non-YAML content.

Example:

yaml <- "
---
title: Extracting YAML front matter
---
This is technically now the second document in a YAML stream
"
str(parse_yaml(yaml))
#> List of 1
#>  $ title: chr "Extracting YAML front matter"
str(parse_yaml(yaml, multi = TRUE))
#> List of 2
#>  $ :List of 1
#>   ..$ title: chr "Extracting YAML front matter"
#>  $ : chr "This is technically now the second document in a YAML stream"

Performance and safety notes

yaml12 is implemented in Rust and written with performance and safety in mind. It avoids unnecessary allocations, copies, and extra traversals where possible. In Python, py-yaml12 (imported as yaml12) also releases the GIL for large parses and serializations.

In typical usage, the R package yaml12 is ~2× faster than the yaml package, and the Python package py-yaml12 is ≥50× faster than default PyYAML in the benchmarks (R benchmarks ; Python benchmarks ).

Tags are preserved by default, and interpreting them (including any kind of evaluation) is always an explicit opt-in via handlers. Plain scalars follow the YAML 1.2 core schema rules for predictable typing.

In Python, py-yaml12 ships prebuilt wheels for common platforms. If you do need to build from source, you’ll need a Rust toolchain. In R, yaml12 is available from CRAN (including binaries on common platforms).

Wrapping up

If you work with YAML as a data format for configuration, front matter, or data interchange, we hope yaml12 (R) and py-yaml12 (Python) help you parse and emit YAML 1.2 predictably. If you run into YAML that doesn’t behave as expected, we’d love to hear about it in the issue trackers: r-yaml12 and py-yaml12 .

Learn more

• R package docs: https://posit-dev.github.io/r-yaml12/
• R package on CRAN: https://cran.r-project.org/package=yaml12
• Python package docs: https://posit-dev.github.io/py-yaml12/
• Python package on PyPI: https://pypi.org/project/py-yaml12/

Acknowledgements

Both packages build on the fantastic work in the YAML ecosystem, especially the saphyr Rust crate and the yaml-test-suite .

We’re chuffed to announce the release of testthat 3.3.0. testthat is a testing framework for R that makes it easy to turn your existing informal tests into formal, automated tests that you can rerun quickly and easily.

You can install it from CRAN with:

install.packages("testthat")

This blog post highlights the most important changes in this release, including lifecycle changes that removed long-deprecated mocking functions, improvements to expectations and their error messages, and a variety of new features that make testing easier and more robust. You can see a full list of changes in the release notes .

library(testthat)

Claude Code experiences

Before we dive into the changes, I wanted to talk a little bit about some changes to my development process, as I used this release as an opportunity to learn Claude Code . This is the first package where I’ve really used AI to support the development of many features and I thought it might be useful to share my experience.

Overall it was a successful experiment. It helped me close over 100 issues in what felt like less time than usual. I don’t have any hard numbers, but my gut feeling is that it was maybe a 10-20% improvement to my development velocity. This is still significant, especially since I’m an experienced R programmer and my workflow has been pretty stable for the last few years. I mostly used Claude for smaller, well-defined tasks where I had a good sense of what was needed. I found it particularly useful for refactoring, where it was easy to say precisely what I wanted, but executing the changes required a bunch of fiddly edits across many files.

I also found it generally useful for getting over the “activation energy hump”: there were a few issues that had been stagnating for years because they felt like they were going to be hard to do and with relatively limited payoff. I let Claude Code loose on a few of these and found it super useful. It only produced code I was really happy with a couple of times, but every time it gave me something to react to (often with strong negative feelings!) and that got me started actually engaging with the problem.

If you’re interested in using Claude Code yourself, there are a couple of files you might find useful. My CLAUDE.md tells Claude how to execute a devtools-based workflow, along with a few pointers to resolve common issues. My settings.json allows Claude to run longer without human intervention, doing things that should mostly be safe. One note of caution: these settings do allow Claude to run R code, which does allow it to do practically anything. In my experience, Claude only used R to run tests or documentation.

I also experimented with using Claude Code to review PRs. It was just barely useful enough that I kept it turned on for my own PRs, but I didn’t bother trying to get it to work for contributed PRs. Most of the time it either gave a thumbs up or bad advice, but every now and then it would pick up a small error.

(I’ve also used Claude Code to proofread this blog post!)

Lifecycle changes

The biggest change in this release is that local_mock() and with_mock() are defunct. They were deprecated in 3.0.0 (2020-10-31) because it was becoming clear that the technique that made them work would be disallowed in a future version of R. This has now happened in R 4.5.0, so the functions have been removed. Removing local_mock() and with_mock() was a fairly disruptive change, affecting ~100 CRAN packages, but it had to be done, and I’ve been working on notifying package developers since January so everyone had plenty of time to update. Fortunately, the needed changes are generally small, since the newer local_mocked_bindings() and with_mocked_bindings() can solve most additional needs. (If you haven’t heard of mocking before, you can read the new vignette("mocking") to learn what it is and why you might want to use it.)

Other lifecycle changes:

• testthat now requires R 4.1. This follows our supported version policy , which documents our commitment to support five versions of R (the current version and four previous versions). We’re excited to be able to finally take advantage of the base pipe and compact anonymous functions (i.e. \(x) x + 1)!

• is_null()/matches(), deprecated in 2.0.0 (2017-12-19), and is_true()/is_false(), deprecated in 2.1.0 (2019-04-23), have been removed. These conflicted with other tidyverse functions so we pushed their deprecation through, even though we have generally left the old test_that() API untouched.

• expect_snapshot(binary), soft deprecated in 3.0.3 (2021-06-16), is now fully deprecated. test_files(wrap), deprecated in 3.0.0 (2020-10-31), has now been removed.

• There were a few other changes that broke existing packages. The most impactful change was to start checking the inputs to expect() which, despite the name, is actually an internal helper. That revealed a surprising number of packages were accidentally using expect() instead of expect_true() or expect_equal() . We don’t technically consider this a breaking change because it revealed off-label function usage: the function API hasn’t changed; you just now learn when you’re using it incorrectly.

If you’re interested in the process we use to manage the release of a package that breaks its reverse dependencies, you might like to read the issue where I track all the problems and prepare PRs to fix them.

Expectations and the interactive testing experience

A lot of work in this release was prompted by an overhaul of vignette("custom-expectations"), which describes how to create your own expectations that work just like testthat’s. This is a long time coming, and as I was working on it, I realized that I didn’t really know how to write new expectations, which had led to a lot of variation in the existing implementations. This kicked off a bunch of experimentation and iterating, leading to a swath of improvements:

• All expectations have new failure messages: they now state what was expected, what was actually received, and, if possible, they clearly illustrate the difference.

• Expectations now consistently return the value of the first argument, regardless of whether the expectation succeeds or fails (the only exception is expect_error() and friends which return the captured condition so that you can perform additional checks on the condition object). This is a relatively subtle change that won’t affect tests that already pass, but it does improve failures when you pipe together multiple expectations.

• A new pass() function makes it clear how to signal when an expectation succeeds. All existing expectations were rewritten to use pass() and (the existing) fail() instead of expect() , which I think makes the flow of logic easier to understand.

• Improved expect_success() and expect_failure() expectations now test that an expectation always returns exactly one success or failure (this ensures that the counts that you see in the reporters are correct).

This new framework helped us write six new expectations:

• expect_all_equal() , expect_all_true() , and expect_all_false() check that every element of a vector has the same value, giving better error messages than expect_true(all(...)):

  test_that("some test", {
    x <- c(0.408, 0.961, 0.883, 0.46, 0.537, 0.961, 0.851, 0.887, 0.023)
    expect_all_true(x < 0.95)
  })
  #> ── Failure: some test ────────────────────────────────────────────────
  #> Expected every element of `x < 0.95` to equal TRUE.
  #> Differences:
  #> `actual`:   TRUE FALSE TRUE TRUE TRUE FALSE TRUE TRUE TRUE
  #> `expected`: TRUE TRUE  TRUE TRUE TRUE TRUE  TRUE TRUE TRUE
  #> Error:
  #> ! Test failed with 1 failure and 0 successes.
  

• expect_disjoint() , by @stibu81 , expects values to be absent:

  test_that("", {
    expect_disjoint(c("a", "b", "c"), c("c", "d", "e"))
  })
  #> ── Failure:  ─────────────────────────────────────────────────────────
  #> Expected `c("a", "b", "c")` to be disjoint from `c("c", "d", "e")`.
  #> Actual: "a", "b", "c"
  #> Expected: None of "c", "d", "e"
  #> Invalid: "c"
  #> Error:
  #> ! Test failed with 1 failure and 0 successes.
  

• expect_r6_class() expects an R6 object:

  test_that("", {
    x <- 10
    expect_r6_class(x, "foo")
  
    x <- R6::R6Class("bar")$new()
    expect_r6_class(x, "foo")
  })
  #> ── Failure:  ─────────────────────────────────────────────────────────
  #> Expected `x` to be an R6 object.
  #> Actual OO type: none.
  #> ── Failure:  ─────────────────────────────────────────────────────────
  #> Expected `x` to inherit from "foo".
  #> Actual class: "bar"/"R6".
  #> Error:
  #> ! Test failed with 2 failures and 0 successes.
  

• expect_shape() , by @michaelchirico , expects a specific shape (i.e., nrow() , ncol() , or dim() ):

  test_that("show off expect_shape() failure messages", {
    x <- matrix(1:9, nrow = 3)
    expect_shape(x, nrow = 4)
    expect_shape(x, dim = c(3, 3, 3))
    expect_shape(x, dim = c(3, 4))
  })
  #> ── Failure: show off expect_shape() failure messages ─────────────────
  #> Expected `x` to have 4 rows.
  #> Actual rows: 3.
  #> ── Failure: show off expect_shape() failure messages ─────────────────
  #> Expected `x` to have 3 dimensions.
  #> Actual dimensions: 2.
  #> ── Failure: show off expect_shape() failure messages ─────────────────
  #> Expected `x` to have dim (3, 4).
  #> Actual dim: (3, 3).
  #> Error:
  #> ! Test failed with 3 failures and 0 successes.
  

As you can see from the examples above, when you run a single test interactively (i.e. not as a part of a test suite) you now see exactly how many expectations succeeded and failed.

Other new features

• testthat generally does a better job of handling nested tests, aka subtests, where you put a test_that() inside another test_that() , or more typically it() inside of describe() . Subtests will now generate more informative failure messages, free from duplication, with more informative skips if any subtests don’t contain any expectations.

• The snapshot experience has been significantly improved, with all known bugs fixed and some new helpers added: snapshot_reject() rejects all modified snapshots by deleting the .new variants, and snapshot_download_gh() makes it easy to get snapshots off GitHub and into your local package. Additionally, expect_snapshot() and friends will now fail when creating a new snapshot on CI, as that’s usually a signal that you’ve forgotten to run the snapshot code locally before committing.

• On CRAN, test_that() will automatically skip if a package is not installed, which means that you no longer need to check if suggested packages are installed in your tests.

• vignette("mocking") explains mocking in detail, and new local_mocked_s3_method() , local_mocked_s4_method() , and local_mocked_r6_class() make it easier to mock S3 and S4 methods and R6 classes.

• test_dir() , test_check() , and friends gain a shuffle argument that uses sample() to randomly reorder the top-level expressions in each test file. This random reordering surfaces dependencies between tests and code outside of any test, as well as dependencies between tests, helping you find and eliminate unintentional dependencies.

• try_again() is now publicized, as it’s a useful tool for testing flaky code:

  flaky_function <- function() {
      if (runif(1) < 0.1) 0 else 1
    }
    
    # 10% chance of failure:
    test_that("my flaky test is ok", {
      skip_on_cran()
      expect_equal(flaky_function(), 1)
    })
    
    # 1% chance of failure:
    test_that("my flaky test is ok", {
      skip_on_cran()
      try_again(1, expect_equal(flaky_function(), 1))
    })
    
    # 0.1% chance of failure:
    test_that("my flaky test is ok", {
      skip_on_cran()
      try_again(2, expect_equal(flaky_function(), 1))
    })

  Note that it’s still good practice to skip such tests on CRAN.

• New skip_unless_r() skips tests on unsuitable versions of R. It has a convenient syntax so you can use, e.g., skip_unless_r(">= 4.1.0") to skip tests that require ...names() .

• New SlowReporter makes it easier to find the slowest tests in your package. You can run it with devtools::test(reporter = "slow").

• New vignette("challenging-functions") provides an index to other documentation organized by various challenges.

Acknowledgements

A big thank you to all the folks who helped make this release happen: @3styleJam , @afinez , @andybeet , @atheriel , @averissimo , @d-morrison , @DanChaltiel , @DanielHermosilla , @eitsupi , @EmilHvitfeldt , @emstruong , @gaborcsardi , @gael-millot , @hadley , @hoeflerb , @jamesfowkes , @jan-swissre , @jdblischak , @jennybc , @jeroenjanssens , @kevinushey , @krivit , @kubajal , @lawalter , @m-muecke , @maelle , @math-mcshane , @mcol , @metanoid , @MichaelChirico , @moodymudskipper , @njtierney , @nunotexbsd , @pabangan , @pachadotdev , @plietar , @schloerke , @schuemie , @sebkopf , @shikokuchuo , @snystrom , @stibu81 , @TimTaylor , and @tylermorganwall .

We’re delighted to announce the release of pkgdown 2.2.0. pkgdown is designed to make it quick and easy to build a beautiful and accessible website for your package.

You can install it from CRAN with:

install.packages("pkgdown")

This version of pkgdown has one major change: a new pkgdown::build_llm_docs() function that automatically creates files that make it easier for LLMs to read your documentation. Concretely, this means two things:

• You’ll get an llms.txt at the root directory of your site. llms.txt is an emerging standard that provides an easy way for an LLM to get an overview of your site. pkgdown creates an overview by combining your README, your function index, and your article index: this should give the LLM a broad overview of what your package does, along with links to find out more.

• Every existing .html on your site gets a corresponding .md file. These are generally easier for LLMs to understand because they contain just the content of the site, without any extraneous styling.

If you don’t want to generate these files, just add the following to your _pkgdown.yaml:

llm-docs: false

This release also includes new translations for Dutch and Japanese, removal of the long-deprecated autolink_html() and preview_page(), and a handful of other bug fixes and minor improvements. You can read about them all in the release notes .

Acknowledgements

As always, a big thanks to everyone who helped make this release possible: @cderv , @chabld , @Danny-dK , @davidorme , @dmurdoch , @hadley , @hfrick , @IndrajeetPatil , @jayhesselberth , @jeroenjanssens , @jmgirard , @krlmlr , @lorenzwalthert , @maelle , @MichaelChirico , @pepijn-devries , @remlapmot , @rempsyc , @Rohit-Satyam , @royfrancis , @rparmm , @schloerke , @TimTaylor , and @usrbinr .

We’re excited to announce mirai 2.5.0, bringing production-grade async computing to R!

This milestone release delivers enhanced observability through OpenTelemetry, reproducible parallel RNG, and key user interface improvements. We’ve also packed in twice as many changes as usual - going all out in delivering a round of quality-of-life fixes to make your use of mirai even smoother!

You can install it from CRAN with:

install.packages("mirai")

Introduction to mirai

mirai (Japanese for ‘future’) provides a clean, modern approach to parallel computing in R. Built on current communication technologies, it delivers extreme performance through professional-grade scheduling and an event-driven architecture.

It continues to evolve as the foundation for asynchronous and parallel computing across the R ecosystem, powering everything from async Shiny applications to parallel map in purrr to hyperparameter tuning in tidymodels.

library(mirai)

# Set up persistent background processes
daemons(4)

# Async evaluation - non-blocking
m <- mirai({
  Sys.sleep(1)
  100 + 42
})
m
#> < mirai [] >

# Results are available when ready
m[]
#> [1] 142

# Shut down persistent background processes
daemons(0)

A unique design philosophy

Modern foundation: mirai builds on nanonext , the R binding to Nanomsg Next Generation, a high-performance messaging library designed for distributed systems. This means that it’s using the very latest technologies, and supports the most optimal connections out of the box: IPC (inter-process communications), TCP or secure TLS. It also extends base R’s serialization mechanism to support custom serialization of newer cross-language data formats such as safetensors, Arrow and Polars.

Extreme performance: as a consequence of its solid technological foundation, mirai has the proven capacity to scale to millions of concurrent tasks over thousands of connections. Moreover, it delivers up to 1,000x the efficiency and responsiveness of other alternatives. A key innovation is the implementation of event-driven promises that react with zero latency - this provides an extra edge for real-time applications such as live inference or Shiny apps.

Production first: mirai provides a clear mental model for parallel computation, with a clean separation of a user’s current environment with that in which a mirai is evaluated. This explicitness and simplicity helps avoid common pitfalls that can afflict parallel processing, such as capturing incorrect or extraneous variables. Transparency and robustness are key to mirai’s design, and are achieved by minimizing complexity, and eliminating all hidden state with no reliance on options or environment variables. Finally, its integration with OpenTelemetry provides for production-grade observability.

Deploy everywhere: deployment of daemon processes is made through a consistent interface across local, remote (SSH), and HPC environments (Slurm, SGE, PBS, LSF). Compute profiles are daemons settings that are managed independently, such that you can be connected to all three resource types simultaneously. You then have the freedom to distribute workload to the most appropriate resource for any given task - especially important if tasks have differing requirements such as GPU compute.

OpenTelemetry integration

New in mirai 2.5.0: complete observability of mirai requests through OpenTelemetry traces. This is a core feature that completes the final pillar in mirai’s ‘production first’ design philosophy.

When tracing is enabled via the otel and otelsdk packages, you can monitor the entire lifecycle of your async computations, from creation through to evaluation, making it easier to debug and optimize performance in production environments. This is especially powerful when used in conjunction with other otel-enabled packages (such as an upcoming Shiny release), providing end-to-end observability across your entire application stack.

Reproducible parallel RNG

Introduced in mirai 2.4.1: reproducible parallel random number generation. Developed in consultation with our tidymodels colleagues and core members of the mlr team, this is a great example of the R community pulling together to solve a common problem. It addresses a long-standing challenge in parallel computing in R, important for reproducible science.

mirai has, since its early days, used L’Ecuyer-CMRG streams for statistically-sound parallel RNG. Streams essentially cut into the RNG’s period (a very long sequence of pseudo-random numbers) at intervals that are far apart from each other that they do not in practice overlap. This ensures that statistical results obtained from parallel computations remain correct and valid.

Previously, we only offered the following option, matching the behaviour of base R’s parallel package:

Default behaviour daemons(seed = NULL): creates independent streams for each daemon. This ensures statistical validity but not numerical reproducibility between runs.

Now, we also offer the following option:

Reproducible mode daemons(seed = integer): creates a stream for each mirai() call rather than each daemon. This guarantees identical results across runs, regardless of the number of daemons used.

# Always provides identical results:

with(
  daemons(3, seed = 1234L),
  mirai_map(1:3, rnorm, .args = list(mean = 20, sd = 2))[]
)
#> [[1]]
#> [1] 19.86409
#> 
#> [[2]]
#> [1] 19.55834 22.30159
#> 
#> [[3]]
#> [1] 20.62193 23.06144 19.61896

User interface improvements

Compute profile helper functions

with_daemons() and local_daemons() make working with compute profiles much more convenient by allowing the temporary switching of contexts. This means that developers can continue to write mirai code without worrying about the resources on which it is eventually run. End-users now have the ability to change the destination of any mirai computation dynamically using one of these scoped helpers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Work with specific compute profiles
with_daemons("gpu", {
  result <- mirai(gpu_intensive_task())
})

# Local version for use inside functions
async_gpu_intensive_task <- function() {
  local_daemons("gpu")
  mirai(gpu_intensive_task())
}

Re-designed daemons()

Creating new daemons is now more ergonomic, as it automatically resets existing ones. This provides for more convenient use in contexts such as notebooks, where cells may be run out of order. Manual daemons(0) calls are no longer required to reset daemons.

1
2
3
4
5
6

# Old approach
daemons(0)  # Had to reset first
daemons(4)

# New approach - automatic reset
daemons(4)  # Just works, resets if needed

New info() function

Provides a more succinct alternative to status() for reporting key statistics. This is optimized and is now a supported developer interface for programmatic use.

info()
#> connections  cumulative    awaiting   executing   completed 
#>           4           4           8           4           2

Acknowledgements

We extend our gratitude to the R community for their continued feedback and contributions. Special thanks to all contributors who helped shape this release through feature requests, bug reports, and code contributions: @agilly , @D3SL , @DavZim , @dipterix , @eliocamp , @erydit , @karangattu , @louisaslett , @mikkmart , @sebffischer , @shikokuchuo , and @wlandau .

Introducing nanonext: breaking down language barriers in data science

We’re excited to welcome nanonext to the r-lib family! nanonext is R’s binding to NNG (Nanomsg Next Generation), a high-performance C messaging library that implements scalability protocols for distributed systems. Because NNG has bindings and ports across multiple languages—including Python, Go, Rust, C++, and many others—nanonext enables seamless interoperability between R and other modern programming languages.

The latest version 1.7.0 brings enhanced reliability with improved HTTP client functionality, better handling of custom serialization methods, and more robust event-driven promises.

Get started by installing the package from CRAN now:

1

install.packages("nanonext")

The challenge: multi-language data science

If you’ve worked in data science, you’ve likely encountered this scenario: your workflow spans multiple programming languages. Perhaps you have Python models, R analysis scripts, Go services, or C++ performance libraries that all need to work together.

Traditionally, making these components communicate means:

• Writing data to files and reading them back
• Building REST APIs and making HTTP calls
• Handling different serialization formats like JSON or protocol buffers
• Dealing with the latency and complexity that comes with each approach

The solution: NNG’s scalability protocols

nanonext changes this by bringing NNG’s scalability protocols to R. NNG is a high-performance C library that implements standardized communication patterns like request/reply, publish/subscribe, and pipeline architectures. Any process using NNG can communicate directly with any other NNG process using the same protocol—regardless of the programming language.

This means that for simple atomic vector types, your R data doesn’t even need to be serialized and converted to a common format, enabling direct, real-time communication between processes. For more complex data types, as long as serialization and unserialization methods exist in both languages, then nanonext can be used to send and receive arbitrary binary data.

What can you do with nanonext?

nanonext opens up several powerful possibilities for R users:

🔗 Cross-language integration: Connect R directly with Python machine learning models, Go microservices, Rust compute engines, or C libraries without intermediate files or complex APIs.

⚡ Real-time data pipelines: Build data systems where different components process data as it flows, perfect for live dashboards or high-frequency analytics.

📡 Modern web integration: Create WebSocket clients, make asynchronous HTTP requests, or build real-time APIs that integrate with web services.

🚀 Asynchronous programming: Write non-blocking R code that can handle multiple operations simultaneously, improving performance for concurrent tasks.

Python ↔ R interoperability example

Here’s a concrete example of R and Python working together through NNG’s protocols. Both processes use their respective NNG bindings to establish a direct communication channel using NNG’s ‘pair’ protocol—a simple one-to-one bidirectional communication pattern.

Python side (using pynng):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import numpy as np
import pynng

# Create socket to communicate with R
socket = pynng.Pair0(listen="ipc:///tmp/nanonext.socket")

# Wait for data from R
raw = socket.recv()
array = np.frombuffer(raw)
print(array)  # [1.1 2.2 3.3 4.4 5.5]

# Process data (could be ML model prediction, transformation, etc.)
processed = array * 2  # Simple example: multiply by 2

# Send back to R as bytes
socket.send(processed.tobytes())
socket.close()

R side (using nanonext):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

library(nanonext)

# Connect to Python process
sock <- socket("pair", dial = "ipc:///tmp/nanonext.socket")

# Send numeric data directly to Python (no serialization needed!)
sock |> send(c(1.1, 2.2, 3.3, 4.4, 5.5), mode = "raw")

# Receive processed results back from Python
processed_data <- sock |> recv(mode = "double")
print(processed_data)  # [1] 2.2 4.4 6.6 8.8 11.0

# Continue with R-specific analysis
summary(processed_data)
plot(processed_data)

close(sock)

What just happened? Your R session sent numerical data directly to Python’s memory space, Python processed it (possibly performing inference on a complex ML model), and sent results back—all happening in memory without touching the disk. This is orders of magnitude faster than traditional file-based approaches.

Why this matters

Speed: Direct memory communication is dramatically faster than file I/O or HTTP requests. Your R session doesn’t wait for disk writes or network round-trips.

Simplicity: No need to design REST APIs, manage file formats, or handle serialization. Send R vectors directly and receive results back.

Flexibility: nanonext supports different communication patterns (one-to-one, one-to-many, publish/subscribe) and transport methods (IPC, TCP, WebSocket).

Reliability: Built on NNG, a mature library that powers mission-critical systems in technology, finance and many other industries.

Asynchronous: Your R session stays responsive. Send a request for a long-running computation and continue working while it processes in the background.

The future is multi-language

nanonext facilitates a shift toward more flexible, performance-oriented data science workflows. Instead of being locked into a single language or accepting the overhead of traditional integration methods, you can now build systems where each component uses the best tool for the job.

We’re excited to see how the R community uses these capabilities.

Ready to try it? Visit the package website for comprehensive documentation, or explore the code at the GitHub repository .

Positron

The Air extension is now included in Positron by default, and will automatically keep itself up to date. We’ve been working hard to ensure that Air leaves a positive first impression, and we think that having Positron come batteries included with Air really helps with that! Positron now also ships with Ruff , the extremely fast Python formatter and linter, ensuring that you have a great editing experience out of the box, no matter which language you prefer.

We’ve also streamlined the process of adding Air to a new or existing project. With dev usethis, you can now run usethis::use_air() to automatically configure recommended Air settings. In particular, this will:

• Create an empty air.toml .

• Create .vscode/settings.json filled with the following settings. This enables Format on Save within your workspace.

  1 2 3 4 5 6

  { "[r]": { "editor.formatOnSave": true, "editor.defaultFormatter": "Posit.air-vscode" } }

• Create .vscode/extensions.json filled with the following settings. This automatically prompts contributors that don’t have the Air extension to install it when they open your workspace, ensuring that everyone is using the same formatter!

  1 2 3 4 5

  { "recommendations": [ "Posit.air-vscode" ] }

• Update your .Rbuildignore to exclude Air related configuration, if you’re working on an R package.

Once you’ve used usethis to configure Air, you can now immediately reformat your entire workspace by running Air: Format Workspace Folder from the Command Palette (accessible via Cmd + Shift + P on Mac/Linux, or Ctrl + Shift + P on Windows). I’ve found that this is invaluable for adopting Air in an existing project!

To summarize, we’ve reduced our advice on adding Air to an existing project down to:

• Open Positron

• Run usethis::use_air()

• Run Air: Format Workspace Folder

• Commit, push, and then enjoy using Format on Save forevermore 😄

More editors!

Positron isn’t the only editor that’s received some love! We now have official documentation for using Air in the following editors:

• Zed

• Neovim

• Helix

We’re very proud of the fact that Air can be used within any editor, not just RStudio and Positron! This documentation was a community effort - thanks in particular to @taplasz , @PMassicotte , @m-muecke , @TymekDev , and @wurli .

Autobracing

Autobracing is the process of adding braces (i.e. { } ) to if statements, loops, and function definitions to create more consistent, readable, and portable code. It looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

for (i in seq_along(x)) x[[i]] <- x[[i]] + 1L

# Becomes:
for (i in seq_along(x)) {
  x[[i]] <- x[[i]] + 1L
}

function(x, y)
  call_that_spans_lines(
    x,
    y,
    fixed_option = FALSE
  )

# Becomes:
function(x, y) {
  call_that_spans_lines(
    x,
    y,
    fixed_option = FALSE
  )
}

It’s particularly important to autobrace multiline if statements for portability, which we roughly define as the ability to copy and paste that if statement into any context and have it still parse correctly. Consider the following if statement:

1
2
3
4
5
6

do_something <- function(this = TRUE) {
  if (this)
    do_this()
  else 
    do_that()
}

As written, this is correct R code, but if you were to pull out the if statement and place it in a file at “top level” and try to run it, you’d see a parse error:

1
2
3
4
5

if (this)
  do_this()
else 
  do_that()
#> Error: unexpected 'else'

In practice, this typically bites you when you’re debugging and you send a chunk of lines to the console:

Air autobraces this if statement to the following, which has no issues with portability:

1
2
3
4
5
6
7

do_something <- function(this = TRUE) {
  if (this) {
    do_this()
  } else {
    do_that()
  }
}

Give side effects some Air

We believe code that create side effects which modify state or affect control flow are important enough to live on their own line. For example, the following stop() call is an example of a side effect, so it moves to its own line and is autobraced:

1
2
3
4
5
6

if (anyNA(x)) stop("`x` can't contain missing values.")

# Becomes:
if (anyNA(x)) {
  stop("`x` can't contain missing values.")
}

You might be thinking, “But I like my single line if statements!” We do too! Air still allows single line if statements if they look to be used for their value rather than for their side effect. These single line if statements are still allowed:

1
2
3
4
5

x <- if (condition) this else that

x <- x %||% if (condition) this else that

list(a = if (condition) this else that)

Similarly, single line function definitions are also still allowed if they don’t already have braces and don’t exceed the line length:

1
2
3

add_one <- function(x) x + 1

bools <- map_lgl(xs, function(x) is.logical(x) && length(x) == 1L && !is.na(x))

For the full set of rules, check out our documentation on autobracing .

Empty braces

You may have noticed the following forced expansion of empty {} in previous versions of Air:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

dummy <- function() {}

# Previously became:
dummy <- function() {
}

tryCatch(fn, error = function(e) {})

# Previously became:
tryCatch(fn, error = function(e) {
})

my_fn(expr = {}, option = TRUE)

# Previously became:
my_fn(
  expr = {
  }, 
  option = TRUE
)

As of 0.7.0, empty braces {} are now never expanded, which retains the original form of each of these examples.

skip configuration

In our release post , we detailed how to disable formatting using a # fmt: skip comment for a single expression, or a # fmt: skip file comment for an entire file. Skip comments are useful for disabling formatting for one-off function calls, but sometimes you may find yourself repeatedly using functions from a domain specific language (DSL) that doesn’t follow conventional formatting rules. For example, the igraph package contains a DSL for constructing a graph from a literal representation:

1

igraph::graph_from_literal(A +-+ B +---+ C ++ D + E)

By default, Air would format this as:

1

igraph::graph_from_literal(A + -+B + ---+C + +D + E)

If you use graph_from_literal() often, it would be annoying to add # fmt: skip comments at every call site. Instead, air.toml now supports a skip field that allows you to specify function names that you never want formatting for. Specifying this would retain the original formatting of the graph_from_literal() call, even without a # fmt: skip comment:

1

skip = ["graph_from_literal"]

In the short term, you may also want to use this for tibble::tribble() calls, i.e. skip = ["tribble"]. In the long term, we’re hoping to provide more sophisticated tooling for formatting using a specified alignment .

GitHub Action

Air now has an official GitHub Action, setup-air . This action really only has one job - to get Air installed on your GitHub runner and put on the PATH. The basic usage is:

1
2

- name: Install Air
  uses: posit-dev/setup-air@v1

If you need to pin a version:

1
2
3
4

- name: Install Air 0.4.4
  uses: posit-dev/setup-air@v1
  with:
    version: "0.4.4"

From there, you can call Air’s CLI in downstream steps. A minimal workflow that errors if any files require formatting might look like:

1
2
3
4
5

- name: Install Air
  uses: posit-dev/setup-air@v1

- name: Check formatting
  run: air format . --check

Rather than creating the workflow file yourself, we instead recommend using usethis to pull in our example workflow :

1

usethis::use_github_action(url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-suggest.yaml")

This is a special workflow that runs on pull requests. It calls air format and then uses reviewdog/action-suggester to push any formatting diffs as GitHub Suggestion comments on your pull request. It looks like this:

You can accept all suggestions in a single batch, which will then rerun the format check, along with any other GitHub workflows (like an R package check), so you can feel confident that accepting the changes hasn’t broken anything.

We like this workflow because it provides an easy way for external contributors who aren’t using Air to still abide by your formatting rules. The external contributor can even accept the suggestions themselves, so by the time you look at their pull request it’s already good to go from a formatting perspective ✅!

Acknowledgements

A big thanks to the 49 users who helped make this release possible by finding bugs, discussing issues, contributing documentation, and writing code: @adisarid , @aronatkins , @ateucher , @avhz , @aymennasri , @christophe-gouel , @dkStevensNZed , @eitsupi , @ELICHOS , @fh-mthomson , @fzenoni , @gaborcsardi , @grasshoppermouse , @hadley , @idavydov , @j-dobner , @jacpete , @jeffkeller-einc , @jhk0530 , @joakimlinde , @JosephBARBIERDARNAL , @JosiahParry , @kkanden , @krlmlr , @Kupac , @kv9898 , @lcolladotor , @lulunac27a , @m-muecke , @maelle , @matanhakim , @njtierney , @novica , @ntluong95 , @philibe , @PMassicotte , @RobinKohrs , @salim-b , @sawelch-NIVA , @schochastics , @Sebastian-T-T , @stevenpav-helm , @t-kalinowski , @taplasz , @tbadams45cdm , @wurli , @xx02al , @Yunuuuu , and @yutannihilation .

(An updated version of this blog post will be available at the systemfonts webpage )

The purpose of this document is to give you a thorough overview of fonts in R. However, for this to be possible, you’ll first need a basic understanding of fonts in general. If you already have a thorough understanding of digital typography you can skip to the next section .

Digital typography

Many books could be, and have been, written about the subject of typography. This blog post is not meant to be an exhaustive deep dive into all areas of this vast subject. Rather, it is meant to give you just enough understanding of core concepts and terminology to appreciate how it all plays into using fonts in R.

Typeface or font?

There is a good chance that you, like 99% of world, use “font” as the term describing “the look” of the letters you type. You may, perhaps, have heard the term “typeface” as well and thought it synonymous. This is in fact slightly wrong, and a great deal of typography snobbery has been dealt out on that account (much like the distinction between packages and libraries in R). It is a rather inconsequential mix-up for the most part, especially because 99% of the population wouldn’t bat an eye if you use them interchangeably. However, the distinction between the two serves as a good starting point to talk about other terms in digital typography as well as the nature of font files, so let’s dive in.

When most people use the word “font” or “font family”, what they are actually describing is a typeface. A typeface is a style of lettering that forms a cohesive whole. As an example, consider the well-known “Helvetica” typeface. This name embraces many different weights (bold, normal, light) as well as slanted (italic) and upright. However, all of these variations are all as much Helvetica as the others - they are all part of the same typeface.

A font is a subset of a typeface, describing a particular variation of the typeface, i.e. the combination of weight, width, and slant that comes together to describe the specific subset of a typeface that is used. We typically give a specific combination of these features a name, like “bold” or “medium” or “italic”, which we call the font style¹. In other words, a font is a particularly style within a typeface.

Different fonts from the Avenir Next typeface

In the rest of this document we will use the terms typeface and font with the meaning described above.

Font files

Next, we need to talk about how typefaces are represented for use by computers. Font files record information on how to draw the individual glyphs (characters), but also instructions about how to draw sequences of glyphs like distance adjustments (kerning) and substitution rules (ligatures). Font files typically encode a single font but can encode a full typeface:

typefaces <- systemfonts::system_fonts()[, c("path", "index", "family", "style")]

# Full typeface in one file
typefaces[typefaces$family == "Helvetica", ]
#> # A tibble: 6 × 4
#>   path                                index family    style        
#>   <chr>                               <int> <chr>     <chr>        
#> 1 /System/Library/Fonts/Helvetica.ttc     2 Helvetica Oblique      
#> 2 /System/Library/Fonts/Helvetica.ttc     4 Helvetica Light        
#> 3 /System/Library/Fonts/Helvetica.ttc     5 Helvetica Light Oblique
#> 4 /System/Library/Fonts/Helvetica.ttc     1 Helvetica Bold         
#> 5 /System/Library/Fonts/Helvetica.ttc     3 Helvetica Bold Oblique 
#> 6 /System/Library/Fonts/Helvetica.ttc     0 Helvetica Regular

# One font per font file
typefaces[typefaces$family == "Arial", ]
#> # A tibble: 4 × 4
#>   path                                                     index family style      
#>   <chr>                                                    <int> <chr>  <chr>      
#> 1 /System/Library/Fonts/Supplemental/Arial.ttf                 0 Arial  Regular    
#> 2 /System/Library/Fonts/Supplemental/Arial Bold.ttf            0 Arial  Bold       
#> 3 /System/Library/Fonts/Supplemental/Arial Bold Italic.ttf     0 Arial  Bold Italic
#> 4 /System/Library/Fonts/Supplemental/Arial Italic.ttf          0 Arial  Italic

Here, each row is a font, with family giving the name of the typeface, and style the font style.

It took a considerable number of tries before the world managed to nail the digitial representation of fonts, leading to a proliferation of file types. As an R user, there are three formats that are particularly improtant:

• TrueType (ttf/ttc). Truetype is the baseline format that all modern formats stand on top of. It was developed by Apple in the ’80s and became popular due to its great balance between size and quality. Fonts can be encoded, either as scalable paths, or as bitmaps of various sizes, the former generally being preferred as it allows for seamless scaling and small file size at the same time.

• OpenType (otf/otc). OpenType was created by Microsoft and Adobe to improve upon TrueType. While TrueType was a great success, the number of glyphs it could contain was limited and so was its support for selecting different features during shaping . OpenType resolved these issues, so if you want access to advanced typography features you’ll need a font in OpenType format.

• Web Open Font Format (woff/woff2). TrueType and OpenType tend to create large files. Since a large percentage of the text consumed today is delivered over the internet this creates a problem. WOFF resolves this problem by acting as a compression wrapper around TrueType/OpenType to reduce file sizes while also limiting the number of advanced features provided to those relevant to web fonts. The woff2 format is basically identical to woff except it uses the more efficient brotli compression algorithm. WOFF was designed specifically to be delivered over the internet and support is still a bit limited outside of browsers.

While we have mainly talked about font files as containers for the shape of glyphs, they also carries a lot of other information needed for rendering text in a way pleasant for reading. Font level information records a lot of stylistic information about typeface/font, statistics on the number of glyphs and how many different mappings between character encodings and glyphs it contains, and overall sizing information such as the maximum descend of the font, the position of an underline relative to the baseline etc. systemfonts provdies a convenient way to access this data from R:

dplyr::glimpse(systemfonts::font_info(family = "Helvetica"))
#> Rows: 1
#> Columns: 24
#> $ path               <chr> "/System/Library/Fonts/Helvetica.ttc"
#> $ index              <int> 0
#> $ family             <chr> "Helvetica"
#> $ style              <chr> "Regular"
#> $ italic             <lgl> FALSE
#> $ bold               <lgl> FALSE
#> $ monospace          <lgl> FALSE
#> $ weight             <ord> normal
#> $ width              <ord> normal
#> $ kerning            <lgl> FALSE
#> $ color              <lgl> FALSE
#> $ scalable           <lgl> TRUE
#> $ vertical           <lgl> FALSE
#> $ n_glyphs           <int> 2252
#> $ n_sizes            <int> 0
#> $ n_charmaps         <int> 10
#> $ bbox               <list> <-11.406250, 17.343750, -5.765625, 13.453125>
#> $ max_ascend         <dbl> 9.234375
#> $ max_descend        <dbl> -2.765625
#> $ max_advance_width  <dbl> 18
#> $ max_advance_height <dbl> 12
#> $ lineheight         <dbl> 12
#> $ underline_pos      <dbl> -1.203125
#> $ underline_size     <dbl> 0.59375

Further, for each glyph there is a range of information in addition to its shape:

systemfonts::glyph_info("j", family = "Helvetica", size = 30)
#> # A tibble: 1 × 9
#>   glyph index width height x_bearing y_bearing x_advance y_advance bbox     
#>   <chr> <int> <dbl>  <dbl>     <dbl>     <dbl>     <dbl>     <dbl> <list>   
#> 1 j        77     6     27        -1        21         7         0 <dbl [4]>

These terms are more easily understood with a diagram:

The x_advance in particular is important when rendering text because it tells you how far to move to the right before rendering the next glyph (ignoring for a bit the concept of kerning)

Text shaping

The next important concept to understand is text shaping, which, in the simplest of terms, is to convert a succession of characters into a sequence of glyphs along with their locations. Important here is the distinction between characters, the things you think of as letters, and glyphs, which is what the font will draw. For example, think of the character “f”, which is often tricky to draw because the “hook” of the f can interfere with other characters. To solve this problem, many typefaces include ligatures, like “fi”, which are used for specific pairs of characaters. Ligatures are extremely important for languages like Arabic.

A few of the challenges of text shaping include kerning, bidirectional text, and font substitution. Kerning is the adjustment of distance between specific pairs of characters. For example, you can put “VM” a little closer together but “OO” needs to be a little further apart. Kerning is an integral part of all modern text rendering and you will almost solemnly notice it when it is absent (or worse, wrongly applied ).

Not every language writes text in the same direction, but regardless of your native script, you are likely to use arabic numerals which are always written left-to-right. This gives rise to the challenge of bidirectional (or bidi) text, which mixes text flowing in different directions. This imposes a whole new range of challenges!

Finally, you might request a character that a font doesn’t contain. One way to deal with this is to render a glyph representing a missing glyph, usually an empty box or a question mark. But it’s typically more useful to use the correct glyph from a different font. This is called font fallback and happens all the time for emojis, but can also happen when you suddenly change script without bothering to pick a new font. Font fallback is an imprecise science, typically relying on an operating system font that has a very large number of characters, but might look very different from your existing font.

Once you have determined the order and location of glyphs, you are still not done. Text often needs to be wrapped to fit into a specific width, it may need a specific justification, perhaps, indentation or tracking must be applied, etc. Thankfully, all of this is generally a matter of (often gnarly) math that you just have to get right. That is, all except text wrapping which should happen at the right boundaries, and may need to break up a word and inserting a hyphen etc.

Like I said, the pit of despair is bottomless…

Font handling in R

You hopefully arrive at this section with an appreciation of the horrors that goes into rendering text. If not, maybe this blog post will convince you.

Are you still here? Good.

Now that you understand the basics of what goes into handling fonts and text, we can now discuss the details of fonts in R specifically.

Fonts and text from a user perspective

The users perception of working with fonts in R is largely shaped by plots. This means using either base or grid graphics or one of the packages that have been build on top of it, like ggplot2 . While the choice of tool will affect where you specify the font to use, they generally agree on how to specify it.

From the table it is clear that in R fontfamily/family is used to describe the typeface and font/fontface/face is used to select a font from the typeface. Size settings is just a plain mess.

The major limitation in fontface (and friends) is that it takes a number, not a string, and you can only select from four options: 1: plain, 2: bold, 3: italic, and 4: bold-italic. This means, for example, that there’s no way to select Futura Condensed Extra Bold. Another limitation is that it’s not possible to specify any font variations such as using tabular numbers or stylistic ligatures.

Fonts and text from a graphics device perspective

In R, a graphics device is the part responsible for doing the rendering you request and put it on your screen or in a file. When you call png() or ragg::agg_png() you open up a graphics device that will receive all the plotting instructions from R. Both graphics devices will ultimately produce the same file type (PNG), but how they choose to handle and respond to the plotting instructions may differ (greatly). Nowhere is this difference more true than when it comes to text rendering.

After a user has made a call that renders some text, it is funneled through the graphic system (base or grid), handed off to the graphics engine, which ultimately asks the graphics device to render the text. From the perspective of the graphics device it is much the same information that the user provided which are presented to it. The text() method of the device are given an array of characters, the typeface, the size in points, and an integer denoting if the style is regular, bold, italic, or bold-italic.

This means that it is up to the graphics device to find the approprate font file (using the provided typeface and font style) and shape the text with all that that entails. This is a lot of work, which is why text is handled so inconsistently between graphics devices. Issues can range from not being able to find fonts installed on the computer, to not providing font fallback mechanisms, or even handling right-to-left text. It may also be that certain font file formats are not well supported so that e.g. color emojis are not rendered correctly.

There have been a number of efforts to resolve these problems over the years:

• extrafont: Developed by Winston Chang, extrafont sought to mainly improve the situation for the pdf() device which generally only had access to the postscript fonts that comes with R. The package allows the pdf() device to get access to TrueType fonts installed on the computer, as well as provide means for embedding the font into the PDF so that it can be opened on systems where the font is not installed. (It also provides the capabilities to the Windows png() device).

• sysfonts and showtext. These packages are developed by Yixuan Qiu and provide support for system fonts to all graphics devices, by hijacking the text() method of the graphics device to treat text as polygons or raster images. This guarantees your plots will look the same on every device, but it doesn’t do advanced text shaping, so there’s no support for ligatures or font substitution. Additionally, it produces large files with inaccessible text when used to produce pdf and svg outputs.

• systemfonts and textshaping. These packages are developed by me to provide a soup-to-nuts solution to text rendering for graphics devices. systemfonts provides access to fonts installed on the system along with font fallback mechanisms, registration of non-system fonts, reading of font files etc. textshaping builds on top of systemfonts and provides a fully modern engine for shaping text. The functionality is exposed both at the R level and at the C level, so that graphics devices can directly access to font lookup and shaping.

We will fosus on systemfonts, because it’s designed to give R a modern text rendering stack. That’s unfortunately impossible without coordination with the graphics device, which means that to use all these features you need a supported graphics device. There are currently two options:

• The ragg package provides graphics devices for rendering raster graphics in a variety of formats (PNG, JPEG, TIFF) and uses systemfonts and textshaping extensively.
• The svglite package provides a graphic device for rendering vector graphics to SVG using systemfonts and textshaping for text.

You might notice there’s currently a big hole in this workflow: PDFs. This is something we plan to work on in the future.

A systemfonts based workflow

With all that said, how do you actually use systemfonts to use custom fonts in your plots? First, you’ll need to use ragg or svglite.

Using ragg

While there is no way to unilaterally make ragg::agg_png() the default everywhere, it’s possible to get close:

• Positron: recent versions automatically use ragg for the plot pane if it’s installed.

• RStudio IDE: set “AGG” as the backend under Global Options > General > Graphics.

• ggplot2::ggsave() : ragg will be automatically used for raster output if installed.

• R Markdown and Quarto: you need to set the dev option to "ragg_png". You can either do this with code:

  1 2	#| include: false knitr::opts_chunk$set(dev = "ragg_png")

  Or in Quarto, you can set it in the yaml metadata:

  1 2 3 4 5 6 7

  --- title: "My Document" format: html knitr: opts_chunk: dev: "ragg_png" ---

If you want to use a font installed on your computer, you’re done!

grid::grid.text(
  "FUTURA 🎉",
  gp = grid::gpar(fontfamily = "Futura", fontface = 3, fontsize = 30)
)

Or, if using ggplot2

ggplot(na.omit(penguins)) +
  geom_point(aes(x = bill_len, y = body_mass, colour = species)) +
  labs(x = "Bill Length", y = "Body Mass", colour = "Species") +
  theme_minimal(base_family = "Futura")

If the results don’t look as you expect, you can use various systemfonts helpers to diagnose the problem:

systemfonts::match_fonts("Futura", weight = "bold")
#> # A tibble: 1 × 3
#>   path                                          index features  
#>   <chr>                                         <int> <list>    
#> 1 /System/Library/Fonts/Supplemental/Futura.ttc     2 <font_ftr>
systemfonts::font_fallback("🎉", family = "Futura", weight = "bold")
#>                                          path index
#> 1 /System/Library/Fonts/Apple Color Emoji.ttc     0

If you want to see all the fonts that are available for use, you can use systemfonts::system_fonts()

systemfonts::system_fonts()

#> # A tibble: 570 × 9
#>    path                                         index name  family style weight width italic monospace
#>    <chr>                                        <int> <chr> <chr>  <chr> <ord>  <ord> <lgl>  <lgl>    
#>  1 /System/Library/Fonts/Supplemental/Rockwell…     2 Rock… Rockw… Bold  bold   norm… FALSE  FALSE    
#>  2 /System/Library/Fonts/Noteworthy.ttc             0 Note… Notew… Light normal norm… FALSE  FALSE    
#>  3 /System/Library/Fonts/Supplemental/Devanaga…     1 Deva… Devan… Bold  bold   norm… FALSE  FALSE    
#>  4 /System/Library/Fonts/Supplemental/Kannada …     0 Kann… Kanna… Regu… normal norm… FALSE  FALSE    
#>  5 /System/Library/Fonts/Supplemental/Verdana …     0 Verd… Verda… Bold  bold   norm… FALSE  FALSE    
#>  6 /System/Library/Fonts/ArialHB.ttc                8 Aria… Arial… Light light  norm… FALSE  FALSE    
#>  7 /System/Library/Fonts/AppleSDGothicNeo.ttc      10 Appl… Apple… Thin  thin   norm… FALSE  FALSE    
#>  8 /System/Library/Fonts/Supplemental/DecoType…     0 Deco… DecoT… Regu… normal norm… FALSE  FALSE    
#>  9 /System/Library/Fonts/Supplemental/Trebuche…     0 Treb… Trebu… Ital… normal norm… TRUE   FALSE    
#> 10 /System/Library/Fonts/Supplemental/Khmer MN…     0 Khme… Khmer… Regu… normal norm… FALSE  FALSE    
#> # ℹ 560 more rows

Extra font styles

As we discussed above, the R interface only allows you to select between four styles: plain, italic, bold, and bold-italic. If you want to use a thin font, you have no way of communicating this wish to the device. To overcome this, systemfonts provides register_variant() which allows you to register a font with a new typeface name. For example, to use the thin font from the Avenir Next typeface you can register it as follows:

systemfonts::register_variant(
  name = "Avenir Thin",
  family = "Avenir Next",
  weight = "thin"
)

Now you can use Avenir Thin where you would otherwise specify the typeface:

grid::grid.text(
  "Thin weight is soo classy",
  gp = grid::gpar(fontfamily = "Avenir Thin", fontsize = 30)
)

register_variant() also allows you to turn on font features otherwise hidden away:

systemfonts::register_variant(
  name = "Avenir Small Caps",
  family = "Avenir Next",
  features = systemfonts::font_feature(
    letters = "small_caps"
  )
)
grid::grid.text(
  "All caps — Small caps",
  gp = grid::gpar(fontfamily = "Avenir Small Caps", fontsize = 30)
)

Fonts from other places

Historically, systemfonts primary role was to access the font installed on your computer, the system fonts. But what if you’re using a computer where you don’t have the rights to install new fonts, or you don’t want the hassle of installing a font just to use it for a single plot? That’s the problem solved by systemfonts::add_font() which makes it easy to use a font based on a path. But in many cases you don’t even need that as systemfont now scans ./fonts and ~/fonts and adds any font files it find. This means that you can put personal fonts in a fonts folder in your home directory, and project fonts in a fonts directory at the root of the project. This is a great way to ensure that specific fonts are available when you deploy some code to a server.

And you don’t even need to leave R to populate these folders. systemfonts::get_from_google_fonts() will download and install a google font in ~/fonts:

systemfonts::get_from_google_fonts("Barrio")

grid::grid.text(
  "A new font a day keeps Tufte away",
  gp = grid::gpar(fontfamily = "Barrio", fontsize = 30)
)

And if you want to make sure this code works for anyone using your code (regardless of whether or not they already have the font installed), you can use systemfonts::require_font() . If the font isn’t already installed, this function download it from one of the repositories it knows about. If it can’t find it it will either throw an error (the default) or remap the name to another font so that plotting will still succeed.

systemfonts::require_font("Rubik Distressed")
#> Trying Google Fonts... Found! Downloading font to /var/folders/l4/tvfrd0ps4dqdr2z7kvnl9xh40000gn/T//Rtmp2qw4bE

grid::grid.text(
  "There are no bad fonts\nonly bad text",
  gp = grid::gpar(fontfamily = "Rubik Distressed", fontsize = 30)
)

By default, require_font() places new fonts in a temporary folder so it doesn’t pollute your carefully curated collection of fonts.

Font embedding in SVG

Fonts work a little differently in vector formats like SVG. These formats include the raw text and only render the font when you open the file. This makes for small, accessible files with crisp text at every level of zoom. But it comes with a price: since the text is rendered when it’s opened, it relies on the font in use being available on the viewer’s computer. This obviously puts you at the mercy of their font selection, so if you want consistent outputs you’ll need to embed the font.

In SVG, you can embed fonts using an @import statement in the stylesheet, and can point to a web resource so the SVG doesn’t need to contain the entire font. systemfonts provides facilities to generate URLs for import statements and can provide them in a variety of formats:

systemfonts::fonts_as_import("Barrio")
#> [1] "https://fonts.bunny.net/css2?family=Barrio&display=swap"
systemfonts::fonts_as_import("Rubik Distressed", type = "link")
#> [1] "<link rel=\"stylesheet\" href=\"https://fonts.bunny.net/css2?family=Rubik+Distressed&display=swap\"/>"

Further, if the font is not available from an online repository, it can embed the font data directly into the URL:

substr(systemfonts::fonts_as_import("Chalkduster"), 1, 200)
#> [1] "data:text/css,@font-face%20%7B%0A%20%20font-family:%20%22Chalkduster%22;%0A%20%20src:%20url(data:font/ttf;charset=utf-8;base64,AAEAAAAMAIAAAwC4T1MvMmk8+wsAAAFIAAAAYGNtYXBJhgfNAAAEOAAACspnbHlmLDPYGwAAf"

svglite uses this feature to allow seamless font embedding with the web_fonts argument. It can take a URL as returned by fonts_as_import() or just the name of the typeface and the URL will automatically be resolved. Look at line 6 in the SVG generated below

svg <- svglite::svgstring(web_fonts = "Barrio")
grid::grid.text("Example", gp = grid::gpar(fontfamily = "Barrio"))
invisible(dev.off())
svg()
#> <?xml version='1.0' encoding='UTF-8' ?>
#> <svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='720.00pt' height='576.00pt' viewBox='0 0 720.00 576.00'>
#> <g class='svglite'>
#> <defs>
#>   <style type='text/css'><![CDATA[
#>     @import url('https://fonts.bunny.net/css2?family=Barrio&display=swap');
#>     .svglite line, .svglite polyline, .svglite polygon, .svglite path, .svglite rect, .svglite circle {
#>       fill: none;
#>       stroke: #000000;
#>       stroke-linecap: round;
#>       stroke-linejoin: round;
#>       stroke-miterlimit: 10.00;
#>     }
#>     .svglite text {
#>       white-space: pre;
#>     }
#>     .svglite g.glyphgroup path {
#>       fill: inherit;
#>       stroke: none;
#>     }
#>   ]]></style>
#> </defs>
#> <rect width='100%' height='100%' style='stroke: none; fill: #FFFFFF;'/>
#> <defs>
#>   <clipPath id='cpMC4wMHw3MjAuMDB8MC4wMHw1NzYuMDA='>
#>     <rect x='0.00' y='0.00' width='720.00' height='576.00' />
#>   </clipPath>
#> </defs>
#> <g clip-path='url(#cpMC4wMHw3MjAuMDB8MC4wMHw1NzYuMDA=)'>
#> <text x='360.00' y='292.32' text-anchor='middle' style='font-size: 12.00px; font-family: "Barrio";' textLength='48.12px' lengthAdjust='spacingAndGlyphs'>Example</text>
#> </g>
#> </g>
#> </svg>

Want more?

This document has mainly focused on how to use the fonts you desire from within R. R has other limitations when it comes to text rendering specifically how to render text that consists of a mix of fonts. This has been solved by marquee and the curious soul can continue there in order to up their skills in rendering text with R

grid::grid.draw(
  marquee::marquee_grob(
    "_This_ **is** the {.red end}",
    marquee::classic_style(base_size = 30)
  )
)

We’re excited to announce that S7 v0.2.0 is now available on CRAN! S7 is a new object-oriented programming (OOP) system designed to supersede both S3 and S4. You might wonder why R needs a new OOP system when we already have two. The reason lies in the history of R’s OOP journey: S3 is a simple and effective system for single dispatch, while S4 adds formal class definitions and multiple dispatch, but at the cost of complexity. This has forced developers to choose between the simplicity of S3 and the sophistication of S4.

The goal of S7 is to unify the OOP landscape by building on S3’s existing dispatch system and incorporating the most useful features of S4 (along with some new ones), all with a simpler syntax. S7’s design and implementation have been a collaborative effort by a working group from the R Consortium , including representatives from R-Core, Bioconductor, tidyverse/Posit, ROpenSci, and the wider R community. Since S7 builds on S3, it is fully compatible with existing S3-based code. It’s also been thoughtfully designed to work with S4, and as we learn more about the challenges of transitioning from S4 to S7, we’ll continue to add features to ease this process.

Our long-term goal is to include S7 in base R, but for now, you can install it from CRAN:

install.packages("S7")

What’s new in the second release

The second release of S7 brings refinements and bug fixes. Highlights include:

• Support for lazy property defaults, making class setup more flexible.
• Custom property setters now run on object initialization.
• Significant speed improvements for setting and getting properties with @ and @<-.
• Expanded compatibility with base S3 classes.
• convert() now provides a default method for transforming a parent class into a subclass.

Additionally, there are numerous bug fixes and quality-of-life improvements, such as better error messages, improved support for base Ops methods, and compatibility improvements for using @ in R versions prior to 4.3. You can see a full list of changes in the release notes .

Who should use S7

S7 is a great fit for R users who like to try new things but don’t need to be the first. It’s already used in several CRAN packages, and the tidyverse team is applying it in new projects. While you may still run into a few issues, many early problems have been resolved.

Usage

library(S7)

Let’s dive into the basics of S7. To learn more, check out the package vignettes, including a more detailed introduction in vignette("S7") , and coverage of generics and methods in vignette("generics-methods") , and classes and objects in vignette("classes-objects") .

Classes and objects

S7 classes have formal definitions, specified by new_class() , which includes a list of properties and an optional validator. For example, the following code creates a Range class with start and end properties, and a validator to ensure that start is always less than end:

Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double
  ),
  validator = function(self) {
    if (length(self@start) != 1) {
      "@start must be length 1"
    } else if (length(self@end) != 1) {
      "@end must be length 1"
    } else if (self@end < self@start) {
      "@end must be greater than or equal to @start"
    }
  }
)

new_class() returns the class object, which also serves as the constructor to create instances of the class:

x <- Range(start = 1, end = 10)
x
#> <Range>
#>  @ start: num 1
#>  @ end  : num 10

Properties

The data an object holds are called its properties. Use @ to get and set properties:

x@start
#> [1] 1
x@end <- 20
x
#> <Range>
#>  @ start: num 1
#>  @ end  : num 20

Properties are automatically validated against the type declared in new_class() (in this case, double) and checked by the class validator:

x@end <- "x"
#> Error: <Range>@end must be <double>, not <character>
x@end <- -1
#> Error: <Range> object is invalid:
#> - @end must be greater than or equal to @start

Generics and methods

Like S3 and S4, S7 uses functional OOP, where methods belong to generic functions, and method calls look like regular function calls: generic(object, arg2, arg3). A generic uses the types of its arguments to automatically pick the appropriate method implementation.

You can create a new generic with new_generic() , specifying the arguments to dispatch on:

inside <- new_generic("inside", "x")

To define a method for a specific class, use method(generic, class) <- implementation:

method(inside, Range) <- function(x, y) {
  y >= x@start & y <= x@end
}

inside(x, c(0, 5, 10, 15))
#> [1] FALSE  TRUE  TRUE  TRUE

Printing the generic shows its methods:

inside
#> <S7_generic> inside(x, ...) with 1 methods:
#> 1: method(inside, Range)

And you can retrieve the method for a specific class:

method(inside, Range)
#> <S7_method> method(inside, Range)
#> function (x, y) 
#> {
#>     y >= x@start & y <= x@end
#> }

Known limitations

While we are pleased with S7’s design, there are still some limitations:

• S7 objects can be serialized to disk (with saveRDS() ), but the current implementation saves the entire class specification with each object. This may change in the future.
• Support for implicit S3 classes "array" and "matrix" is still in development.

We expect the community will uncover more issues as S7 is more widely adopted. If you encounter any problems, please file an issue at https://github.com/RConsortium/OOP-WG/issues . We appreciate your feedback in helping us make S7 even better! 😃

Acknowledgements

Thank you to all people who have contributed issues, code, and comments to this release:

@calderonsamuel , @Crosita , @DavisVaughan , @dipterix , @guslipkin , @gvelasq , @hadley , @jeffkimbrel , @jl5000 , @jmbarbone , @jmiahjones , @jonthegeek , @JosiahParry , @jtlandis , @lawremi , @MarcellGranat , @mikmart , @mmaechler , @mynanshan , @rikivillalba , @sjcowtan , @t-kalinowski , @teunbrand , and @waynelapierre .

We’re delighted to announce the release of pkgdown 2.1.0. pkgdown is designed to make it quick and easy to build a beautiful and accessible website for your package.

You can install it from CRAN with:

install.packages("pkgdown")

This is a massive release with a bunch of new features. I’ll highlight the most important here, but as always, I highlight recommend skimming the release notes for other smaller improvements and bug fixes.

First, and most importantly, please join me in welcoming two new authors to pkgdown: Olivier Roy and Salim Brüggemann . They have both contributed many improvements to the package and I’m very happy to officially have them aboard as package authors.

library(pkgdown)

Lifecycle changes

Let’s get started with the important stuff, the lifecycle updates . Most important we’ve decided to deprecate support for Bootstrap 3, which was superseded in December 2021. We’re starting to more directly encourage folks to move away from it as maintaining two separate sets of site templates is a time sink. If you’re still using BS3, now’s the time to upgrade .

There are three other changes that are less likely to affect folks:

• The document argument to build_site() and build_reference() has been removed after being deprecated in pkgdown 1.4.0; use the devel argument instead.

• autolink_html() was deprecated in pkgdown 1.6.0 and now warns every time you use it; use downlit::downlit_html_path() instead.

• preview_page() has been deprecated; use preview_site() instead.

Major new features

pkgdown 2.1.0 has two major new features: support for Quarto vignettes and a new light switch that toggles between light and dark modes.

Quarto support

build_article() /build_articles() now support articles and vignettes written with Quarto. To use it, make sure you have the the latest version of Quarto, 1.5, which was released last week. By and large you should be able to just write in Quarto and things will just work, but you will need to make a small change to your GitHub action. Learn more at vignette("quarto") .

Combining the individual quarto and pkgdown templating systems is a delicate art, so while I’ve done my best to make it work, there may be some rough edges. Check out the current known limitations in vignette("quarto") , and please file an issue if you encounter a quarto feature that doesn’t work quite right.

Light switch

pkgdown sites can now provide a “light switch” that allows the reader to switch between light and dark modes (based on work in bslib by @gadenbuie ). You can try it out on https://pkgdown.r-lib.org : the light switch appears at the far right at the navbar and remembers the users choice between visits to your site.

(Note that the light switch works differently to quarto dark mode. In quarto, you can provide two completely different themes for light and dark mode. In pkgdown, dark mode is a relatively thin overlay that based on your light theme colours.)

For now, you’ll need to opt-in to the light-switch by adding the following to your _pkgdown.yml:

1
2

template
  light-switch: true

In the future we hope to turn it on automatically.

You can learn more about customising the light switch in vignette("customise") : you can choose to select your own syntax highlighting scheme for dark mode, override dark-specific BS lib variables, and move its location in the navbar.

User experience

We’ve made a bunch of small changes to enhance the user experience of pkgdown sites:

• We’ve continued in our efforts to make pkgdown sites as accessible as possible by now warning if you’ve forgotten to add alt text to images (including plots) in your articles. We’ve also added a new vignette("accessibility") which describes additional manual tasks you can perform to make your site as accessible as possible.

• build_reference() adds anchors to arguments making it possible to link directly to an argument. This is very useful when you’re trying to direct folks to the documentation for a specific argument, e.g. https://pkgdown.r-lib.org/reference/build_site.html#arg-devel .

• build_reference_index() now displays function lifecycle badges next to the function name . If you want to gather together (e.g.) all the deprecated function in one spot in the reference index, you can use the new topic selector has_lifecycle("deprecated").

• The new template.math-rendering option allows you to control how math is rendered on your site. The default uses mathml which is zero dependency but has the lowest fidelity. If you use a lot of math on your site, you can switch back to the previous method with mathjax, or try out katex, a faster alternative.

• pkgdown sites no longer depend on external content distribution networks (CDN) for common javascript, CSS, and font files. CDNs no longer provide any performance advantages and make deployment harder inside certain locked-down corporate environments.

• pkgdown includes translations for more terms including “Abstract” and “Search site”. A big thanks to @jplecavalier, @dieghernan, @krlmlr, @LDalby, @rich-iannone, @jmaspons, and @mine-cetinkaya-rundel for providing updated translations in French, Spanish, Portugese, Germna, Catalan, and Turkish!

  I’ve also written vignette("translations") , a brief vignette that discusses how translation works for non-English sites, and includes how you can create translations for new languages. (This is a great way to contribute to pkgdown if you are multi-lingual!)

Developer experience

We’ve also made a bunch of minor improvements to make improve the package developer experience:

• YAML validation has been substantially improved so you should get much clearer errors if you have made a mistake in your _pkgdown.yml. Please file an issue if you find a case where the error message is not helpful.

• The build_*() functions (apart from build_site() ) no longer automatically preview in interactive sessions since they all emit clickable links to any files that have changed. You can continue to use preview_site() to open the site in your browser.

• The build_*() functions now work better if you’re previewing just part of a site and haven’t built the whole thing. It should no longer be necessary to run init_site() in most cases, and you shouldn’t be able to get into a state where you’re told to run init_site() and then it doesn’t work.

• We give more and clearer details of the site building process including reporting on exactly what is generated by bslib, what is copied from templates, and what redirects are generated.

Acknowledgements

A big thanks to all 212 folks who contributed to this release! @Adafede , @AEBilgrau , @albertocasagrande , @alex-d13 , @AliSajid , @arkadiuszbeer , @ArneBab , @asadow , @ateucher , @avhz , @banfai , @barcaroli , @BartJanvanRossum , @bastistician , @ben18785 , @bijoychandraAU , @Bisaloo , @bkmgit , @bnprks , @brycefrank , @bschilder , @bundfussr , @cararthompson , @Carol-seven , @cbailiss , @cboettig , @cderv , @chlebowa , @chuxinyuan , @cromanpa94 , @cthombor , @d-morrison , @DanChaltiel , @DarioS , @davidchall , @DavisVaughan , @dbosak01 , @dchiu911 , @ddsjoberg , @DeepanshKhurana , @dhersz , @dieghernan , @djhocking , @dkarletsos , @dmurdoch , @dshemetov , @dsweber2 , @dvg-p4 , @DyfanJones , @ecmerkle , @eddelbuettel , @eeholmes , @eitsupi , @eliocamp , @elong0527 , @EmilHvitfeldt , @erikarasnick , @esimms999 , @espinielli , @etiennebacher , @ewenharrison , @filipsch , @FlukeAndFeather , @francoisluc , @friendly , @fweber144 , @gaborcsardi , @gadenbuie , @galachad , @gangstR , @gavinsimpson , @GeoBosh , @GFabien , @ggcostoya , @ghost , @givison , @gladkia , @glin , @gmbecker , @gravesti , @GregorDeCillia , @gregorypenn , @gsmolinski , @gsrohde , @gungorMetehan , @hadley , @harshkrishna17 , @HenrikBengtsson , @hfrick , @hrecht , @hsloot , @idavydov , @idmn , @igordot , @IndrajeetPatil , @jabenninghoff , @jack-davison , @jangorecki , @jayhesselberth , @jennybc , @jeroen , @JerryWho , @jhelvy , @jmaspons , @john-harrold , @john-ioannides , @jonasmuench , @jonnybaik , @josherrickson , @joshualerickson , @JosiahParry , @jplecavalier , @JSchoenbachler , @juliasilge , @jwimberl , @kalaschnik , @kevinushey , @klmr , @krlmlr , @LDalby , @ldecicco-USGS , @lhdjung , @LiNk-NY , @lionel- , @Liripo , @lorenzwalthert , @lschneiderbauer , @mabesa , @maelle , @maRce10 , @margotbligh , @marine-ecologist , @markfairbanks , @martinlaw , @matt-dray , @mattfidler , @matthewjnield , @MattPM , @mccarthy-m-g , @MEO265 , @merliseclyde , @MichaelChirico , @mikeblazanin , @mikeroswell , @mine-cetinkaya-rundel , @MLopez-Ibanez , @Moohan , @mpadge , @mrcaseb , @mrchypark , @ms609 , @msberends , @musvaage , @nanxstats , @nathaneastwood , @netique , @nicholascarey , @nicolerg , @olivroy , @pearsonca , @peterdesmet , @phauchamps , @przmv , @quantsch , @ramiromagno , @rcannood , @rempsyc , @rgaiacs , @rich-iannone , @rickhelmus , @rmflight , @robmoss , @royfrancis , @rsangole , @ryantibs , @salim-b , @samuel-marsh , @SebKrantz , @SESjo , @sgvignali , @spsanderson , @srfall , @stefanoborini , @stephenashton-dhsc , @strengejacke , @swsoyee , @t-kalinowski , @talgalili , @tanho63 , @tedmoorman , @telphick , @TFKentUSDA , @ThierryO , @thisisnic , @thomasp85 , @tomsing1 , @tony-aw , @trevorld , @tylerlittlefield , @uriahf , @urswilke , @ValValetl , @venpopov , @vincentvanhees , @wangq13 , @willgearty , @wviechtb , @xuyiqing , @yjunechoe , @ynsec37 , @zeehio , and @zkamvar .

You can install it from CRAN with:

install.packages("withr")

In this blog post we’ll go over the changes that made this rewrite possible, but first we’ll review the cleanup strategies made possible by withr.

You can see a full list of changes in the release notes .

Cleaning up resources with base R and with withr

Traditionally, resource cleanup in R is done with base::on.exit() . Cleaning up in the on-exit hook ensures that the cleanup happens both in the normal case, when the code has finished running without error, and in the error case, when something went wrong and execution is interrupted.

on.exit() is meant to be used inside functions but it also works within local() , which we’ll use here for our examples:

local({
  on.exit(message("Cleaning time!"))
  print(1 + 2)
})
#> [1] 3
#> Cleaning time!

local({
  on.exit(message("Cleaning time!"))
  stop("uh oh")
  print(1 + 2)
})
#> Error:
#> ! uh oh
#> Cleaning time!

on.exit() is guaranteed to run no matter what and this property makes it invaluable for resource cleaning. No more accidental littering!

However the process of cleaning up this way can be a bit verbose and feel too manual. Here is how you’d create and clean up a temporary file for instance:

local({
  my_file <- tempfile()

  file.create(my_file)
  on.exit(file.remove(my_file))

  writeLines(c("a", "b"), con = my_file)
})

Wouldn’t it be great if we could wrap this code up in a function? That’s the goal of withr’s local_-prefixed functions. They combine both the creation or modification of a resource and its (eventual) restoration to the original state into a single function:

local({
  my_file <- withr::local_tempfile()

  writeLines(c("a", "b"), con = my_file)
})

In this case we have created a resource (a file), but the same principle applies to modifying resources such as global options:

local({
  # Let's temporarily print with a single decimal place
  withr::local_options(digits = 1)
  print(1/3)
})
#> [1] 0.3

# The original option value has been restored
getOption("digits")
#> [1] 7

print(1/3)
#> [1] 0.3333333

And you can equivalently use the with_-prefixed variants (from which the package takes its name!), this way you don’t need to wrap in local() :

withr::with_options(list(digits = 1), print(1/3))
#> [1] 0.3

The with_ functions are useful for creating very small scopes for given resources, inside or outside a function.

The withr 3.0.0 rewrite

Traditionally, withr implemented its own exit event system on top of on.exit() . We needed an extra layer because of a couple of missing features:

• When multiple resources are managed by a piece of code, the order in which these resources are restored or cleaned up sometimes matter. The most consistent order for cleanup is last-in first-out (LIFO). In other words the oldest resource, on which younger resources might depend, is cleaned up last. But historically R only supported first-in first-out (FIFO) order.

• The other missing piece was being able to inspect the contents of the exit hook. The sys.on.exit() R helper was created for this purpose but was affected by a bug that prevented it from working inside functions.

We contributed two changes to R 3.5.0 that filled these missing pieces, fixing the sys.on.exit() bug and adding an after argument to on.exit() to allow last-in first-out ordering.

Until now, we haven’t been able to leverage these contributions because of our policy of supporting the current and previous four versions of R . Now that enough time has passed, it was time for a rewrite! Our version of base::on.exit() is withr::defer() . Along with better default behaviour, withr::defer() allows the clean up of resources non-locally (ironically an essential feature for implementing local_ functions). Given the changes in R 3.5.0, withr::defer() can now be implemented as a simple wrapper around on.exit() .

One benefit of the rewrite is that mixing withr tools and on.exit() in the same function now correctly interleaves cleanup:

local({
  on.exit(print(1))

  withr::defer(print(2))

  on.exit(print(3), add = TRUE, after = FALSE)

  withr::defer(print(4))

  print(5)
})
#> [1] 5
#> [1] 4
#> [1] 3
#> [1] 2
#> [1] 1

But the main benefit is increased performance. Here is how defer() compared to on.exit() in the previous version:

base <- function() on.exit(NULL)
withr <- function() defer(NULL)

# withr 2.5.2
bench::mark(base(), withr(), check = FALSE)[1:8]
#> # A tibble: 2 × 8
#>   expression      min median `itr/sec` mem_alloc `gc/sec` n_itr  n_gc
#>   <bch:expr> <bch:tm> <bch:>     <dbl> <bch:byt>    <dbl> <int> <dbl>
#> 1 base()            0   82ns  6954952.        0B    696.   9999     1
#> 2 withr()      26.2µs 27.9µs    35172.    88.4KB     52.8  9985    15

withr 3.0.0 has now caught up to on.exit() quite a bit:

# withr 3.0.0
bench::mark(base(), withr(), check = FALSE)[1:8]
#> # A tibble: 2 × 8
#>   expression      min median `itr/sec` mem_alloc `gc/sec` n_itr  n_gc
#>   <bch:expr> <bch:tm> <bch:>     <dbl> <bch:byt>    <dbl> <int> <dbl>
#> 1 base()            0   82ns  7329829.        0B       0  10000     0
#> 2 withr()      2.95µs  3.4µs   280858.        0B     225.  9992     8

Of course on.exit() is still much faster, in part because defer() supports more features (more on that below), but mostly because on.exit is a primitive function whereas defer() is implemented as a normal R function. That said, we hope that we now have made defer() (and the local_ and with_ functions that use it) sufficiently fast to be used even in performance-critical micro-tools.

Improved withr features

Over the successive releases of withr we’ve improved the behaviour of cleanup expressions interactively, in scripts executed with source() , and in knitr. on.exit() is a bit inconsistent when it is used outside of a function:

• Interactively, it doesn’t do anything.
• In source() and in knitr, it runs immediately instead of a the end of the script

withr::defer() and the withr::local_ helpers try to be more helpful for these cases.

Interactively, it saves the cleanup action in a special global hook and you get information about how to actually perform the cleanup:

file <- withr::local_tempfile()
#> Setting global deferred event(s).
#> i These will be run:
#>   * Automatically, when the R session ends.
#>   * On demand, if you call `withr::deferred_run()`.
#> i Use `withr::deferred_clear()` to clear them without executing.

# Clean up now
withr::deferred_run()
#> Ran 1/1 deferred expressions

In knitr or source() ¹, the cleanup is performed at the end of the document or of the script. If you need chunk-level cleanup, use local() as we’ve been doing in the examples of this blog post:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Cleaning up at the end of the document:

```r
document_wide_file <- withr::local_tempfile()
```

Cleaning up at the end of the chunk:

```r
local({
  local_file <- withr::local_tempfile()
})
```

Starting from withr 3.0.0, you can also run deferred_run() inside of a chunk:

1
2
3
4

```r
withr::deferred_run()
#> Ran 1/1 deferred expressions
```

Acknowledgements

Thanks to the github contributors who helped us with this release!

@ashbythorpe , @bastistician , @DavisVaughan , @fkohrt , @gaborcsardi , @gdurif , @hadley , @HenrikBengtsson , @honghaoli42 , @IndrajeetPatil , @jameslairdsmith , @jennybc , @jonkeane , @krlmlr , @lionel- , @maelle , @MichaelChirico , @MLopez-Ibanez , @moodymudskipper , @multimeric , @orichters , @pfuehrlich-pik , @solmos , @tillea , and @vanhry .

We’re well pleased to announce the release of roxygen2 7.3.0. roxygen2 allows you to write specially formatted R comments that generate R documentation files (man/*.Rd) and the NAMESPACE file. roxygen2 is used by over 13,000 CRAN packages.

You can install it from CRAN with:

install.packages("roxygen2")

There are four major improvements in this release:

• The NAMESPACE roclet now reports if you have S3 methods that are missing an @export tag. All S3 methods need to be @exported even if the generic is not. This avoids rare, but hard to debug, problems. If you think this is giving a false positive, please file an issue and suppress the warning with @exportS3Method NULL.

  I’ve also considerably revamped the documentation for S3 methods in vignette("namespace") . The docs now discuss what exporting an S3 method really means, and why it would be technically better to call it registering the method.

• Finally, the NAMESPACE roclet once again regenerates imports before loading package code and parsing roxygen blocks. This has been the goal for a long time , but we accidentally broke it when adding support for code execution in markdown blocks. This change resolves a family of problems where you somehow bork your NAMESPACE and can’t easily get fix it because you can’t re-document the package because you can’t load your package because your NAMESPACE is borked.

• @docType package now works like "_PACKAGE" , including creating a {packagename}-package alias automatically. This resolves a bug introduced in roxygen2 7.0.0 that meant that many packages lacked the correct alias for their package documentation topic.

• "_PACKAGE" does a better job of automatically generating aliases. In particular, it will no longer generate a duplicate alias if you have a function with the same name as your package (like glue::glue() or reprex::reprex() ). If you’ve previously had to hack around this bug, you can now delete any custom @aliases tags associated with the "_PACKAGE" docs.

You can see a full list of other minor improvements and bug fixes in the release notes .

Acknowledgements

A big thanks to the 46 folks who helped make this release possible through their thoughtful questions and carefully crafted code! @andrewmarx , @ashbythorpe , @ateucher , @bahadzie , @bastistician , @beginb , @brodieG , @bryanhanson , @cbielow , @daattali , @DanChaltiel , @dpprdan , @dsweber2 , @espinielli , @hadley , @hughjonesd , @jeroen , @jmbarbone , @johnbaums , @jonocarroll , @kathi-munk , @krlmlr , @kylebutts , @lionel- , @LouisLeNezet , @maelle , @MaximilianPi , @MichaelChirico , @moodymudskipper , @msberends , @multimeric , @musvaage , @neshvig10 , @olivroy , @ralmond , @RMHogervorst , @Robinlovelace , @rossellhayes , @rsbivand , @sbgraves237 , @schradj , @sebffischer , @simonpcouch , @stemangiola , @tau31 , and @trusch139 .