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.

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

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

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