Skip to contents

Coerce R objects to cff_pers_lst objects (cff persons)

Source: R/as_cff_person.R
as_cff_person.Rd

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: Strings with the definition of an author or multiple authors, using the standard BibTeX notation (see Markey, 2007) and others, such as 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 using 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.

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 has classes cff_pers, cff.

Details

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

as_cff_person() uses a custom algorithm that breaks 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.

For entities, the entire character is mapped to name. It is recommended to "protect" entity 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() attempts to extract as much information as possible. For character strings from format.person(), the email and ORCID are also extracted.

References

See Examples for more information.

See also

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

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
#> [1] "First Author <first.last@example.com> [aut, cre] (ORCID: <https://orcid.org/0000-0001-8457-4658>, affiliation: An affiliation)"

cff_person <- as_cff_person(a_person)

# Class cff_pers_lst / cff
class(cff_person)
#> [1] "cff_pers_lst" "cff"         

# With each element with class cff_pers / cff
class(cff_person[[1]])
#> [1] "cff_pers" "cff"     

# Print
cff_person
#> - family-names: Author
#>   given-names: First
#>   email: first.last@example.com
#>   orcid: https://orcid.org/0000-0001-8457-4658
#>   affiliation: An affiliation

# Back to person object with S3 Method
as.person(cff_person)
#> [1] "First Author <first.last@example.com> (ORCID: <https://orcid.org/0000-0001-8457-4658>, affiliation: An affiliation)"

# Coerce a string
a_str <- paste0(
  "Julio Iglesias <fake@email.com> ",
  "(city: Miami, region: California, country: US)"
)
as_cff_person(a_str)
#> - family-names: Iglesias
#>   given-names: Julio
#>   email: fake@email.com
#>   city: Miami
#>   region: California
#>   country: US

# 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
#> - family-names: Kent
#>   given-names: Clark
#>   affiliation: Daily Planet
#> - family-names: Lane
#>   given-names: Lois
#> - name: Oscorp Inc.

# Printed as Bibtex thanks to the method
toBibtex(a_cff)
#> Kent, Clark and Lane, Lois and {Oscorp Inc.}

# Or as person object
as.person(a_cff)
#> [1] "Clark Kent (affiliation: Daily Planet)"
#> [2] "Lois Lane"                             
#> [3] "Oscorp Inc."                           

# 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)
#> - family-names: Sinatra
#>   given-names: Frank
#> - family-names: Martin
#>   given-names: Dean
#> - family-names: Davis
#>   given-names: Sammy
#>   name-suffix: Jr.
#> - family-names: Bishop
#>   given-names: Joey

as_cff_person("Herbert von Karajan")
#> - family-names: Karajan
#>   given-names: Herbert
#>   name-particle: von

toBibtex(as_cff_person("Herbert von Karajan"))
#> von Karajan, Herbert