Title: | Manipulate DESCRIPTION Files |
---|---|
Description: | Tools to read, write, create, and manipulate DESCRIPTION files. It is intended for packages that create or manipulate other packages. |
Authors: | Gábor Csárdi [aut, cre], Kirill Müller [aut], Jim Hester [aut], Maëlle Salmon [ctb] , Posit Software, PBC [cph, fnd] |
Maintainer: | Gábor Csárdi <[email protected]> |
License: | MIT + file LICENSE |
Version: | 1.4.3.9000 |
Built: | 2024-10-27 05:19:46 UTC |
Source: | https://github.com/r-lib/desc |
Syntactical check of a DESCRIPTION field
check_field(x, warn = FALSE, ...)
check_field(x, warn = FALSE, ...)
x |
The field. |
warn |
Whether to generate a warning if the syntax check fails. |
... |
Additional arguments, they might be used in the future. |
TRUE
if the field is syntactically correct,
otherwise a character vector, containing one or multiple
error messages.
The DESCRIPTION fields that are supposed to be in plain ASCII encoding
cran_ascii_fields
cran_ascii_fields
An object of class character
of length 16.
Other field types:
cran_valid_fields
,
dep_types
A list of DESCRIPTION fields that are valid according to the CRAN checks
cran_valid_fields
cran_valid_fields
An object of class character
of length 125.
Other field types:
cran_ascii_fields
,
dep_types
Currently it has the following ones: Imports, Depends, Suggests, Enhances and LinkingTo. See the Writing R Extensions manual for when to use which.
dep_types
dep_types
An object of class character
of length 5.
Other field types:
cran_ascii_fields
,
cran_valid_fields
This is a convenience wrapper for description$new()
.
Very often you want to read an existing DESCRIPTION
file, and to do this you can just supply the path to the file or its
directory to desc()
.
desc(cmd = NULL, file = NULL, text = NULL, package = NULL)
desc(cmd = NULL, file = NULL, text = NULL, package = NULL)
cmd |
A command to create a description from scratch.
Currently only |
file |
Name of the |
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. |
desc(package = "desc") DESCRIPTION <- system.file("DESCRIPTION", package = "desc") desc(DESCRIPTION)
desc(package = "desc") DESCRIPTION <- system.file("DESCRIPTION", package = "desc") desc(DESCRIPTION)
Add an author to Authors@R in DESCRIPTION
desc_add_author( given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_add_author( given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
given |
Given name. |
family |
Family name. |
email |
Email address. |
role |
Role. |
comment |
Comment. |
orcid |
ORCID. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Authors@R:
desc_add_author_gh()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
Uses the Authors@R field.
desc_add_author_gh( username, role = "ctb", comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_add_author_gh( username, role = "ctb", comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
username |
GitHub username of the GitHub user |
role |
Role to set for the user, defaults to contributor. |
comment |
Comment, empty by default. |
orcid |
ORCID, empty by default. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
desc_add_author_gh
is a convenience function, it adds the
GitHub user as an author, and it needs the
gh
package to be installed.
The full name is parsed using
as.person
and collapsing the given name and the family name
in order to e.g. have the first and middle names together as given
name. This approach might be limited to some full name structures.
Other Authors@R:
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
Uses the Authors@R field.
desc_add_me( role = "ctb", comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_add_me( role = "ctb", comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
role |
Role to set for the user, defaults to contributor. |
comment |
Comment, empty by default. |
orcid |
ORCID, empty by default. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
desc_add_me
is a convenience function, it adds the
current user as an author, and it needs the
whoami
package to be installed. It'll add your ORCID ID
if you provide it as argument or save it as ORCID_ID
environment
variable in .Renviron.
The full name is parsed using
as.person
and collapsing the given name and the family name
in order to e.g. have the first and middle names together as given
name. This approach might be limited to some full name structures.
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
The author(s) can be specified by a combination of the given
,
family
, email
, comment
and role
fields.
If multiple filters are specified, then all must match
to identify the author(s).
desc_add_orcid( orcid, given = NULL, family = NULL, email = NULL, comment = NULL, role = NULL, file = ".", normalize = FALSE )
desc_add_orcid( orcid, given = NULL, family = NULL, email = NULL, comment = NULL, role = NULL, file = ".", normalize = FALSE )
orcid |
orcid to add. |
given |
Given name to filter on. Regular expression. |
family |
Family name to filter on. Regular expression. |
email |
Email address to filter on. Regular expression. |
comment |
Comment field to filter on. Regular expression. |
role |
Role field to filter on. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
Add locations in the Remotes field in DESCRIPTION
desc_add_remotes(remotes, file = ".", normalize = FALSE)
desc_add_remotes(remotes, file = ".", normalize = FALSE)
remotes |
Character vector of remote locations to add. Duplicate locations are eliminated. Note that existing locations are not updated, so if you want to change a remote location of a package, you need to delete the old location first and then add the new one. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
The author(s) can be specified by a combination of the given
,
family
, email
, comment
and orcid
fields.
If multiple filters are specified, then all must match
to identify the author(s).
desc_add_role( role, given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_add_role( role, given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
role |
Role to add. |
given |
Given name to filter on. Regular expression. |
family |
Family name to filter on. Regular expression. |
email |
Email address to filter on. Regular expression. |
comment |
Comment field to filter on. Regular expression. |
orcid |
ORCID field to filter on. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
Add one or more files to the Collate field, in DESCRIPTION
desc_add_to_collate( files, which = c("default", "all", "main", "windows", "unix"), file = ".", normalize = FALSE )
desc_add_to_collate( files, which = c("default", "all", "main", "windows", "unix"), file = ".", normalize = FALSE )
files |
Character vector, files to add. |
which |
Which collate field to use. Collate fields can be operating system type specific. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Collate field:
desc_del_collate()
,
desc_del_from_collate()
,
desc_get_collate()
,
desc_set_collate()
Add URLs to the URL field in DESCRIPTION
desc_add_urls(urls, file = ".", normalize = FALSE)
desc_add_urls(urls, file = ".", normalize = FALSE)
urls |
Character vector of URLs to add. Duplicate URLs are eliminated. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
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
.
desc_bump_version(which, file = ".", normalize = FALSE)
desc_bump_version(which, file = ".", normalize = FALSE)
which |
Which component to increase. See details below. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
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.
Other version numbers:
desc_get_version()
,
desc_set_version()
Only works with the Authors@R field.
desc_change_maintainer( given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_change_maintainer( given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
given |
Given name. |
family |
Family name. |
email |
Email address. |
comment |
Comment. |
orcid |
ORCID. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
The current maintainer is kept if they have at least another role.
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
This simply means that the field is deleted.
desc_clear_remotes(file = ".", normalize = FALSE)
desc_clear_remotes(file = ".", normalize = FALSE)
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Remove all URLs from the URL field of DESCRIPTION
desc_clear_urls(file = ".", normalize = FALSE)
desc_clear_urls(file = ".", normalize = FALSE)
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Convert the Author
and Maintainer
fields to
Authors@R
, which is necessary for other functions such as
desc_get_authors()
.
desc_coerce_authors_at_r(file = ".", normalize = FALSE)
desc_coerce_authors_at_r(file = ".", normalize = FALSE)
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
If the Authors@R
field does not exist,
desc_coerce_authors_at_r
tries to parse the Author
and
Maintainer
fields with utils::as.person()
and writes
them to the Authors@R
field.
Note that Author
and Maintainer
are free-form fields, so
parsing them may fail.
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
Remove fields from a DESCRIPTION file
desc_del(keys, file = ".", normalize = FALSE)
desc_del(keys, file = ".", normalize = FALSE)
keys |
Character vector of keys to remove. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other simple queries:
desc_fields()
,
desc_get_field()
,
desc_get()
,
desc_has_fields()
,
desc_set()
It uses the Authors@R field. 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.
desc_del_author( given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_del_author( given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
given |
Given name to filter on. Regular expression. |
family |
Family name to filter on. Regular expression. |
email |
Email address to filter on. Regular expression. |
role |
Role to filter on. Regular expression. |
comment |
Comment field to filter on. Regular expression. |
orcid |
ORCID field to filter on. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
Delete the Collate field from DESCRIPTION
desc_del_collate( which = c("all", "main", "windows", "unix"), file = ".", normalize = FALSE )
desc_del_collate( which = c("all", "main", "windows", "unix"), file = ".", normalize = FALSE )
which |
Which collate field to use. Collate fields can be operating system type specific. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Collate field:
desc_add_to_collate()
,
desc_del_from_collate()
,
desc_get_collate()
,
desc_set_collate()
Remove a package dependency from DESCRIPTION
desc_del_dep( package, type = c("all", desc::dep_types), file = ".", normalize = FALSE )
desc_del_dep( package, type = c("all", desc::dep_types), file = ".", normalize = FALSE )
package |
Package dependency to remove. |
type |
Dependency type to remove. Sometimes a package is depended
on via multiple dependency types, e.g. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other dependencies:
desc_del_deps()
,
desc_get_deps()
,
desc_has_dep()
,
desc_set_deps()
,
desc_set_dep()
Remove all dependencies from DESCRIPTION
desc_del_deps(file = ".", normalize = FALSE)
desc_del_deps(file = ".", normalize = FALSE)
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other dependencies:
desc_del_dep()
,
desc_get_deps()
,
desc_has_dep()
,
desc_set_deps()
,
desc_set_dep()
Remove files from the Collate field.
desc_del_from_collate( files, which = c("all", "main", "windows", "unix"), file = ".", normalize = FALSE )
desc_del_from_collate( files, which = c("all", "main", "windows", "unix"), file = ".", normalize = FALSE )
files |
Files to remove from the Collate field. |
which |
Which collate field to use. Collate fields can be operating system type specific. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Collate field:
desc_add_to_collate()
,
desc_del_collate()
,
desc_get_collate()
,
desc_set_collate()
All locations matching the specified pattern are deleted.
desc_del_remotes(pattern, file = ".", normalize = FALSE)
desc_del_remotes(pattern, file = ".", normalize = FALSE)
pattern |
Perl-compatible regular expression, all locations matching this expression will be deleted. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
The author(s) can be specified by a combination of the given
,
family
, email
, comment
and orcid
fields.
If multiple filters are specified, then all must match
to identify the author(s).
desc_del_role( role, given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
desc_del_role( role, given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL, file = ".", normalize = FALSE )
role |
Role to remove. |
given |
Given name to filter on. Regular expression. |
family |
Family name to filter on. Regular expression. |
email |
Email address to filter on. Regular expression. |
comment |
Comment field to filter on. Regular expression. |
orcid |
ORCID field to filter on. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
All URLs matching the specified pattern are deleted.
desc_del_urls(pattern, file = ".", normalize = FALSE)
desc_del_urls(pattern, file = ".", normalize = FALSE)
pattern |
Perl-compatible regular expression, all URLs matching this expression will be deleted. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
List all fields in a DESCRIPTION file
desc_fields(file = ".")
desc_fields(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Character vector of fields.
Other simple queries:
desc_del()
,
desc_get_field()
,
desc_get()
,
desc_has_fields()
,
desc_set()
Get a field from a DESCRIPTION file
desc_get(keys, file = ".")
desc_get(keys, file = ".")
keys |
Character vector of fields to get. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Character vector, values of the specified keys.
Non-existing keys return NA
.
Other simple queries:
desc_del()
,
desc_fields()
,
desc_get_field()
,
desc_has_fields()
,
desc_set()
Query authors by role in Authors@R, in DESCRIPTION
desc_get_author(role = "cre", file = ".")
desc_get_author(role = "cre", file = ".")
role |
Role to query. Defaults to the package maintainer. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A person object, see utils::person()
.
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_maintainer()
,
desc_set_authors()
Query all authors in Authors@R, in DESCRIPTION
desc_get_authors(file = ".")
desc_get_authors(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A person object, see utils::person()
.
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_author()
,
desc_get_maintainer()
,
desc_set_authors()
If the file has no Built
field then it throws an error.
desc_get_built(file = ".", normalize = FALSE)
desc_get_built(file = ".", normalize = FALSE)
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
A list with fields R
, Platform
, Date
,
OStype
.
Query the Collate field in DESCRIPTION
desc_get_collate(which = c("main", "windows", "unix"), file = ".")
desc_get_collate(which = c("main", "windows", "unix"), file = ".")
which |
Which collate field to use. Collate fields can be operating system type specific. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Character vector of file names.
Other Collate field:
desc_add_to_collate()
,
desc_del_collate()
,
desc_del_from_collate()
,
desc_set_collate()
List all package dependencies from a DESCRIPTION file
desc_get_deps(file = ".")
desc_get_deps(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Data frame with columns: type
(dependency type),
package
, and version
. For non-versioned dependencies
version
is *
.
Other dependencies:
desc_del_deps()
,
desc_del_dep()
,
desc_has_dep()
,
desc_set_deps()
,
desc_set_dep()
desc_get_list()
parses a comma separated list into a character
vector.
desc_get_field( key, default = stop("Field '", key, "' not found"), trim_ws = TRUE, squish_ws = trim_ws, file = "." ) desc_get_or_fail(keys, file = ".") desc_get_list( key, default = stop("Field '", key, "' not found"), sep = ",", trim_ws = TRUE, squish_ws = trim_ws, file = "." )
desc_get_field( key, default = stop("Field '", key, "' not found"), trim_ws = TRUE, squish_ws = trim_ws, file = "." ) desc_get_or_fail(keys, file = ".") desc_get_list( key, default = stop("Field '", key, "' not found"), sep = ",", trim_ws = TRUE, squish_ws = trim_ws, file = "." )
key |
The field to query. |
default |
Value to return if |
trim_ws |
Whether to trim leading and trailing whitespace
from the value. Defaults to |
squish_ws |
Whether to reduce repeated whitespace in the value.
Defaults to |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
keys |
Character vector of fields to get. |
sep |
Separator string for |
Character string, the value of key
, or default
if key
is not found and default
is specified.
Other simple queries:
desc_del()
,
desc_fields()
,
desc_get()
,
desc_has_fields()
,
desc_set()
Either from the Maintainer
or the Authors@R
field.
desc_get_maintainer(file = ".")
desc_get_maintainer(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A character scalar.
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_set_authors()
List the locations in the Remotes field in DESCRIPTION
desc_get_remotes(file = ".")
desc_get_remotes(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A character vectors or remote locations. A length zero vector is returned if there is no Remotes field in the package.
Query the URL field in DESCRIPTION
desc_get_urls(file = ".")
desc_get_urls(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A character vectors or URLs. A length zero vector is returned if there is no URL field in the package.
If the file has no Version
field, or it is an invalid
version string, then it throws an error.
desc_get_version(file = ".")
desc_get_version(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A base::package_version object.
Other version numbers:
desc_bump_version()
,
desc_set_version()
Check for a dependency
desc_has_dep(package, type = c("any", desc::dep_types), file = ".")
desc_has_dep(package, type = c("any", desc::dep_types), file = ".")
package |
The package name. |
type |
A dependency type or “any'. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
A logical scalar.
Other dependencies:
desc_del_deps()
,
desc_del_dep()
,
desc_get_deps()
,
desc_set_deps()
,
desc_set_dep()
Check if some fields are present in a DESCRIPTION file
desc_has_fields(keys, file = ".")
desc_has_fields(keys, file = ".")
keys |
Character vector of keys to check. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Logical vector.
Other simple queries:
desc_del()
,
desc_fields()
,
desc_get_field()
,
desc_get()
,
desc_set()
Re-formats and re-orders fields in DESCRIPTION in a standard way. Reorders the packages alphabetically.
desc_normalize(file = ".")
desc_normalize(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Other repair functions:
desc_reformat_fields()
,
desc_reorder_fields()
Print the contents of a DESCRIPTION file to the screen
desc_print(file = ".")
desc_print(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Reformat the fields in DESCRIPTION in a standard way.
desc_reformat_fields(file = ".")
desc_reformat_fields(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Other repair functions:
desc_normalize()
,
desc_reorder_fields()
Reorder the fields in DESCRIPTION in a standard way.
desc_reorder_fields(file = ".")
desc_reorder_fields(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Other repair functions:
desc_normalize()
,
desc_reformat_fields()
Set one or more fields in a DESCRIPTION file
desc_set(..., check = TRUE, file = ".", normalize = FALSE) desc_set_list(key, list_value, sep = ", ", file = ".", normalize = FALSE)
desc_set(..., check = TRUE, file = ".", normalize = FALSE) desc_set_list(key, list_value, sep = ", ", file = ".", normalize = FALSE)
... |
Values to set, see details below. |
check |
Whether to check the validity of the new fields. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
key |
Key to set in |
list_value |
Character vector, to collapse in
|
sep |
Separator string for |
desc_set()
supports two forms, the first is two unnamed
arguments: the key and its value to set.
The second form requires named arguments: names are used as keys and values as values to set.
desc_set_list()
collapses a character vector into string,
separating the elements by commas.
Other simple queries:
desc_del()
,
desc_fields()
,
desc_get_field()
,
desc_get()
,
desc_has_fields()
Set authors in Authors@R, in DESCRIPTION
desc_set_authors(authors, file = ".", normalize = FALSE)
desc_set_authors(authors, file = ".", normalize = FALSE)
authors |
Authors, to set, a person object, see |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Authors@R:
desc_add_author_gh()
,
desc_add_author()
,
desc_add_me()
,
desc_add_orcid()
,
desc_add_role()
,
desc_change_maintainer()
,
desc_coerce_authors_at_r()
,
desc_del_author()
,
desc_del_role()
,
desc_get_authors()
,
desc_get_author()
,
desc_get_maintainer()
Set the Collate field in DESCRIPTION
desc_set_collate( files, which = c("main", "windows", "unix"), file = ".", normalize = FALSE )
desc_set_collate( files, which = c("main", "windows", "unix"), file = ".", normalize = FALSE )
files |
Collate field to set, as a character vector. |
which |
Which collate field to use. Collate fields can be operating system type specific. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other Collate field:
desc_add_to_collate()
,
desc_del_collate()
,
desc_del_from_collate()
,
desc_get_collate()
Add a package dependency to a DESCRIPTION file
desc_set_dep( package, type = desc::dep_types, version = "*", file = ".", normalize = FALSE )
desc_set_dep( package, type = desc::dep_types, version = "*", file = ".", normalize = FALSE )
package |
Package to depend on. |
type |
Dependency type. |
version |
Version to depend on, for versioned dependencies. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other dependencies:
desc_del_deps()
,
desc_del_dep()
,
desc_get_deps()
,
desc_has_dep()
,
desc_set_deps()
Set all package dependencies in DESCRIPTION
desc_set_deps(deps, file = ".", normalize = FALSE)
desc_set_deps(deps, file = ".", normalize = FALSE)
deps |
Package dependency data frame, in the same format
returned by |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other dependencies:
desc_del_deps()
,
desc_del_dep()
,
desc_get_deps()
,
desc_has_dep()
,
desc_set_dep()
The specified locations replace the current ones. The Remotes field is created if it does not exist currently.
desc_set_remotes(remotes, file = ".", normalize = FALSE)
desc_set_remotes(remotes, file = ".", normalize = FALSE)
remotes |
A character vector of remote locations to set. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
The specified urls replace the current ones. The URL field is created if it does not exist currently.
desc_set_urls(urls, file = ".", normalize = FALSE)
desc_set_urls(urls, file = ".", normalize = FALSE)
urls |
A character vector of urls to set. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Both $set_version()
and $bump_version()
use dots to
separate the version number components.
desc_set_version(version, file = ".", normalize = FALSE)
desc_set_version(version, file = ".", normalize = FALSE)
version |
A string or a base::package_version object. |
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
normalize |
Whether to "normalize" (reorder and reformat) the fields when writing back
the result. See |
Other version numbers:
desc_bump_version()
,
desc_get_version()
Returns the contents of the DESCRIPTION in LaTeX format.
desc_to_latex(file = ".")
desc_to_latex(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
This function is not implemented yet.
desc_validate(file = ".")
desc_validate(file = ".")
file |
DESCRIPTION file to use. By default the DESCRIPTION file of the current package (i.e. the package the working directory is part of) is used. |
Read, write, update, validate DESCRIPTION files
An R6 class.
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.
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_field
is similar to $get
, but it queries a single
field, it returns an unnamed vector if found, and returns the
specified default
value if not. By default it throws an error
if the field is not found.
The complete API reference:
description$get(keys) description$get_field(key, default, trim_ws = TRUE, squish_ws = trim_ws) description$set(..., check = TRUE) description$fields() description$has_fields(keys) description$del(keys)
key
: a character string (length one), the key to query.
default
: If specified and key
is missing, this value
is returned. If not specified, an error is thrown.
trim_ws
: whether to trim leading and trailing whitespace
from the returned value.
squish_ws
: whether to reduce repeated whitespace in the
returned value.
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.
check
: A logical scalar. Whether to check the validity of the
new values.
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
re-formats 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.
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 compulsory:
x$write(file = "DESCRIPTION")
The API:
description$write(file = 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.
description$get_version() description$set_version(version) description$bump_version(which = c("patch", "minor", "major", "dev"))
version
: a string or a base::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
base::package_version object. It throws an error if the
package does not have a Version
field.
$set_version()
takes a string or a base::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.
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 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"))
iles
: 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.
There is a specialized API for the Authors@R
field,
to add and remove authors, update their roles, change the maintainer,
etc.
The API:
description$get_authors() description$set_authors(authors) description$get_author(role) description$get_maintainer() description$coerce_authors_at_r()
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 utils::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.
$coerce_authors_at_r
converts an Author
field to one with
a person
object. This coercion may be necessary for other
functions such as $get_authors
.
description$add_author(given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = NULL) description$add_me(role = "ctb", comment = NULL, orcid = NULL) description$add_author_gh(username, role = "ctb", comment = NULL, orcid = NULL)
Add a new author. The arguments correspond to the arguments of the
utils::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. It'll add your ORCID ID
if you provide it as argument or save it as ORCID_ID
environment
variable in .Renviron.
The full name is parsed by add_me
and add_author_gh
using
as.person
and collapsing the given name and the family name
in order to e.g. have the first and middle names together as given
name. This approach might be limited to some full name structures.
description$del_author(given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = 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, orcid = NULL) description$add_orcid(orcid, given = NULL, family = NULL, email = NULL, comment = NULL, role = NULL) description$del_role(role, given = NULL, family = NULL, email = NULL, comment = NULL, orcid = NULL) description$change_maintainer(given = NULL, family = NULL, email = NULL, comment = NULL, orcid = 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
.
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.
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.
The Built
field is used in binary packages to store information
about when and how a binary package was built.
$get_built()
returns the built information as a list with fields
R
, Platform
, Date
, OStype
. It throws an
error if the package does not have a Built
field.
When creating a description
object, desc
observes the Encoding
field, if present, and uses the specified encoding to parse the file.
Internally, it converts all fields to UTF-8.
When writing a description
object to a file, desc
uses the
Encoding
field (if present), and converts all fields to the specified
encoding.
We suggest that whenever you need to use non-ASCII characters in your package, you use the UTF-8 encoding, for maximum portability.
## 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
## 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