Parse DESCRIPTION files
Parse, manipulate and reformat DESCRIPTION files. The package provides two APIs, one is object oriented, the other one is procedural and manipulates the files in place.
Installation
# Install the released version from CRAN
install.packages("desc")
# Or the development version from GitHub:
# install.packages("pak")
pak::pak("r-lib/desc")The object oriented API
Introduction
The object oriented API uses R6 classes.
Loading or creating new DESCRIPTION files
A new description object can be created by reading a DESCRIPTION file form the disk. By default the DESCRIPTION file in the current directory is read:
desc <- description$new()
desc#> Package: desc
#> Title: Manipulate DESCRIPTION Files
#> Version: 1.0.0
#> Author: Gábor Csárdi
#> Maintainer: Gábor Csárdi <csardi.gabor@gmail.com>
#> Description: Tools to read, write, create, and manipulate DESCRIPTION
#> files. It is intented for packages that create or manipulate other
#> packages.
#> License: MIT + file LICENSE
#> URL: https://github.com/r-lib/desc
#> BugReports: https://github.com/r-lib/desc/issues
#> Imports:
#> R6
#> Suggests:
#> newpackage,
#> testthat,
#> whoami
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 5.0.0A new object can also be created from scratch:
desc2 <- description$new("!new")
desc2#> Package: {{ Package }}
#> Title: {{ Title }}
#> Version: 1.0.0
#> Authors@R (parsed):
#> * Jo Doe <jodoe@dom.ain> [aut, cre]
#> Maintainer: {{ Maintainer }}
#> Description: {{ Description }}
#> License: {{ License }}
#> URL: {{ URL }}
#> BugReports: {{ BugReports }}
#> Encoding: UTF-8Normalizing DESCRIPTION files
Most DESCRIPTION fields may be formatted in multiple equivalent ways. desc does not reformat fields, unless they are updated or reformatting is explicitly requested via a call to the normalize() method or using the normalize argument of the write() method.
Querying, changing and removing fields
get() and set() queries or updates a field:
desc$set("Package", "foo")
desc$get("Package")#> Package
#> "foo"They work with multiple fields as well:
desc$set(Package = "bar", Title = "Bar Package")
desc$get(c("Package", "Title"))#> Package Title
#> "bar" "Bar Package"Dependencies
Package dependencies can be set and updated via an easier API:
desc$get_deps()#> type package version
#> 1 Suggests testthat *
#> 2 Suggests whoami *
#> 3 Suggests newpackage *
#> 4 Imports R6 *
desc$set_dep("mvtnorm")
desc$set_dep("Rcpp", "LinkingTo")
desc$get_deps()#> type package version
#> 1 Suggests testthat *
#> 2 Suggests whoami *
#> 3 Suggests newpackage *
#> 4 Imports mvtnorm *
#> 5 Imports R6 *
#> 6 LinkingTo Rcpp *
desc#> Package: bar
#> Title: Bar Package
#> Version: 1.0.0
#> Author: Gábor Csárdi
#> Maintainer: Gábor Csárdi <csardi.gabor@gmail.com>
#> Description: Tools to read, write, create, and manipulate DESCRIPTION
#> files. It is intented for packages that create or manipulate other
#> packages.
#> License: MIT + file LICENSE
#> URL: https://github.com/r-lib/desc
#> BugReports: https://github.com/r-lib/desc/issues
#> Imports:
#> mvtnorm,
#> R6
#> Suggests:
#> newpackage,
#> testthat,
#> whoami
#> LinkingTo:
#> Rcpp
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 5.0.0Collate fields
Collate fields can be queried and set using simple character vectors of file names:
desc$set_collate(list.files("../R"))#> Warning in idesc_set_collate(self, private, files, match.arg(which)): No files
#> in 'Collate' field
desc$get_collate()#> character(0)Authors
Authors information, when specified via the Authors@R field, also has a simplified API:
desc <- description$new("tools/pkg2")
desc$get_authors()#> [1] "Hadley Wickham <h.wickham@gmail.com> [aut, cre, cph]"
#> [2] "Peter Danenberg <pcd@roxygen.org> [aut, cph]"
#> [3] "Manuel Eugster [aut, cph]"
#> [4] "RStudio [cph]"
desc$add_author("Bugs", "Bunny", email = "bb@acme.com")
desc$add_me()
desc$add_author_gh("jeroen")
desc$get_authors()#> [1] "Hadley Wickham <h.wickham@gmail.com> [aut, cre, cph]"
#> [2] "Peter Danenberg <pcd@roxygen.org> [aut, cph]"
#> [3] "Manuel Eugster [aut, cph]"
#> [4] "RStudio [cph]"
#> [5] "Bugs Bunny <bb@acme.com>"
#> [6] "First Last <first.last@dom.com> [ctb]"
#> [7] "Jeroen Ooms <jeroen@berkeley.edu> [ctb]"If the Author field is specified, it can be changed to a Authors@R field using coerce_authors_at_r(), incorporating the Maintainer information if necessary:
desc <- description$new("!new")
desc$del("Authors@R")
desc$del("Maintainer")
desc$set(Author = "Gábor Csárdi <csardi.gabor@gmail.com>")
desc$get_authors()#> Error in ensure_authors_at_r(self): No 'Authors@R' field!
#> You can create one with $add_author.
#> You can also use $coerce_authors_at_r() to change Author fields
desc$coerce_authors_at_r()
desc$get_authors()#> [1] "Gábor Csárdi <csardi.gabor@gmail.com> [aut]"The procedural API
The procedural API is simpler to use for one-off DESCRIPTION manipulation, since it does not require dealing with description objects. Each object oriented method has a procedural counterpart that works on a file, and potentially writes its result back to the same file.
For example, adding a new dependency to DESCRIPTION in the current working directory can be done with
desc_set_dep("newpackage", "Suggests")#> Package: desc
#> Title: Manipulate DESCRIPTION Files
#> Version: 1.4.2.9000
#> Authors@R (parsed):
#> * Gábor Csárdi <csardi.gabor@gmail.com> [aut, cre]
#> * Kirill Müller [aut]
#> * Jim Hester <james.f.hester@gmail.com> [aut]
#> * Maëlle Salmon [ctb] (<https://orcid.org/0000-0002-2815-0399>)
#> * Posit Software, PBC [cph, fnd]
#> Maintainer: Gábor Csárdi <csardi.gabor@gmail.com>
#> Description: Tools to read, write, create, and manipulate DESCRIPTION
#> files. It is intended for packages that create or manipulate other
#> packages.
#> License: MIT + file LICENSE
#> URL: https://desc.r-lib.org/, https://github.com/r-lib/desc
#> BugReports: https://github.com/r-lib/desc/issues
#> Depends:
#> R (>= 3.4)
#> Imports:
#> cli,
#> R6,
#> utils
#> Suggests:
#> callr,
#> covr,
#> gh,
#> newpackage,
#> spelling,
#> testthat,
#> whoami,
#> withr
#> Config/Needs/website: tidyverse/tidytemplate
#> Config/testthat/edition: 3
#> Encoding: UTF-8
#> Language: en-US
#> Roxygen: list(r6 = FALSE, load = "installed", markdown = TRUE)
#> RoxygenNote: 7.2.3
#> Collate:
#> 'assertions.R'
#> 'authors-at-r.R'
#> 'built.R'
#> 'classes.R'
#> 'collate.R'
#> 'constants.R'
#> 'deps.R'
#> 'desc-package.R'
#> 'description.R'
#> 'encoding.R'
#> 'find-package-root.R'
#> 'latex.R'
#> 'non-oo-api.R'
#> 'package-archives.R'
#> 'read.R'
#> 'remotes.R'
#> 'str.R'
#> 'syntax_checks.R'
#> 'urls.R'
#> 'utils.R'
#> 'validate.R'
#> 'version.R'This added newpackage to the Suggests field:
desc_get("Suggests")#> Suggests
#> "\n callr,\n covr,\n gh,\n newpackage,\n spelling,\n testthat,\n whoami,\n withr"So the full list of dependencies are now
#> type package version
#> 1 Depends R >= 3.4
#> 2 Imports cli *
#> 3 Imports R6 *
#> 4 Imports utils *
#> 5 Suggests callr *
#> 6 Suggests covr *
#> 7 Suggests gh *
#> 8 Suggests newpackage *
#> 9 Suggests spelling *
#> 10 Suggests testthat *
#> 11 Suggests whoami *
#> 12 Suggests withr *Code of Conduct
Please note that the desc project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.