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:

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"))
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
a + 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"))
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
style_text("a + b", scope = "indention")
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.

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):

There are two ways to specify the scope of styling.

# tokens and everything less invasive
style_text("a=2", scope = "tokens")
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
a <- 2
# just tokens and indention
style_text("a=2", scope = I(c("tokens", "indention")))
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
a<-2

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
   )"
)
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
tibble::tibble(
  small  = 2,
  medium = 4, # comment without space
  large  = 6
)

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
"
)
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.

#> 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

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:

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.
x   0   Styling threw an error.
────────────────────────────────────────
Please review the changes carefully!
out
# A tibble: 1 × 2
  file   changed
  <chr>  <lgl>  
1 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("'/'", "'*'", "'^'"))
)
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
1 + +1/2*2^2

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
)
Warning: Could not use colored = TRUE, as the package prettycode is not
installed. Please install it if you want to see colored output or see `?
print.vertical` for more information.
a <- function() {
### not to be indented
    # indent normally
    33
}

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").