1% File src/library/utils/man/packageStatus.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{packageStatus}
7\title{Package Management Tools}
8\alias{packageStatus}
9\alias{print.packageStatus}
10\alias{summary.packageStatus}
11\alias{update.packageStatus}
12\alias{upgrade.packageStatus}
13\alias{upgrade}
14\description{
15  Summarize information about installed packages and packages
16  available at various repositories, and automatically upgrade outdated
17  packages.
18}
19\usage{
20packageStatus(lib.loc = NULL, repositories = NULL, method,
21              type = getOption("pkgType"), \dots)
22
23\method{summary}{packageStatus}(object, \dots)
24
25\method{update}{packageStatus}(object, lib.loc = levels(object$inst$LibPath),
26       repositories = levels(object$avail$Repository), \dots)
27
28\method{upgrade}{packageStatus}(object, ask = TRUE, \dots)
29}
30\arguments{
31  \item{lib.loc}{a character vector describing the location of \R
32    library trees to search through, or \code{NULL}.  The default value
33    of \code{NULL} corresponds to all libraries currently known.}
34  \item{repositories}{a character vector of URLs describing the location of \R
35    package repositories on the Internet or on the local machine.
36    If specified as \code{NULL}, derive appropriate URLs from \link{option}
37    \code{"repos"}.}
38  \item{method}{Download method, see \code{\link{download.file}}.}
39  \item{type}{type of package distribution:
40    see \code{\link{install.packages}}.}
41  \item{object}{an object of class \code{"packageStatus"} as returned by
42    \code{packageStatus}.}
43  \item{ask}{if \code{TRUE}, the user is prompted which packages should
44    be upgraded and which not.}
45  \item{\dots}{for \code{packageStatus}: arguments to be passed to
46    \code{\link{available.packages}} and \code{\link{installed.packages}}.\cr
47    for the \code{upgrade} method, arguments to be passed to
48    \code{\link{install.packages}}\cr
49    for other methods: currently not used.}
50}
51\details{
52  The URLs in \code{repositories} should be full paths to the
53  appropriate contrib sections of the repositories.  The default is
54  \code{contrib.url(getOption("repos"))}.
55
56  There are \code{print} and \code{summary} methods for the
57  \code{"packageStatus"} objects: the \code{print} method gives a brief
58  tabular summary and the \code{summary} method prints the results.
59
60  The \code{update} method updates the \code{"packageStatus"} object.
61  The \code{upgrade} method is similar to \code{\link{update.packages}}:
62  it offers to install the current versions of those packages which are not
63  currently up-to-date.
64}
65\value{
66  An object of class \code{"packageStatus"}.  This is a list with two
67  components
68
69  \item{inst}{a data frame with columns as the \emph{matrix} returned by
70    \code{\link{installed.packages}} plus \code{"Status"}, a factor with
71    levels \code{c("ok", "upgrade", "unavailable")}.  Only the newest
72    version of each package is reported, in the first repository in
73    which it appears.
74  }
75
76  \item{avail}{a data frame with columns as the \emph{matrix} returned by
77    \code{\link{available.packages}} plus \code{"Status"}, a factor with
78    levels \code{c("installed", "not installed")}.
79  }
80
81  For the \code{summary} method the result is also of class
82  \code{"summary.packageStatus"} with additional components
83
84  \item{Libs}{a list with one element for each library}
85  \item{Repos}{a list with one element for each repository}
86
87  with the elements being lists of character vectors of package name for
88  each status.
89}
90\seealso{
91  \code{\link{installed.packages}}, \code{\link{available.packages}}
92}
93\examples{
94\dontrun{
95x <- packageStatus()
96print(x)
97summary(x)
98upgrade(x)
99x <- update(x)
100print(x)
101}}
102\keyword{utilities}
103