New toBibtex.cff method

CITATION.cff

@@ -10,9 +10,9 @@ license: GPL-3.0-or-later
 title: 'cffr: Generate Citation File Format (''cff'') Metadata for R Packages'
 version: 0.5.0.9000
 doi: 10.21105/joss.03900
-abstract: The Citation File Format version 1.2.0 <doi:10.5281/zenodo.5171937> is a
-  human and machine readable file format which provides citation metadata for software.
-  This package provides core utilities to generate and validate this metadata.
+abstract: The Citation File Format version 1.2.0 <https://doi.org/10.5281/zenodo.5171937>
+  is a human and machine readable file format which provides citation metadata for
+  software. This package provides core utilities to generate and validate this metadata.
 authors:
 - family-names: Hernangómez
   given-names: Diego

NAMESPACE

@@ -6,6 +6,7 @@ S3method(c,cff)
 S3method(head,cff)
 S3method(print,cff)
 S3method(tail,cff)
+S3method(toBibtex,cff)
 export(as.cff)
 export(cff)
 export(cff_create)
@@ -19,6 +20,7 @@ export(cff_parse_person)
 export(cff_parse_person_bibtex)
 export(cff_read)
 export(cff_read_bib)
+export(cff_read_biblines)
 export(cff_read_cff_citation)
 export(cff_read_citation)
 export(cff_read_description)

NEWS.md

@@ -13,7 +13,9 @@
 
 -   Now reading from external files is performed exclusively by `cff_read()` and
     additionally by the more-specific new functions `cff_read_cff_citation()`,
-    `cff_read_description()`, `cff_read_citation()` and `cff_read_bib()`.
+    `cff_read_description()`, `cff_read_citation()` and `cff_read_bib()`. It is
+    also possible to read BibTeX lines with `cff_read_biblines()`. Previous
+    function `cff_from_bibtex()` is now superseded.
 
     ### Methods
 
@@ -27,8 +29,9 @@
         [entity](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsentity)
         (e.g. authors, contacts, editors, publisher).
     -   `head.cff()`, `tail.cff()`.
+    -   `toBibtex.cff()`
 
-## Changes on bibtex crosswalk
+## Changes on BibTeX crosswalk
 
 -   **\@inbook** and **\@book** gains a new value on [CFF]{.underline} when
     **series** is provided: [collection-type: book-series.]{.underline}

R/cff-methods.R

@@ -79,3 +79,47 @@ head.cff <- function(x, n = 6L, ...) {
 tail.cff <- function(x, n = 6L, ...) {
   as.cff(NextMethod())
 }
+
+
+#' Converting [`cff`][cff-class] objects to BibTeX
+#'
+#' @description
+#'
+#' This method convert [`cff`][cff-class] objects to `Bibtex` objects as
+#' provided by [utils::toBibtex()]. These objects are character vectors with
+#' BibTeX markup.
+#'
+#' @keywords internal
+#' @family s3method
+#' @family bibtex
+#' @export
+#' @rdname toBibtex.cff
+#' @seealso [utils::toBibtex()]
+#'
+#' @param object `cff` object.
+#' @param ... Arguments passed to [utils::toBibtex()].
+#' @inheritParams cff_to_bibentry
+#'
+#' @examples
+#' a_cff <- cff_create("cffr")
+#' a_cff$`preferred-citation`
+#'
+#' toBibtex(a_cff, "preferred")
+toBibtex.cff <- function(object, ...,
+                         what = c("preferred", "references", "all")) {
+  # If a single reference...
+  if ("cff-version" %in% names(object)) {
+    # If full cff
+    biblist_cff <- cff_to_bibentry(x = object, what = what)
+  } else {
+    # Need to enlist if single
+    if ("type" %in% names(object)) {
+      object <- list(object)
+      class(object) <- c("cff", "list")
+    }
+
+    bib_list <- lapply(object, cff_bibtex_parser)
+    biblist_cff <- do.call(c, bib_list)
+  }
+  toBibtex(biblist_cff, ...)
+}

R/cff.R

@@ -9,7 +9,7 @@
 #' A `cff` object. Under the hood, a `cff` object is a regular [`list`] object
 #' with a special [print()] method.
 #'
-#' @family Core functions
+#' @family core
 #'
 #' @param path The path to a `CITATION.cff` file.
 #' @param ... Named arguments to be used for creating a [`cff`] object. See

R/cff_create.R

@@ -10,7 +10,7 @@
 #'
 #' @return A [`cff`][cff-class] object.
 #'
-#' @family Core functions
+#' @family core
 #'
 #' @export
 #'

R/cff_gha_update.R

@@ -26,7 +26,7 @@
 #' }
 #' @export
 #'
-#' @family Git helpers
+#' @family git
 cff_gha_update <- function(path = ".",
                            overwrite = FALSE) {
   destdir <- file.path(path, ".github", "workflows")

R/cff_git_hook.R

@@ -8,7 +8,7 @@
 #'
 #' @name cff_git_hook
 #'
-#' @family Git helpers
+#' @family git
 #'
 #' @export
 #'

R/cff_parse_citation.R

@@ -6,7 +6,7 @@
 #'
 #' @export
 #'
-#' @family Parsers
+#' @family parsers
 #'
 #' @param bib A `bibentry` object, either created with [bibentry()]
 #'   (preferred) or [citEntry()].

R/cff_parse_person.R

@@ -9,7 +9,7 @@
 #'
 #' @export
 #'
-#' @family Parsers
+#' @family parsers
 #'
 #' @param person A `person` object created with [person()] or a
 #'   character string. See **Details**.

R/cff_read.R

@@ -3,9 +3,9 @@
 #' @description
 #' Read files and convert them to [`cff`][cff-class] objects. Files supported
 #' are:
-#' - `CITATION.cff` files
-#' - `DESCRIPTION` files
-#' - **R** citation files (usually located in `inst/CITATION`)
+#' - `CITATION.cff` files.
+#' - `DESCRIPTION` files.
+#' - **R** citation files (usually located in `inst/CITATION`).
 #' - BibTeX files (with extension `*.bib`).
 #'
 #' [cff_read()] would try to guess the type of file provided in `path`. However
@@ -18,8 +18,16 @@
 #'
 #' @export
 #' @rdname cff_read
+#' @family reading
+#' @seealso
 #'
-#' @param path Path to a file
+#' The underlying functions used for reading external files:
+#' - [yaml::read_yaml()] for `CITATION.cff` files.
+#' - [desc::desc()] for `DESCRIPTION` files.
+#' - [utils::readCitationFile()] for **R** citation files.
+#' - [bibtex::read.bib()] for BibTeX files (extension `*.bib`).
+#'
+#' @param path Path to a file.
 #' @param cff_version The Citation File Format schema version that the
 #'   `CITATION.cff` file adheres to for providing the citation metadata.
 #' @param gh_keywords Logical `TRUE/FALSE`. If the package is hosted on
@@ -79,11 +87,12 @@
 #'
 #' # Create cff object from BibTex
 #'
-#' from_bib <- cff_read(system.file("examples/example.bib", package = "cffr"))
-#'
-#' # First item only
-#' from_bib[[1]]
+#' if (requireNamespace("bibtex", quietly = TRUE)) {
+#'   from_bib <- cff_read(system.file("examples/example.bib", package = "cffr"))
 #'
+#'   # First item only
+#'   from_bib[[1]]
+#' }
 #' # Create cff object from CITATION
 #' from_citation <- cff_read(system.file("CITATION", package = "cffr"))
 #'
@@ -246,6 +255,7 @@ cff_read_citation <- function(path, meta = NULL, ...) {
 }
 
 #' @export
+#' @family bibtex
 #' @rdname cff_read
 cff_read_bib <- function(path, encoding = "UTF-8", ...) {
   if (!file.exists(path)) {

R/cff_read_biblines.R

@@ -0,0 +1,86 @@
+#' Create a [`cff`][cff-class] object from BibTeX lines
+#'
+#' @description
+#' Convert a [`character`][character()] representing a BibTeX entry to a
+#' [`cff`][cff-class] object.
+#'
+#' @family bibtex
+#' @family reading
+#' @seealso
+#' [cff_read_bib()] for reading `*.bib` files.
+#'
+#' @export
+#'
+#' @param x A vector of characters with the full BibTeX string.
+#' @param encoding Encoding to be assumed for `x`, see [readLines()].
+#' @param ... Arguments passed on to [cff_read_bib()].
+#' @inheritDotParams cff_read_bib -path
+#'
+#' @return
+#'
+#' ```{r child = "man/chunks/value.Rmd"}
+#' ```
+#'
+#' @details
+#' This is a helper function that writes `x` to a `*.bib` file and reads it with
+#' [cff_read_bib()].
+#'
+#' This function requires \CRANpkg{bibtex} (>= 0.5.0) and uses
+#' [bibtex::read.bib()].
+#'
+#' @examples
+#' if (requireNamespace("bibtex", quietly = TRUE)) {
+#'   x <- c(
+#'     "@book{einstein1921,
+#'       title        = {Relativity: The Special and the General Theory},
+#'       author       = {Einstein, Albert},
+#'       year         = 1920,
+#'       publisher    = {Henry Holt and Company},
+#'       address      = {London, United Kingdom},
+#'       isbn         = 9781587340925
+#'   }",
+#'     "@misc{misc-full,
+#'       title        = {Handing out random pamphlets in airports},
+#'       author       = {Joe-Bob Missilany},
+#'       year         = 1984,
+#'       month        = oct,
+#'       note         = {This is a full MISC entry},
+#'       howpublished = {Handed out at O'Hare}
+#'   }"
+#'   )
+#'
+#'
+#'   cff_read_biblines(x)
+#' }
+cff_read_biblines <- function(x, encoding = "UTF-8", ...) {
+  # Validations
+  if (!inherits(x, "character")) {
+    cli::cli_abort(
+      paste0(
+        "{.arg x} should be a {.cls character}, not a ",
+        "{.cls {class(x)}}."
+      )
+    )
+  }
+
+  if (any(grepl("\\.bib$", x, ignore.case = TRUE))) {
+    cli::cli_alert_warning(
+      paste0("{.arg x} seems to be a {.val .bib} file, not a BibTeX entry.")
+    )
+    cli::cli_alert_info("Reading {.arg x} with {.fn cffr:cff_read_bib}")
+    the_cff <- cff_read_bib(x, encoding = encoding, ...)
+    return(the_cff)
+  }
+
+  if (!any(grepl("^@", x))) {
+    cli::cli_alert_warning(
+      paste0("{.arg x} doesn't look as a BibTeX entry. Check the results.")
+    )
+  }
+  # Write x to a tempfile
+  file <- tempfile(fileext = ".bib")
+  writeLines(x, file)
+
+  the_cff <- cff_read_bib(file, encoding = encoding, ...)
+  the_cff
+}

R/cff_to_bibentry.R

@@ -39,7 +39,7 @@
 #'   - `all`: A combination of the previous two options. This would extract
 #'      both the preferred citation info and the references.
 #'
-#' @family BibTeX helpers
+#' @family bibtex
 #'
 #' @return A `bibentry` object or a list of `bibentry` objects. This could
 #' be parsed to BibTeX using [toBibtex()]