Learn R Programming

desc

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

library(desc)

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.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 <jodoe@dom.ain> [aut, cre]
#> Maintainer: {{ Maintainer }}
#> Description: {{ Description }}
#> License: {{ License }}
#> URL: {{ URL }}
#> BugReports: {{ BugReports }}
#> Encoding: UTF-8

Normalizing 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.0

Collate 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

desc_get_deps()
#>        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.

Copy Link

Version

Install

install.packages('desc')

Monthly Downloads

470,859

Version

1.4.3

License

MIT + file LICENSE

Issues

15

Pull Requests

0

Stars

125

Forks

29

Maintainer

Gabor Csardi

Last Published

December 10th, 2023

Functions in desc (1.4.3)

desc_del

Remove fields from a DESCRIPTION file
desc

Read a DESCRIPTION file
desc_get_remotes

List the locations in the Remotes field in DESCRIPTION
desc_change_maintainer

Change maintainer of the package, in DESCRIPTION
desc_get_urls

Query the URL field in DESCRIPTION
desc_del_author

Remove one or more authors from DESCRIPTION.
desc_clear_urls

Remove all URLs from the URL field of DESCRIPTION
desc_del_deps

Remove all dependencies from DESCRIPTION
desc_get_deps

List all package dependencies from a DESCRIPTION file
desc_add_role

Add a role to one or more authors in Authors@R, in DESCRIPTION
desc_coerce_authors_at_r

Coerce Author and Maintainer Fields to Authors@R
desc_clear_remotes

Remove all locations from the Remotes field of DESCRIPTION
desc_del_from_collate

Remove files from the Collate field.
desc_add_urls

Add URLs to the URL field in DESCRIPTION
desc_get_collate

Query the Collate field in DESCRIPTION
desc_get_field

Get a single field from a DESCRIPTION file, fail if not found
desc_del_urls

Delete URLs from the URL field in DESCRIPTION
desc_add_to_collate

Add one or more files to the Collate field, in DESCRIPTION
desc_get_maintainer

Query the package maintainer in DESCRIPTION
desc_get_authors

Query all authors in Authors@R, in DESCRIPTION
desc_fields

List all fields in a DESCRIPTION file
desc_get_author

Query authors by role in Authors@R, in DESCRIPTION
desc_del_role

Delete a role of an author, in DESCRIPTION
desc_del_remotes

Delete locations from the Remotes field in DESCRIPTION
desc_get

Get a field from a DESCRIPTION file
desc_reorder_fields

Reorder fields in a DESCRIPTION file
desc_get_built

Query the built field in DESCRIPTION
desc_set

Set one or more fields in a DESCRIPTION file
desc_normalize

Normalize a DESCRIPTION file
desc_set_authors

Set authors in Authors@R, in DESCRIPTION
desc_has_fields

Check if some fields are present in a DESCRIPTION file
desc_set_collate

Set the Collate field in DESCRIPTION
desc_set_dep

Add a package dependency to a DESCRIPTION file
desc_set_deps

Set all package dependencies in DESCRIPTION
desc_print

Print the contents of a DESCRIPTION file to the screen
desc_reformat_fields

Reformat fields in a DESCRIPTION file
desc_validate

Validate a DESCRIPTION file
description

Read, write, update, validate DESCRIPTION files
desc_set_remotes

Set the Remotes field in DESCRIPTION
desc_set_urls

Set the URL field in DESCRIPTION
desc_del_collate

Delete the Collate field from DESCRIPTION
desc_del_dep

Remove a package dependency from DESCRIPTION
desc_bump_version

Increase the version number in DESCRIPTION
desc_to_latex

Converts a DESCRIPTION file to LaTeX
desc_set_version

Set the package version in DESCRIPTION
desc_get_version

Query the package version in DESCRIPTION
desc_has_dep

Check for a dependency
dep_types

DESCRIPTION fields that denote package dependencies
desc_add_author_gh

Add a GitHub user as an author to DESCRIPTION
desc_add_author

Add an author to Authors@R in DESCRIPTION
desc_add_orcid

Add an ORCID to one or more authors in Authors@R, in DESCRIPTION
cran_valid_fields

A list of DESCRIPTION fields that are valid according to the CRAN checks
cran_ascii_fields

The DESCRIPTION fields that are supposed to be in plain ASCII encoding
desc-package

desc: Manipulate DESCRIPTION Files
check_encoding

Check encoding of new or existing fields
desc_add_me

Add the current user as an author to DESCRIPTION
check_field

Syntactical check of a DESCRIPTION field
desc_add_remotes

Add locations in the Remotes field in DESCRIPTION