packageDescription           package:utils           R Documentation

Package Description

Description:

     Parses and returns the 'DESCRIPTION' file of a package.

Usage:

     packageDescription(pkg, lib.loc = NULL, fields = NULL,
                        drop = TRUE, encoding = "")

Arguments:

     pkg: a character string with the package name.

 lib.loc: a character vector of directory names of R libraries, or
          'NULL'.  The default value of 'NULL' corresponds to all
          libraries currently known.  If the default is used, the
          loaded packages are searched before the libraries.

  fields: a character vector giving the tags of fields to return (if
          other fields occur in the file they are ignored).

    drop: If 'TRUE' and the length of 'fields' is 1, then a single
          character string with the value of the respective field is
          returned instead of an object of class
          '"packageDescription"'.

encoding: If there is an 'Encoding' field, to what encoding should
          re-encoding be attempted?  If 'NA', no re-encoding.  The
          other values are as used by 'iconv', so the default '""'
          indicates the encoding of the current locale.

Details:

     A package will not be 'found' unless it has a 'DESCRIPTION' file
     which contains a valid 'Version' field.  Different warnings are
     given when no package directory is found and when there is a
     suitable directory but no valid 'DESCRIPTION' file.

     An attached environment named to look like a package (e.g.
     'package:utils2') will be ignored as from R 2.6.0.

Value:

     If a 'DESCRIPTION' file for the given package is found and can
     successfully be read, 'packageDescription' returns an object of
     class '"packageDescription"', which is a named list with the
     values of the (given) fields as elements and the tags as names,
     unless 'drop = TRUE'.

     If parsing the 'DESCRIPTION' file was not successful, it returns a
     named list of 'NA's with the field tags as names if 'fields' is
     not null, and 'NA' otherwise.

See Also:

     'read.dcf'

Examples:

     packageDescription("stats")
     packageDescription("stats", fields = c("Package", "Version"))

     packageDescription("stats", fields = "Version")
     packageDescription("stats", fields = "Version", drop = FALSE)

