as_cff_person: Coerce R objects to `cff_pers_lst` objects (`cff` persons)

Description

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

Usage

as_cff_person(x, ...)
# S3 method for default
as_cff_person(x, ...)
# S3 method for person
as_cff_person(x, ...)
# S3 method for character
as_cff_person(x, ...)

Value

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.

Arguments

x: Any R object.
...: Ignored by this method.

Details

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.

References

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

Run this code

# Create a person object
a_person <- person(
  given = "First", family = "Author",
  role = c("aut", "cre"),
  email = "first.last@example.com", 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  ",
  "()"
)
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"))

Run the code above in your browser using DataLab