Title: | Generate Citation File Format ('cff') Metadata for R Packages |
---|---|
Description: | The Citation File Format version 1.2.0 <doi:10.5281/zenodo.5171937> is a human and machine readable file format which provides citation metadata for software. This package provides core utilities to generate and validate this metadata. |
Authors: | Diego Hernangómez [aut, cre, cph]
|
Maintainer: | Diego Hernangómez <[email protected]> |
License: | GPL (>= 3) |
Version: | 1.1.1 |
Built: | 2024-08-28 15:18:10 UTC |
Source: | https://github.com/ropensci/cffr |
bibentry
objects from several sourcesThis 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.
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, ...)
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, ...)
x |
The source that would be used for generating
the
|
... |
Additional arguments to be passed to or from methods. |
what |
Fields to extract from a full
See |
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")'.
as_bibentry()
returns a bibentry
object with one or more entries.
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.
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:
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
# From a cff object ---- cff_object <- cff() cff_object # bibentry object bib <- as_bibentry(cff_object) class(bib) bib # Print as bibtex toBibtex(bib) # Thanks to the S3 Method we can also do 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)
# From a cff object ---- cff_object <- cff() cff_object # bibentry object bib <- as_bibentry(cff_object) class(bib) bib # Print as bibtex toBibtex(bib) # Thanks to the S3 Method we can also do 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)
person
and bibentry
objects to cff
as_cff()
turns an existing list-like R object into a so-called
cff
, a list with class cff
, with the corresponding
sub-class if 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
object as produced by toBibtex()
.
Default: Other inputs are first coerced with as.list()
.
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, ...)
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, ...)
x |
A |
... |
Additional arguments to be passed on to other methods. |
For as_cff.bibentry()
/ as_cff.Bibtex()
see
vignette("bibtex_cff", "cffr")
to understand how the mapping is performed.
as_cff_person()
is preferred over as_cff.person()
, since it can handle
character
person such as "Davis, Jr., Sammy"
. For person
objects both
functions are similar.
as_cff.person()
returns an object with classes
cff_pers_lst, cff
.
as_cff.bibentry()
and as_cff.Bibtex()
returns an object with classes
cff_ref_lst, cff
.
The rest of methods returns usually an object of class cff
. However if
x
have an structure compatible with definitions.person
,
definitions.entity
or definitions.reference
the object would have the
corresponding subclass.
Learn more about the cffr class system in cff_class.
cff()
: Create a full cff
object from scratch.
cff_modify()
: Modify a cff
object.
cff_create()
: Create a cff
object of a R package.
cff_read()
: Create a cff
object from a external file.
as_cff_person()
: Recommended way for creating persons in CFF format.
Learn more about the cffr class system in cff_class.
Coercing between R classes with S3 Methods:
as_bibentry()
,
as_cff_person()
,
cff_class
# Convert a list to "cff" object cffobj <- as_cff(list( "cff-version" = "1.2.0", title = "Manipulating files" )) class(cffobj) # Nice display thanks to 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)
# Convert a list to "cff" object cffobj <- as_cff(list( "cff-version" = "1.2.0", title = "Manipulating files" )) class(cffobj) # Nice display thanks to 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)
cff_pers_lst
objects (cff
persons)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
: String with the definition of an author or several authors,
using the standard BibTeX notation (see Markey, 2007) and others, like
the output of format()
for person (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()
.
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, ...)
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, ...)
x |
Any R object. |
... |
Ignored by this method. |
as_cff_person()
would recognize if the input should be converted using the
CFF reference for definition.person
or definition.entity
.
as_cff_person()
uses a custom algorithm that tries to break a name 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 field given-names
.
von
is mapped to the CFF field name-particle
.
Last
is mapped to the CFF field family-names
.
Jr
is mapped to the CFF field name-suffix
.
In the case of entities, the whole character
would be mapped to name
.
It is a good practice to "protect" entity's names with {}
:
# Don't do entity <- "Elephant and Castle" as_cff_person(entity) - name: Elephant - name: Castle # Do entity_protect <- "{Elephant and Castle}" as_cff_person(entity_protect) - name: Elephant and Castle
as_cff_person()
would try to add as many information as possible.
On character
string coming from format.person()
the
email and the ORCID would be retrieved as well.
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 would have classes
cff_pers, cff
.
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.
Examples in vignette("cffr", "cffr")
and utils::person()
.
Learn more about the classes cff_pers_lst, cff_pers
classes in cff_class.
Coercing between R classes with S3 Methods:
as_bibentry()
,
as_cff()
,
cff_class
# Create a person object a_person <- person( given = "First", family = "Author", role = c("aut", "cre"), email = "[email protected]", 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) # With each element with 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 <[email protected]> ", "(<https://orcid.org/0000-0001-8457-4658>)" ) 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 you can use BibTeX style as input if you prefer 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 a person object a_person <- person( given = "First", family = "Author", role = c("aut", "cre"), email = "[email protected]", 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) # With each element with 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 <[email protected]> ", "(<https://orcid.org/0000-0001-8457-4658>)" ) 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 you can use BibTeX style as input if you prefer 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"))
cff
objects from direct inputsA class and utility methods for reading, creating and holding CFF
information. See cff_class to learn more about cff
objects.
cff(path, ...)
cff(path, ...)
path |
|
... |
Named arguments to be used for creating a |
cff()
would convert _
in the name of the argument to -
, e.g.
cff_version = "1.2.0'
would be converted to cff-version = "1.2.0'
.
Valid parameters 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
A cff
object. Under the hood, a cff
object is a regular list
object with a special print
method.
Other core functions of cffr:
cff_create()
,
cff_modify()
,
cff_validate()
# Blank cff cff() # Use custom params test <- cff( title = "Manipulating files", keywords = c("A", "new", "list", "of", "keywords"), authors = as_cff_person("New author") ) test # 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 # Would pass cff_validate(new)
# Blank cff cff() # Use custom params test <- cff( title = "Manipulating files", keywords = c("A", "new", "list", "of", "keywords"), authors = as_cff_person("New author") ) test # 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 # Would pass cff_validate(new)
cff
object from several sourcesCreate a full and possibly valid cff
object from a given source. This
object can be written to a *.cff
file with cff_write()
,
see Examples.
Most of the heavy lifting of cffr is done via this function.
cff_create( x, keys = list(), cff_version = "1.2.0", gh_keywords = TRUE, dependencies = TRUE, authors_roles = c("aut", "cre") )
cff_create( x, keys = list(), cff_version = "1.2.0", gh_keywords = TRUE, dependencies = TRUE, authors_roles = c("aut", "cre") )
x |
The source that would be used for generating
the
|
keys |
List of additional keys to add to the |
cff_version |
The Citation File Format schema version that the
|
gh_keywords |
Logical |
dependencies |
Logical |
authors_roles |
Roles to be considered as authors of the package when
generating the |
If x
is a path to a DESCRIPTION
file or inst/CITATION
, is not present
on your package, cffr would auto-generate a preferred-citation
key using the information provided on that file.
By default, only persons whose role in the DESCRIPTION
file of the package
is author ("aut"
) or maintainer ("cre"
) are considered to be authors
of the package. The default setting can be controlled via the authors_roles
parameter. See Details on person()
to get additional insights
on person roles.
A cff
object.
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 CFF file.
vignette("cffr", "cffr")
shows an introduction on how manipulate
cff
objects.
vignette("crosswalk", package = "cffr")
provides details on how the
metadata of a package is mapped to produce a cff
object.
Other core functions of cffr:
cff()
,
cff_modify()
,
cff_validate()
# 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 fields", abstract = "New abstract", keywords = c("A", "new", "list", "of", "keywords"), authors = as_cff_person("New author") ) cff_create(demo_file, keys = newkeys) # Update a field on a list - i,e: authors, contacts, etc. # We are adding a new contact here 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))
# 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 fields", abstract = "New abstract", keywords = c("A", "new", "list", "of", "keywords"), authors = as_cff_person("New author") ) cff_create(demo_file, keys = newkeys) # Update a field on a list - i,e: authors, contacts, etc. # We are adding a new contact here 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))
This function would install a GitHub Action on your repo. The action will
update your CITATION.cff
when any of these events occur:
You publish a new release of the package.
Your DESCRIPTION
or inst/CITATION
are modified.
The action can be run also manually.
cff_gha_update(path = ".", overwrite = FALSE)
cff_gha_update(path = ".", overwrite = FALSE)
path |
Project root directory. |
overwrite |
Logical. If already present, do you want to overwrite your action? |
Triggers on your action can be modified, see Events that trigger workflows.
Invisible, this function is called by its side effects.
Other Git/GitHub helpers provided by cffr:
cff_git_hook
## Not run: cff_gha_update() ## End(Not run)
## Not run: cff_gha_update() ## End(Not run)
Install a
pre-commit hook
that remembers you to update your CITATION.cff
file. This is a wrapper of
usethis::use_git_hook()
.
cff_git_hook_install() cff_git_hook_remove()
cff_git_hook_install() cff_git_hook_remove()
This function would install 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 would warn you if any of the following conditions are met:
You included in a commit your DESCRIPTION
or inst/CITATION
file, you
are not including your CITATION.cff
and the CITATION.cff
file is
"older" than any of your DESCRIPTION
or inst/CITATION
file.
You have updated your CITATION.cff
but you are not including it on
your commit.
Invisible. This function is called for its side effects.
The pre-commit hook may prevent you to commit if you are not updating your
CITATION.cff
. However, the mechanism of detection is not perfect and would
be triggered also even if you have tried to update your CITATION.cff
file.
This is typically the case when you have updated your DESCRIPTION
or
inst/CITATION
files but those changes doesn't make a change on your
CITATION.cff
file (i.e. you are including new dependencies).
In those cases, you can override the check running git commit --no-verify
on the terminal.
If you are using RStudio you can run also this command from a R script by selecting that line and sending it to the terminal using:
Windows & Linux: Ctrl+Alt+Enter
.
Mac: Cmd+Option+Return
.
You can remove the pre-commit hook by running cff_git_hook_remove()
.
usethis::use_git_hook()
, that is the underlying function used by
cff_git_hook_install()
.
usethis::use_git()
and related function of usethis for using
Git with R packages.
Other Git/GitHub helpers provided by cffr:
cff_gha_update()
## Not run: cff_git_hook_install() ## End(Not run)
## Not run: cff_git_hook_install() ## End(Not run)
cff
objectAdd new keys or modify existing ones on a cff
object.
cff_modify(x, ...)
cff_modify(x, ...)
x |
A |
... |
Named arguments to be used for modifying |
Keys provided in ...
would override the corresponding key in x
.
It is possible to add additional keys not detected by cff_create()
using
the keys
argument. A list of valid keys can be retrieved with
cff_schema_keys()
. Please refer to
Guide to Citation File Format schema version 1.2.0.
for additional details.
A cff
object.
This function is wrapper of utils::modifyList()
.
See cff()
for creating cff
objects from scratch.
Other core functions of cffr:
cff()
,
cff_create()
,
cff_validate()
x <- cff() x cff_validate(x) x_mod <- cff_modify(x, contact = as_cff_person("A contact"), message = "This overwrites fields", title = "New Title", abstract = "New abstract", doi = "10.21105/joss.03900" ) x_mod cff_validate(x_mod)
x <- cff() x cff_validate(x) x_mod <- cff_modify(x, contact = as_cff_person("A contact"), message = "This overwrites fields", title = "New Title", abstract = "New abstract", doi = "10.21105/joss.03900" ) x_mod cff_validate(x_mod)
cff
objectRead files and convert them to cff
objects. Files supported
are:
CITATION.cff
files.
DESCRIPTION
files.
R citation files (usually located in inst/CITATION
).
BibTeX files (with extension *.bib
).
cff_read()
would try to guess the type of file provided in path
. However
we provide a series of alias for each specific type of file:
cff_read_cff_citation()
, that uses yaml::read_yaml()
.
cff_read_description()
, using desc::desc()
.
cff_read_bib()
requires bibtex (>= 0.5.0) and uses
bibtex::read.bib()
.
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", ...)
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", ...)
path |
Path to a file. |
... |
Arguments to be passed to other functions (i.e. to
|
cff_version |
The Citation File Format schema version that the
|
gh_keywords |
Logical |
authors_roles |
Roles to be considered as authors of the package when
generating the |
meta |
A list of package metadata as obtained by
|
encoding |
Encoding to be assumed for |
For details of cff_read_description()
see cff_create()
.
meta
objectSection 1.9 CITATION files of Writing R Extensions (R Core Team 2023)
specifies how to create dynamic CITATION
files using meta
object, hence
the meta
argument in cff_read_citation()
may be needed for reading
some files correctly.
cff_read_cff_citation()
and cff_read_description()
returns a object
with class cff
.
cff_read_citation()
and cff_read_bib()
returns an object of classes
cff_ref_lst, cff
according to the definitions.references
specified in the Citation File Format schema.
Learn more about the cffr class system in cff_class.
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.
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
).
Other functions for reading external files:
cff_read_bib_text()
Other functions for working with BibTeX format:
as_bibentry()
,
cff_read_bib_text()
,
cff_write_bib()
,
encoded_utf_to_latex()
# Create cff object from cff file from_cff_file <- cff_read(system.file("examples/CITATION_basic.cff", package = "cffr" )) head(from_cff_file, 7) # Create cff object from DESCRIPTION from_desc <- cff_read(system.file("examples/DESCRIPTION_basic", package = "cffr" )) from_desc # Create 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 cff object from CITATION from_citation <- cff_read(system.file("CITATION", package = "cffr")) # First item only from_citation[[1]]
# Create cff object from cff file from_cff_file <- cff_read(system.file("examples/CITATION_basic.cff", package = "cffr" )) head(from_cff_file, 7) # Create cff object from DESCRIPTION from_desc <- cff_read(system.file("examples/DESCRIPTION_basic", package = "cffr" )) from_desc # Create 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 cff object from CITATION from_citation <- cff_read(system.file("CITATION", package = "cffr")) # First item only from_citation[[1]]
cff_ref_lst
objectConvert a character
representing a BibTeX entry to a
cff_ref_lst
object.
cff_read_bib_text(x, encoding = "UTF-8", ...)
cff_read_bib_text(x, encoding = "UTF-8", ...)
x |
A vector of |
encoding |
Encoding to be assumed for |
... |
Arguments passed on to |
This is a helper function that writes x
to a *.bib
file and reads it with
cff_read_bib()
.
This function requires bibtex (>= 0.5.0) and uses
bibtex::read.bib()
.
An object of classes cff_ref_lst, cff
according to the
definitions.references
specified in
the Citation File Format schema.
Each element of the cff_ref_lst
object would have classes
cff_ref, cff
.
cff_read_bib()
for reading *.bib
files.
Other functions for working with BibTeX format:
as_bibentry()
,
cff_read()
,
cff_write_bib()
,
encoded_utf_to_latex()
Other functions for reading external files:
cff_read()
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) }
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) }
Helper functions with the valid values of different 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 the valid
SPDX license identifier(s) to be used on the
CITATION.cff
file.
cff_schema_definitions_person()
and cff_schema_definitions_entity()
returns the valid fields to be included when defining a
person or entity.
cff_schema_definitions_refs()
provides the valid
keys to be used on the preferred-citation
and references
keys.
cff_schema_keys(sorted = FALSE) cff_schema_keys_license() cff_schema_definitions_person() cff_schema_definitions_entity() cff_schema_definitions_refs()
cff_schema_keys(sorted = FALSE) cff_schema_keys_license() cff_schema_definitions_person() cff_schema_definitions_entity() cff_schema_definitions_refs()
sorted |
Logical |
A vector of characters with the names of the valid keys to be used on a Citation File Format version 1.2.0
Guide to Citation File Format schema version 1.2.0.
cff_schema_keys(sorted = TRUE) # Valid Licenses keys head(cff_schema_keys_license(), 20) cff_schema_definitions_person() cff_schema_definitions_entity() cff_schema_definitions_refs()
cff_schema_keys(sorted = TRUE) # Valid Licenses keys head(cff_schema_keys_license(), 20) cff_schema_definitions_person() cff_schema_definitions_entity() cff_schema_definitions_refs()
CITATION.cff
file or a cff
objectValidate a CITATION.cff
file or a cff
object using the corresponding validation schema.
cff_validate(x = "CITATION.cff", verbose = TRUE)
cff_validate(x = "CITATION.cff", verbose = TRUE)
x |
This is expected to be either a full |
verbose |
Logical |
A message indicating the result of the validation and an invisible value
TRUE/FALSE
. On error, the results would have an attribute "errors"
containing the error summary (see Examples and attr()
).
Guide to Citation File Format schema version 1.2.0.
jsonvalidate::json_validate()
, that is the function that performs the
validation.
Other core functions of cffr:
cff()
,
cff_create()
,
cff_modify()
# Full .cff example cff_validate(system.file("examples/CITATION_complete.cff", package = "cffr")) # Validate a cffr object cffr <- cff_create("jsonlite") class(cffr) cff_validate(cffr) # .cff with errors err_f <- system.file("examples/CITATION_error.cff", package = "cffr") # Can manipulate the errors as data frame res <- try(cff_validate(err_f)) isTRUE(res) isFALSE(res) attr(res, "errors") # If a CITATION file (note that is not .cff) it throws an error try(cff_validate(system.file("CITATION", package = "cffr")))
# Full .cff example cff_validate(system.file("examples/CITATION_complete.cff", package = "cffr")) # Validate a cffr object cffr <- cff_create("jsonlite") class(cffr) cff_validate(cffr) # .cff with errors err_f <- system.file("examples/CITATION_error.cff", package = "cffr") # Can manipulate the errors as data frame res <- try(cff_validate(err_f)) isTRUE(res) isFALSE(res) attr(res, "errors") # If a CITATION file (note that is not .cff) it throws an error try(cff_validate(system.file("CITATION", package = "cffr")))
CITATION.cff
fileThis is the core function of the package and likely to be the only one you would need when developing a package.
This function writes out a CITATION.cff
file for a given package. This
function is basically a wrapper around cff_create()
to both create the
cff
object and write it out to a YAML-formatted file in
one command.
cff_write( x, outfile = "CITATION.cff", keys = list(), cff_version = "1.2.0", gh_keywords = TRUE, dependencies = TRUE, validate = TRUE, verbose = TRUE, authors_roles = c("aut", "cre"), encoding = "UTF-8" )
cff_write( x, outfile = "CITATION.cff", keys = list(), cff_version = "1.2.0", gh_keywords = TRUE, dependencies = TRUE, validate = TRUE, verbose = TRUE, authors_roles = c("aut", "cre"), encoding = "UTF-8" )
x |
The source that would be used for generating
the
|
outfile |
The name and path of the |
keys |
List of additional keys to add to the |
cff_version |
The Citation File Format schema version that the
|
gh_keywords |
Logical |
dependencies |
Logical |
validate |
validate Logical |
verbose |
Logical |
authors_roles |
Roles to be considered as authors of the package when
generating the |
encoding |
The name of the encoding to be assumed. Default is |
For details of authors_roles
see cff_create()
.
When creating and writing a CITATION.cff
for the first time, the function
adds the pattern "^CITATION\.cff$"
to your .Rbuildignore
file to avoid
NOTE
s and WARNING
s in R CMD CHECK
.
A CITATION.cff
file and an (invisible) cff
object.
Guide to Citation File Format schema version 1.2.0.
This function unifies the workflow cff_create()
+ cff_validate()
+
write a file.
Other functions for creating external files:
cff_write_bib()
tmpfile <- tempfile(fileext = ".cff") cff_obj <- cff_write("jsonlite", outfile = tmpfile) cff_obj # Force clean-up file.remove(tmpfile)
tmpfile <- tempfile(fileext = ".cff") cff_obj <- cff_write("jsonlite", outfile = tmpfile) cff_obj # Force clean-up file.remove(tmpfile)
Export R objects representing citations to specific file types:
cff_write_bib()
creates a .bib
file.
cff_write_citation()
creates a R citation file as explained in
Section 1.9 CITATION files of Writing R Extensions (R Core Team 2023).
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, ... )
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, ... )
x |
|
file |
Name of the file to be created. If |
append |
Whether to append the entries to an existing file or not. |
verbose |
Display informative messages |
ascii |
Whether to write the entries using ASCII characters only or not. |
... |
Arguments passed on to
|
When x
is a cff
object it would be converted to Bibtex
using
toBibtex.cff()
.
For security reasons, if the file already exists the function would create a backup copy on the same directory.
Writes the corresponding file specified on the file
parameter.
R Core Team (2023). Writing R Extensions. https://cran.r-project.org/doc/manuals/r-release/R-exts.html
vignette("bibtex_cff", "cffr")
, knitr::write_bib()
and the
following packages:
Other functions for working with BibTeX format:
as_bibentry()
,
cff_read()
,
cff_read_bib_text()
,
encoded_utf_to_latex()
Other functions for creating external files:
cff_write()
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 a 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, use meta object meta <- packageDescription("cffr") meta$Encoding <- "UTF-8" utils::readCitationFile(out, meta)
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 a 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, use meta object meta <- packageDescription("cffr") meta$Encoding <- "UTF-8" utils::readCitationFile(out, meta)
License
fields and SPDXA dataset containing the mapping between the License
strings observed
on CRAN packages and its (approximate) match on the
SPDX License List.
cran_to_spdx
cran_to_spdx
A data frame with 94 rows and 2 variables:
LICENSE: A valid License
string on CRAN.
SPDX. A valid SPDX License Identifier.
Writing R Extensions, Licensing section.
data("cran_to_spdx") head(cran_to_spdx, 20)
data("cran_to_spdx") head(cran_to_spdx, 20)