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.
install.packages("desc")library(desc)The object oriented API uses R6 classes.
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 <[email protected]>
#> 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.0
A 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 <[email protected]> [aut, cre]
#> Maintainer: {{ Maintainer }}
#> Description: {{ Description }}
#> License: {{ License }}
#> URL: {{ URL }}
#> BugReports: {{ BugReports }}
#> Encoding: UTF-8
#> LazyData: true
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.
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"
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 <[email protected]>
#> 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.0
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 information, when specified via the Authors@R field, also has
a simplified API:
desc <- description$new("tools/pkg2")
desc$get_authors()#> [1] "Hadley Wickham <[email protected]> [aut, cre, cph]"
#> [2] "Peter Danenberg <[email protected]> [aut, cph]"
#> [3] "Manuel Eugster [aut, cph]"
#> [4] "RStudio [cph]"
desc$add_author("Bugs", "Bunny", email = "[email protected]")
desc$add_me()
desc$add_author_gh("jeroen")
desc$get_authors()#> [1] "Hadley Wickham <[email protected]> [aut, cre, cph]"
#> [2] "Peter Danenberg <[email protected]> [aut, cph]"
#> [3] "Manuel Eugster [aut, cph]"
#> [4] "RStudio [cph]"
#> [5] "Bugs Bunny <[email protected]>"
#> [6] "Gabor Csardi <[email protected]> [ctb]"
#> [7] "Jeroen Ooms <[email protected]> [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 <[email protected]>")
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 <[email protected]> [aut]"
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.2.0.9000
#> Authors@R (parsed):
#> * Gábor Csárdi <[email protected]> [aut, cre]
#> * Kirill Müller [aut]
#> * Jim Hester <[email protected]> [aut]
#> * Maëlle Salmon [ctb] (<https://orcid.org/0000-0002-2815-0399>)
#> Maintainer: Gábor Csárdi <[email protected]>
#> 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://github.com/r-lib/desc#readme
#> BugReports: https://github.com/r-lib/desc/issues
#> Depends:
#> R (>= 3.1.0)
#> Imports:
#> crayon,
#> R6,
#> rprojroot,
#> utils
#> Suggests:
#> covr,
#> gh,
#> newpackage,
#> spelling,
#> testthat,
#> whoami,
#> withr
#> Encoding: UTF-8
#> Language: en-US
#> LazyData: true
#> Roxygen: list(r6 = FALSE, load = "installed")
#> RoxygenNote: 7.1.1.9000
#> Collate:
#> 'assertions.R'
#> 'authors-at-r.R'
#> 'built.R'
#> 'classes.R'
#> 'collate.R'
#> 'constants.R'
#> 'deps.R'
#> 'description.R'
#> 'encoding.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 covr,\n testthat,\n whoami,\n withr,\n spelling,\n gh,\n newpackage"
So the full list of dependencies are now
desc_get_deps()#> type package version
#> 1 Depends R >= 3.1.0
#> 2 Suggests covr *
#> 3 Suggests testthat *
#> 4 Suggests whoami *
#> 5 Suggests withr *
#> 6 Suggests spelling *
#> 7 Suggests gh *
#> 8 Suggests newpackage *
#> 9 Imports utils *
#> 10 Imports R6 *
#> 11 Imports crayon *
#> 12 Imports rprojroot *
MIT © Gábor Csárdi, RStudio Inc