Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/r-lib/desc

Manipulate DESCRIPTION files
https://github.com/r-lib/desc

r

Last synced: 1 day ago
JSON representation

Manipulate DESCRIPTION files

Awesome Lists containing this project

README 

        
---

output: github_document

---



```{r, setup, echo = FALSE, message = FALSE}

knitr::opts_chunk$set(

  comment = "#>",

  tidy = FALSE,

  error = FALSE

)

```



# desc



> Parse DESCRIPTION files



[![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)



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" = "[email protected]")

)

```



```{r}

desc <- description$new("tools/pkg2")

desc$get_authors()

desc$add_author("Bugs", "Bunny", email = "[email protected]")

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

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.