tidy_source: Reformat R code while preserving blank lines and comments

Description

This function returns reformatted source code; it tries to preserve blank lines and comments, which is different with parse and deparse. It can also replace = with <- where = means assignments, and reindent code by a specified number of spaces (default is 4).

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), output = TRUE, text = NULL, width.cutoff = getOption("width"), 
    ...)

Arguments

source

a character string: location of the source code (default to be the clipboard; this means we can copy the code to clipboard and use tidy_source() without specifying the argument source)

comment

whether to keep comments (TRUE by default)

blank

whether to keep blank lines (TRUE by default)

arrow

whether to replace the assign operator = with <-

brace.newline

whether to put the left brace { to a new line (default FALSE)

indent

number of spaces to indent the code (default 4)

wrap

whether to wrap comments to the linewidth determined by width.cutoff (note that roxygen comments will never be wrapped)

output

output to the console or a file using cat?

text

an alternative way to specify the input: if it is NULL, the function will read the source code from the source argument; alternatively, if text is a character vector containing the source code, it will be used as the input and the source argument will be ignored

width.cutoff

passed to deparse: integer in [20, 500] determining the cutoff at which line-breaking is tried (default to be getOption("width"))

...

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

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

References

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

Examples

Run this code

# NOT RUN {
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}"))
# }