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 simply a named list to which we added 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() not only converts a list to cff but also 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.

  • Similarly, 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 the utils::person() function.

## 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 according to the Citation File Format schema:

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

cff_validate(a_cff_object)
#> == Validating cff ==============================================================
#> x Validation failed. This <cff> 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 result of the validation (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> is valid.

Base methods provided by cffr

cffr version 1.0.0 provides additional S3 methods for common coercion functions of 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

See also

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