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.

[strengejacke]

Would it possible to ignore a function "header" from being formatted? E.g., we usually have something like:

and air should ignore that formatting.

[juliasilge]

You might check out the discussion at posit-dev/air#278 for more info on this.

[strengejacke]

Ok, thanks!

[ntluong95]

The formatted code looks weird in case_when function when the condition is long

The current code

The expected code

[DavisVaughan]

This looks correct to me. The formatter breaks lines from "the outside" working in. The formula (i.e. LHS ~ RHS) is the outermost group on that line, so it is the first thing to break. Moving the 2 onto the next line lets the line fit within the line length, so it stops there.

We actually never automatically generate formatted code like your "expected code" example. Do you see how with the rainbow indents it drastically increased the number of indents from one line to the next? In general Air will only increase or decrease the indent level by 1 between lines, which is good for both readability and accessibility

[r2evans]

I'm a little with @ntluong95 here, and I find the expected code easier for readability: it's clear that the "SDG-04" is a continuation of the c( above it. How is "accessibility" affected by the indentation? I'm not an "accessibility" person, just trying to learn how that topic plays in the discussion of layout and placement. @DavisVaughan

[strengejacke]

Would it be possible for the formatter to "fill lines" with vector elements that are not named, instead of adding new lines?

Example code:

  pattern <- c(
    "as.factor", "as.numeric", "factor", "frailty", "offset", "log1p", "log10",
    "log2", "log(log", "scale(log", "log", "lag", "diff", "lspline", "as.logical",
    "logical", "ordered", "as.ordered", "pspline", "scale(poly", "poly", "catg",
    "asis", "matrx", "pol", "strata", "strat", "scale", "scored", "interaction",
    "sqrt", "sin", "cos", "tan", "acos", "asin", "atan", "atan2", "exp", "lsp",
    "rcs", "pb", "lo", "bs", "ns", "mSpline", "bSpline", "t2", "te", "ti", "tt",
    "mmc", "mm", "mi", "mo", "gp", "s", "I", "gr", "relevel(as.factor", "relevel"
  )

Air reformats that section into:

  pattern <- c(
    "as.factor",
    "as.numeric",
    "factor",
    "frailty",
    "offset",
    "log1p",
    "log10",
    "log2",
    "log(log",
    "scale(log",
    "log",
    "lag",
    "diff",
    "lspline",
    "as.logical",
    "logical",
    "ordered",
    "as.ordered",
    "pspline",
    "scale(poly",
    "poly",
    "catg",
    "asis",
    "matrx",
    "pol",
    "strata",
    "strat",
    "scale",
    "scored",
    "interaction",
    "sqrt",
    "sin",
    "cos",
    "tan",
    "acos",
    "asin",
    "atan",
    "atan2",
    "exp",
    "lsp",
    "rcs",
    "pb",
    "lo",
    "bs",
    "ns",
    "mSpline",
    "bSpline",
    "t2",
    "te",
    "ti",
    "tt",
    "mmc",
    "mm",
    "mi",
    "mo",
    "gp",
    "s",
    "I",
    "gr",
    "relevel(as.factor",
    "relevel"
  )

My proposal would be that if the vector / elements do not contain multiple information (likes names, a named vector / list), it's ok to not add a linebreak after each element, but only at the end of a line. This makes the code really hard to read, because I cannot see the context of that code chunk without scrolling back and forth.

If there are good reasons to not implement this, I would really love to see an ignore option as for the styler package, like:

  ## Air: off
  pattern <- c(
    "as.factor", "as.numeric", "factor", "frailty", "offset", "log1p", "log10",
    "log2", "log(log", "scale(log", "log", "lag", "diff", "lspline", "as.logical",
    "logical", "ordered", "as.ordered", "pspline", "scale(poly", "poly", "catg",
    "asis", "matrx", "pol", "strata", "strat", "scale", "scored", "interaction",
    "sqrt", "sin", "cos", "tan", "acos", "asin", "atan", "atan2", "exp", "lsp",
    "rcs", "pb", "lo", "bs", "ns", "mSpline", "bSpline", "t2", "te", "ti", "tt",
    "mmc", "mm", "mi", "mo", "gp", "s", "I", "gr", "relevel(as.factor", "relevel"
  )
  ## Air: on

Else, formatting on save or automatic formatting is more or less "harmful", because it makes certain parts of the code worse in terms of readability.

[strengejacke]

The logic would be that it is easy / natural / clear to read something like c(1, 2, 4), so no line break needed, while for c('test' = 1, 'new name' = 2, 'last name' = 4), it might be easier to read when these named elements are put into a new line.

Having a line break after each element like in the example above, has no benefit over putting everything into one line - you either need to scroll down/up, or left/right - except that in the first case, you do not see the other "context" code on your screen (i.e. the code lines before and after that formatted section)-

[juliasilge]

You may want to chime in on posit-dev/air#103 about the formatting for vectors.

For skipping certain lines, check out the documentation at https://posit-dev.github.io/air/formatter.html#disabling-formatting

[strengejacke]

Ok, how did I miss the feature to skip formatting nodes? I think this was already mentioned in another issues I read...

And thanks for the pointer to the discussion for formatting vectors. I think the last answer from @lionel- summarizes what I had in mind quite well.

[natehall329]

I've been using this for about a week now, and so far so great, thanks for working on this!

One quick q: is it possible to have Air respect block indentation? I've been using bannerCommenter package for a couple years and try to nest code chunks so i can collapse the chunk when i don't need to see it. Currently when I indent a section and save, Air removes the extra indent and then i cant fold my sections.

FWIW: I'm willing to change the formatting of my section headers to get this behavior working right (though I'm partial to open_box in bannerCommenter).

Example (no indentation, no folding. Saves revert back to this format):

Desired Behavior (don't overwrite on save!):

[juliasilge]

Have you tried out using some of the "skip" functionality? This may not get you where you want to be, because it basically just says not to format a bit of code at all. If that doesn't work for you, you might want to open an issue on the air repo with more details of what you are doing trying to do:
https://github.com/posit-dev/air/issues

[natehall329]

I used it a bit and not quite what im looking for but i can somewhat get the desired behavior if i chunk the entire code block in {}

. Since this is more minor on my end, I'm satisfied with this but I'm happy to open an issue if you think there's a desire to implement some sort of hierarchical indenting!

[DavisVaughan]

@natehall329 I do think this precise feature is probably out of scope for Air

But in the future we will allow you to write something like

## MF1: Base ----

mf1_base <- code(
)

## Next header ----

(i.e. without the indentation)

And then collapse all code between ## MF1: Base ---- and ## Next header ----, but you'll have to use whatever the "blessed" convention is for code collapsing.

I'm not even sure where the code collapsing for ##---- is coming from right now!

[natehall329]

Thanks for clarifying @DavisVaughan, I think it'd be a great addition! I get that the heirarchical indenting might be a long-shot for Air... the flip side of my note is that i'm still refining my internal threshold for encapsulating more complex procedures, so the solution you suggested could have the positive side-effect of nudging us plebeians towards being succinct :)

[r2evans]

This article opens with "a new formatter for R" which suggests that there is a legacy, default, or some other kind of formatter already present. If so, is there a comparison of Air with the current/legacy formatter?

[juliasilge]

You may be interested in this announcement blog post: https://www.tidyverse.org/blog/2025/02/air/

[r2evans]

the comparison with styler is what I was looking for, thank you @juliasilge

[lijiaqi-github]

I met a problem in use. I am not sure if I missed something.
For example, I want to format a long code.

dtnfp.model <- cph(Surv(dm_py, diabetes) ~ AGE + SEX + SEX + SEX + SEX + SEX + SEX + SEX  + SEX  + SEX  + SEX  + SEX  + SEX  + SEX ,
  data = dt,
  x = TRUE,
  y = TRUE
)

After saving and formatting, it becomes like this.

In the model variables, the spaces for age and sex are not aligned.

I want to align them. But when I manually align them and save, they return to this state.

Is this misalignment a normal behavior?

[lionel-]

yep this is expected behaviour. The code you mention is of the same form as:

foo <-
  bar %>%
    baz() %>%
    qux()

[grasshoppermouse]

I'm not sure I follow. In pipes, the order of elements is critical, but in the RHS of many (most?) formulas, the order is arbitrary, so all elements are equivalent. (I have the same issue)

[lijiaqi-github]

Hi, @grasshoppermouse. Yes, I also think they should be equivalent. Even if I take out the formulas separately, the first one does not align with the following ones. I imagine that formulas should be different from functions and have no hierarchical relationship.

[lionel-]

Follow-up at posit-dev/air#336 (comment), you're totally right! We missed something in our initial assessment.

[lijiaqi-github]

Also, when I formatted in RStudio before, I selected the code and used the shortcut key (ctrl + shift + a) to format.

In Position, it seems that I can't format after selecting it. Instead, I put the cursor near the code, press the shortcut key and I can format the code.

I'm not missing RStudio. Both methods are good. I'm not sure if I set it wrong. So I want to confirm my understanding. Is this a normal behavior?

In addition, I have a very personal habit. I will align the equal signs of a group of codes, so that I can see the values ​​of each setting at a glance.
like this：

But after saving, the space before the equal sign will be forced to be reduced.

I want to ask if this can be avoided. I guess it is unlikely, this is a very personal habit of mine. I just want to ask if there is such a setting. It doesn't matter if there is not.

[lionel-]

The alignment of = is indeed on purpose.

Positron has a "Format selection" command. I believe the default keybinding is Cmd+K Cmd+F (or Crtl instead of Cmd on Windows).