R: Read, write, update, validate DESCRIPTION files

description {desc} | R Documentation

## Read, write, update, validate DESCRIPTION files

### Description

Read, write, update, validate DESCRIPTION files

### Usage

    description

### Format

An R6 class.

### Constructors

There are two ways of creating a description object. The first is reading an already existing `DESCRIPTION` file; simply give the name of the file as an argument. The default is `DESCRIPTION`:

      x <- description$new()
      x2 <- description$new("path/to/DESCRIPTION")

The second way is creating a description object from scratch, supply `"!new"` as an argument to do this.

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

The complete API reference:

    description$new(cmd = NULL, file = NULL, text = NULL,
        package = NULL)

cmd:

  A command to create a description from scratch. Currently only `"!new"` is implemented. If it does not start with an exclamation mark, it will be interpreted as a ‘file’ argument.

file:

  Name of the `DESCRIPTION` file to load. If it is a directory, then we assume that it is inside an R package and conduct a search for the package root directory, i.e. the first directory up the tree that contains a `DESCRIPTION` file. If ‘cmd’, ‘file’, ‘text’ and ‘package’ are all `NULL` (the default), then the search is started from the working directory. The file can also be an R package (source, or binary), in which case the DESCRIPTION file is extracted from it, but note that in this case `$write()` cannot write the file back in the package archive.

text:

  A character scalar containing the full DESCRIPTION. Character vectors are collapsed into a character scalar, with newline as the separator.

package

  If not NULL, then the name of an installed package and the DESCRIPTION file of this package will be loaded.

### Setting and Querying fields

Set a field with `$set` and query it with `$get`:

      x <- description$new("!new")
      x$get("Package)
      x$set("Package", "foobar")
      x$set(Title = "Example Package for 'description'")
      x$get("Package")

Note that `$set` has two forms. You can either give the field name and new value as two arguments; or you can use a single named argument, the argument name is the field name, the argument value is the field value.

The `$fields` method simply lists the fields in the object:

      x$fields()

The `$has_fields` method checks if one or multiple fields are present in a description object:

      x$has_fields("Package")
      x$has_fields(c("Title", "foobar"))

The `$del` method removes the specified fields:

      x$set(foo = "bar")
      x$del("foo")

`$get_or_fail` is similar to `$get`, but throws an error if a field does not exist, except of silently returning `NA_character`.

The complete API reference:

      description$get(keys)
      description$get_or_fail(keys)
      description$set(...)
      description$fields()
      description$has_fields(keys)
      description$del(keys)

keys:

  A character vector of keys to query, check or delete.

...:

  This must be either two unnamed arguments, the key and and the value to set; or an arbitrary number of named arguments, names are used as keys, values as values to set.

### Normalizing

Format DESCRIPTION in a standard way. `$str` formats each field in a standard way and returns them (it does not change the object itself), `$print` is used to print it to the screen. The `$normalize` function normalizes each field (i.e. it changes the object). Normalization means reformatting the fields, via `$reformat_fields()` and also reordering them via `$reorder_fields()`. The format of the various fields is opinionated and you might like it or not. Note that `desc` only reformats fields that it updates, and only on demand, so if your formatting preferences differ, you can still manually edit `DESCRIPTION` and `desc` will respect your edits.

      description$str(by_field = FALSE, normalize = TRUE,
        mode = c("file", "screen"))
      description$normalize()
      description$reformat_fields()
      description$reorder_fields()
      description$print()

by_field:

  Whether to return the normalized format by field, or collapsed into a character scalar.

normalize:

  Whether to reorder and reformat the fields.

mode:

  ‘file’ mode formats the fields as they are written to a file with the `write` method. ‘screen’ mode adds extra markup to some fields, e.g. formats the `Authors@R` field in a readable way.

### Writing it to file

The `$write` method writes the description to a file. By default it writes it to the file it was created from, if it was created from a file. Otherwise giving a file name is compulsary:

      x$write(file = "DESCRIPTION")

The `normalize` argument controls whether the fields are reformatted according to a standard style. By default they are not.

The API:

      description$write(file = NULL, normalize = NULL)

file:

  Path to write the description to. If it was created from a file in the first place, then it is written to the same file. Otherwise this argument must be specified.

normalize:

  Whether to reformat the fields in a standard way.

### Version numbers

      description$get_version()
      description$set_version(version)
      description$bump_version(which = c("patch", "minor", "major", "dev"))

version:

  A string or a `package_version` object.

which:

  Which component of the version number to increase. See details just below.

These functions are simple helpers to make it easier to query, set and increase the version number of a package.

`$get_version()` returns the version number as a `package_version` object. It throws an error if the package does not have a ‘Version’ field.

`$set_version()` takes a string or a `package_version` object and sets the ‘Version’ field to it.

`$bump_version()` increases the version number. The `which` parameter specifies which component to increase. It can be a string referring to a component: ‘major’, ‘minor’, ‘patch’ or ‘dev’, or an integer scalar, for the latter components are counted from one, and the beginning. I.e. component one is equivalent to ‘major’.

If a component is bumped, then the ones after it are zeroed out. Trailing zero components are omitted from the new version number, but if the old version number had at least two or three components, then the one will also have two or three.

The bumping of the ‘dev’ version (the fourth component) is special: if the original version number had less than four components, and the ‘dev’ version is bumped, then it is set to `9000` instead of `1`. This is a convention often used by R developers, it was originally invented by Winston Chang.

Both `$set_version()` and `$bump_version()` use dots to separate the version number components.

### Dependencies

These functions handle the fields that define how the R package uses another R packages. See `dep_types` for the list of fields in this group.

The `$get_deps` method returns all declared dependencies, in a data frame with columns: `type`, `package` and `version`. `type` is the name of the dependency field, `package` is the name of the R package, and `version` is the required version. If no specific versions are required, then this is a `"\*"`.

The `$set_deps` method is the opposite of `$get_deps` and it sets all dependencies. The input is a data frame, with the same structure as the return value of `$get_deps`.

The `$has_dep` method checks if a package is included in the dependencies. It returns a logical scalar. If `type` is not ‘any’, then it has to match as well.

The `$del_deps` method removes all declared dependencies.

The `$set_dep` method adds or updates a single dependency. By default it adds the package to the `Imports` field.

The API:

      description$set_dep(package, type = dep_types, version = "\*")
      description$set_deps(deps)
      description$get_deps()
      description$has_dep(package, type = c("any", dep_types))
      description$del_dep(package, type = c("all", dep_types))
      description$del_deps()

package:

  Name of the package to add to or remove from the dependencies.

type:

  Dependency type, see `dep_types`. For `$del_dep` it may also be `"all"`, and then the package will be deleted from all dependency types.

version:

  Required version. Defaults to `"\*"`, which means no explicit version requirements.

deps:

  A data frame with columns `type`, `package` and `version`. `$get_deps` returns the same format.

### Collate fields

Collate fields contain lists of file names with R source code, and the package has a separate API for them. In brief, you can use `$add_to_collate` to add one or more files to the main or other collate field. You can use `$del_from_collate` to remove it from there.

The API:

      description$set_collate(files, which = c("main", "windows", "unix"))
      description$get_collate(which = c("main", "windows", "unix"))
      description$del_collate(which = c("all", "main", "windows", "unix"))
      description$add_to_collate(files, which = c("default", "all", "main",
        "windows", "unix"))
      description$del_from_collate(files, which = c("all", "main",
        "windows", "unix"))

files:

  The files to add or remove, in a character vector.

which:

  Which collate field to manipulate. `"default"` for `$add_to_collate` means all existing collate fields, or the main one if none exist.

### Authors

There is a specialized API for the `Authors@R` field, to add and remove authors, udpate their roles, change the maintainer, etc.

The API:

      description$get_authors()
      description$set_authors(authors)
      description$get_author(role)
      description$get_maintainer()

authors:

  A `person` object, a list of authors.

role:

  The role to query. See `person` for details.

`$get_authors` returns a `person` object, the parsed authors. See `person` for details.

`$get_author` returns a `person` object, all authors with the specified role.

`$get_maintainer` returns the maintainer of the package. It works with `Authors@R` fields and with traditional `Maintainer` fields as well.

      description$add_author(given = NULL, family = NULL, email = NULL,
        role = NULL, comment = NULL)
      description$add_me(role = "ctb", comment = NULL)

Add a new author. The arguments correspond to the arguments of the `person` function. `add_me` is a convenience function, it adds the current user as an author, and it needs the `whoami` package to be installed.

      description$del_author(given = NULL, family = NULL, email = NULL,
        role = NULL, comment = NULL)

Remove an author, or multiple authors. The author(s) to be removed can be specified via any field(s). All authors matching all specifications will be removed. E.g. if only `given = "Joe"` is supplied, then all authors whole given name matches `Joe` will be removed. The specifications can be (PCRE) regular expressions.

      description$add_role(role, given = NULL, family = NULL, email = NULL,
        comment = NULL)
      description$del_role(role, given = NULL, family = NULL, email = NULL,
         comment = NULL)
      description$change_maintainer(given = NULL, family = NULL,
        email = NULL, comment = NULL)

`role` is the role to add or delete. The other arguments are used to select a subset of the authors, on which the operation is performed, similarly to `$del_author`.

### URLs

We provide helper functions for manipulating URLs in the `URL` field:

      description$get_urls()
      description$set_urls(urls)
      description$add_urls(urls)
      description$del_urls(pattern)
      description$clear_urls()

urls:

  Character vector of URLs to set or add.

pattern:

  Perl compatible regular expression to specify the URLs to be removed.

`$get_urls()` returns all urls in a character vector. If no URL fields are present, a zero length vector is returned.

`$set_urls()` sets the URL field to the URLs specified in the character vector argument.

`$add_urls()` appends the specified URLs to the URL field. It creates the field if it does not exists. Duplicate URLs are removed.

`$del_urls()` deletes the URLs that match the specified pattern.

`$clear_urls()` deletes all URLs.

### Remotes

`devtools`, `remotes` and some other packages support the non-standard `Remotes` field in `DESCRIPTION`. This field can be used to specify locations of dependent packages: GitHub or BitBucket repositories, generic git repositories, etc. Please see the ‘Package remotes’ vignette in the `devtools` package.

`desc` has helper functions for manipulating the `Remotes` field:

      description$get_remotes()
      description$get_remotes()
      description$set_remotes(remotes)
      description$add_remotes(remotes)
      description$del_remotes(pattern)
      description$clear_remotes()

remotes:

  Character vector of remote dependency locations to set or add.

pattern:

  Perl compatible regular expression to specify the remote dependency locations to remove.

`$get_remotes()` returns all remotes in a character vector. If no URL fields are present, a zero length vector is returned.

`$set_remotes()` sets the URL field to the Remotes specified in the character vector argument.

`$add_remotes()` appends the specified remotes to the `Remotes` field. It creates the field if it does not exists. Duplicate remotes are removed.

`$del_remotes()` deletes the remotes that match the specified pattern.

`$clear_remotes()` deletes all remotes.

### Examples

    ## Create a template
    desc <- description$new("!new")
    desc

    ## Read a file
    desc2 <- description$new(file = system.file("DESCRIPTION",
                               package = "desc"))
    desc2

    ## Remove a field
    desc2$del("LazyData")

    ## Add another one
    desc2$set(VignetteBuilder = "knitr")
    desc2$get("VignetteBuilder")
    desc2

[Package desc version 1.1.0 Index]