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.
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. Seecff_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 thereferences
CFF key?Roles to be considered as authors of the package when generating the
CITATION.cff
file. See Details.
Value
A cff
object.
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.
See also
Guide to Citation File Format schema version 1.2.0.
cff_modify()
as the recommended way to modify acff
object.cff_write()
for creating a CFF file.vignette("cffr", "cffr")
shows an introduction on how manipulatecff
objects.vignette("crosswalk", package = "cffr")
provides details on how the metadata of a package is mapped to produce acff
object.
Other core functions of cffr:
cff()
,
cff_modify()
,
cff_validate()
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.8
#> identifiers:
#> - type: doi
#> value: 10.32614/CRAN.package.jsonlite
#> - type: url
#> value: https://arxiv.org/abs/1403.2805
#> 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: jeroen@berkeley.edu
#> 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: jeroen@berkeley.edu
#> 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://jeroen.r-universe.dev/jsonlite
#> date-released: '2023-12-04'
#> contact:
#> - family-names: Ooms
#> given-names: Jeroen
#> email: jeroen@berkeley.edu
#> 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
#> institution:
#> name: R Foundation for Statistical Computing
#> address: Vienna, Austria
#> year: '2024'
#> - 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: hadley@posit.co
#> - family-names: Henry
#> given-names: Lionel
#> email: lionel@posit.co
#> - family-names: Vaughan
#> given-names: Davis
#> email: davis@posit.co
#> year: '2024'
#> doi: 10.32614/CRAN.package.vctrs
#> - 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: hadley@posit.co
#> year: '2024'
#> doi: 10.32614/CRAN.package.testthat
#> - 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: xie@yihui.name
#> orcid: https://orcid.org/0000-0003-0645-5666
#> year: '2024'
#> doi: 10.32614/CRAN.package.knitr
#> - 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: jj@posit.co
#> - family-names: Xie
#> given-names: Yihui
#> email: xie@yihui.name
#> orcid: https://orcid.org/0000-0003-0645-5666
#> - family-names: Dervieux
#> given-names: Christophe
#> email: cderv@posit.co
#> orcid: https://orcid.org/0000-0003-4474-2498
#> - family-names: McPherson
#> given-names: Jonathan
#> email: jonathan@posit.co
#> - family-names: Luraschi
#> given-names: Javier
#> - family-names: Ushey
#> given-names: Kevin
#> email: kevin@posit.co
#> - family-names: Atkins
#> given-names: Aron
#> email: aron@posit.co
#> - family-names: Wickham
#> given-names: Hadley
#> email: hadley@posit.co
#> - family-names: Cheng
#> given-names: Joe
#> email: joe@posit.co
#> - family-names: Chang
#> given-names: Winston
#> email: winston@posit.co
#> - family-names: Iannone
#> given-names: Richard
#> email: rich@posit.co
#> orcid: https://orcid.org/0000-0003-3925-190X
#> year: '2024'
#> doi: 10.32614/CRAN.package.rmarkdown
# 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: marcbasic@gmail.com
#> repository-code: https://github.com/basic/package
#> url: https://basic.github.io/package
#> contact:
#> - family-names: Basic
#> given-names: Marc
#> email: marcbasic@gmail.com
# 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)
#> 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: marcbasic@gmail.com
#> 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,
as_cff_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: marcbasic@gmail.com
#> repository-code: https://github.com/basic/package
#> url: https://basic.github.io/package
#> contact:
#> - family-names: Basic
#> given-names: Marc
#> email: marcbasic@gmail.com
#> - family-names: New Contact
#> given-names: I am
# }