| % File src/library/utils/man/packageDescription.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Copyright 2005-2017 The R Foundation |
| % Distributed under GPL 2 or later |
| |
| \name{packageDescription} |
| \title{Package Description} |
| \alias{packageDescription} |
| \alias{packageVersion} |
| \alias{packageDate} |
| \alias{asDateBuilt} |
| \alias{print.packageDescription} |
| \description{ |
| Parses and returns the \file{DESCRIPTION} file of a package as a |
| \code{"packageDescription"}. |
| |
| Utility functions return (transformed) parts of that. |
| } |
| \usage{ |
| packageDescription(pkg, lib.loc = NULL, fields = NULL, |
| drop = TRUE, encoding = "") |
| packageVersion(pkg, lib.loc = NULL) |
| packageDate(pkg, lib.loc = NULL, |
| date.fields = c("Date", "Packaged", "Date/Publication", "Built"), |
| tryFormats = c("\%Y-\%m-\%d", "\%Y/\%m/\%d", "\%D", "\%m/\%d/\%y"), |
| desc = packageDescription(pkg, lib.loc=lib.loc, fields=date.fields)) |
| asDateBuilt(built) |
| } |
| \arguments{ |
| \item{pkg}{a character string with the package name.} |
| \item{lib.loc}{a character vector of directory names of \R libraries, |
| or \code{NULL}. The default value of \code{NULL} corresponds to all |
| libraries currently known. If the default is used, the loaded |
| packages and namespaces are searched before the libraries.} |
| \item{fields}{a character vector giving the tags of fields to return |
| (if other fields occur in the file they are ignored).} |
| \item{drop}{If \code{TRUE} and the length of \code{fields} is 1, then |
| a single character string with the value of the respective field is |
| returned instead of an object of class \code{"packageDescription"}.} |
| \item{encoding}{If there is an \code{Encoding} field, to what encoding |
| should re-encoding be attempted? If \code{NA}, no re-encoding. The |
| other values are as used by \code{\link{iconv}}, so the default |
| \code{""} indicates the encoding of the current locale.} |
| \item{date.fields}{character vector of field tags to be tried. The |
| first for which \code{\link{as.Date}(.)} is not \code{\link{NA}} |
| will be returned. (Partly experimental, see \emph{Note}.)} |
| \item{tryFormats}{date formats to try, see \code{\link{as.Date.character}()}.} |
| \item{desc}{optionally, a named \code{\link{list}} with components |
| named from \code{date.fields}; where the default is fine, a |
| complete \code{packageDescription()} maybe specified as well.} |
| \item{built}{for \code{asDateBuilt()}, a \code{\link{character}} |
| string as from \code{packageDescription(*, fields="Built")}.} |
| } |
| \details{ |
| A package will not be \sQuote{found} unless it has a \file{DESCRIPTION} file |
| which contains a valid \code{Version} field. Different warnings are |
| given when no package directory is found and when there is a suitable |
| directory but no valid \file{DESCRIPTION} file. |
| |
| An \link{attach}ed environment named to look like a package |
| (e.g., \code{package:utils2}) will be ignored. |
| |
| \code{packageVersion()} is a convenience shortcut, allowing things |
| like \code{if (packageVersion("MASS") < "7.3") { do.things } }. |
| |
| For \code{packageDate()}, if \code{desc} is valid, both \code{pkg} and |
| \code{lib.loc} are not made use of. |
| } |
| \note{The default behavior of \code{packageDate()}, notably for |
| \code{date.fields}, is somewhat experimental and may change. Using |
| \code{date.fields = <string>} |
| single |
| } |
| \value{ |
| If a \file{DESCRIPTION} file for the given package is found and can |
| successfully be read, \code{packageDescription} returns an object of |
| class \code{"packageDescription"}, which is a named list with the |
| values of the (given) fields as elements and the tags as names, unless |
| \code{drop = TRUE}. |
| |
| If parsing the \file{DESCRIPTION} file was not successful, it returns |
| a named list of \code{NA}s with the field tags as names if \code{fields} |
| is not null, and \code{NA} otherwise. |
| |
| \code{packageVersion()} returns a (length-one) object of class |
| \code{"\link{package_version}"}. |
| |
| \code{packageDate()} will return a \code{"Date"} object from |
| \code{\link{as.Date}()} or \code{NA}. |
| |
| \code{asDateBuilt(built)} returns a \code{"Date"} object or signals an |
| error if \code{built} is invalid. |
| } |
| \seealso{ |
| \code{\link{read.dcf}} |
| } |
| \examples{\donttest{ |
| packageDescription("stats") |
| packageDescription("stats", fields = c("Package", "Version")) |
| |
| packageDescription("stats", fields = "Version") |
| packageDescription("stats", fields = "Version", drop = FALSE) |
| |
| if(packageVersion("MASS") < "7.3.29") |
| message("you need to update 'MASS'") |
| }%dont |
| pu <- packageDate("utils") |
| \donttest{str(pu)} |
| stopifnot(identical(pu, packageDate(desc = packageDescription("utils"))), |
| identical(pu, packageDate("stats"))) # as "utils" and "stats" are |
| # both 'base R' and "Built" at same time |
| } |
| \keyword{utilities} |