styler 1.4.0

I am happy to announce that styler 1.4.0 is available on CRAN. Since the last release over a year ago, styler was improved in various ways.

Dry and quiet runs

You can run styler without modifying any files with the dry mode enabled. When "on", the styling is performed without writing back, when "fail", it will return an error if any file does not correspond to the style guide applied:

style_file("/path/to/file", dry = "fail")

To programmatically process the result, you can continue to use the invisible return value of the styler functions.

On a related note, you can now also silence the communication of styler with the R option styler.quiet.

Changes to the Addin

Styler now detects if the code you are styling is indented, and if so, preserves it. That is most useful when you want to style some parts of a function body of if statement, but not all of it (e.g. because you don’t want to introduce convoluted style changes). Let’s see this in action:

This feature is also available in the style_*() functions via the argument base_indention.

The environment variable save_after_styling is deprecated in favor of the R option styler.save_after_styling to control if a file is saved after styling with the RStudio Addin. Note than in RStudio >= 1.3.0, you can auto-save edits in general (Code -> Saving -> Auto-Save), e.g. on idle editor or focus loss, so this feature becomes less relevant

Documentation overhaul

We refactored the README into different vignettes and reviewed existing documentation to better reflect changes since the initial CRAN release of styler back in 2017. We now also have a dedicated Get Started vignette. Have a look: https://styler.r-lib.org.

More granular scope specification

Before this release, it was impossible to include more invasive levels in the styling scope while excluding less invasive levels. E.g. to style tokens, you had to style spaces, indention and line breaks as well. This is no longer needed, since you can provide the individual levels for scope with I():

styler::style_text("a=3", scope = I("tokens"))
a[32m<-[39m[34m3[39m

To use multiple scopes, do something like I(c('tokens', 'indention')).

Speed improvements

styler now uses the experimental touchstone package to monitor how performance on typical styling changes with every pull request. This helped us to improve performance for unseen code by ~15% for typical expressions (this is a net improvement factoring in the slow-down caused by other changes), and even more for simple and cached expressions.

roxygen2 code examples

We have added support for the experimental @exampleIf tag from roxygen2. This required us to fix two minor other issues: styler no longer squashes multiple @examples sections and does not move code that is on the same line as @examples to the next line.

Blank lines

styler now removes blank lines more aggressively, e.g. in assignments and pipes as well as function calls. In the latter, comments preserve existing blank lines.

styler::style_text(
  "x <-

  call(
    x =2,
    y = 444,


    # in function calls:
    # comments keep spacing above and below

    zzjk = 2
  ) %>%

  d()
  "
)

This release also contains bug-fixes, some changes for developers of style guides and internal changes. You can see all changes in the Changelog. Thanks to all the people who made this release possible, in particular:

@assignUser, @ColmanHumphrey, @davidchall, @espinielli, @giko45, @hadley, @IndrajeetPatil, @intiben, @jamespeapen, @jthomasmock, @Kalaschnik, @kevinushey, @krlmlr, @lcolladotor, @lorenzha, @MichaelChirico, @michaelquinn32, @mine-cetinkaya-rundel, @pat-s, @PMassicotte, @QuLogic, @renkun-ken, @RichardJActon, @seed-of-apricot, @select-id-from-users, @SimonDedman, @stefanoborini, @swsoyee, and @Winterstorm-j.