README.Rmd

---
output: github_document
---

```{r, setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  tidy = FALSE,
  error = FALSE
)
```

# desc

> Parse DESCRIPTION files

<!-- badges: start -->
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![R-CMD-check](https://github.com/r-lib/desc/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/desc/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/r-lib/desc/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/desc?branch=main)
[![](https://www.r-pkg.org/badges/version/desc)](https://www.r-pkg.org/pkg/desc)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/desc)](https://www.r-pkg.org/pkg/desc)
<!-- badges: end -->

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](#installation)
  - [The object oriented API](#the-oo-api)
    - [Introduction](#introduction)
    - [Loading or creating new `DESCRIPTION` files](#loading-or-creating-new-description-files)
	- [Normalizing `DESCRIPTION` files](#normalizing-description-files)
	- [Querying, changing and removing fields](#querying-changing-and-removing-fields)
	- [Dependencies](#dependencies)
	- [Collate fields](#collate-fields)
	- [Authors](#authors)
  - [The procedural API](#the-procedural-api)
  - [License](#license)

## Installation

```{r, eval = FALSE}
# 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

```{r}
library(desc)
```

### Introduction

The object oriented API uses [R6](https://github.com/r-lib/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:

```{r include = FALSE}
desc <- description$new("tools/pkg1")
```

```{r eval = FALSE}
desc <- description$new()
```

```{r}
desc
```

A new object can also be created from scratch:

```{r}
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:

```{r}
desc$set("Package", "foo")
desc$get("Package")
```

They work with multiple fields as well:

```{r}
desc$set(Package = "bar", Title = "Bar Package")
desc$get(c("Package", "Title"))
```

### Dependencies

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

```{r}
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:

```{r}
desc$set_collate(list.files("../R"))
desc$get_collate()
```

### Authors

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

```{r, include=FALSE}
withr::local_envvar(
  c("FULLNAME" = "First Last", "EMAIL" = "first.last@dom.com")
)
```

```{r}
desc <- description$new("tools/pkg2")
desc$get_authors()
desc$add_author("Bugs", "Bunny", email = "bb@acme.com")
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:

```{r, error = TRUE}
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()
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

```{r}
desc_set_dep("newpackage", "Suggests")
```

This added `newpackage` to the `Suggests` field:

```{r}
desc_get("Suggests")
```

So the full list of dependencies are now

```{r}
desc_get_deps()
```

```{r include = FALSE}
desc_del_dep("newpackage")
```

## Code of Conduct

Please note that the desc project is released with a
[Contributor Code of Conduct](https://desc.r-lib.org/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.