Reformat R code while preserving blank lines and comments — tidy_source • formatR

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

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

Note

Be sure to read the reference to know other limitations.

References

https://yihui.name/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)
#> # a single line of comments is preserved
#> 1 + 1
#> 
#> if (TRUE) {
#>     x = 1  # inline comments
#> } else {
#>     x = 2
#>     print("Oh no... ask the right bracket to go away!")
#> }
#> 1 * 3  # one space before this comment will become two!
#> 2 + 2 + 2  # 'short comments'
#> 
#> # only 'single quotes' are allowed in comments
#> df = data.frame(y = rnorm(100), x1 = rnorm(100), x2 = rnorm(100))
#> lm(y ~ x1 + x2, data = df)
#> 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 
#>     1 + 1  ## comments after a long line
#> 
#> ## here is a long long long long long long long long long long long long long long
#> ## long long long long long long comment

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

## source code
cat(src, sep = "\n")
#>     # a single line of comments is preserved
#> 1+1
#> 
#> if(TRUE){
#> x=1  # inline comments
#> }else{
#> x=2;print('Oh no... ask the right bracket to go away!')}
#> 1*3 # one space before this comment will become two!
#> 2+2+2    # 'short comments'
#> 
#> # only 'single quotes' are allowed in comments
#> df=data.frame(y=rnorm(100),x1=rnorm(100),x2=rnorm(100))
#> lm(y~x1+x2, data=df)
#> 1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1+1  ## comments after a long line
#> 
#> ## here is a long long long long long long long long long long long long long long long long long long long long comment

## the formatted version
tidy_source(text = src)
#> # a single line of comments is preserved
#> 1 + 1
#> 
#> if (TRUE) {
#>     x = 1  # inline comments
#> } else {
#>     x = 2
#>     print("Oh no... ask the right bracket to go away!")
#> }
#> 1 * 3  # one space before this comment will become two!
#> 2 + 2 + 2  # 'short comments'
#> 
#> # only 'single quotes' are allowed in comments
#> df = data.frame(y = rnorm(100), x1 = rnorm(100), x2 = rnorm(100))
#> lm(y ~ x1 + x2, data = df)
#> 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 
#>     1 + 1  ## comments after a long line
#> 
#> ## here is a long long long long long long long long long long long long long long
#> ## long long long long long long comment

## preserve blank lines
tidy_source(text = src, blank = TRUE)
#> # a single line of comments is preserved
#> 1 + 1
#> 
#> if (TRUE) {
#>     x = 1  # inline comments
#> } else {
#>     x = 2
#>     print("Oh no... ask the right bracket to go away!")
#> }
#> 1 * 3  # one space before this comment will become two!
#> 2 + 2 + 2  # 'short comments'
#> 
#> # only 'single quotes' are allowed in comments
#> df = data.frame(y = rnorm(100), x1 = rnorm(100), x2 = rnorm(100))
#> lm(y ~ x1 + x2, data = df)
#> 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 
#>     1 + 1  ## comments after a long line
#> 
#> ## here is a long long long long long long long long long long long long long long
#> ## long long long long long long comment

## indent with 2 spaces
tidy_source(text = src, indent = 2)
#> # a single line of comments is preserved
#> 1 + 1
#> 
#> if (TRUE) {
#>   x = 1  # inline comments
#> } else {
#>   x = 2
#>   print("Oh no... ask the right bracket to go away!")
#> }
#> 1 * 3  # one space before this comment will become two!
#> 2 + 2 + 2  # 'short comments'
#> 
#> # only 'single quotes' are allowed in comments
#> df = data.frame(y = rnorm(100), x1 = rnorm(100), x2 = rnorm(100))
#> lm(y ~ x1 + x2, data = df)
#> 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 
#>   1 + 1  ## comments after a long line
#> 
#> ## here is a long long long long long long long long long long long long long long
#> ## long long long long long long comment

## discard comments!
tidy_source(text = src, comment = FALSE)
#> 1 + 1
#> if (TRUE) {
#>     x = 1
#> } else {
#>     x = 2
#>     print("Oh no... ask the right bracket to go away!")
#> }
#> 1 * 3
#> 2 + 2 + 2
#> df = data.frame(y = rnorm(100), x1 = rnorm(100), x2 = rnorm(100))
#> lm(y ~ x1 + x2, data = df)
#> 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 
#>     1 + 1

## wanna see the gory truth??
tidy_source(text = src, output = FALSE)$text.mask
#>  [1] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa# a single line of comments is preserved.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"                                          
#>  [2] "1 + 1"                                                                                                                                                    
#>  [3] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"                                                                                  
#>  [4] "if (TRUE) {\n    x = 1 %InLiNe_IdEnTiFiEr% \"# inline comments\"\n} else {\n    x = 2\n    print(\"Oh no... ask the right bracket to go away!\")\n}"      
#>  [5] "1 * 3 %InLiNe_IdEnTiFiEr% \"# one space before this comment will become two!\""                                                                           
#>  [6] "2 + 2 + 2 %InLiNe_IdEnTiFiEr% \"# 'short comments'\""                                                                                                     
#>  [7] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"                                                                                  
#>  [8] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa# only 'single quotes' are allowed in comments.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"                                    
#>  [9] "df = data.frame(y = rnorm(100), x1 = rnorm(100), x2 = rnorm(100))"                                                                                        
#> [10] "lm(y ~ x1 + x2, data = df)"                                                                                                                               
#> [11] "1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + \n    1 + 1 %InLiNe_IdEnTiFiEr% \"## comments after a long line\""    
#> [12] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"                                                                                  
#> [13] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa## here is a long long long long long long long long long long long long long long.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"
#> [14] "invisible(\".BeGiN_TiDy_IdEnTiFiEr_HaHaHa## long long long long long long comment.HaHaHa_EnD_TiDy_IdEnTiFiEr\")"                                          


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

# to console
tidy_source(x)
#> # Copyright (C) 1997-2009 The R Core Team
#> 
#> require(datasets)
#> require(grDevices)
#> require(graphics)
#> 
#> x <- 10 * (1:nrow(volcano))
#> x.at <- seq(100, 800, by = 100)
#> y <- 10 * (1:ncol(volcano))
#> y.at <- seq(100, 600, by = 100)
#> 
#> # Using Terrain Colors
#> 
#> image(x, y, volcano, col = terrain.colors(100), axes = FALSE)
#> contour(x, y, volcano, levels = seq(90, 200, by = 5), add = TRUE, col = "brown")
#> axis(1, at = x.at)
#> axis(2, at = y.at)
#> box()
#> title(main = "Maunga Whau Volcano", sub = "col=terrain.colors(100)", font.main = 4)
#> 
#> # Using Heat Colors
#> 
#> image(x, y, volcano, col = heat.colors(100), axes = FALSE)
#> contour(x, y, volcano, levels = seq(90, 200, by = 5), add = TRUE, col = "brown")
#> axis(1, at = x.at)
#> axis(2, at = y.at)
#> box()
#> title(main = "Maunga Whau Volcano", sub = "col=heat.colors(100)", font.main = 4)
#> 
#> # Using Gray Scale
#> 
#> image(x, y, volcano, col = gray(100:200/200), axes = FALSE)
#> contour(x, y, volcano, levels = seq(90, 200, by = 5), add = TRUE, col = "black")
#> axis(1, at = x.at)
#> axis(2, at = y.at)
#> box()
#> title(main = "Maunga Whau Volcano \n col=gray(100:200/200)", font.main = 4)
#> 
#> ## Filled Contours are even nicer sometimes :
#> example(filled.contour)

# 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)
#> # Copyright (C) 1997-2009 The R Core Team
#> 
#> require(datasets)
#> require(grDevices)
#> require(graphics)
#> 
#> x <- 10 * (1:nrow(volcano))
#> x.at <- seq(100, 800, by = 100)
#> y <- 10 * (1:ncol(volcano))
#> y.at <- seq(100, 600, by = 100)
#> 
#> # Using Terrain Colors
#> 
#> image(x, y, volcano, col = terrain.colors(100), axes = FALSE)
#> contour(x, y, volcano, levels = seq(90, 200, by = 5), add = TRUE, col = "brown")
#> axis(1, at = x.at)
#> axis(2, at = y.at)
#> box()
#> title(main = "Maunga Whau Volcano", sub = "col=terrain.colors(100)", font.main = 4)
#> 
#> # Using Heat Colors
#> 
#> image(x, y, volcano, col = heat.colors(100), axes = FALSE)
#> contour(x, y, volcano, levels = seq(90, 200, by = 5), add = TRUE, col = "brown")
#> axis(1, at = x.at)
#> axis(2, at = y.at)
#> box()
#> title(main = "Maunga Whau Volcano", sub = "col=heat.colors(100)", font.main = 4)
#> 
#> # Using Gray Scale
#> 
#> image(x, y, volcano, col = gray(100:200/200), axes = FALSE)
#> contour(x, y, volcano, levels = seq(90, 200, by = 5), add = TRUE, col = "black")
#> axis(1, at = x.at)
#> axis(2, at = y.at)
#> box()
#> title(main = "Maunga Whau Volcano \n col=gray(100:200/200)", font.main = 4)
#> 
#> ## Filled Contours are even nicer sometimes :
#> example(filled.contour)

## 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}"))
#> {
#>     if (TRUE) 
#>         1 else 2
#>     if (FALSE) {
#>         1 + 1
#>         ## comments
#>     } else 2
#> }