Read an external file as a cff object

Read files and convert them to cff objects. Files supported are:

• CITATION.cff files.

• DESCRIPTION files.

• R citation files (usually located in inst/CITATION).

• BibTeX files (with extension *.bib).

cff_read() would try to guess the type of file provided in path. However we provide a series of alias for each specific type of file:

• cff_read_cff_citation(), that uses yaml::read_yaml().

• cff_read_description(), using desc::desc().

• cff_read_citation() uses utils::readCitationFile().

• cff_read_bib() requires bibtex (>= 0.5.0) and uses bibtex::read.bib().

Usage

cff_read(path, ...)

cff_read_cff_citation(path, ...)

cff_read_description(
  path,
  cff_version = "1.2.0",
  gh_keywords = TRUE,
  authors_roles = c("aut", "cre"),
  ...
)

cff_read_citation(path, meta = NULL, ...)

cff_read_bib(path, encoding = "UTF-8", ...)

Arguments

path

Path to a file.

...

Arguments to be passed to other functions (i.e. to yaml::read_yaml(), bibtex::read.bib(), etc.).

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?

authors_roles

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

meta

A list of package metadata as obtained by utils::packageDescription() or NULL (the default). See Details.

encoding

Encoding to be assumed for path. See readLines().

Value

• cff_read_cff_citation() and cff_read_description() returns a object with class cff.

• cff_read_citation() and cff_read_bib() returns an object of classes cff_ref_lst, cff according to the definitions.references specified in the Citation File Format schema.

Learn more about the cffr class system in cff_class.

Details

For details of cff_read_description() see cff_create().

The meta object

Section 1.9 CITATION files of Writing R Extensions (R Core Team 2023) specifies how to create dynamic CITATION files using meta object, hence the meta argument in cff_read_citation() may be needed for reading some files correctly.

References

• R Core Team (2023). Writing R Extensions. https://cran.r-project.org/doc/manuals/r-release/R-exts.html

• Hernangomez D (2022). "BibTeX and CFF, a potential crosswalk." The cffr package, Vignettes. doi:10.21105/joss.03900 , https://docs.ropensci.org/cffr/articles/bibtex_cff.html.

See also

The underlying functions used for reading external files:

• yaml::read_yaml() for CITATION.cff files.

• desc::desc() for DESCRIPTION files.

• utils::readCitationFile() for R citation files.

• bibtex::read.bib() for BibTeX files (extension *.bib).

Other functions for reading external files: cff_read_bib_text()

Other functions for working with BibTeX format: as_bibentry(), cff_read_bib_text(), cff_write_bib(), encoded_utf_to_latex()

Examples

# Create cff object from cff file

from_cff_file <- cff_read(system.file("examples/CITATION_basic.cff",
  package = "cffr"
))

head(from_cff_file, 7)
#> cff-version: 1.2.0
#> message: If you use this software in your research, please cite it as below.
#> title: cff-validator
#> abstract: Validate your repository's CITATION.cff file using R software
#> authors:
#> - family-names: Hernangómez
#>   given-names: Diego
#>   orcid: https://orcid.org/0000-0001-8457-4658
#> license: MIT
#> repository-code: https://github.com/dieghernan/cff-validator

# Create cff object from DESCRIPTION
from_desc <- cff_read(system.file("examples/DESCRIPTION_basic",
  package = "cffr"
))

from_desc
#> cff-version: 1.2.0
#> message: 'To cite package "basicdesc" in publications use:'
#> type: software
#> title: 'basicdesc: A Basic Description'
#> version: 0.1.6
#> authors:
#> - family-names: Basic
#>   given-names: Marc
#>   email: marcbasic@gmail.com
#> 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: marcbasic@gmail.com
#> license: GPL-3.0-only

# Create cff object from BibTex

if (requireNamespace("bibtex", quietly = TRUE)) {
  from_bib <- cff_read(system.file("examples/example.bib",
    package = "cffr"
  ))

  # First item only
  from_bib[[1]]
}
#> type: generic
#> title: Citation File Format
#> authors:
#> - family-names: Druskat
#>   given-names: Stephan
#> - family-names: Spaaks
#>   given-names: Jurriaan H.
#> - family-names: Chue Hong
#>   given-names: Neil
#> - family-names: Haines
#>   given-names: Robert
#> - family-names: Baker
#>   given-names: James
#> - family-names: Bliven
#>   given-names: Spencer
#> - family-names: Willighagen
#>   given-names: Egon
#> - family-names: Pérez-Suárez
#>   given-names: David
#> - family-names: Konovalov
#>   given-names: Alexander
#> year: '2021'
#> month: '8'
#> doi: 10.5281/zenodo.5171937
#> url: https://github.com/citation-file-format/citation-file-format
#> date-accessed: '2021-11-07'
#> copyright: CC-BY-4.0
#> abstract: The Citation File Format lets you provide citation metadata for software
#>   or datasets in plaintext files that are easy to read by both humans and machines.
# Create cff object from CITATION
from_citation <- cff_read(system.file("CITATION", package = "cffr"))

# First item only
from_citation[[1]]
#> type: article
#> title: 'cffr: Generate Citation File Format Metadata for R Packages'
#> authors:
#> - family-names: Hernangómez
#>   given-names: Diego
#> doi: 10.21105/joss.03900
#> url: https://doi.org/10.21105/joss.03900
#> year: '2021'
#> publisher:
#>   name: The Open Journal
#> volume: '6'
#> issue: '67'
#> journal: Journal of Open Source Software
#> start: '3900'