Skip to contents

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
)

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?

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

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.0
#> 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-02-22'
#> 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: '2022'
#>   url: https://www.R-project.org/
#>   institution:
#>     name: R Foundation for Statistical Computing
#> - type: software
#>   title: httr
#>   abstract: 'httr: Tools for Working with URLs and HTTP'
#>   notes: Suggests
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: [email protected]
#>   year: '2022'
#> - type: software
#>   title: curl
#>   abstract: 'curl: A Modern and Flexible Web Client for R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Ooms
#>     given-names: Jeroen
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0002-4035-0289
#>   year: '2022'
#> - type: software
#>   title: vctrs
#>   abstract: 'vctrs: Vector Helpers'
#>   notes: Suggests
#>   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: '2022'
#>   url: https://vctrs.r-lib.org/
#> - type: software
#>   title: testthat
#>   abstract: 'testthat: Unit Testing for R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: [email protected]
#>   year: '2022'
#> - type: software
#>   title: knitr
#>   abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: [email protected]
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2022'
#>   url: https://yihui.org/knitr/
#> - type: software
#>   title: rmarkdown
#>   abstract: 'rmarkdown: Dynamic Documents for R'
#>   notes: Suggests
#>   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: McPherson
#>     given-names: Jonathan
#>     email: [email protected]
#>   - family-names: Luraschi
#>     given-names: Javier
#>     email: [email protected]
#>   - 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: '2022'

# 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]
#> preferred-citation:
#>   type: manual
#>   title: 'basicdesc: A Basic Description'
#>   authors:
#>   - family-names: Basic
#>     given-names: Marc
#>     email: [email protected]
#>   version: 0.1.6
#>   abstract: A very basic description. Should parse without problems.
#>   repository-code: https://github.com/basic/package
#>   url: https://basic.github.io/package
#>   contact:
#>   - family-names: Basic
#>     given-names: Marc
#>     email: [email protected]
#>   license: GPL-3.0-only
#>   year: '2022'
#> 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
#> preferred-citation:
#>   type: manual
#>   title: 'basicdesc: A Basic Description'
#>   authors:
#>   - family-names: Basic
#>     given-names: Marc
#>     email: [email protected]
#>   version: 0.1.6
#>   abstract: A very basic description. Should parse without problems.
#>   repository-code: https://github.com/basic/package
#>   url: https://basic.github.io/package
#>   contact:
#>   - family-names: Basic
#>     given-names: Marc
#>     email: [email protected]
#>   license: GPL-3.0-only
#>   year: '2022'
#> 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]
#> preferred-citation:
#>   type: manual
#>   title: 'basicdesc: A Basic Description'
#>   authors:
#>   - family-names: Basic
#>     given-names: Marc
#>     email: [email protected]
#>   version: 0.1.6
#>   abstract: A very basic description. Should parse without problems.
#>   repository-code: https://github.com/basic/package
#>   url: https://basic.github.io/package
#>   contact:
#>   - family-names: Basic
#>     given-names: Marc
#>     email: [email protected]
#>   license: GPL-3.0-only
#>   year: '2022'
#> 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
# }