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 <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:
#>     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
#> Authors@R (parsed):
#>     * Jo Doe <jodoe@dom.ain> [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 <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,
#>     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"     "built.R"           
#>  [4] "classes.R"          "collate.R"          "constants.R"       
#>  [7] "deps.R"             "description.R"      "encoding.R"        
#> [10] "latex.R"            "non-oo-api.R"       "package-archives.R"
#> [13] "read.R"             "remotes.R"          "str.R"             
#> [16] "syntax_checks.R"    "urls.R"             "utils.R"           
#> [19] "validate.R"         "version.R"

Authors

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

desc <- description$new("DESCRIPTION2")
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$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] "John Muschelli III <muschellij2@gmail.com> [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:

tfile <- tempfile()
dir.create(tfile)
package.skeleton(name = "pkg", path = tfile)
desc <- description$new(file.path(tfile, "pkg", "DESCRIPTION"))
desc

#> Type: Package
#> Package: pkg
#> Title: What the package does (short line)
#> Version: 1.0
#> Date: 2018-05-08
#> Author: Who wrote it
#> Maintainer: Who to complain to <yourfault@somewhere.net>
#> Description: More about what it does (maybe more than one line)
#> License: What license is it under?

desc$coerce_authors_at_r()
desc

#> Type: Package
#> Package: pkg
#> Title: What the package does (short line)
#> Version: 1.0
#> Date: 2018-05-08
#> Authors@R (parsed):
#>     * Who to complain to <yourfault@somewhere.net> [cre]
#>     * Who wrote it [aut]
#> Author: Who wrote it
#> Maintainer: Who to complain to <yourfault@somewhere.net>
#> Description: More about what it does (maybe more than one line)
#> License: What license is it under?

If you run get_authors() without conversion, then an error will result.