cff_read {cffr}

Read an external file as a cff object

Description

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

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.

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.

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)

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

from_desc

# 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]]
}
# Create cff object from CITATION
from_citation <- cff_read(system.file("CITATION", package = "cffr"))

# First item only
from_citation[[1]]