Package {cffr}

Title:	Generate Citation File Format ('CFF') Metadata for R Packages
Version:	1.4.1
Description:	Citation File Format ('CFF') version 1.2.0 <doi:10.5281/zenodo.5171937> is a human- and machine-readable file format for software citation metadata. Core utilities generate, read, write and validate Citation File Format metadata for R packages.
License:	GPL (≥ 3)
URL:	https://docs.ropensci.org/cffr/, https://github.com/ropensci/cffr
BugReports:	https://github.com/ropensci/cffr/issues
Depends:	R (≥ 4.1.0)
Imports:	cli (≥ 2.0.0), desc (≥ 1.3.0), jsonlite (≥ 1.7.2), jsonvalidate (≥ 1.1.0), tools, utils, yaml (≥ 2.2.1)
Suggests:	bibtex (≥ 0.5.0), knitr, lifecycle, quarto, rmarkdown, testthat (≥ 3.0.0), usethis
VignetteBuilder:	quarto
Config/Needs/website:	devtools
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
LazyData:	true
X-schema.org-isPartOf:	https://ropensci.org
X-schema.org-keywords:	attribution, citation, credit, citation-files, cff, metadata, citation-file-format, cran, r, r-package, ropensci, rstats, r-cran
NeedsCompilation:	no
Packaged:	2026-06-17 12:54:11 UTC; diego
Author:	Diego Hernangómez [aut, cre, cph], João Martins [rev], Scott Chamberlain [rev]
Maintainer:	Diego Hernangómez <diego.hernangomezherrero@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-17 15:00:07 UTC

cffr: Generate Citation File Format ('CFF') Metadata for R Packages

Description

Citation File Format ('CFF') version 1.2.0 doi:10.5281/zenodo.5171937 is a human- and machine-readable file format for software citation metadata. Core utilities generate, read, write and validate Citation File Format metadata for R packages.

Author(s)

Maintainer: Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

Authors:

• Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

Other contributors:

• João Martins (ORCID) [reviewer]

• Scott Chamberlain (ORCID) [reviewer]

See Also

Useful links:

• https://docs.ropensci.org/cffr/

• https://github.com/ropensci/cffr

• Report bugs at https://github.com/ropensci/cffr/issues

Create bibentry objects from multiple sources

Description

This function creates bibentry objects from multiple metadata sources (cff objects, DESCRIPTION files and other sources). The inverse transformation (bibentry object to cff_ref_lst) can be done with the corresponding as_cff.bibentry() method.

With toBibtex(), you can convert cff objects to BibTeX markup on the fly. See Examples.

Usage

as_bibentry(x, ...)

## Default S3 method:
as_bibentry(x, ...)

## S3 method for class 'character'
as_bibentry(x, ..., what = c("preferred", "references", "all"))

## S3 method for class ''NULL''
as_bibentry(x, ...)

## S3 method for class 'list'
as_bibentry(x, ...)

## S3 method for class 'cff'
as_bibentry(x, ..., what = c("preferred", "references", "all"))

## S3 method for class 'cff_ref_lst'
as_bibentry(x, ...)

## S3 method for class 'cff_ref'
as_bibentry(x, ...)

Arguments

Details

An R bibentry object is the representation of a BibTeX entry. These objects can be converted to BibTeX markup with toBibtex(), which creates an object of class Bibtex that can be printed and exported as a valid BibTeX entry.

as_bibentry() tries to map the information of the source x into a cff object and performs a mapping of the metadata to BibTeX, according to vignette("bibtex-cff", package = "cffr").

Value

as_bibentry() returns a bibentry object with one or more entries.

References

• Patashnik, Oren. "BIBTEXTING" February 1988. https://osl.ugr.es/CTAN/biblio/bibtex/base/btxdoc.pdf.

• Haines, R., & The Ruby Citation File Format Developers. (2021). Ruby CFF Library (Version 0.9.0) (Computer software). doi:10.5281/zenodo.1184077.

• 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

utils::bibentry() to understand more about the bibentry class.

• vignette("r-cff", package = "cffr") provides details on how the metadata of a package is mapped to produce a cff object.

• vignette("bibtex-cff", package = "cffr") provides details about the internal mapping performed between cff objects and BibTeX markup, both cff to BibTeX and BibTeX to cff.

Other related functions:

• utils::toBibtex().

Work with BibTeX metadata: cff_read(), cff_read_bib_text(), cff_write_bib(), encoded_utf_to_latex()

Coerce between R classes: as_cff(), as_cff_person(), cff_class

Examples

# From a `cff` object ----
cff_object <- cff()

cff_object

# A bibentry object.
bib <- as_bibentry(cff_object)

class(bib)

bib

# Print as BibTeX.
toBibtex(bib)

# Thanks to the S3 method, you can also do this.
toBibtex(cff_object)

# Other sources ----
# From a CITATION.cff.

path <- system.file("examples/CITATION_complete.cff", package = "cffr")
cff_file <- as_bibentry(path)

cff_file

# For an installed package with options.
installed_package <- as_bibentry("jsonvalidate", what = "all")

installed_package

# Use a DESCRIPTION file.
path2 <- system.file("examples/DESCRIPTION_gitlab", package = "cffr")
desc_file <- as_bibentry(path2)

toBibtex(desc_file)

Coerce lists and citation objects to cff

Description

as_cff() turns an existing list-like R object into a cff object, a list with class cff and the corresponding subclass when applicable.

as_cff() is an S3 generic, with methods for:

• person objects as produced by utils::person().

• bibentry objects as produced by utils::bibentry().

• Bibtex objects as produced by toBibtex().

• Default: Other inputs are first coerced with as.list().

Usage

as_cff(x, ...)

## Default S3 method:
as_cff(x, ...)

## S3 method for class 'list'
as_cff(x, ...)

## S3 method for class 'person'
as_cff(x, ...)

## S3 method for class 'bibentry'
as_cff(x, ...)

## S3 method for class 'Bibtex'
as_cff(x, ...)

Arguments

Details

For as_cff.bibentry() and as_cff.Bibtex(), see vignette("bibtex-cff", package = "cffr") to understand how the mapping is performed.

as_cff_person() is preferred over as_cff.person() because it can handle character inputs such as "Davis, Jr., Sammy". For person objects both functions behave similarly.

Value

• as_cff.person() returns an object with classes cff_pers_lst, cff.

• as_cff.bibentry() and as_cff.Bibtex() return an object with classes cff_ref_lst, cff.

• The remaining methods return an object of class cff. However, if x has a structure compatible with definitions.person, definitions.entity or definitions.reference, the object has the corresponding subclass.

Learn more about the cffr class system in cff_class.

See Also

• cff(): Create a full cff object from scratch.

• cff_modify(): Modify a cff object.

• cff_create(): Create a cff object for an R package.

• cff_read(): Create a cff object from an external file.

• as_cff_person(): Recommended way to create CFF person metadata.

Learn more about the cffr class system in cff_class.

Coerce between R classes: as_bibentry(), as_cff_person(), cff_class

Examples

# Convert a list to a `cff` object.
cffobj <- as_cff(list(
  "cff-version" = "1.2.0",
  title = "Manipulating files"
))

class(cffobj)

# Nice display thanks to the yaml package.
cffobj

# `bibentry` method.
a_cit <- citation("cffr")[[1]]

a_cit

as_cff(a_cit)

# BibTeX method.
a_bib <- toBibtex(a_cit)

a_bib

as_cff(a_cit)

Coerce R objects to cff_pers_lst objects

Description

as_cff_person() turns an existing list-like R object into a cff_pers_lst object representing a list of definitions.person or definitions.entity, as defined by the Citation File Format schema.

as_cff_person() is an S3 generic, with methods for:

• person: Objects created with person().

• character: Strings with the definition for one or more authors, using the standard BibTeX notation (see Markey, 2007) and related formats, such as the output of format() for person objects (see format.person()).

• Default: Other inputs are first coerced with as.character().

The inverse transformation (cff_pers_lst to person) can be done with the methods as.person.cff_pers() and as.person.cff_pers_lst().

Usage

as_cff_person(x, ...)

## Default S3 method:
as_cff_person(x, ...)

## S3 method for class 'person'
as_cff_person(x, ...)

## S3 method for class 'character'
as_cff_person(x, ...)

Arguments

Details

as_cff_person() recognizes whether the input should be converted with the CFF reference for definitions.person or definitions.entity.

as_cff_person() uses a custom algorithm that parses names as explained in Section 11 of "Tame the BeaST" (Markey, 2007) (see also Decoret, 2007):

• ⁠First von Last⁠.

• ⁠von Last, First⁠.

• ⁠von Last, Jr, First⁠.

Mapping is performed as follows:

• First is mapped to the CFF key given-names.

• von is mapped to the CFF key name-particle.

• Last is mapped to the CFF key family-names.

• Jr is mapped to the CFF key name-suffix.

For entities, the entire character is mapped to name. We recommend "protecting" entity names with {}:

# Avoid unprotected entity names.
entity <- "Elephant and Castle"
as_cff_person(entity)
- name: Elephant
- name: Castle

# Protect entity names with braces.
entity_protect <- "{Elephant and Castle}"
as_cff_person(entity_protect)
- name: Elephant and Castle

as_cff_person() attempts to extract as much information as possible. For character strings from format.person(), the email and ORCID are also extracted.

Value

as_cff_person() returns an object of classes cff_pers_lst, cff according to the definitions.person or definitions.entity specified in the Citation File Format schema. Each element of the cff_pers_lst object has classes cff_pers, cff.

References

• Patashnik, Oren. "BIBTEXTING" February 1988. https://osl.ugr.es/CTAN/biblio/bibtex/base/btxdoc.pdf.

• Markey, Nicolas. "Tame the BeaST" The B to X of BibTeX, Version 1.4 (October 2007). https://osl.ugr.es/CTAN/info/bibtex/tamethebeast/ttb_en.pdf.

• Decoret X (2007). "A summary of BibTeX."https://maverick.inria.fr/~Xavier.Decoret/resources/xdkbibtex/bibtex_summary.html#names

See Examples for more information.

See Also

Examples in vignette("cffr", package = "cffr") and utils::person(). Learn more about the cff_pers_lst and cff_pers classes in cff_class.

Coerce between R classes: as_bibentry(), as_cff(), cff_class

Examples

# Create a person object.
a_person <- person(
  given = "First", family = "Author",
  role = c("aut", "cre"),
  email = "first.last@example.com", comment = c(
    ORCID = "0000-0001-8457-4658",
    affiliation = "An affiliation"
  )
)

a_person

cff_person <- as_cff_person(a_person)

# Class cff_pers_lst / cff.
class(cff_person)

# Each element has class cff_pers / cff.
class(cff_person[[1]])

# Print.
cff_person

# Back to person object with S3 method.
as.person(cff_person)

# Coerce a string.
a_str <- paste0(
  "Julio Iglesias <fake@email.com> ",
  "(city: Miami, region: California, country: US)"
)
as_cff_person(a_str)

# Several persons.
persons <- c(
  person("Clark", "Kent", comment = c(affiliation = "Daily Planet")),
  person("Lois", "Lane"), person("Oscorp Inc.")
)

a_cff <- as_cff_person(persons)

a_cff

# Printed as BibTeX thanks to the method.
toBibtex(a_cff)

# Or as person object.
as.person(a_cff)

# Or use BibTeX style as input.

x <- "Frank Sinatra and Dean Martin and Davis, Jr., Sammy and Joey Bishop"

as_cff_person(x)

as_cff_person("Herbert von Karajan")

toBibtex(as_cff_person("Herbert von Karajan"))

Create cff objects from direct inputs

Description

A class and utility methods for reading, creating and storing CFF information. See cff_class to learn more about cff objects.

Usage

cff(path, ...)

Arguments

Details

cff() converts ⁠_⁠ in the argument name to -. For example, cff_version = "1.2.0" is converted to cff-version = "1.2.0".

Valid arguments are those specified on cff_schema_keys():

• cff-version

• message

• type

• license

• title

• version

• doi

• identifiers

• abstract

• authors

• preferred-citation

• repository

• repository-artifact

• repository-code

• commit

• url

• date-released

• contact

• keywords

• references

• license-url

Value

A cff object. Under the hood, a cff object is a regular list object with a special print method.

See Also

Core cffr workflow: cff_create(), cff_modify(), cff_validate()

Examples

# Blank `cff` object.
cff()

# Use custom parameters.
test <- cff(
  title = "Manipulating files",
  keywords = c("A", "new", "list", "of", "keywords"),
  authors = as_cff_person("New author")
)
test

# This would fail.
cff_validate(test)


# Modify with cff_create().
new <- cff_create(test, keys = list(
  "cff_version" = "1.2.0",
  message = "A blank file"
))
new

# This would pass.
cff_validate(new)

The cff class

Description

cffr implements an S3 object with class cff, which represents the information in a CITATION.cff file in R.

Under the hood, a cff object is a named list with additional methods, most notably print and as_cff().

a_named_list <- list(
  first = "I", second = "am", third = "a", fourth = "list",
  fifth = "with", sixth = "names", "none" = NULL
)

# Convert to `cff`.
a_cff_object <- as_cff(a_named_list)

class(a_cff_object)
#> [1] "cff"

a_cff_object
#> first: I
#> second: am
#> third: a
#> fourth: list
#> fifth: with
#> sixth: names

is.list(a_cff_object)
#> [1] TRUE

as_cff() converts a list to cff and removes items that are NULL or NA. These items are known as keys in CFF terminology.

Subclasses

cffr implements two special subclasses of cff, which represent two special types of objects defined in the Citation File Format schema:

• definitions.person and definitions.entity: CFF definitions for sublists representing persons or entities. In cffr, the subclass cff_pers_lst collects an array of definitions.person or definitions.entity objects, where each individual person or entity has subclass cff_pers.

• definitions.reference is the CFF definition for collecting references to related works and other software used in the development of the main work of the CITATION.cff file. In cffr, the subclass cff_ref_lst represents arrays of definitions.reference objects, where each element has subclass cff_ref.

These two subclasses do not provide full valid cff objects, but adapt information to the schema required by CFF:

# Use `utils::person()`.

## Array.
two_persons <- as_cff_person(
  c(
    person("A", "person", comment = c(ORCID = "0000-0001-8457-4658")),
    person("An entity", email = "fake@gmail.com")
  )
)

two_persons
#> - family-names: person
#>   given-names: A
#>   orcid: https://orcid.org/0000-0001-8457-4658
#> - name: An entity
#>   email: fake@gmail.com

class(two_persons)
#> [1] "cff_pers_lst" "cff"

# Single element.

two_persons[[1]]
#> family-names: person
#> given-names: A
#> orcid: https://orcid.org/0000-0001-8457-4658

class(two_persons[[1]])
#> [1] "cff_pers" "cff"

# Array of references.

cit <- c(citation(), citation("jsonlite"))

ref_list <- as_cff(cit)

ref_list
#> - type: manual
#>   title: 'R: A Language and Environment for Statistical Computing'
#>   authors:
#>   - name: R Core Team
#>     website: https://ror.org/02zz1nj61
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     website: https://ror.org/05qewa988
#>     address: Vienna, Austria
#>   year: '2026'
#>   doi: 10.32614/R.manuals
#>   url: https://www.R-project.org/
#> - type: article
#>   title: 'The jsonlite Package: A Practical and Consistent Mapping Between JSON Data
#>     and R Objects'
#>   authors:
#>   - family-names: Ooms
#>     given-names: Jeroen
#>   journal: arXiv:1403.2805 [stat.CO]
#>   year: '2014'
#>   url: https://arxiv.org/abs/1403.2805

class(ref_list)
#> [1] "cff_ref_lst" "cff"

# Single element.

ref_list[[1]]
#> type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#>   website: https://ror.org/02zz1nj61
#> institution:
#>   name: R Foundation for Statistical Computing
#>   website: https://ror.org/05qewa988
#>   address: Vienna, Austria
#> year: '2026'
#> doi: 10.32614/R.manuals
#> url: https://www.R-project.org/

class(ref_list[[1]])
#> [1] "cff_ref" "cff"

Valid cff objects

Creating a cff object does not ensure its validity against the Citation File Format schema:

class(a_cff_object)
#> [1] "cff"

cff_validate(a_cff_object)
#> == Validating CFF ==============================================================
#> x Validation failed. This <cff> object has the following errors:
#> * cff/: must have required property 'authors'
#> * cff/: must have required property 'cff-version'
#> * cff/: must have required property 'message'
#> * cff/: must have required property 'title'
#> * cff/: must NOT have additional properties
#> * cff/: must NOT have additional properties
#> * cff/: must NOT have additional properties
#> * cff/: must NOT have additional properties
#> * cff/: must NOT have additional properties
#> * cff/: must NOT have additional properties

cff_validate() gives minimal messages about what is wrong with the cff object and invisibly returns the validation result (TRUE/FALSE).

We can use cff_modify() to add more keys:

cff_valid <- cff_modify(a_cff_object,
  authors = as_cff_person("{James and James}"),
  cff_version = "1.2.0",
  message = "Hi there",
  title = "My title"
)

# Remove invalid keys.
cff_valid <- as_cff(cff_valid[names(cff_valid) %in% cff_schema_keys()])

cff_valid
#> authors:
#> - name: James and James
#> cff-version: 1.2.0
#> message: Hi there
#> title: My title

cff_validate(cff_valid)
#> == Validating CFF ==============================================================
#> v This <cff> object is valid.

Base methods provided by cffr

cffr provides additional S3 methods for common coercion functions from the base and utils packages.

as.data.frame()

minimal_cff <- cff()

minimal_cff
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: My Research Software
#> authors:
#> - family-names: Doe
#>   given-names: John

as_df <- as.data.frame(minimal_cff)

class(as_df)
#> [1] "data.frame"

t(as_df)
#>                         [,1]                                                            
#> cff_version             "1.2.0"                                                         
#> message                 "If you use this software, please cite it using these metadata."
#> title                   "My Research Software"                                          
#> authors.00.family_names "Doe"                                                           
#> authors.00.given_names  "John"

c()

new_keys <- c("date-released" = "2020-01-31", abstract = "Minimal example")

c(minimal_cff, new_keys)
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: My Research Software
#> authors:
#> - family-names: Doe
#>   given-names: John
#> date-released: '2020-01-31'
#> abstract: Minimal example

as.list()

as.list(minimal_cff)
#> $`cff-version`
#> [1] "1.2.0"
#> 
#> $message
#> [1] "If you use this software, please cite it using these metadata."
#> 
#> $title
#> [1] "My Research Software"
#> 
#> $authors
#> $authors[[1]]
#> $authors[[1]]$`family-names`
#> [1] "Doe"
#> 
#> $authors[[1]]$`given-names`
#> [1] "John"

as.person()

Only for cff_pers_lst and cff_pers objects:

as.person(two_persons)
#> [1] "A person (ORCID: <https://orcid.org/0000-0001-8457-4658>)"
#> [2] "An entity <fake@gmail.com>"

toBibtex()

# For `cff`.
toBibtex(minimal_cff)
#> @Misc{doe,
#>   title = {My Research Software},
#>   author = {John Doe},
#> }

# For `cff_ref` and `cff_ref_lst`.
toBibtex(cit)
#> @Manual{,
#>   title = {R: A Language and Environment for Statistical Computing},
#>   author = {{R Core Team}},
#>   organization = {R Foundation for Statistical Computing},
#>   address = {Vienna, Austria},
#>   year = {2026},
#>   doi = {10.32614/R.manuals},
#>   url = {https://www.R-project.org/},
#> }
#> 
#> @Article{,
#>   title = {The jsonlite Package: A Practical and Consistent Mapping Between JSON Data and R Objects},
#>   author = {Jeroen Ooms},
#>   journal = {arXiv:1403.2805 [stat.CO]},
#>   year = {2014},
#>   url = {https://arxiv.org/abs/1403.2805},
#> }

# For `cff_pers` and `cff_pers_lst`.
toBibtex(two_persons)
#> person, A and {An entity}

References

• Wickham H (2019). "S3." In Advanced R, 2nd edition. Chapman and Hall/CRC. doi:10.1201/9781351201315, https://adv-r.hadley.nz/s3.html.

See Also

Coerce between R classes: as_bibentry(), as_cff(), as_cff_person()

Create a cff object from multiple sources

Description

Create a full, possibly valid cff object from a given source. This object can be written to a CITATION.cff file with cff_write(). See Examples.

Most of the heavy lifting of cffr is done by this function.

Usage

cff_create(
  x,
  keys = list(),
  cff_version = "1.2.0",
  gh_keywords = TRUE,
  dependencies = TRUE,
  authors_roles = c("aut", "cre")
)

Arguments

Details

If x is a path to a DESCRIPTION file, or if inst/CITATION is not present in your package, cffr auto-generates a preferred-citation key using the information provided in that file.

By default, only persons whose role in the DESCRIPTION file of the package is author ("aut") or maintainer ("cre") are considered package authors. The default setting can be controlled with the authors_roles argument. See Details on person() for additional information about person roles.

Value

A cff object.

See Also

Guide to Citation File Format schema version 1.2.0.

• cff_modify() as the recommended way to modify a cff object.

• cff_write() for creating a CITATION.cff file.

• vignette("cffr", package = "cffr") shows an introduction to manipulating cff objects.

• vignette("r-cff", package = "cffr") provides details on how the metadata of a package is mapped to produce a cff object.

Core cffr workflow: cff(), cff_modify(), cff_validate()

Examples

# Installed package.
cff_create("jsonlite")

# Demo file.
demo_file <- system.file("examples/DESCRIPTION_basic", package = "cffr")
cff_create(demo_file)

# Add additional keys.

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

cff_create(demo_file, keys = newkeys)

# Update a key in a list, for example authors or contacts.
# Add a new contact.

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

Previous API: Create BibTeX entries from multiple sources

Description

Use as_bibentry() instead.

Usage

cff_extract_to_bibtex(x, what = c("preferred", "references", "all"))

cff_to_bibtex(x, what = c("preferred", "references", "all"))

Arguments

Value

See as_bibentry().

See Also

Deprecated functions: cff_from_bibtex(), cff_parse_citation(), cff_parse_person(), write_bib()

Examples

# From a `cff` object.
cff_object <- cff()

cff_object

# A bibentry object.
bib <- as_bibentry(cff_object)

Previous API: Create a cff object from BibTeX entries

Description

Use either cff_read_bib() or cff_read_bib_text().

Usage

cff_from_bibtex(x, encoding = "UTF-8", ...)

Arguments

Value

See cff_read_bib() for reading ⁠*.bib⁠ files and cff_read_bib_text() for reading a character object representing a BibTeX entry.

See Also

Deprecated functions: cff_extract_to_bibtex(), cff_parse_citation(), cff_parse_person(), write_bib()

Examples

if (requireNamespace("bibtex", quietly = TRUE)) {
  x <- c(
    "@book{einstein1921,
    title        = {Relativity: The Special and the General Theory},
    author       = {Einstein, Albert},
    year         = 1920,
    publisher    = {Henry Holt and Company},
    address      = {London, United Kingdom},
    isbn         = 9781587340925
}",
    "@misc{misc-full,
    title        = {Handing out random pamphlets in airports},
    author       = {Joe-Bob Missilany},
    year         = 1984,
    month        = oct,
    note         = {This is a full MISC entry},
    howpublished = {Handed out at O'Hare}
}"
  )

  cff_read_bib_text(x)

  # From a file.

  x2 <- system.file("examples/example.bib", package = "cffr")
  cff_read_bib(x2)
}

Install a cffr GitHub Actions workflow

Description

This function installs a GitHub Actions workflow in your repository. The workflow updates your CITATION.cff when any of these events occur:

• You publish a new release of the package.

• Your DESCRIPTION or inst/CITATION file is modified.

• The action can be run manually.

Usage

cff_gha_update(path = ".", overwrite = FALSE)

Arguments

Details

Triggers on your action can be modified. See Events that trigger workflows.

Value

Invisible. This function is called for its side effects.

See Also

Keep ‘CITATION.cff’ up to date: cff_git_hook

Examples

## Not run: 
cff_gha_update()

## End(Not run)

Use a git pre-commit hook

Description

Install a pre-commit hook that reminds you to update your CITATION.cff file. This is a wrapper around usethis::use_git_hook().

Usage

cff_git_hook_install()

cff_git_hook_remove()

Details

This function installs a pre-commit hook using usethis::use_git_hook().

A pre-commit hook is a script that identifies simple issues before submission to code review. This pre-commit hook warns you if any of the following conditions are met:

• You included your DESCRIPTION or inst/CITATION file in a commit but did not include your CITATION.cff, and the CITATION.cff file is "older" than your DESCRIPTION or inst/CITATION file.

• You updated your CITATION.cff but did not include it in your commit.

Value

Invisible. This function is called for its side effects.

A word of caution

The pre-commit hook may prevent you from committing if you are not updating your CITATION.cff. However, the detection mechanism is not perfect and may be triggered even if you have attempted to update your CITATION.cff file.

This typically occurs when you have updated your DESCRIPTION or inst/CITATION files, but those changes do not affect your CITATION.cff file, for example, when you add new dependencies.

In those cases, you can override the check by running ⁠git commit --no-verify⁠ in the terminal.

If you are using RStudio, you can also run this command from an R script by selecting that line and sending it to the terminal using:

• Windows & Linux: Ctrl+Alt+Enter.

• Mac: Cmd+Option+Return.

Removing the git pre-commit hook

You can remove the pre-commit hook using cff_git_hook_remove().

See Also

• usethis::use_git_hook(), which is the underlying function used by cff_git_hook_install().

• usethis::use_git() and related functions of usethis for using Git with R packages.

Keep ‘CITATION.cff’ up to date: cff_gha_update()

Examples

## Not run: 
cff_git_hook_install()

## End(Not run)

Modify a cff object

Description

Add new keys to a cff object or modify existing ones.

Usage

cff_modify(x, ...)

Arguments

Details

Keys provided in ... override the corresponding key in x.

You can add additional keys not detected by cff_create() using the keys argument. A list of valid keys can be retrieved with cff_schema_keys(). For details, refer to Guide to Citation File Format schema version 1.2.0. for additional details.

Value

A cff object.

See Also

This function is a wrapper of utils::modifyList(). See cff() for creating cff objects from scratch.

Core cffr workflow: cff(), cff_create(), cff_validate()

Examples

x <- cff()
x

cff_validate(x)

x_mod <- cff_modify(x,
  contact = as_cff_person("A contact"),
  message = "This overwrites keys",
  title = "New Title",
  abstract = "New abstract",
  doi = "10.21105/joss.03900"
)

x_mod

cff_validate(x_mod)

Previous API: Parse a bibentry object to cff

Description

Use the as_cff.bibentry() method instead.

Usage

cff_parse_citation(bib)

Arguments

Value

A bibentry object in cff format.

See Also

as_cff.bibentry()

Deprecated functions: cff_extract_to_bibtex(), cff_from_bibtex(), cff_parse_person(), write_bib()

Examples

bib <- citation("base")
bib

# To cff.
bib_to_cff <- as_cff(bib)
bib_to_cff

Previous API: Parse a person to cff

Description

Use as_cff_person() instead.

Usage

cff_parse_person(person)

cff_parse_person_bibtex(person)

Arguments

Value

A person in cff format.

See Also

as_cff_person()

Deprecated functions: cff_extract_to_bibtex(), cff_from_bibtex(), cff_parse_citation(), write_bib()

Examples

# Create a person object.
a_person <- person(
  given = "First", family = "Author",
  role = c("aut", "cre"),
  email = "first.last@example.com", comment = c(
    ORCID = "0000-0001-8457-4658",
    affiliation = "An affiliation"
  )
)

a_person

cff_person <- as_cff_person(a_person)

cff_person

# Back to person object with S3 method.
as.person(cff_person)

# Parse a string.
a_str <- paste0(
  "Julio Iglesias <fake@email.com> ",
  "(<https://orcid.org/0000-0001-8457-4658>)"
)
as_cff_person(a_str)

# Several persons.
persons <- c(person("Clark", "Kent"), person("Lois", "Lane"))

as_cff_person(persons)

# Or use BibTeX style.

x <- "Frank Sinatra and Dean Martin and Davis, Jr., Sammy and Joey Bishop"

as_cff_person(x)

as_cff_person("Herbert von Karajan")

Read an external file as a cff object

Description

Read files and convert them to cff objects. Supported files are:

• CITATION.cff files.

• DESCRIPTION files.

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

• BibTeX files (with extension ⁠*.bib⁠).

cff_read() attempts to guess the type of file provided in path. However, we provide aliases for each specific file type:

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

• cff_read_description(), which uses desc::desc().

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

• cff_read_bib(), which 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

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 a meta object. Therefore, the meta argument in cff_read_citation() may be needed to read some files correctly.

Value

• cff_read_cff_citation() and cff_read_description() return an object with class cff.

• cff_read_citation() and cff_read_bib() return an object of classes cff_ref_lst, cff according to the definitions.reference 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⁠).

Read external citation metadata: cff_read_bib_text()

Work with BibTeX metadata: as_bibentry(), cff_read_bib_text(), cff_write_bib(), encoded_utf_to_latex()

Examples

# Create a `cff` object from a `CITATION.cff` file.
from_cff_file <- cff_read(system.file("examples/CITATION_basic.cff",
  package = "cffr"
))

head(from_cff_file, 7)

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

from_desc

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

# First item only.
from_citation[[1]]

Read BibTeX markup as a cff_ref_lst object

Description

Convert a character string representing a BibTeX entry into a cff_ref_lst object.

Usage

cff_read_bib_text(x, encoding = "UTF-8", ...)

Arguments

Details

This function writes x to a temporary ⁠*.bib⁠ file and reads it using cff_read_bib().

This function requires bibtex (>= 0.5.0) and uses bibtex::read.bib() for parsing.

Value

An object of classes cff_ref_lst, cff according to the definitions.reference specified in the Citation File Format schema. Each element of the cff_ref_lst object has classes cff_ref, cff.

See Also

cff_read_bib() for reading ⁠*.bib⁠ files.

Work with BibTeX metadata: as_bibentry(), cff_read(), cff_write_bib(), encoded_utf_to_latex()

Read external citation metadata: cff_read()

Examples

if (requireNamespace("bibtex", quietly = TRUE)) {
  x <- c(
    "@book{einstein1921,
      title        = {Relativity: The Special and the General Theory},
      author       = {Einstein, Albert},
      year         = 1920,
      publisher    = {Henry Holt and Company},
      address      = {London, United Kingdom},
      isbn         = 9781587340925
  }",
    "@misc{misc-full,
      title        = {Handing out random pamphlets in airports},
      author       = {Joe-Bob Missilany},
      year         = 1984,
      month        = oct,
      note         = {This is a full MISC entry},
      howpublished = {Handed out at O'Hare}
  }"
  )

  cff_read_bib_text(x)
}

Inspect CFF schema values

Description

Helper functions with valid values for different keys and definition fields, according to the Citation File Format schema version 1.2.0.

• cff_schema_keys() provides the valid high-level keys of the Citation File Format.

• cff_schema_keys_license() provides valid SPDX license identifier(s) to be used on the CITATION.cff file.

• cff_schema_definitions_person() and cff_schema_definitions_entity() return the valid fields to include when defining a person or entity.

• cff_schema_definitions_refs() provides the valid keys to use in the preferred-citation and references keys.

Usage

cff_schema_keys(sorted = FALSE)

cff_schema_keys_license()

cff_schema_definitions_person()

cff_schema_definitions_entity()

cff_schema_definitions_refs()

Arguments

Value

A character vector with the names of valid keys for Citation File Format version 1.2.0.

Source

Guide to Citation File Format schema version 1.2.0.

Examples

cff_schema_keys(sorted = TRUE)
# Valid license keys.
head(cff_schema_keys_license(), 20)
cff_schema_definitions_person()
cff_schema_definitions_entity()
cff_schema_definitions_refs()

Validate a CITATION.cff file or a cff object

Description

Validate a CITATION.cff file or a cff object using the corresponding validation schema.

Usage

cff_validate(x = "CITATION.cff", verbose = TRUE)

Arguments

Value

A message indicating the validation result and an invisible TRUE/FALSE value. On error, the result has an "errors" attribute with the error summary. See Examples and attr().

See Also

jsonvalidate::json_validate(), which is the function that performs the validation. Guide to Citation File Format schema version 1.2.0.

Core cffr workflow: cff(), cff_create(), cff_modify()

Examples

# Full `.cff` example.
cff_validate(system.file("examples/CITATION_complete.cff", package = "cffr"))

# Validate a `cff` object.
cffr <- cff_create("jsonlite")
class(cffr)
cff_validate(cffr)


# `.cff` with errors.
err_f <- system.file("examples/CITATION_error.cff", package = "cffr")
# You can manipulate the errors as a data frame.
res <- try(cff_validate(err_f))

isTRUE(res)
isFALSE(res)

# Detailed results.
df_errors <- attr(res, "errors")

df_errors[, c("field", "message")]

# An R citation file is not a `.cff` file, so it throws an error.
try(cff_validate(system.file("CITATION", package = "cffr")))

Write a CITATION.cff file

Description

This is the core function of the package and likely to be the only one you need when developing a package.

This function writes a CITATION.cff file for a given package. It wraps cff_create() to create the cff object, then writes it to a YAML-formatted file in one command.

Usage

cff_write(
  x,
  outfile = "CITATION.cff",
  keys = list(),
  cff_version = "1.2.0",
  gh_keywords = TRUE,
  r_citation = FALSE,
  dependencies = TRUE,
  validate = TRUE,
  verbose = TRUE,
  authors_roles = c("aut", "cre"),
  encoding = "UTF-8"
)

Arguments

Details

For details of authors_roles, see cff_create().

When creating and writing a CITATION.cff for the first time, this function adds the pattern "^CITATION\.cff$" to your .Rbuildignore file.

Value

A CITATION.cff file and an invisible cff object.

See Also

Guide to Citation File Format schema version 1.2.0. This function unifies the cff_create() and cff_validate() workflow for writing a file.

Write citation metadata files: cff_write_bib()

Examples

tmpfile <- tempfile(fileext = ".cff")
cff_obj <- cff_write("jsonlite", outfile = tmpfile)

cff_obj

# Force cleanup.
file.remove(tmpfile)

Export R objects to multiple file types

Description

Export R objects representing citations to specific file formats:

• cff_write_bib() creates a .bib file.

• cff_write_citation() creates an R citation file as described in Section 1.9 of Writing R Extensions (R Core Team 2023).

Usage

cff_write_bib(
  x,
  file = tempfile(fileext = ".bib"),
  append = FALSE,
  verbose = TRUE,
  ascii = FALSE,
  ...
)

cff_write_citation(
  x,
  file = tempfile("CITATION_"),
  append = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Details

When x is a cff object, it is converted to BibTeX using toBibtex.cff().

For security reasons, if the file already exists, the function creates a backup copy in the same directory.

Value

Writes the corresponding file specified by the file argument.

References

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

See Also

vignette("bibtex-cff", package = "cffr"), knitr::write_bib() and the following packages:

• bibtex.

• RefManageR.

• rbibutils.

Work with BibTeX metadata: as_bibentry(), cff_read(), cff_read_bib_text(), encoded_utf_to_latex()

Write citation metadata files: cff_write()

Examples

bib <- bibentry("Misc",
  title = "My title",
  author = "Fran Pérez"
)

my_temp_bib <- tempfile(fileext = ".bib")

cff_write_bib(bib, file = my_temp_bib)

cat(readLines(my_temp_bib), sep = "\n")

cff_write_bib(bib, file = my_temp_bib, ascii = TRUE, append = TRUE)

cat(readLines(my_temp_bib), sep = "\n")
# Create an R citation file.
# Use a system file.
f <- system.file("examples/preferred-citation-book.cff", package = "cffr")
a_cff <- cff_read(f)

out <- file.path(tempdir(), "CITATION")
cff_write_citation(a_cff, file = out)

# Check by reading with a meta object.
meta <- packageDescription("cffr")
meta$Encoding <- "UTF-8"

utils::readCitationFile(out, meta)

Mapping between License fields and SPDX

Description

A dataset containing the mapping between the License strings observed on CRAN packages and their approximate match on the SPDX License List.

Format

A data frame with 86 rows and 2 variables:

LICENSE

A valid License string on CRAN.

SPDX

A valid SPDX License Identifier.

Source

https://spdx.org/licenses/

See Also

Writing R Extensions, Licensing section.

Examples

data("cran_to_spdx")

head(cran_to_spdx, 20)

Encode UTF-8 text to LaTeX

Description

Transform a UTF-8 string into LaTeX special characters.

Usage

encoded_utf_to_latex(x)

Arguments

Details

This is a variation of tools::encoded_text_to_latex() with some additional replacements for better compatibility.

Value

A string with the corresponding transformations.

See Also

tools::encoded_text_to_latex()

Work with BibTeX metadata: as_bibentry(), cff_read(), cff_read_bib_text(), cff_write_bib()

Examples

# Full range of supported characters in R.
library(tools)

range <- 1:511

ascii_table <- data.frame(
  dec = range,
  utf8 = intToUtf8(range, multiple = TRUE)
)

# Add LaTeX using the base approach.
ascii_table$latex_base <- encoded_text_to_latex(ascii_table$utf8,
  encoding = "UTF-8"
)

# With cffr.
ascii_table$latex_cffr <- encoded_utf_to_latex(ascii_table$utf8)

ascii_table

Previous API: Write files

Description

Use cff_write_bib() or cff_write_citation().

Usage

write_bib(x, file = tempfile(), append = FALSE, verbose = TRUE, ascii = FALSE)

write_citation(
  x,
  file = "./inst/CITATION",
  append = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

Writes a file.

See Also

• cff_write_bib() for writing ⁠*.bib⁠ files.

• cff_write_citation() for writing R CITATION files.

Deprecated functions: cff_extract_to_bibtex(), cff_from_bibtex(), cff_parse_citation(), cff_parse_person()

Examples

bib <- bibentry("Misc",
  title = "My title",
  author = "Fran Pérez"
)

my_temp_bib <- tempfile(fileext = ".bib")

cff_write_bib(bib, file = my_temp_bib)

cat(readLines(my_temp_bib), sep = "\n")

cff_write_bib(bib, file = my_temp_bib, ascii = TRUE, append = TRUE)

cat(readLines(my_temp_bib), sep = "\n")