cff_create {cffr}

Create a cff object from several sources

Description

Create a full and possibly valid cff object from a given source. This object can be written to a ⁠*.cff ⁠ file with cff_write(), see Examples.

Most of the heavy lifting of cffr is done via this function.

Usage

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

Arguments

x

The source that would be used for generating the cff object. It could be:

• A missing value. That would retrieve the DESCRIPTION file on your in-development R package.

• An existing cff object.

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

• Path to a DESCRIPTION file ("./DESCRIPTION").

keys

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

cff_version

The Citation File Format schema version that the CITATION.cff file adheres to for providing the citation metadata.

gh_keywords

Logical TRUE/FALSE. If the package is hosted on GitHub, would you like to add the repo topics as keywords?

dependencies

Logical TRUE/FALSE. Would you like to add the of your package 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 inst/CITATION, is not present on your package, cffr would auto-generate a preferred-citation key using the information provided on that file.

By default, only persons whose role in the DESCRIPTION file of the package is author ("aut") or maintainer ("cre") are considered to be authors of the package. The default setting can be controlled via the authors_roles parameter. See Details on person() to get additional insights on person roles.

Value

A cff object.

See Also

Guide to Citation File Format schema version 1.2.0.

• cff_modify() as the recommended way to modify a cff object.

• cff_write() for creating a CFF file.

• vignette("cffr", "cffr") shows an introduction on how manipulate cff objects.

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

Other core functions of cffr: cff(), cff_modify(), cff_validate()

Examples

# 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 fields",
  abstract = "New abstract",
  keywords = c("A", "new", "list", "of", "keywords"),
  authors = as_cff_person("New author")
)

cff_create(demo_file, keys = newkeys)

# Update a field on a list - i,e: authors, contacts, etc.
# We are adding a new contact here

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))