Non-Invasive Pretty Printing of R Code

Pretty-prints R code without changing the user's formatting intent.


The goal of styler is to provide non-invasive pretty-printing of R source code while adhering to the tidyverse formatting rules. styler can be customized to format code according to other style guides too.

Installation

You can install the package from CRAN:

install.packages("styler") 

Or get the development version from GitHub:

# install.packages("remotes") 
remotes::install_github("r-lib/styler") 

API

You can style a simple character vector of code with style_text():

library("styler")
ugly_code <- "a=function( x){1+1}           "
style_text(ugly_code)
#> a <- function(x) {
#>   1 + 1
#> }

There are a few variants of style_text():

  • style_file() styles .R and/or .Rmd 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 code region.

Functionality of styler

scope

You can decide on the level of invasiveness with the scope argument. You can style:

  • just spaces.
  • spaces and indention.
  • spaces, indention and line breaks.
  • spaces, indention, line breaks and tokens.
ugly_code <- "a=function( x){1+1}           "
style_text(ugly_code, scope = "spaces")
#> a = function(x) {1 + 1}

Note that compared to the default used above scope = "tokens":

  • no line breaks were added.
  • <- was not replaced with =.

While spaces still got styled (around = in (x)).

strict

If you wish to keep alignment as is, you can use strict = FALSE:

style_text(
  c(
    "first  <- 4", 
    "second <- 1+1"
  ),
  strict = FALSE 
#> first  <- 4
#> second <- 1 + 1

This was just the tip of the iceberg. Learn more about customization with the tidyverse style guide in in this vignette. If this is not flexible enough for you, you can implement your own style guide, as explained in the corresponding vignette.

Adaption of styler

styler functionality is made available through other packages, most notably

  • usethis::use_tidy_style() styles your project according to the tidyverse style guide.
  • reprex::reprex(style = TRUE) to prettify reprex code before printing. To permanently use style = TRUE without specifying it every time, you can add the following line to your .Rprofile (via usethis::edit_r_profile()): options(reprex.styler = TRUE).
  • you can pretty-print your R code in RMarkdown reports without having styler modifying the source. This feature is implemented as a code chunk option in knitr. use tidy = "styler" in the header of a code chunks (e.g. ```{r name-of-the-chunk, tidy = "styler"}), or knitr::opts_chunk$set(tidy = "styler") at the top of your RMarkdown script.
  • pretty-printing of drake workflow data frames with drake::drake_plan_source().

Further resources

  • The official web documentation of styler, containing various vignettes function documentation as well as a change-log.
  • Blog post about how you can customize styler without being an expert.
  • A tidyverse.org blog post introducing the functionality of styler.
  • The wiki of Google Summer of Code 2017 or the pkgdown page contain information related to the initial development phase during Google Summer of Code 2017.

News

styler 1.1.0

This release introduces new features and is fully backward-compatible. It also adapts to changes in the R parser committed into R devel (#419).

Major Changes

  • styler can now style roxygen code examples in the source code of package (#332) as well as Rnw files (#431).
  • the print method for the output of style_text() (print.vertical()) now returns syntax-highlighted code by default, controllable via the option styler.colored_print.vertical (#417).
  • the README was redesigned (#413).
  • semi-colon expression that contained multiple assignments was fixed(#404).

Minor Changes

  • cursor position is remembered for styling via Addin (#416).
  • adapt spacing around tilde for multi-token expressions(#424) and brace edge case (#425).
  • only add brackets to piped function call if RHS is a symbol (#422).
  • increase coverage again to over 90% (#412).
  • move rule that turns single quotes into double quotes to token modifier in `tidyverse_style_guide() (#406).
  • remove line-breaks before commas (#405).
  • removed package dependency enc in favour of xfun (#442).

Thanks to all contributors for patches, issues and the like: @jonmcalder, @krlmlr, @IndrajeetPatil, @kalibera, @Hasnep, @kiranmaiganji, @dirkschumacher, @ClaytonJY, @wlandau, @maurolepore,

styler 1.0.2

This is a maintenance release without any breaking API changes.

Major Changes

  • Fixed indention for named multi-line function calls (#372).
  • Non-R code chunks in .Rmd files are now respected and won't get styled (#386).

Minor Changes

  • Fixing an edge case in which, if very long strings were present in the code, tokens could be replaced with wrong text (#384).
  • Spacing around tilde in formulas depends now on whether there is a LHS in the formula (#379).
  • Spaces are now also added around EQ_SUB (=) (#380).
  • Added CONTRIBUTING.md to outline guidelines for contributing to styler.
  • More informative error messages for parsing problems (#401, #400).
  • Improved documentation (#387).

Thanks to all contributors for patches, issues and the like: @katrinleinweber, @krlmlr, @dchiu911, @ramnathv, @aedobbyn, @Bio7, @tonytonov, @samhinshaw, @fny, @vnijs, @martin-mfg, @NGaffney, @dchiu911.

styler 1.0.1

This is a maintenance release without any breaking API changes.

Major & dependency related changes

  • Removed implicit dplyr dependency via purrr:::map_dfr() (thanks @jimhester, #324).
  • Added required minimal version dependency for purr (>= 0.2.3) (#338).
  • We rely on the tibble package which was optimized for speed in v1.4.2 so styler should run ~2x as fast (#348). For that reason, styler now depends on tibble >= 1.4.2.
  • In the dependency enc, a bug was fixed that removed/changed non-ASCII characters. Hence, styler now depends on enc >= 0.2 (#348).

Minor changes

  • We're now recognizing and respecting more DSLs used in R comments: rplumber (#*, #306), shebang #/! (#345), knitr chunk headers for spinning (#+ / #-, #362).
  • Named arguments can stay on the first line if call is multi-line (#318).
  • No space anymore with tidyverse_style() after !! since with rlang 0.2, !! now binds tighter (#322), spacing around ~ (#316), no space anymore around ^ (#308).
  • Code chunks in Rmd documents that don't use the R engine are no longer formatted (#313).
  • Various bug fixes and edge case improvements.

Thanks to all contributors for patches, issues and the like: @devSJR, @klrmlr, @yutannihilation, @samhinshaw, @martin-mfg, @jjramsey, @RMHogervorst, @wlandau, @llrs, @aaronrudkin, @crew102, @jkgrain, @jennybc, @joranE.

styler 1.0.0

Initial release.

stylers

These are functions used to style code. They style a directory, a whole package, a file or a string.

style_dir(path = ".", 
  ..., style = tidyverse_style, transformers = style(...), 
  filetype = "R", recursive = TRUE, exclude_files = NULL
)

style_pkg(pkg = ".", 
  ..., style = tidyverse_style, transformers = style(...), filetype = "R", 
  exclude_files = "R/RcppExports.R"
)


style_file(path, 
  ..., style = tidyverse_style, transformers = style(...)
)

style_text(text, ..., style = tidyverse_style, transformers = style(...))

style guides

These functions are the style guides implemented.

tidyverse_style(
  scope = "tokens", 
  strict = TRUE, 
  indent_by = 2, 
  start_comments_with_one_space = FALSE, 
  reindention = tidyverse_reindention(), 
  math_token_spacing = tidyverse_math_token_spacing()
)
tidyverse_reindention()
tidyverse_math_token_spacing())

style guide creators

This function is used to create a style guide.

create_style_guide(
  initialize = default_style_guide_attributes, 
  line_break = NULL, 
  space = NULL, 
  token = NULL, 
  indention = NULL, 
  use_raw_indention = FALSE, 
  reindention = tidyverse_reindention()
)

Helpers

These are helper functions used to specify the style guides in use.

specify_math_token_spacing(
  zero = NULL, 
  one = c("'+'", "'-'", "'*'", "'/'", "'^'")
)

specify_reindention(
  regex_pattern = NULL, 
  indention = 0, 
  comments_only = TRUE
)
initialize_default_attributes(pd_flat)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("styler")

1.1.0 by Lorenz Walthert, 4 months ago


https://github.com/r-lib/styler


Report a bug at https://github.com/r-lib/styler/issues


Browse source code at https://github.com/cran/styler


Authors: Kirill Müller [aut] , Lorenz Walthert [cre, aut]


Documentation:   PDF Manual  


GPL-3 license


Imports backports, cli, magrittr, purrr, rematch2, rlang, rprojroot, tibble, tools, withr, xfun

Suggests data.tree, dplyr, here, knitr, prettycode, rmarkdown, rstudioapi, testthat


Imported by exampletestr, languageserver.

Suggested by autothresholdr, crunch, detrendr, drake, knitr, nandb, reprex, shinydashboardPlus, usethis.


See at CRAN