readNEWS {tools}R Documentation

Read R's NEWS file or a similar one

Description

Read/check R's ‘NEWS’ file or a similarly formatted one. This was an experimental feature added in R 2.4.0: as from R 2.12.0 the preferred format is ‘NEWS.Rd’.

Usage

readNEWS(file = file.path(R.home(), "NEWS"), trace = FALSE,
         chop = c("first", "1", "par1", "keepAll"))
checkNEWS(file = file.path(R.home(), "NEWS"))

Arguments

file

the name of the file which the data are to be read from. Alternatively, file can be a connection, which will be opened if necessary, and can also be a complete URL. For more details, see the file argument of read.table.

trace

logical indicating if the recursive reading should be traced, i.e., print what it is doing.

chop

a character string specifying how the news entries should be chopped; chop = "keepAll" saves the full entries.

Details

readNEWS() reads a pre-R-2.12.0-style ‘NEWS’ file; checkNEWS() checks for common errors in formatting. Currently it detects an incorrect number of spaces before the "o" item marker.

If non-ASCII characters are needed, the ‘NEWS’ file may be encoded in UTF-8 with a byte-order mark (BOM) at the beginning, which readNEWS() will recognize. Other encodings will display incorrectly on some systems. However, BOMs are discouraged on many systems and not all editors recognize them, so ‘NEWS’ files should normally be written in ASCII.

Value

readNEWS() returns an (S3) object of class "newsTree"; effectively a list of lists which is a tree of NEWS entries.

checkNEWS() returns TRUE if no suspected errors are found, or prints a message for each suspected error and returns FALSE.

Note that this was only ever experimental and may be removed soon, since the NEWS-file format is not longer supported (but there are examples ‘ONEWS’, ‘OONEWS’ and perhaps in packages).

Examples

NEWStr  <- readNEWS(trace = TRUE)# chop = "first" ( = "first non-empty")
## keep the full NEWS entry text i.e. "no chopping":
NEWStrA <- readNEWS(chop = "keepAll")
object.size(NEWStr)
object.size(NEWStrA) ## (no chopping) ==> about double the size

str(NEWStr, max.level = 3)

str(NEWStr[[c("2.3", "2.3.1")]], max.level=2, vec.len=1)

NEWStr [[c("2.3", "2.3.1", "NEW FEATURES")]]
NEWStrA[[c("2.4", "2.4.0", "NEW FEATURES")]]

# Check the current NEWS file

stopifnot(checkNEWS())
[Package tools version 2.15.1 Index]