Skip to contents

Create cff object

Source: R/cff_create.R
cff_create.Rd

Create a cff object from a given source for further manipulation. Similar to cff_write(), but returns a object rather than writing directly to a file. See Examples.

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 package.

  • An existing cff object,

  • The name of an installed package ("jsonlite"), or

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

keys

List of additional keys to add to the cff object. See Details.

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 reference key?

authors_roles

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

Value

A cff list object.

Details

It is possible to add additional keys not detected by cff_create() using the keys argument. A list of valid keys can be retrieved with cff_schema_keys().

Please refer to Guide to Citation File Format schema version 1.2.0. for additional 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 utils::person() to get additional insights on person roles.

See also

Guide to Citation File Format schema version 1.2.0.

vignette("cffr", "cffr")

Other core functions: cff_read(), cff_validate(), cff_write()

Examples

# \donttest{
# Installed package
cff_create("jsonlite")
#> cff-version: 1.2.0
#> message: 'To cite package "jsonlite" in publications use:'
#> type: software
#> license: MIT
#> title: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
#> version: 1.8.4
#> abstract: A reasonably fast JSON parser and generator, optimized for statistical data
#>   and the web. Offers simple, flexible tools for working with JSON in R, and is particularly
#>   powerful for building pipelines and interacting with a web API. The implementation
#>   is based on the mapping described in the vignette (Ooms, 2014). In addition to converting
#>   JSON data from/to R objects, 'jsonlite' contains functions to stream, validate,
#>   and prettify JSON data. The unit tests included with the package verify that all
#>   edge cases are encoded and decoded consistently for use with dynamic data in systems
#>   and applications.
#> authors:
#> - family-names: Ooms
#>   given-names: Jeroen
#>   email: [email protected]
#>   orcid: https://orcid.org/0000-0002-4035-0289
#> preferred-citation:
#>   type: article
#>   title: 'The jsonlite Package: A Practical and Consistent Mapping Between JSON Data
#>     and R Objects'
#>   authors:
#>   - family-names: Ooms
#>     given-names: Jeroen
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0002-4035-0289
#>   journal: arXiv:1403.2805 [stat.CO]
#>   year: '2014'
#>   url: https://arxiv.org/abs/1403.2805
#> repository: https://CRAN.R-project.org/package=jsonlite
#> repository-code: https://github.com/jeroen/jsonlite
#> url: https://arxiv.org/abs/1403.2805
#> date-released: '2022-12-06'
#> contact:
#> - family-names: Ooms
#>   given-names: Jeroen
#>   email: [email protected]
#>   orcid: https://orcid.org/0000-0002-4035-0289
#> keywords:
#> - json
#> - parser
#> - r
#> - rstats
#> references:
#> - type: software
#>   title: methods
#>   abstract: 'R: A Language and Environment for Statistical Computing'
#>   notes: Depends
#>   authors:
#>   - name: R Core Team
#>   location:
#>     name: Vienna, Austria
#>   year: '2023'
#>   institution:
#>     name: R Foundation for Statistical Computing
#> - type: software
#>   title: httr
#>   abstract: 'httr: Tools for Working with URLs and HTTP'
#>   notes: Suggests
#>   url: https://httr.r-lib.org/
#>   repository: https://CRAN.R-project.org/package=httr
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: [email protected]
#>   year: '2023'
#> - type: software
#>   title: vctrs
#>   abstract: 'vctrs: Vector Helpers'
#>   notes: Suggests
#>   url: https://vctrs.r-lib.org/
#>   repository: https://CRAN.R-project.org/package=vctrs
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: [email protected]
#>   - family-names: Henry
#>     given-names: Lionel
#>     email: [email protected]
#>   - family-names: Vaughan
#>     given-names: Davis
#>     email: [email protected]
#>   year: '2023'
#> - type: software
#>   title: testthat
#>   abstract: 'testthat: Unit Testing for R'
#>   notes: Suggests
#>   url: https://testthat.r-lib.org
#>   repository: https://CRAN.R-project.org/package=testthat
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: [email protected]
#>   year: '2023'
#> - type: software
#>   title: knitr
#>   abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
#>   notes: Suggests
#>   url: https://yihui.org/knitr/
#>   repository: https://CRAN.R-project.org/package=knitr
#>   authors:
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2023'
#> - type: software
#>   title: rmarkdown
#>   abstract: 'rmarkdown: Dynamic Documents for R'
#>   notes: Suggests
#>   url: https://pkgs.rstudio.com/rmarkdown/
#>   repository: https://CRAN.R-project.org/package=rmarkdown
#>   authors:
#>   - family-names: Allaire
#>     given-names: JJ
#>     email: [email protected]
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   - family-names: Dervieux
#>     given-names: Christophe
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0003-4474-2498
#>   - family-names: McPherson
#>     given-names: Jonathan
#>     email: [email protected]
#>   - family-names: Luraschi
#>     given-names: Javier
#>   - family-names: Ushey
#>     given-names: Kevin
#>     email: [email protected]
#>   - family-names: Atkins
#>     given-names: Aron
#>     email: [email protected]
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: [email protected]
#>   - family-names: Cheng
#>     given-names: Joe
#>     email: [email protected]
#>   - family-names: Chang
#>     given-names: Winston
#>     email: [email protected]
#>   - family-names: Iannone
#>     given-names: Richard
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0003-3925-190X
#>   year: '2023'

# Demo file
demo_file <- system.file("examples/DESCRIPTION_basic", package = "cffr")
cff_create(demo_file)
#> cff-version: 1.2.0
#> message: 'To cite package "basicdesc" in publications use:'
#> type: software
#> license: GPL-3.0-only
#> title: 'basicdesc: A Basic Description'
#> version: 0.1.6
#> abstract: A very basic description. Should parse without problems.
#> authors:
#> - family-names: Basic
#>   given-names: Marc
#>   email: [email protected]
#> repository-code: https://github.com/basic/package
#> url: https://basic.github.io/package
#> contact:
#> - family-names: Basic
#>   given-names: Marc
#>   email: [email protected]

# Add additional keys

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

cff_create(demo_file, keys = newkeys)
#> cff-version: 1.2.0
#> message: This overwrites fields
#> type: software
#> license: GPL-3.0-only
#> title: 'basicdesc: A Basic Description'
#> version: 0.1.6
#> abstract: New abstract
#> authors:
#> - family-names: author
#>   given-names: New
#> repository-code: https://github.com/basic/package
#> url: https://basic.github.io/package
#> contact:
#> - family-names: Basic
#>   given-names: Marc
#>   email: [email protected]
#> keywords:
#> - A
#> - new
#> - list
#> - of
#> - keywords

# 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,
  list(
    cff_parse_person(person(
      given = "I am",
      family = "New Contact"
    ))
  )
)


cff_create(demo_file, keys = list("contact" = new_contact))
#> cff-version: 1.2.0
#> message: 'To cite package "basicdesc" in publications use:'
#> type: software
#> license: GPL-3.0-only
#> title: 'basicdesc: A Basic Description'
#> version: 0.1.6
#> abstract: A very basic description. Should parse without problems.
#> authors:
#> - family-names: Basic
#>   given-names: Marc
#>   email: [email protected]
#> repository-code: https://github.com/basic/package
#> url: https://basic.github.io/package
#> contact:
#> - family-names: Basic
#>   given-names: Marc
#>   email: [email protected]
#> - family-names: New Contact
#>   given-names: I am
# }