R: Coerce *R* objects to 'cff_pers_lst' objects ('cff' persons)

as_cff_person {cffr}

R Documentation

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

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

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.

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.

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

# 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 <fake@email.com> ",
  "(<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"))

[Package cffr version 1.0.1 Index]

Coerce R objects to cff_pers_lst objects (cff persons)