An introduction to styler

This is an old vignette superseded by Get started. It might be outdated and is not yet deleted to avoid HTTP 404 errors until re-directs are implemented in pkgdown: https://github.com/r-lib/pkgdown/issues/1259

Entry-points

styler provides the following API to format code:

style_file() styles .R, .Rmd .Rnw and .Rprofile files.
style_dir() styles all .R and/or .Rmd files in a directory.
style_pkg() styles the source files of an R package.
RStudio Addins for styling the active file, styling the current package and styling the highlighted selection, see help("styler_addins").

Beyond that, styler can be used through other tools documented in the vignette("third-party-integrations").

Passing arguments to the style guide

styler separates the abstract definition of a style guide from the application of it. That’s why you must supply a style guide via transformers when styling (in case you don’t want to rely on the defaults):

library(styler)
style_text("a + b", transformers = tidyverse_style(scope = "indention"))

a  [32m+ [39m b

The styler API was designed so that you can pass arguments to the style guide via the styling function (e.g. style_file()) to allow more concise syntax:

# equivalent
style_text("a + b", transformers = tidyverse_style(scope = "indention"))
style_text("a + b", scope = "indention")

The magic is possible thanks to .... See style_text() for details.

Invasiveness

`scope`: What to style?

This argument of tidyverse_style() determines the invasiveness of styling. The following levels for scope are available (in increasing order):

“none”: Performs no transformation at all.
“spaces”: Manipulates spacing between token on the same line.
“indention”: Manipulates the indention, i.e. number of spaces at the beginning of each line.
“line_breaks”: Manipulates line breaks between tokens.
“tokens”: manipulates tokens.

There are two ways to specify the scope of styling.

As a string: In this case all less invasive scope levels are implied, e.g. "line_breaks" includes "indention", "spaces". This is brief and what most users need. This is supported in styler >= 1.0.0.
As vector of class AsIs: Each level has to be listed explicitly by wrapping one ore more levels of the scope in I(). This offers more granular control at the expense of more verbosity. This is supported in styler > 1.3.2.

# tokens and everything less invasive
style_text("a=2", scope = "tokens")

a  [32m<- [39m  [34m2 [39m

# just tokens and indention
style_text("a=2", scope = I(c("tokens", "indention")))

a [32m<- [39m [34m2 [39m

As you can see from the output, the assignment operator = is replaced with <- in both cases, but spacing remained unchanged in the second example.

How `strict` do you want styler to be?

Another option that is helpful to determine the level of ‘invasiveness’ is strict (defaulting to TRUE). Some rules won’t be applied so strictly with strict = FALSE, assuming you deliberately formatted things the way they are. Please see in vignette("strict"). For styler >= 1.2 alignment in function calls is detected and preserved so you don’t need strict = FALSE, e.g.

style_text(
  "tibble::tibble(
     small  = 2 ,
     medium = 4,#comment without space
     large  = 6
   )"
)

tibble:: [36mtibble [39m [33m( [39m
  small  =  [34m2 [39m,
  medium =  [34m4 [39m,  [38;5;247m [3m# comment without space [23m [39m
  large  =  [34m6 [39m
 [33m) [39m

The details are in vignette("detect-alignment").

Ignoring certain lines

You can tell styler to ignore some lines if you want to keep current formatting. You can mark whole blocks or inline expressions with styler: on and styler: off:

styler::style_text(
  "
  #> blocks
  blibala= 3
  # styler: off
  I_have(good+reasons, to = turn_off,
    styler
  )
  # styler: on
  1+1

  #> inline
  ignore( this) # styler: off
  f( ) # not ignored anymore
"
)


 [38;5;247m [3m#> blocks [23m [39m
blibala  [32m<- [39m  [34m3 [39m
   [38;5;247m [3m# styler: off [23m [39m
   [36mI_have [39m [33m( [39mgood [32m+ [39mreasons, to = turn_off,
    styler
   [33m) [39m
 [38;5;247m [3m# styler: on [23m [39m
 [34m1 [39m  [32m+ [39m  [34m1 [39m

 [38;5;247m [3m#> inline [23m [39m
   [36mignore [39m [33m( [39m this [33m) [39m  [38;5;247m [3m# styler: off [23m [39m
 [36mf [39m [33m( [39m [33m) [39m  [38;5;247m [3m# not ignored anymore [23m [39m

You can also use custom markers as described in help("stylerignore", package = "styler"). As described above and in vignette("detect-alignment"), some alignment is recognized and hence, stylerignore should not be necessary in that context.

Caching

styler is rather slow, so leveraging a cache for styled code brings big speedups in many situations. Starting with version 1.3.0, you can benefit from it. For people using styler interactively (e.g. in RStudio), typing styler::cache_info() and then confirming the creation of a permanent cache is sufficient. Please refer to help("caching") for more information. The cache is by default dependent on the version of styler which means if you upgrade, the cache will be re-built. Also, the cache takes literally 0 disk space because only the hash of styled code is stored.

Dry mode

As of version 1.3.2, styler has a dry mode which avoids writing output to the file(s) you want to format. The following options are available:

off (default): Write back to the file if applying styling changes the input.
on: Applies styling and returns the results without writing changes (if any) back to the file(s).
fail: returns an error if the result of styling is not identical to the input.

In any case, you can use the (invisible) return value of style_file() and friends to learn how files were changed (or would have changed):

out <- withr::with_tempfile(
  "code.R",
  {
    writeLines("1+1", "code.R")
    style_file("code.R", dry = "on")
  }
)

Styling  1  files:
 code.R ℹ 
────────────────────────────────────────
Status  Count   Legend 
✔   0   File unchanged.
ℹ   1   File changed.
✖   0   Styling threw an error.
────────────────────────────────────────
Please review the changes carefully!

out

 [38;5;246m# A tibble: 1 × 2 [39m
  file   changed
   [3m [38;5;246m<chr> [39m [23m   [3m [38;5;246m<lgl> [39m [23m  
 [38;5;250m1 [39m code.R TRUE

More configuration options

Roxygen code example styling

This is enabled by default, you can turn it off with include_roxygen_examples = FALSE.

Custom math token spacing

styler can identify and handle unary operators and other math tokens:

# Before
1++1-1-1/2

# After
1 + +1 - 1 - 1 / 2

This is tidyverse style. However, styler offers very granular control for math token spacing. Assuming you like spacing around + and -, but not around / and * and ^, do the following:

style_text(
  "1++1/2*2^2",
  math_token_spacing = specify_math_token_spacing(zero = c("'/'", "'*'", "'^'"))
)

 [34m1 [39m  [32m+ [39m  [32m+ [39m [34m1 [39m [32m/ [39m [34m2 [39m [32m* [39m [34m2 [39m [32m^ [39m [34m2 [39m

Custom indention

If you, say, don’t want comments starting with ### to be indented and indention to be 4 instead of two spaces, you can formulate an unindention rule and set indent_by to 4:

style_text(
  c(
    "a <- function() {",
    "### not to be indented",
    "# indent normally",
    "33",
    "}"
  ),
  reindention = specify_reindention(regex_pattern = "###", indention = 0),
  indent_by = 4
)

a  [32m<- [39m  [31mfunction [39m [33m( [39m [33m) [39m  [33m{ [39m
 [38;5;247m [3m### not to be indented [23m [39m
     [38;5;247m [3m# indent normally [23m [39m
     [34m33 [39m
 [33m} [39m

Custom style guides

These verse some (not all) configurations exposed in style_file() and friends as well as tidyverse_style(). If the above did not give you the flexibility you hoped for, your can create your own style guide and customize styler even further, as described in vignette("customizing_styler").