Format R Code Automatically

Provides a function tidy_source() to format R source code. Spaces and indent will be added to the code automatically, and comments will be preserved under certain conditions, so that R code will be more human-readable and tidy. There is also a Shiny app as a user interface in this package (see tidy_app()).

Format R code automatically.

See the package homepage for more information.


       CHANGES IN formatR VERSION 1.4


o tidy_source() can preserve line breaks in character strings in source code


o the deprecated functions tidy.source(), tidy.dir(), and tidy.eval() have been removed; use tidy_source(), tidy_dir() and tidy_eval() instead

o comments that begin with #+ or #- are no longer wrapped; such comments are treated as knitr chunk options in knitr::spin() (#52)


o tidy_source() should not write an extra space to the last line of code (thanks, @mr-karan, #49)

o long strings (> 1000 characters) in source code can be preserved now (thanks, @jholtman, #50)

o tidy_source() might move any lines of code starting with else back to the previous lines (thanks, @Auburngrads, #51)

       CHANGES IN formatR VERSION 1.3


o tidy_source() can deal with multibyte characters that cannot represented in the system native encoding now (on Windows)

o usage() works for functions obtained from :: or ::: now, e.g. usage(formatR::tidy_source)

       CHANGES IN formatR VERSION 1.2


o the minimal required R version is 3.0.2 now

       CHANGES IN formatR VERSION 1.1


o added a new argument output to usage()


o fixed yihui/knitr#918: when code is NULL, parse() will hang (with a question mark waiting for input)

       CHANGES IN formatR VERSION 1.0


o added a function tidy_app() to replace tidy.gui() in previous versions: tidy_app() launches a Shiny app in the browser to reformat R code. The gWidgets interface (e.g. GTK+) is no longer supported. See for a live demo.


o the shebang #! is no longer treated as an R comment (thanks, Mirko Ebert, #36)


o three functions were renamed (from the style to foo_bar): tidy.source() (tidy_source()), tidy.dir() (tidy_dir()), and tidy.eval() (tidy_eval())

o the arguments of tidy_source() were renamed: keep.comment was renamed to comment, keep.blank.line -> blank, replace.assign -> arrow, left.brace.newline -> brace.newline, and reindent.spaces -> indent; similarly, the corresponding global options were also renamed: now you should use options(formatR.comment) instead of options(keep.comment), keep.blank.line -> formatR.blank, and so on; see ?tidy_source and for details


o the usage() function returns the source code of the usage of a function now; in previous versions, it only returns NULL

o added a new argument 'tidy' in usage() to make it possible not to reformat the usage code

o tidy_source() may not work for R 3.0.0 or 3.0.1 if the code only contains comments due to a bug in base R, which has been fixed; if you use R 3.0, please upgrade to at least R 3.0.2 (R 2.15.x is not affected)

       CHANGES IN formatR VERSION 0.10


o the argument 'replace.assign' in tidy.source() will be treated as FALSE if there is no = in the code, because there is no need to replace = in such cases (this slighly improves the performance)

o the PDF vignette was removed, and only the Markdown vignette was kept in this package, which uses the vignette engine knitr::docco_linear; see vignette('formatR', package = 'formatR')

       CHANGES IN formatR VERSION 0.9


o tidy.source() uses utils::getParseData() to identify comments in R code under R 3.0.x, which is much more accurate than the regular expressions in previous versions; users are strongly recommended to try R 3.0.x (#25, #26)

o changed the meaning of the argument 'width' in usage(); see documentation

       CHANGES IN formatR VERSION 0.8


o tidy.source(text = character(0)) returns character(0) instead of ''

o removed the (dark voodoo) functions parse.tidy() and deparse.tidy() as well as the operator "%InLiNe_IdEnTiFiEr%"; they were designed for the pgfSweave package, which has been archived on CRAN for a long time

o the function unmask.source() is no longer exported

       CHANGES IN formatR VERSION 0.7


o backslashes in whole lines of comments can be correctly retained now (e.g. #' \code{1+1}) (thanks, KAPLAN Bernard)

o the font button in tidy.gui() works again (#23) (thanks, Dason Kurkiewicz)

o the option left.brace.newline was buggy; it did not work for empty lines


o the option in tidy.source() was removed; the spaces before comments will not be faithfully kept


o the number of spaces for indentation can be specified in tidy.gui()

       CHANGES IN formatR VERSION 0.6


o the replace.assign argument is much more reliable now; it is based on the codetools package (code analysis) instead of regular expressions (big thanks to Kohske Takahashi)

o replace.assign also works when keep.comment=FALSE; in previous versions, replace.assign=TRUE only applies to keep.comment=TRUE

o tidy.source() gained a new argument 'left.brace.newline'; when set to TRUE, the left curly brace { will be moved to a new line (#18) (thanks, Jared Lander)


o the 'text.tidy' component in the results of tidy.source() is a character vector of code blocks instead of code lines now, e.g. in previous versions, the result may be c('if (TRUE) {', '1', '}') (vector of length 3), but now it becomes 'if (TRUE) {\n1\n}'; each element of 'text.tidy' contains a minimal complete code block

o potential dependency on the parser package has been removed (replaced by the codetools package); this also makes it more robust to use Unicode characters in R code now, see issue #13 for example

o roxygen comments (#') will not be reflowed; this gives us control over which comments to be reflowed (sometimes we do not want comments to be wrapped and we can write them in the special roxygen comments)


o the results of tidy.source() (a list) only contain text.tidy and text.mask now; begin.comment and end.comment were removed since they were not used anywhere

       CHANGES IN formatR VERSION 0.5


o the dependency on the parser package was removed because it was orphaned on CRAN; this affects two features: replace = with <- (the 'replace.assign' option in tidy.source()) and the identification of inline comments; tidy.source() will still work in most cases, but please keep in mind that (1) 'replace.assign=TRUE' will not be entirely reliable without parser (so use with extreme caution if you do not have parser installed) (2) if you want to write # in a character string, you must use double quotes, e.g. "here is a #" will be fine whereas 'here is a #' is not; if you want to use quotes in comments, please always use single quotes, e.g. # 'single quotes' (inline comments that contain double quotes will be dropped); if the parser package is available in your system (e.g. you installed it from the archived source on CRAN), everything will be the same as before

o the default value for 'envir' in tidy.eval() was changed from globalenv() to parent.frame()


o \t will no longer be replaced with \t when because it is dangerous to do so; see #17 for an example

       CHANGES IN formatR VERSION 0.4


o a new argument 'reindent.spaces' for tidy.source() to reindent the code with a specified number of spaces (e.g. 2)

o comments will be reflowed as a whole block when possible (instead of being wrapped line by line); thanks, Paul Johnson


o when a comment block is reflowed, the second and following lines will not be indented

o the default value of the 'width.cutoff' argument in tidy.source() is getOption('width') now; in the past it was 75% of that width which was less intuitive

o part of the documentation of tidy.source() has been moved to

o internally the comments are preserved by putting them in an expression invisible("# comments"); in past versions comments were retained in assignments; this change should not affect end users


o fixed #16: \ in comments are preserved correctly now

       CHANGES IN formatR VERSION 0.3-4


o slight tweaks to the vignette (stopped Sweave from adding \usepackage{Sweave} which introduces ae by default)

o fixed the error message in tidy.source(), pointing users to the wiki page on GitHub (thanks, Gabor Grothendieck)

       CHANGES IN formatR VERSION 0.3-3


o functions unmask.source(), parse.tidy(), deparse.tidy() and the operator %InLiNe_IdEnTiFiEr% were marked as `internal' in documentation

o the vignette is processed by the knitr package

o fixed a buglet in usage() so it can process functions with dots correctly

       CHANGES IN formatR VERSION 0.3-2


o the parser package is imported (in previous versions formatR depends on parser); thanks, Romain Francois

       CHANGES IN formatR VERSION 0.3-1


o the function formatR() was renamed to tidy.gui() which is a more meaningful name since it is used to create a GUI


o usage() will tell if the function is S3

o a wiki is set up as the manual for formatR:

o tidy.eval() can evaluate the code in a specified environment now; see the 'envir' argument


o keep.blank.line is TRUE by default now (was FALSE in previous versions), i.e. blank lines are preserved by default

       CHANGES IN formatR VERSION 0.2-4


o a new function tidy.eval(): evaluate R code and insert the output masked in comments (following ##)

o the empty lines before 'else' will be removed even if keep.blank.line = TRUE; it is ill-advised to use blank lines among incomplete code chunks, e.g.

if (TRUE)

{'this is a BAD style of R programming'}

o tidy.source() reports the line number when errors occur, which can help users detect the problem in the R code more quickly (thanks, Hadley Wickham)

       CHANGES IN formatR VERSION 0.2-3


o 'else ...' will be moved back to the last line so that we will no longer see an 'else' statement in a new line

       CHANGES IN formatR VERSION 0.2-2


o formatR now uses the parser package to parse inline comments,

which can guarantee that these comments will be correctly parsed (no longer uses the 'unsafe' regular expressions to parse comments, so forget about the previous rules of writing comments -- just write comments with an arbitrary number of spaces before # as you wish)

o the use of parser also enabled a new feature: '=' can be

replaced with '<-' wherever appropriate (for example, '=' in function arguments will not be replaced; only thoese equal signs which are used to assigning purposes can be replaced)

o long roxygen comments will not be wrapped (i.e. comments begin

with #' or ##')


o fixed a minor problem in the function usage() (out --> output)

o comments after { will be moved to the next line (in previous

versions, these comments will cause errors)

       CHANGES IN formatR VERSION 0.2-1


o the escape character '\' in comments of complete lines will be

successfully preserved, which is especially useful for tidy.source() to format the roxygen comments since we usually write comments like "##' @author Someone \email{}" but "\e" is not a legal character in R (this will lead to errors in earlier versions of this package)

       CHANGES IN formatR VERSION 0.2-0


o a new function usage() to print the formatted usage of a function

       CHANGES IN formatR VERSION 0.1-9


o tidy.source() can wrap long comments into shorter ones now (this

only applies to the whole lines of comments; the inline comments will not be wrapped since it is tricky to do so)


o '\t' will be parsed to ' ' when '' is TRUE in

tidy.source() (this might be undesirable, though)

       CHANGES IN formatR VERSION 0.1-8


o new functions parse.tidy() and deparse.tidy() for the package

pgfSweave to help tidy the source code in Sweave

o a new function tidy.dir() to format all the R scripts under a


o added a package vignette

       CHANGES IN formatR VERSION 0.1-7


o full support to multi-byte characters in the formatR() GUI

o a new function unmask.source() to obtain the real source code

from the masked source

o a new operator '%InLiNe_IdEnTiFiEr%' designed mainly for

pgfSweave (mask the inline comments)

       CHANGES IN formatR VERSION 0.1-6


o the inline comments will also be preserved in most cases (in

earlier versions, only single lines of comments are preserved)

o tidy.source() gained a new argument 'text' to accept a character

vector as the source code

o multi-byte characters are partially supported in the formatR() GUI

now (full support will come in 0.1-7)

Reference manual

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


1.5 by Yihui Xie, 5 months ago

Report a bug at

Browse source code at

Authors: Yihui Xie [aut, cre], Eugene Ha [ctb], Kohske Takahashi [ctb], Ed Lee [ctb]

Documentation:   PDF Manual  

Task views: Reproducible Research

GPL license

Suggests codetools, shiny, testit, rmarkdown, knitr

Imported by RFormatter, Rd2roxygen, Rz, automagic, exampletestr, ggThemeAssist, googleAuthR, splashr.

Suggested by DeLorean, ProjectTemplate, SqlRender, dynamichazard, elevatr, knitr, manifestoR, pinbasic, pvar, reprex, shinyWidgets.

See at CRAN