Manipulate DESCRIPTION Files

Tools to read, write, create, and manipulate DESCRIPTION files. It is intended for packages that create or manipulate other packages.


Linux Build Status Windows Build status CRAN RStudio mirror downloads Coverage Status

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

source("https://install-github.me/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 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

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

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

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

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       *

License

MIT © Gábor Csárdi.

News

1.1.1

  • Relax the R >= 3.2.0 dependency, R 3.1.0 is enough now.

1.1.0

  • 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.

1.0.1

  • 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

1.0.0

First public release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("desc")

1.2.0 by Gábor Csárdi, 3 months ago


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


Report a bug at https://github.com/r-lib/desc/issues


Browse source code at https://github.com/cran/desc


Authors: Gábor Csárdi [aut, cre], Kirill Müller [aut], Jim Hester [aut]


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports assertthat, utils, R6, crayon, rprojroot

Suggests covr, testthat, whoami, withr


Imported by DBItest, available, codemetar, cranlike, cyclocomp, document, dynutils, fiery, goodpractice, pkgbuild, pkgdown, pkgload, prodigenr, rhub, roxygen2, usethis.


See at CRAN