News

	   CHANGES IN formatR VERSION 1.5

NEW FEATURES

o added a new function tidy_file() to format specified R scripts (thanks, @edlee123, #61)

o usage() was re-implemented by @egnha in #66; the major difference with the previous version is that width means the maximum width (if possible) instead of the minimum; it also gained two new arguments, indent.by.FUN and fail; see ?formatR::usage for details

	   CHANGES IN formatR VERSION 1.4

NEW FEATURES

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

MAJOR CHANGES

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)

BUG FIXES

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

NEW FEATURES

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

MAJOR CHANGES

o the minimal required R version is 3.0.2 now

	   CHANGES IN formatR VERSION 1.1

NEW FEATURES

o added a new argument output to usage()

BUG FIXES

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

NEW FEATURES

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 https://yihui.shinyapps.io/formatR/ for a live demo.

BUG FIXES

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

MAJOR CHANGES

o three functions were renamed (from the foo.bar 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 http://yihui.name/formatR for details

MINOR CHANGES

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

MINOR CHANGES

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

MAJOR CHANGES

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

MAJOR CHANGES

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

BUG FIXES

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

MAJOR CHANGES

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

NEW FEATURES

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

	   CHANGES IN formatR VERSION 0.6

NEW FEATURES

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)

MAJOR CHANGES

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)

MINOR CHANGES

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

MAJOR CHANGES

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

MINOR CHANGES

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

	   CHANGES IN formatR VERSION 0.4

NEW FEATURES

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

MAJOR CHANGES

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 https://github.com/yihui/formatR/wiki/

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

BUG FIXES

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

	   CHANGES IN formatR VERSION 0.3-4

MINOR CHANGES

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

MINOR CHANGES

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

MINOR CHANGES

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

	   CHANGES IN formatR VERSION 0.3-1

SIGNIFICANT CHANGES

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

NEW FEATURES

o usage() will tell if the function is S3

o a wiki is set up as the manual for formatR: https://github.com/yihui/formatR/wiki

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

MINOR CHANGES

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

NEW FEATURES

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

NEW FEATURES

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

NEW FEATURES

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

MINOR CHANGES

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

MINOR CHANGES

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

NEW FEATURES

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


	   CHANGES IN formatR VERSION 0.1-9

NEW FEATURES

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)

MINOR CHANGES

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

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

	   CHANGES IN formatR VERSION 0.1-8

NEW FEATURES

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

directory

o added a package vignette


	   CHANGES IN formatR VERSION 0.1-7

NEW FEATURES

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

NEW FEATURES

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