EVOLUTION-MANAGER
Edit File: description.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Read, write, update, validate DESCRIPTION files</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for description {desc}"><tr><td>description {desc}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Read, write, update, validate DESCRIPTION files</h2> <h3>Description</h3> <p>Read, write, update, validate DESCRIPTION files </p> <h3>Format</h3> <p>An R6 class. </p> <h3>Constructors</h3> <p>There are two ways of creating a description object. The first is reading an already existing <code>DESCRIPTION</code> file; simply give the name of the file as an argument. The default is <code>DESCRIPTION</code>: </p> <div class="sourceCode r"><pre>x <- description$new() x2 <- description$new("path/to/DESCRIPTION") </pre></div> <p>The second way is creating a description object from scratch, supply <code>"!new"</code> as an argument to do this. </p> <div class="sourceCode r"><pre>x3 <- description$new("!new") </pre></div> <p>The complete API reference: </p> <div class="sourceCode r"><pre>description$new(cmd = NULL, file = NULL, text = NULL, package = NULL) </pre></div> <ul> <li> <p><code>cmd</code>: a command to create a description from scratch. Currently only <code>"!new"</code> is implemented. If it does not start with an exclamation mark, it will be interpreted as a <code>file</code> argument. </p> </li> <li> <p><code>file</code>: name of the <code>DESCRIPTION</code> 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 <code>DESCRIPTION</code> file. If <code>cmd</code>, <code>file</code>, <code>text</code> and <code>package</code> are all <code>NULL</code> (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 <code>DESCRIPTION</code> file is extracted from it, but note that in this case <code style="white-space: pre;">$write()</code> cannot write the file back in the package archive. </p> </li> <li> <p><code>text</code>: a character scalar containing the full DESCRIPTION. Character vectors are collapsed into a character scalar, with newline as the separator. </p> </li> <li> <p><code>package</code>: if not NULL, then the name of an installed package and the DESCRIPTION file of this package will be loaded. </p> </li></ul> <h3>Setting and Querying fields</h3> <p>Set a field with <code style="white-space: pre;">$set</code> and query it with <code style="white-space: pre;">$get</code>: </p> <div class="sourceCode r"><pre>x <- description$new("!new") x$get("Package") x$set("Package", "foobar") x$set(Title = "Example Package for 'description'") x$get("Package") </pre></div> <p>Note that <code style="white-space: pre;">$set</code> 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. </p> <p>The <code style="white-space: pre;">$fields</code> method simply lists the fields in the object: </p> <div class="sourceCode r"><pre>x$fields() </pre></div> <p>The <code style="white-space: pre;">$has_fields</code> method checks if one or multiple fields are present in a description object: </p> <div class="sourceCode r"><pre>x$has_fields("Package") x$has_fields(c("Title", "foobar")) </pre></div> <p>The <code style="white-space: pre;">$del</code> method removes the specified fields: </p> <div class="sourceCode r"><pre>x$set(foo = "bar") x$del("foo") </pre></div> <p><code style="white-space: pre;">$get_field</code> is similar to <code style="white-space: pre;">$get</code>, but it queries a single field, it returns an unnamed vector if found, and returns the specified <code>default</code> value if not. By default it throws an error if the field is not found. </p> <p>The complete API reference: </p> <div class="sourceCode r"><pre>description$get(keys) description$get_field(key, default, trim_ws = TRUE, squish_ws = trim_ws) description$set(...) description$fields() description$has_fields(keys) description$del(keys) </pre></div> <ul> <li> <p><code>key</code>: a character string (length one), the key to query. </p> </li> <li> <p><code>default</code>: If specified and <code>key</code> is missing, this value is returned. If not specified, an error is thrown. </p> </li> <li> <p><code>trim_ws</code>: whether to trim leading and trailing whitespace from the returned value. </p> </li> <li> <p><code>squish_ws</code>: whether to reduce repeated whitespace in the returned value. </p> </li> <li> <p><code>keys</code>: a character vector of keys to query, check or delete. </p> </li> <li> <p><code>...</code>: 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. </p> </li></ul> <h3>Normalizing</h3> <p>Format DESCRIPTION in a standard way. <code style="white-space: pre;">$str</code> formats each field in a standard way and returns them (it does not change the object itself), <code style="white-space: pre;">$print</code> is used to print it to the screen. The <code style="white-space: pre;">$normalize</code> function normalizes each field (i.e. it changes the object). Normalization means reformatting the fields, via <code style="white-space: pre;">{$reformat_fields()</code> and also reordering them via <code style="white-space: pre;">$reorder_fields()</code>. The format of the various fields is opinionated and you might like it or not. Note that <code>desc</code> only re-formats fields that it updates, and only on demand, so if your formatting preferences differ, you can still manually edit <code>DESCRIPTION</code> and <code>desc</code> will respect your edits. </p> <div class="sourceCode r"><pre>description$str(by_field = FALSE, normalize = TRUE, mode = c("file", "screen")) description$normalize() description$reformat_fields() description$reorder_fields() description$print() </pre></div> <ul> <li> <p><code>by_field</code>: whether to return the normalized format by field, or collapsed into a character scalar. </p> </li> <li> <p><code>normalize</code>: whether to reorder and reformat the fields. </p> </li> <li> <p><code>mode</code>: <code>file</code> mode formats the fields as they are written to a file with the <code>write</code> method. <code>screen</code> mode adds extra markup to some fields, e.g. formats the <code>Authors@R</code> field in a readable way. </p> </li></ul> <h3>Writing it to file</h3> <p>The <code style="white-space: pre;">$write</code> 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: </p> <div class="sourceCode r"><pre>x$write(file = "DESCRIPTION") </pre></div> <p>The API: </p> <div class="sourceCode r"><pre>description$write(file = NULL) </pre></div> <ul> <li> <p><code>file</code>: 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. </p> </li></ul> <h3>Version numbers</h3> <div class="sourceCode r"><pre>description$get_version() description$set_version(version) description$bump_version(which = c("patch", "minor", "major", "dev")) </pre></div> <ul> <li> <p><code>version</code>: a string or a <a href="../../base/html/numeric_version.html">base::package_version</a> object. </p> </li> <li> <p><code>which</code>: which component of the version number to increase. See details just below. </p> </li></ul> <p>These functions are simple helpers to make it easier to query, set and increase the version number of a package. </p> <p><code style="white-space: pre;">$get_version()</code> returns the version number as a <a href="../../base/html/numeric_version.html">base::package_version</a> object. It throws an error if the package does not have a <code>Version</code> field. </p> <p><code style="white-space: pre;">$set_version()</code> takes a string or a <a href="../../base/html/numeric_version.html">base::package_version</a> object and sets the <code>Version</code> field to it. </p> <p><code style="white-space: pre;">$bump_version()</code> increases the version number. The <code>which</code> parameter specifies which component to increase. It can be a string referring to a component: <code>major</code>, <code>minor</code>, <code>patch</code> or <code>dev</code>, or an integer scalar, for the latter components are counted from one, and the beginning. I.e. component one is equivalent to <code>major</code>. </p> <p>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. </p> <p>The bumping of the <code>dev</code> version (the fourth component) is special: if the original version number had less than four components, and the <code>dev</code> version is bumped, then it is set to <code>9000</code> instead of <code>1</code>. This is a convention often used by R developers, it was originally invented by Winston Chang. </p> <p>Both <code style="white-space: pre;">$set_version()</code> and <code style="white-space: pre;">$bump_version()</code> use dots to separate the version number components. </p> <h3>Dependencies</h3> <p>These functions handle the fields that define how the R package uses another R packages. See <a href="dep_types.html">dep_types</a> for the list of fields in this group. </p> <p>The <code style="white-space: pre;">$get_deps</code> method returns all declared dependencies, in a data frame with columns: <code>type</code>, <code>package</code> and <code>version</code>. <code>type</code> is the name of the dependency field, <code>package</code> is the name of the R package, and <code>version</code> is the required version. If no specific versions are required, then this is a <code>"*"</code>. </p> <p>The <code style="white-space: pre;">$set_deps</code> method is the opposite of <code style="white-space: pre;">$get_deps</code> and it sets all dependencies. The input is a data frame, with the same structure as the return value of <code style="white-space: pre;">$get_deps</code>. </p> <p>The <code style="white-space: pre;">$has_dep</code> method checks if a package is included in the dependencies. It returns a logical scalar. If <code>type</code> is not <code>any</code>, then it has to match as well. </p> <p>The <code style="white-space: pre;">$del_deps</code> method removes all declared dependencies. </p> <p>The <code style="white-space: pre;">$set_dep</code> method adds or updates a single dependency. By default it adds the package to the <code>Imports</code> field. </p> <p>The API: </p> <div class="sourceCode r"><pre>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() </pre></div> <ul> <li> <p><code>package</code>: name of the package to add to or remove from the dependencies. </p> </li> <li> <p><code>type</code>: dependency type, see <a href="dep_types.html">dep_types</a>. For <code style="white-space: pre;">$del_dep</code> it may also be <code>"all"</code>, and then the package will be deleted from all dependency types. </p> </li> <li> <p><code>version</code>: required version. Defaults to <code>"*"</code>, which means no explicit version requirements. </p> </li> <li> <p><code>deps</code>: a data frame with columns <code>type</code>, <code>package</code> and <code>version</code>. <code style="white-space: pre;">$get_deps</code> returns the same format. </p> </li></ul> <h3>Collate fields</h3> <p>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 <code style="white-space: pre;">$add_to_collate</code> to add one or more files to the main or other collate field. You can use <code style="white-space: pre;">$del_from_collate</code> to remove it from there. </p> <p>The API: </p> <div class="sourceCode r"><pre>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")) </pre></div> <ul> <li> <p><code>iles</code>: the files to add or remove, in a character vector. </p> </li> <li> <p><code style="white-space: pre;">which: which collate field to manipulate. </code>"default"<code>for</code>$add_to_collate' means all existing collate fields, or the main one if none exist. </p> </li></ul> <h3>Authors</h3> <p>There is a specialized API for the <code>Authors@R</code> field, to add and remove authors, update their roles, change the maintainer, etc. </p> <p>The API: </p> <div class="sourceCode r"><pre>description$get_authors() description$set_authors(authors) description$get_author(role) description$get_maintainer() description$coerce_authors_at_r() </pre></div> <ul> <li> <p><code>authors</code>: a <code>person</code> object, a list of authors. </p> </li> <li> <p><code>role</code>: The role to query. See <code>person</code> for details. </p> </li></ul> <p><code style="white-space: pre;">$get_authors</code> returns a <code>person</code> object, the parsed authors. See <code><a href="../../utils/html/person.html">utils::person()</a></code> for details. </p> <p><code style="white-space: pre;">$get_author</code> returns a <code>person</code> object, all authors with the specified role. </p> <p><code style="white-space: pre;">$get_maintainer</code> returns the maintainer of the package. It works with <code>Authors@R</code> fields and with traditional <code>Maintainer</code> fields as well. </p> <p><code style="white-space: pre;">$coerce_authors_at_r</code> converts an <code>Author</code> field to one with a <code>person</code> object. This coercion may be necessary for other functions such as <code style="white-space: pre;">$get_authors</code>. </p> <div class="sourceCode r"><pre>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) </pre></div> <p>Add a new author. The arguments correspond to the arguments of the <code><a href="../../utils/html/person.html">utils::person()</a></code> function. <code>add_me</code> is a convenience function, it adds the current user as an author, and it needs the <code>whoami</code> package to be installed. It'll add your ORCID ID if you provide it as argument or save it as <code>ORCID_ID</code> environment variable in .Renviron. The full name is parsed by <code>add_me</code> and <code>add_author_gh</code> using <code>as.person</code> 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. </p> <div class="sourceCode r"><pre>description$del_author(given = NULL, family = NULL, email = NULL, role = NULL, comment = NULL, orcid = NULL) </pre></div> <p>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 <code>given = "Joe"</code> is supplied, then all authors whole given name matches <code>Joe</code> will be removed. The specifications can be (PCRE) regular expressions. </p> <div class="sourceCode r"><pre>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) </pre></div> <p><code>role</code> 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 <code style="white-space: pre;">$del_author</code>. </p> <h3>URLs</h3> <p>We provide helper functions for manipulating URLs in the <code>URL</code> field: </p> <div class="sourceCode r"><pre>description$get_urls() description$set_urls(urls) description$add_urls(urls) description$del_urls(pattern) description$clear_urls() </pre></div> <ul> <li> <p><code>urls</code>: character vector of URLs to set or add. </p> </li> <li> <p><code>pattern</code>: Perl compatible regular expression to specify the URLs to be removed. </p> </li></ul> <p><code style="white-space: pre;">$get_urls()</code> returns all urls in a character vector. If no URL fields are present, a zero length vector is returned. </p> <p><code style="white-space: pre;">$set_urls()</code> sets the URL field to the URLs specified in the character vector argument. </p> <p><code style="white-space: pre;">$add_urls()</code> appends the specified URLs to the URL field. It creates the field if it does not exists. Duplicate URLs are removed. </p> <p><code style="white-space: pre;">$del_urls()</code> deletes the URLs that match the specified pattern. </p> <p><code style="white-space: pre;">$clear_urls()</code> deletes all URLs. </p> <h3>Remotes</h3> <p><code>devtools</code>, <code>remotes</code> and some other packages support the non-standard <code>Remotes</code> field in <code>DESCRIPTION</code>. This field can be used to specify locations of dependent packages: GitHub or BitBucket repositories, generic git repositories, etc. Please see the <code style="white-space: pre;">Package remotes</code> vignette in the <code>devtools</code> package. </p> <p><code>desc</code> has helper functions for manipulating the <code>Remotes</code> field: </p> <div class="sourceCode r"><pre>description$get_remotes() description$get_remotes() description$set_remotes(remotes) description$add_remotes(remotes) description$del_remotes(pattern) description$clear_remotes() </pre></div> <ul> <li> <p><code>remotes</code>: character vector of remote dependency locations to set or add. </p> </li> <li> <p><code>pattern</code>: Perl compatible regular expression to specify the remote dependency locations to remove. </p> </li></ul> <p><code style="white-space: pre;">$get_remotes()</code> returns all remotes in a character vector. If no URL fields are present, a zero length vector is returned. </p> <p><code style="white-space: pre;">$set_remotes()</code> sets the URL field to the Remotes specified in the character vector argument. </p> <p><code style="white-space: pre;">$add_remotes()</code> appends the specified remotes to the <code>Remotes</code> field. It creates the field if it does not exists. Duplicate remotes are removed. </p> <p><code style="white-space: pre;">$del_remotes()</code> deletes the remotes that match the specified pattern. </p> <p><code style="white-space: pre;">$clear_remotes()</code> deletes all remotes. </p> <h3>Built</h3> <p>The <code>Built</code> field is used in binary packages to store information about when and how a binary package was built. </p> <p><code style="white-space: pre;">$get_built()</code> returns the built information as a list with fields <code>R</code>, <code>Platform</code>, <code>Date</code>, <code>OStype</code>. It throws an error if the package does not have a <code>Built</code> field. </p> <h3>Encodings</h3> <p>When creating a <code>description</code> object, <code>desc</code> observes the <code>Encoding</code> field, if present, and uses the specified encoding to parse the file. Internally, it converts all fields to UTF-8. </p> <p>When writing a <code>description</code> object to a file, <code>desc</code> uses the <code>Encoding</code> field (if present), and converts all fields to the specified encoding. </p> <p>We suggest that whenever you need to use non-ASCII characters in your package, you use the UTF-8 encoding, for maximum portability. </p> <h3>Examples</h3> <pre> ## 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 </pre> <hr /><div style="text-align: center;">[Package <em>desc</em> version 1.4.2 <a href="00Index.html">Index</a>]</div> </body></html>