cffr (version 1.4.2)

cff_create: Create a cff object from multiple sources

Description

Create a full, possibly valid cff object from a given source. This object can be written to a CITATION.cff file with cff_write(). See Examples.

This function performs most metadata extraction and conversion in cffr.

Usage

cff_create(
  x,
  keys = list(),
  cff_version = "1.2.0",
  gh_keywords = TRUE,
  dependencies = TRUE,
  authors_roles = c("aut", "cre")
)

Value

A cff object.

Arguments

x

The source used to generate the cff object. It can be:

• A missing value, which retrieves the DESCRIPTION file from your in-development R package.

• An existing cff object.

• The name of an installed package ("jsonlite").

• A path to a DESCRIPTION file ("./DESCRIPTION").

keys

A list of additional keys to add to the cff object. See cff_modify().

cff_version

The Citation File Format schema version used for the generated metadata.

gh_keywords

A logical value. If TRUE and the package is hosted on GitHub, add the repository topics as keywords.

dependencies

A logical value. If TRUE, add the package dependencies to the references CFF key.

authors_roles

Roles to be considered as authors of the package when generating the CITATION.cff file. See Details.

Details

If x is a path to a DESCRIPTION file or if inst/CITATION is not present in your package, cffr auto-generates a preferred-citation key using the information provided in that file.

By default, only persons whose role in the DESCRIPTION file of the package is author ("aut") or maintainer ("cre") are considered package authors. The default setting can be controlled with the authors_roles argument. See Details on utils::person() for additional information about person roles.

See Also

Citation File Format schema guide.

• vignette("cffr", package = "cffr") shows an introduction to manipulating cff objects.

• vignette("r-cff", package = "cffr") provides details about how the metadata of a package is mapped to produce a cff object.

Core cffr workflow: cff(), cff_modify(), cff_validate(), cff_write()

Examples

# \donttest{
# Installed package.
cff_create("jsonlite")

# Demo file.
demo_file <- system.file("examples/DESCRIPTION_basic", package = "cffr")
cff_create(demo_file)

# Add additional keys.

newkeys <- list(
  message = "This overwrites keys",
  abstract = "New abstract",
  keywords = c("A", "new", "list", "of", "keywords"),
  authors = as_cff_person("New author")
)

cff_create(demo_file, keys = newkeys)

# Update a key in a list, such as authors or contacts.
# Add a new contact.

old <- cff_create(demo_file)

new_contact <- append(
  old$contact,
  as_cff_person(person(
    given = "I am",
    family = "New Contact"
  ))
)

cff_create(demo_file, keys = list("contact" = new_contact))
# }