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: 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.

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.

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

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] (<https://orcid.org/0000-0001-8457-4658>, 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> (<https://orcid.org/0000-0001-8457-4658>, An affiliation)"

# Coerce a string
a_str <- paste0(
  "Julio Iglesias <fake@email.com> ",
  "(<https://orcid.org/0000-0001-8457-4658>)"
)
as_cff_person(a_str)
#> - family-names: Iglesias
#>   given-names: Julio
#>   email: fake@email.com
#>   orcid: https://orcid.org/0000-0001-8457-4658

# 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)
#> [1] "Kent, Clark and Lane, Lois and {Oscorp Inc.}"

# Or as person object
as.person(a_cff)
#> [1] "Clark Kent (Daily Planet)" "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"))
#> [1] "von Karajan, Herbert"