Build and query the news data base for R or add-on packages.
news(query, package = "R", lib.loc = NULL, format = NULL,
reader = NULL, db = NULL)# S3 method for news_db
print(x, doBrowse = interactive(),
browser = getOption("browser"), …)
an expression for selecting news entries
a character string giving the name of an installed
add-on package, or "R"
.
a character vector of directory names of R libraries,
or NULL
. The default value of NULL
corresponds to all
libraries currently known.
Not yet used.
Not yet used.
a news db obtained from news()
.
logical specifying that the news should be opened in
the browser (by browseURL
, accessible as via
help.start
) instead of printed to the console.
the browser to be used, see browseURL
.
potentially further arguments passed to print()
.
A data frame inheriting from class "news_db"
, with
attributes
"package"
(and "subset"
if the
query
lead to proper subsetting).
If package
is "R"
(default), a news db is built with the
news since the 3.0.0 release of R (corresponding to R's top-level
NEWS
file). Otherwise, if the given add-on package can be
found in the given libraries, it is attempted to read its news in
structured form from files inst/NEWS.Rd
, NEWS
or
inst/NEWS
(in that order).
File inst/NEWS.Rd
should be an Rd file given the entries as Rd
\itemize
lists, grouped according to version using
section
elements with names starting with a suitable prefix
(e.g.“Changes in version”) followed by a space and the version
number, and optionally followed by a space and a parenthesized ISO
8601 (%Y-%m-%d, see strptime
) format date, and
possibly further grouped according to categories using
\subsection
elements named as the categories.
At the very end of \section{..}
, the date may also be specified
as (%Y-%m-%d, <note>)
, i.e., including parentheses.
The plain text NEWS
files in add-on packages use a variety of
different formats; the default news reader should be capable to
extract individual news entries from a majority of packages from the
standard repositories, which use (slight variations of) the following
format:
Entries are grouped according to version, with version header “Changes in version” at the beginning of a line, followed by a version number, optionally followed by an ISO 8601 format date, possibly parenthesized.
Entries may be grouped according to category, with a category header (different from a version header) starting at the beginning of a line.
Entries are written as itemize-type lists, using one of o, *, - or + as item tag. Entries must be indented, and ideally use a common indentation for the item texts.
Additional formats and readers may be supported in the future.
Package tools provides an (internal) utility function
news2Rd
to convert plain text NEWS
files to Rd. For
NEWS
files in a format which can successfully be handled by the
default reader, package maintainers can use tools:::news2Rd(dir,
"NEWS.Rd")
, possibly with additional argument codify = TRUE
,
with dir
a character string specifying the path to a package's
root directory. Upon success, the NEWS.Rd
file can further be
improved and then be moved to the inst
subdirectory of the
package source directory.
The news db built is a character data frame inheriting from
"news_db"
with variables Version
, Category
,
Date
and Text
, where the last contains the entry texts
read, and the other variables may be NA
if they were missing or
could not be determined.
Using query
, one can select news entries from the db. If
missing or NULL
, the complete db is returned. Otherwise,
query
should be an expression involving (a subset of) the
variables Version
, Category
, Date
and
Text
, and when evaluated within the db returning a logical
vector with length the number of entries in the db. The entries for
which evaluation gave TRUE
are selected. When evaluating,
Version
and Date
are coerced to
numeric_version
and Date
objects,
respectively, so that the comparison operators for these classes can
be employed.
# NOT RUN {
## Build a db of all R news entries.
db <- news()
# }
# NOT RUN {
## Bug fixes with PR number in 3.0.1.
db3 <- news(Version == "3.0.1" & grepl("^BUG", Category) & grepl("PR#", Text),
db = db)
# }
# NOT RUN {
## News from a date range ('Matrix' is there in a regular R installation):
if(length(iM <- find.package("Matrix", quiet=TRUE)) && nzchar(iM)) {
dM <- news(package="Matrix")
stopifnot(identical(dM, news(db=dM)))
dM2014 <- news("2014-01-01" <= Date & Date <= "2014-12-31", db = dM)
stopifnot(paste0("1.1-", 2:4) %in% dM2014[,"Version"])
}
# }
# NOT RUN {
<!-- % <- is not sensibly diff-ed against previous versions -->
## Which categories have been in use? % R-core maybe should standardize a bit more
sort(table(db[, "Category"]), decreasing = TRUE)
## Entries with version >= 3.0.0 (including "3.0.0 patched"):
table(news(Version >= "3.0.0", db = db)$Version)
# }
Run the code above in your browser using DataLab