Skip to contents

The cff class

Source: R/docs.R, R/methods.R
cff_class.Rd

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