Skip to contents

The cff class

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

The cff class

cffr implements a S3 object with class cff, that it is used to represent the information of 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
)

# As 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 (known as keys in CFF terminology) that are NULL or NA.

Sub-classes

cffr implements two special sub-classes of cff, with the aim of representing two special types of objects defined in the CFF Schema:

  • definition.person and definition.entity: CFF definition for sub-lists representing persons or entities. In cffr the sub-class cff_pers_lst has been implemented to collect an array of definition.person/entity, where each individual person or entity of the array has a sub-class cff_pers.

  • Similarly, definition.reference is the definition of CFF for collecting references to related works and other articles of software used in the development of the main work of the CFF file. This is implemented in cffr as a sub-class named cff_ref_lst for arrays of definition.reference where each element of the array has a sub-class named cff_ref.

These two sub-classes does not provide full valid cff objects, but adapts information to the schema required by CFF:

# Using the utils::person() function

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

two_persons
#> - family-names: person
#>   given-names: A
#>   orcid: https://orcid.org/0000-0000-0000-0000
#> - 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-0000-0000-0000

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

# Array of references

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

ref_list <- as_cff(cit)

ref_list
#> - type: manual
#>   title: 'R: A Language and Environment for Statistical Computing'
#>   authors:
#>   - name: R Core Team
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     address: Vienna, Austria
#>   year: '2024'
#>   url: https://www.R-project.org/
#> - type: manual
#>   title: 'yaml: Methods to Convert R Data to YAML and Back'
#>   authors:
#>   - family-names: Garbett
#>     given-names: Shawn P
#>   - family-names: Stephens
#>     given-names: Jeremy
#>   - family-names: Simonov
#>     given-names: Kirill
#>   - family-names: Xie
#>     given-names: Yihui
#>   - family-names: Dong
#>     given-names: Zhuoer
#>   - family-names: Wickham
#>     given-names: Hadley
#>   - family-names: Horner
#>     given-names: Jeffrey
#>   - name: reikoch
#>   - family-names: Beasley
#>     given-names: Will
#>   - family-names: O'Connor
#>     given-names: Brendan
#>   - family-names: Warnes
#>     given-names: Gregory R.
#>   - family-names: Quinn
#>     given-names: Michael
#>   - family-names: Kamvar
#>     given-names: Zhian N.
#>   year: '2023'
#>   notes: R package version 2.3.8
#>   url: https://github.com/vubiostat/r-yaml/

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
#> institution:
#>   name: R Foundation for Statistical Computing
#>   address: Vienna, Austria
#> year: '2024'
#> 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 CFF Schema:

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

cff_validate(a_cff_object)
#> == Validating cff ==============================================================
#> x Oops! This <cff> has the following errors:
#> * cff.authors: is required
#> * cff["cff-version"]: is required
#> * cff.message: is required
#> * cff.title: is required

cff_validate() gives minimal messages of what's wrong with our cff 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 Congratulations! This <cff> is valid

Base methods provided by cffr

cffr version 1.0.0 provides additional S3 Methods for common coercing functions of the base and utils package.

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 (<https://orcid.org/0000-0000-0000-0000>)"
#> [2] "An entity <fake@gmail.com>"

toBibtex()

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

# cff_ref, 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 = {2024},
#>   url = {https://www.R-project.org/},
#> }
#> 
#> @Manual{,
#>   title = {yaml: Methods to Convert R Data to YAML and Back},
#>   author = {Shawn P Garbett and Jeremy Stephens and Kirill Simonov and Yihui Xie and Zhuoer Dong and Hadley Wickham and Jeffrey Horner and {reikoch} and Will Beasley and Brendan O'Connor and Gregory R. Warnes and Michael Quinn and Zhian N. Kamvar},
#>   year = {2023},
#>   note = {R package version 2.3.8},
#>   url = {https://github.com/vubiostat/r-yaml/},
#> }

# cff_pers, cff_pers_lst
toBibtex(two_persons)
#> [1] "person, A and {An entity}"

References

See also

Coercing between R classes with S3 Methods: as_bibentry(), as_cff(), as_cff_person()