Introducing Air, a new formatter for R!

[lionel-]

The Ark team has been working hard on a new formatter for R code called Air. While still experimental, Air is now ready for testing from a larger audience. We'd be thrilled for you to try it!

Air is first and foremost a formatter of R code. On this page, you'll find details about what a formatter is, why you'd want to use one, and you'll learn about how Air makes decisions on how to format your R code.

You can find Air at https://github.com/posit-dev/air. It also has a website: https://posit-dev.github.io/air/

Installation

Air is not included in Positron yet but you can easily install it from Positron as an extension. Copy and paste positron:extension/Posit.air-vscode in the address bar of your web browser and type Enter to open the Air extension page in Positron. You can also look for it in the extensions pane in Positron:

In the extension page you'll find an Install button that you can click to install it in Positron:

Note that Air is currently only available for Mac and Windows. Linux support is coming!

Configuring and running Air

The most convenient way to run a formatter is when you save a file. This is not typically enabled by default so you will need to enable it manually in your settings. In Positron, the relevant setting is called "Format on save". It is generally recommended to enable this feature on a language basis. The easiest way to do that is to open your settings and search for:

 @lang:r format on save

The @lang:r prefix will filter out the global settings, allowing you to configure settings for the R language. Make sure the "Editor: Format on Save" checkbox is ticked.

Once enabled, your code will be reformatted every time you save! This prevents your code from ever diverging from the standards set by Air.

Another way of running the formatter is when you paste code. This is enabled by the setting "Format on paste" which should typically be set on a language basis as well. It's off by default, so if you'd like to try that formatting on paste with Air you'll need to enable it just like you did with "Format on Save".

Finally, Air also provides a CLI tool. See this help page for installation instructions. The command line tool makes it easy to reformat whole directories such as an R project or package. If you're incorporating Air into an existing project, you may want to use the CLI tool to run air format once on the entire project, commit those results, and then rely on per-file format on save from there on out.

Note that in all of these cases, the formatter will only run if your code is grammatically correct. If the formatter is seemingly no longer working, check your code for any syntax error.

What's a formatter?

A formatter is in charge of the layout of your R code. Formatters do not change the meaning of code; instead they ensure that whitespace, newlines, and other punctuation conform to a set of rules and standards, such as:

• Making sure your code is indented with the appropriate amount of leading whitespace depending on the context. By default, Air uses an indentation of 2 spaces. You will see this indentation in pipelines:

  data |>
    ggplot(aes(x, y)) +
    geom_point()

  As well as expanded (i.e. vertically laid out) function calls:

  list(
    foo = 1,
    bar = 2
  )

• Preventing your code from overflowing a given line width. By default, we use a line width of 80 characters. It does so by splitting lines of code that have become too long over multiple lines. For instance, let's say that we've set the line width to be extremely small and these expressions would overflow:

  data |> select(foo)
  
  foo <- function(bar = 1, baz = 2) {
    list(bar, baz)
  }

  To respect the very small line width, Air would switch these expressions from a horizontal layout (called "flat") to a vertical one (called "expanded"):

  data |>
    select(foo)
  
  foo <- function(
    bar = 1,
    baz = 2
  ) {
    list(
      bar,
      baz
    )
  }

• Standardizing the whitespace around code elements. Have you ever had difficulties deciphering very dense code?

  1+2:3*(4/5)

  Air reformats this expression to:

  1 + 2:3 * (4 / 5)

In general, a formatter takes over the whitespace in your code and moves elements around to respect style conventions and maximize readability.

How does a formatter help your workflow?

By using a formatter it might seem like you're rescinding control over the layout of your code. And indeed you are!
However, putting Air in charge of styling your code has substantial advantages.

First, it automatically forces you to write legible code that is neither too wide nor too narrow, with proper breathing room around syntactic elements. Having a formatter as a companion significantly improves the process of writing code as you no longer have to think about style as much - the formatter does that for you!

Second, it reduces friction when working in a team. By agreeing to use a formatter in a project, collaborators no longer have to discuss styling and layout issues. Code sent to you by a colleague will adhere to the standards that you're used to. Code review no longer has to be about style nitpicks and can focus on the substance of the changes instead.

How does Air decide how to format your code?

Air tries to strike a balance between enforcing rigid rules and allowing authors some control over the layout. Our main source of styling rules is the Tidyverse style guide, but we occasionally deviate from these.

There is a trend among modern formatters of being opinionated. Air certainly fits this trend and provides very few configuration options, mostly the indent style (spaces versus tabs), the indent width, and the line width. However, Air also puts code authors in charge of certain aspects of the layout through the notion of persistent line breaks.

In general, Air is in control of deciding where to put vertical space (line breaks) in your code. For instance if you write:

list(foo,
bar)

Air will figure out that this expression fits on a single line without exceeding the line width. It will discard the line break and reformat to:

list(foo, bar)

However there are very specific places at which you can enforce a line break, i.e. make it persistent.

• Before the very first argument in a function call. This:

  list(
  foo, bar)

  gets formatted as:

  list(
    foo,
    bar
  )

• Before the very first right-hand side expression in a pipeline. This:

  data |>
  select(foo) |> filter(!bar)

  gets formatted as:

  data |>
    select(foo) |>
    filter(!bar)

A persistent line break will never be removed by Air. But you can remove it manually. Taking the last example, if you join the first lines like this:

list(foo,
  bar
)

1 + 2 +
  3

Air will recognize that you've removed the persistent line break, and reformat as:

list(foo, bar)

1 + 2 + 3

The goal of this feature is to strike a balance between being opinionated and recognizing that users often know when taking up more vertical space results in more readable output.

[wurli]

This is awesome 🤩 Out of the box the formatting feels pretty much exactly how I'd want my code to be styled anyway, so I'll definitely be integrating Air into my workflow.

The README says Air is also an LSP server. I've not dug into the code – I'm guessing this only provides capabilities related to formatting while stuff like go to definition etc will stay with Ark's LSP?

[lionel-]

In the longer term we plan for the Ark LSP features to migrate to Air. This will make it easy to integrate the LSP in other editors as Air is completely independent of running R sessions (but will optionally communicate with an R session running in Ark to enable more dynamic features).

[wurli]

Aha makes sense! Ark and Air have already improved my life quite a bit so looking forward to seeing how the two projects continue to develop/mature :)

[ntluong95]

Is this intended that the vector in c() will spread multiple lines/ @lionel- What if we have a vector with 100 elements or more? Can we configure this behavior?

[DavisVaughan]

It is intended. There are really only 2 main forms for function calls, flat and expanded.

# flat, if it fits in the line length
c("Ethiopia", "Uganda", "Rwanda")

# expanded, if it doesn't fit
c(
  "Ethiopia", 
  "Uganda", 
  "Rwanda"
)

We believe this provides the most readable output, along with the most predictable formatter results. It also minimizes git diffs when you need to add to or remove from this list.

What if we have a vector with 100 elements or more?

It would still be fully expanded. In that case I'd probably have a separate variable named country_levels defined in my script somewhere, and I'd just let it be fully expanded, or I'd put it in another file and source it in.

There is currently no configuration for this. We believe the benefits of only having two automatic forms greatly outweigh the added complexity of doing something more complex. However, we are toying with the idea of allowing for explicit "formatter behavior comments" sort of like this

# air format: fill
c(
  "Ethiopia", "Uganda", 
  "Rwanda", "etc"
)

But that would be opt in, never automatic, and would likely only be allowed on top level expressions.

[ntluong95]

Can we have a configuration for the number of elements of a vector to be shown per line? Because I dont want to stretch my code too much

[DavisVaughan]

We do not plan to offer a configuration option for this.

The formatters black, ruff, prettier, and biome have all shown that minimally configurable formatters can be wildly successful, and having everyone's code look consistent and predictable ends up being more valuable for teams and for the developers of the formatter itself.