as_cff_person: Coerce R objects to `cff_pers_lst` objects

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 in the following guide: Citation File Format schema guide.

as_cff_person() is an S3 generic, with methods for:

person: Objects created with utils::person().
character: Strings with the definition for one or more authors, using the standard BibTeX notation (see Markey, 2009) and related formats, such as the output of base::format() for person objects (see format.person()).
Default: Other inputs are first coerced with base::as.character().

The inverse transformation (cff_pers_lst to person) can be performed 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 as defined by definitions.person or definitions.entity specified in the following guide: Citation File Format schema guide. Each element of the cff_pers_lst object has classes cff_pers, cff.

Arguments

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

Details

as_cff_person() recognizes whether the input should be converted with the CFF reference for definitions.person or definitions.entity.

as_cff_person() uses a custom algorithm that parses names as explained in Section 11 of "Tame the BeaST" (Markey, 2009) (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 key given-names.
von is mapped to the CFF key name-particle.
Last is mapped to the CFF key family-names.
Jr is mapped to the CFF key name-suffix.

For entities, the entire character is mapped to name. We recommend "protecting" entity names with {}:

# Avoid unprotected entity names.
entity <- "Elephant and Castle"
as_cff_person(entity)
- name: Elephant
- name: Castle
# Protect entity names with braces.
entity_protect <- "{Elephant and Castle}"
as_cff_person(entity_protect)
- name: Elephant and Castle

as_cff_person() attempts to extract as much information as possible. For character strings from format.person(), the email and ORCID are also extracted.

References

Patashnik O (1988). "BIBTEXing." https://osl.ugr.es/CTAN/biblio/bibtex/base/btxdoc.pdf.

Markey N (2009). Tame the BeaST: The B to X of BibTeX. 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.

Examples

Run this code

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

# Classes `cff_pers_lst` and `cff`.
class(cff_person)

# Each element has classes `cff_pers` and `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  ",
  "(city: Miami, region: California, country: US)"
)
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

# Print as BibTeX with the method.
toBibtex(a_cff)

# Or as a `person` object.
as.person(a_cff)

# Or use BibTeX style as input.

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