In metacran/desc: Manipulate DESCRIPTION Files

knitr::opts_chunk$set(
  comment = "#>",
  tidy = FALSE,
  error = FALSE
)

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
• The object oriented API
  • Introduction
  • Loading or creating new DESCRIPTION files
  • Normalizing DESCRIPTION files
  • Querying, changing and removing fields
  • Dependencies
  • Collate fields
  • Authors
• The procedural API
• License

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("tools/pkg1")

desc <- description$new()

desc

A new object can also be created from scratch:

desc2 <- description$new("!new")
desc2

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")

They work with multiple fields as well:

desc$set(Package = "bar", Title = "Bar Package")
desc$get(c("Package", "Title"))

Dependencies

Package dependencies can be set and updated via an easier API:

desc$get_deps()
desc$set_dep("mvtnorm")
desc$set_dep("Rcpp", "LinkingTo")
desc$get_deps()
desc

Collate fields

Collate fields can be queried and set using simple character vectors of file names:

desc$set_collate(list.files("../R"))
desc$get_collate()

Authors

Authors information, when specified via the Authors@R field, also has a simplified API:

withr::local_envvar(
  c("FULLNAME" = "First Last", "EMAIL" = "[e-mail]")
)

desc <- description$new("tools/pkg2")
desc$get_authors()
desc$add_author("Bugs", "Bunny", email = "[e-mail]")
desc$add_me()
desc$add_author_gh("jeroen")
desc$get_authors()

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 <[e-mail]>")
desc$get_authors()
desc$coerce_authors_at_r()
desc$get_authors()

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")

This added newpackage to the Suggests field:

desc_get("Suggests")

So the full list of dependencies are now

desc_get_deps()

desc_del_dep("newpackage")

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.

metacran/desc documentation built on Jan. 16, 2024, 4:31 a.m.