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 for one or more authors, using the standard BibTeX notation (see Markey, 2007) and related formats, such as the output of format() for person objects (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.

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 parses names 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 {}:

# Do not use 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

See Examples for more information.

See also

Examples in vignette("cffr", package = "cffr") and utils::person(). Learn more about the cff_pers_lst and cff_pers classes in cff_class.

Coerce between R classes: 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"         

# Each element has 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 use BibTeX style as input.

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