Create bibentry objects from several sources

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

With toBibtex() it is possible to 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

x

The source that would be used for generating the bibentry object via cffr. It could be:

• A missing value. That would retrieve the DESCRIPTION file on your in-development package.

• An existing cff object created with cff(), cff_create() or as_cff().

• Path to a CITATION.cff file ("CITATION.cff"),

• The name of an installed package ("jsonlite"), or

• Path to a DESCRIPTION file ("DESCRIPTION").

...

Additional arguments to be passed to or from methods.

what

Fields to extract from a full cff object. The value could be:

• preferred: This would create a single entry with the main citation info of the package (key preferred-citation).

• references: Extract all the entries of references key.

• all: A combination of the previous two options. This would extract both the preferred-citation and the references key.

See vignette("crosswalk", package = "cffr").

Value

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

Details

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

as_bibtex() 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", "cffr")`.

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("crosswalk", package = "cffr") provides details on how the metadata of a package is mapped to produce a cff object.

• vignette("bibtex_cff", "cffr") provides detailed information about the internal mapping performed between cff objects and BibTeX markup ( both cff to BibTeX and BibTeX to cff).

Other related functions:

• utils::toBibtex().

Other functions for working with BibTeX format: cff_read(), cff_read_bib_text(), cff_write_bib(), encoded_utf_to_latex()

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

Examples

# \donttest{
# From a cff object ----
cff_object <- cff()

cff_object
#> 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

# bibentry object
bib <- as_bibentry(cff_object)

class(bib)
#> [1] "bibentry"

bib
#> Doe J (????). “My Research Software.”

# Print as bibtex
toBibtex(bib)
#> @Misc{doe,
#>   title = {My Research Software},
#>   author = {John Doe},
#> }

# Thanks to the S3 Method we can also do
toBibtex(cff_object)
#> @Misc{doe,
#>   title = {My Research Software},
#>   author = {John Doe},
#> }

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

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

cff_file
#> van der Real Person, IV O, Entity Project Team Conference entity
#> (2017). “Book Title.” In van der Real Person, IV O, Entity Project Team
#> Conference entity (eds.), volume 2 number 123 series Collection Title,
#> chapter Chapter 2 - "Reference keys", 2nd edition edition, 123-456.
#> Entity Project Team Conference entity, 22 Acacia Avenue, Citationburgh,
#> Renfrewshire, GB. ISBN 978-1-89183-044-0, doi:10.5281/zenodo.1003150
#> <https://doi.org/10.5281/zenodo.1003150>, A field for general notes
#> about the reference, usable in other formats such as BibTeX.,
#> <http://j.mp>.

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

installed_package
#> FitzJohn R, Ashton R, Buus M, Poberezkin E (2024). “jsonvalidate:
#> Validate 'JSON' Schema.” doi:10.32614/CRAN.package.jsonvalidate
#> <https://doi.org/10.32614/CRAN.package.jsonvalidate>,
#> <https://docs.ropensci.org/jsonvalidate/>.
#> 
#> Chang W (2024). “R6.” doi:10.32614/CRAN.package.R6
#> <https://doi.org/10.32614/CRAN.package.R6>, Imports,
#> <https://r6.r-lib.org>.
#> 
#> Ooms J (2024). “V8.” doi:10.32614/CRAN.package.V8
#> <https://doi.org/10.32614/CRAN.package.V8>, Imports,
#> <https://jeroen.r-universe.dev/V8>.
#> 
#> Xie Y (2024). “knitr.” doi:10.32614/CRAN.package.knitr
#> <https://doi.org/10.32614/CRAN.package.knitr>, Suggests,
#> <https://yihui.org/knitr/>.
#> 
#> Ooms J (2024). “jsonlite.” doi:10.32614/CRAN.package.jsonlite
#> <https://doi.org/10.32614/CRAN.package.jsonlite>, Suggests,
#> <https://jeroen.r-universe.dev/jsonlite>.
#> 
#> Allaire J, Xie Y, Dervieux C, McPherson J, Luraschi J, Ushey K, Atkins
#> A, Wickham H, Cheng J, Chang W, Iannone R (2024). “rmarkdown.”
#> doi:10.32614/CRAN.package.rmarkdown
#> <https://doi.org/10.32614/CRAN.package.rmarkdown>, Suggests,
#> <https://pkgs.rstudio.com/rmarkdown/>.
#> 
#> Wickham H (2024). “testthat.” doi:10.32614/CRAN.package.testthat
#> <https://doi.org/10.32614/CRAN.package.testthat>, Suggests,
#> <https://testthat.r-lib.org>.
#> 
#> Hester J, Henry L, Müller K, Ushey K, Wickham H, Chang W (2024).
#> “withr.” doi:10.32614/CRAN.package.withr
#> <https://doi.org/10.32614/CRAN.package.withr>, Suggests,
#> <https://withr.r-lib.org>.


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

toBibtex(desc_file)
#> @Misc{boettiger_etall,
#>   title = {codemetar: Generate 'CodeMeta' Metadata for R Packages},
#>   author = {Carl Boettiger and Maëlle Salmon},
#>   doi = {10.32614/CRAN.package.codemetar},
#>   url = {https://ropensci.github.io/codemetar},
#>   abstract = {The 'Codemeta' Project defines a 'JSON-LD' format for describing software metadata, as detailed at <https://codemeta.github.io>. This package provides utilities to generate, parse, and modify 'codemeta.json' files automatically for R packages, as well as tools and examples for working with 'codemeta.json' 'JSON-LD' more generally.},
#>   keywords = {metadata,codemeta,ropensci,citation,credit,linked-data},
#>   version = {0.1.6},
#> }
# }