formatR: tidy_source – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

tidy_source

Reformat R code while preserving blank lines and comments

Description

Read R code from a file or the clipboard and reformat it. That this function preserves blank lines and comments is a different behavior from that of parse() and deparse(). This function can also replace = with <- where = means assignment, and re-indent code with a specified number of spaces.

Usage

tidy_source(
  source = "clipboard",
  comment = getOption("formatR.comment", TRUE),
  blank = getOption("formatR.blank", TRUE),
  arrow = getOption("formatR.arrow", FALSE),
  brace.newline = getOption("formatR.brace.newline", FALSE),
  indent = getOption("formatR.indent", 4),
  wrap = getOption("formatR.wrap", TRUE),
  width.cutoff = getOption("formatR.width", getOption("width")),
  output = TRUE,
  text = NULL,
  ...
)

Arguments

`source`	A character string: file path to the source code (defaults to the clipboard).
`comment`	Whether to keep comments.
`blank`	Whether to keep blank lines.
`arrow`	Whether to replace the assign operator `=` with `<-`.
`brace.newline`	Whether to put the left brace `{` to a new line.
`indent`	Number of spaces to indent the code.
`wrap`	Whether to wrap comments to the linewidth determined by `width.cutoff` (roxygen comments will never be wrapped).
`width.cutoff`	An integer in `[20, 500]`: if a line's character length is at or over this number, the function will try to break it into a new line. In other words, this is the lower bound of the line width. See ‘Details’ if an upper bound is desired instead.
`output`	Whether to output to the console or a file using `cat()`.
`text`	An alternative way to specify the input: if `NULL`, the function will use the `source` argument; if a character vector containing the source code, the function will use this and ignore the `source` argument.
`...`	Other arguments passed to `cat()`, e.g. `file` (this can be useful for batch-processing R scripts, e.g. `tidy_source(source = 'input.R', file = 'output.R')`).

Details

Value of the argument width.cutoff wrapped in I() (e.g., I(60)) will be treated as the upper bound of the line width. The corresponding argument to deparse() is a lower bound, so the function will perform a binary search for a width value that can make deparse() return code with line width smaller than or equal to the width.cutoff value. If the search fails, a warning will signal, suppressible by global option options(formatR.width.warning = FALSE).

Value

A list with components

`text.tidy`	the reformatted code as a character vector
`text.mask`	the code containing comments, which are masked in assignments or with the weird operator

Note

Be sure to read the reference to know other limitations.

Author(s)

Yihui Xie <https://yihui.org> with substantial contribution from Yixuan Qiu <https://yixuan.blog>

References

https://yihui.org/formatR/ (an introduction to this package, with examples and further notes)

Examples

library(formatR)

## a messy R script
messy = system.file("format", "messy.R", package = "formatR")
tidy_source(messy)

## use the 'text' argument
src = readLines(messy)

## source code
cat(src, sep = "\n")

## the formatted version
tidy_source(text = src)

## preserve blank lines
tidy_source(text = src, blank = TRUE)

## indent with 2 spaces
tidy_source(text = src, indent = 2)

## discard comments!
tidy_source(text = src, comment = FALSE)

## wanna see the gory truth??
tidy_source(text = src, output = FALSE)$text.mask


## tidy up the source code of image demo
x = file.path(system.file(package = "graphics"), "demo", "image.R")

# to console
tidy_source(x)

# to a file
f = tempfile()
tidy_source(x, blank = TRUE, file = f)

## check the original code here and see the difference
file.show(x)
file.show(f)

## use global options
options(comment = TRUE, blank = FALSE)
tidy_source(x)

## if you've copied R code into the clipboard
if (interactive()) {
    tidy_source("clipboard")
    ## write into clipboard again
    tidy_source("clipboard", file = "clipboard")
}

## the if-else structure
tidy_source(text = c("{if(TRUE)1 else 2; if(FALSE){1+1", "## comments", "} else 2}"))

formatR

Format R Code Automatically

v1.10

GPL

Authors

Yihui Xie [aut, cre] (<https://orcid.org/0000-0003-0645-5666>), Ed Lee [ctb], Eugene Ha [ctb], Kohske Takahashi [ctb], Pavel Krivitsky [ctb]

Initial release