readNEWS                package:tools                R Documentation

Read R's NEWS file or a similar one

Description:

     Read R's NEWS file or a similarly formatted one. This is an
     experimental feature, new in R 2.4.0 and may change in several
     ways.

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 NEWS file; 'checkNEWS()' checks for common
     errors in formatting.  Currently it detects an incorrect number of
     spaces before the '"o"' item marker.

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 is still experimental and may change in the future.

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

