Tools to read, write, create, and manipulate DESCRIPTION files. It is intended for packages that create or manipulate other packages.
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.
source("https://install-github.me/r-lib/desc")
library(desc)
The object oriented API uses R6 classes.
DESCRIPTION
filesA new description
object can be created by reading a DESCRPTION
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:
#> testthat,
#> whoami,
#> newpackage
#> 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
#> [email protected] (parsed):
#> * Jo Doe <[email protected]> [aut, cre]
#> Maintainer: {{ Maintainer }}
#> Description: {{ Description }}
#> License: {{ License }}
#> URL: {{ URL }}
#> BugReports: {{ BugReports }}
#> Encoding: UTF-8
#> LazyData: true
DESCRIPTION
filesMost 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 R6 *
#> 5 Imports mvtnorm *
#> 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:
#> R6,
#> mvtnorm
#> Suggests:
#> testthat,
#> whoami,
#> newpackage
#> 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"))desc$get_collate()
#> [1] "assertions.R" "authors-at-r.R" "classes.R"
#> [4] "collate.R" "constants.R" "deps.R"
#> [7] "description.R" "encoding.R" "latex.R"
#> [10] "non-oo-api.R" "package-archives.R" "read.R"
#> [13] "remotes.R" "str.R" "syntax_checks.R"
#> [16] "urls.R" "utils.R" "validate.R"
#> [19] "version.R"
Authors information, when specified via the [email protected]
field,
also has a simplified API:
desc <- description$new("DESCRIPTION2")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$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]"
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.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:
#> testthat,
#> whoami,
#> newpackage
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 5.0.0
This added newpackage
to the Suggests
field:
desc_get("Suggests")
#> Suggests
#> "\n testthat,\n whoami,\n newpackage"
So the full list of dependencies are now
desc_get_deps()
#> type package version
#> 1 Suggests testthat *
#> 2 Suggests whoami *
#> 3 Suggests newpackage *
#> 4 Imports R6 *
MIT © Gábor Csárdi, RStudio Inc
Add get_field()
method, with easier to use failure and fallback
semantics (#62)
Use the Encoding
field to read and write DESCRIPTION with the
corect encoding. UTF-8 is always used internall by desc. (#52, #53)
Add get_built()
function to parse the Built field used in package
binaries. (#48, @jimhester)
get_deps()
(and desc_get_deps()
) return a zero-row data frame
instead of NULL
for packages without any dependencies, for consistency.
Empty DESCRIPTION
files are handled more gracefully, as are querying
no fields with desc_get()
Remotes
, VignetteBuilder
and RdMacros
fields are syntax checked.
(#59, @krlmlr)
Account for non-URL content in the URL
field (#57, @jennybc)
Allow for IETF region subtag in Language
field (#55, @jeroen)
Fix continuation lines in output
get_deps()
returns empty data frame if no dependencies, instead of
NULL
Fix bug when adding authors and there is no [email protected]
field
Get DESCRIPTION
from package archives (#40)
Fix but in del_dep()
and has_dep()
, they only worked if the package
was attached.
Fix formatting of Collate
fields, they always start at a new line now.
Fix formatting of [email protected]
fields, when changed.
Keep trailing space after the :
character, see #14
First public release.