formatR (version 1.14)

tidy_source: Reformat R code

Description

Read R code from a file or the clipboard and reformat it. This function is based on parse() and deparse(), but it does several other things, such as preserving blank lines and comments, substituting the assignment operator = with <-, and re-indenting 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),
  pipe = getOption("formatR.pipe", 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")),
  args.newline = getOption("formatR.args.newline", FALSE),
  output = TRUE,
  text = NULL,
  ...
)

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

.

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 substitute the assignment operator = with <-.

pipe

Whether to substitute the magrittr pipe %>% with R's native pipe operator |>.

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.

args.newline

Whether to start the arguments of a function call on a new line instead of after the function name and ( when the arguments cannot fit one line.

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

Author

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

Details

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

References

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

See Also

parse(), deparse()

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