Merge pull request #65 from ropensci/api

New API

.github/workflows/check-full.yaml

@@ -27,16 +27,14 @@ jobs:
         config:
           - {os: windows-latest, r: 'devel'}
           - {os: windows-latest, r: 'release'}
-         # - {os: windows-latest, r: 'oldrel'}
+          - {os: windows-latest, r: 'oldrel'}
           - {os: macOS-latest, r: 'devel'}
           - {os: macOS-latest, r: 'release'}
-          #- {os: macOS-latest, r: 'oldrel'}
+          - {os: macOS-latest, r: 'oldrel'}
           - {os: ubuntu-latest, r: 'release'}
           - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'}
-          #- {os: ubuntu-latest, r: 'oldrel'}
-          #- {os: ubuntu-latest, r: 'oldrel-2'}
-          #- {os: ubuntu-latest, r: '3.6'}
-
+          - {os: ubuntu-latest, r: 'oldrel'}
+          - {os: ubuntu-latest, r: 'oldrel-2'}
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

.lintr

@@ -1,3 +1,8 @@
 linters: linters_with_defaults() # see vignette("lintr")
 encoding: "UTF-8"
-exclusions: list("data-raw")
+exclusions: list(
+                  "data-raw",
+                  "tests/testthat/test_ci/test-full_cff.R",
+                  "vignettes/cffr.Rmd",
+                  "vignettes/bibtex_cff.Rmd"
+                )

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
@@ -96,7 +96,7 @@ references:
     name: R Foundation for Statistical Computing
     address: Vienna, Austria
   year: '2024'
-  version: '>= 3.6.0'
+  version: '>= 4.0.0'
 - type: software
   title: cli
   abstract: 'cli: Helpers for Developing Command Line Interfaces'

DESCRIPTION

@@ -17,7 +17,7 @@ License: GPL (>= 3)
 URL: https://docs.ropensci.org/cffr/, https://github.com/ropensci/cffr
 BugReports: https://github.com/ropensci/cffr/issues
 Depends: 
-    R (>= 3.6.0)
+    R (>= 4.0.0)
 Imports: 
     cli (>= 2.0.0),
     desc (>= 1.3.0),

NAMESPACE

@@ -1,28 +1,50 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method("[",cff_pers_list)
+S3method("[",cff_ref_list)
+S3method(as.data.frame,cff)
+S3method(as.person,cff)
+S3method(as_cff,Bibtex)
+S3method(as_cff,bibentry)
+S3method(as_cff,default)
+S3method(as_cff,list)
+S3method(as_cff,person)
 S3method(c,cff)
+S3method(head,cff)
 S3method(print,cff)
+S3method(tail,cff)
+S3method(toBibtex,cff)
 export(as.cff)
+export(as_bibentry)
+export(as_cff)
+export(as_cff_person)
 export(cff)
 export(cff_create)
 export(cff_extract_to_bibtex)
 export(cff_from_bibtex)
 export(cff_gha_update)
 export(cff_git_hook_install)
 export(cff_git_hook_remove)
+export(cff_modify)
 export(cff_parse_citation)
 export(cff_parse_person)
 export(cff_parse_person_bibtex)
 export(cff_read)
+export(cff_read_bib)
+export(cff_read_bib_text)
+export(cff_read_cff_citation)
+export(cff_read_citation)
+export(cff_read_description)
 export(cff_schema_definitions_entity)
 export(cff_schema_definitions_person)
 export(cff_schema_definitions_refs)
 export(cff_schema_keys)
 export(cff_schema_keys_license)
-export(cff_to_bibentry)
 export(cff_to_bibtex)
 export(cff_validate)
 export(cff_write)
+export(cff_write_bib)
+export(cff_write_citation)
 export(encoded_utf_to_latex)
 export(write_bib)
 export(write_citation)
@@ -33,9 +55,11 @@ importFrom(utils,bibentry)
 importFrom(utils,capture.output)
 importFrom(utils,citation)
 importFrom(utils,download.file)
+importFrom(utils,head)
 importFrom(utils,installed.packages)
 importFrom(utils,modifyList)
 importFrom(utils,packageDescription)
 importFrom(utils,person)
 importFrom(utils,read.csv)
+importFrom(utils,tail)
 importFrom(utils,toBibtex)

NEWS.md

@@ -1,16 +1,78 @@
 # cffr (development version)
 
-## Major changes in the API
-
+This is a major release with some notable changes. The change mainly **affects
+to non-core functions**, hence the natural workflow (`cff_create()` →
+`cff_write()` → `cff_validate()`) shouldn't be affected.
+
+## Major changes
+
+### API
+
+The API has been completely reviewed to provide more clarity on functions naming
+and to facilitate internal maintenance. This change **only** **affects to
+non-core functions**. Now each function does less things but does it better. The
+old API [has been
+deprecated](https://lifecycle.r-lib.org/articles/stages.html#deprecated) and it
+would warn when used, providing advice on the replacement function.
+
+#### Deprecation
+
+-   `cff_to_bibtex()` and `cff_extract_to_bibtex()`: replaced by
+    `as_bibentry()`.
+-   `cff_from_bibtex()`: replaced by `cff_read_bib()` (for `*.bib` files) and
+    `cff_read_bib_text()` (for character strings).
+-   `write_bib()` and `write_citation()` : replaced by `cff_write_bib()` and
+    `cff_write_citation()` respectively.
+-   `cff_parse_person()` and `cff_parse_person_bibtex()`: replaced by
+    `as_cff_person()`.
 -   The conversion from `cff` to `bibentry` is performed now by a new function
-    `cff_to_bibentry()`. Previous names of this function were `cff_to_bibtex()`
-    and `cff_extract_to_bibtex()` that are now superseded.
-
-## Changes on bibtex crosswalk
-
--   **\@inbook** and **\@book** gains a new value on [CFF]{.underline} when
-    **series** is provided: [collection-type: book-series.]{.underline}
--   Review and update `vignette("bibtex_cff", package = "cffr")`.
+    `as_bibentry()`. Previous names of this function were `cff_to_bibtex()` and
+    `cff_extract_to_bibtex()` that are now deprecated.
+-   `cff_parse_citation()`: replaced by `as_cff()`, see **New capabilities**.
+-   Argument `path` in `cff()` is also deprecated, use `cff_read()`.
+
+### New capabilities
+
+-   New `as_cff()` S3 generic method (replacing `as.cff()`): This method coerces
+    **R** objects to `cff-class` format. Current methods provided are:
+    -   `as_cff.Bibtex()`.
+    -   `as_cff.bibentry()`, replacing cff_parse_citation().
+    -   `as_cff.person()`, similar to `as_cff_person()` but only for `person`
+        objects. We recommend using `as_cff_person()` since it can parse also
+        string representing authors in BibTeX markup (`"{von Neumen}, James"`),
+        that can't be captured properly via methods.
+-   Now reading from external files is performed exclusively by `cff_read()`
+    (that is designed to fit all supported file types on a single entry point)
+    and the new specific readers (that are used under the hood by `cff_read()`),
+    namely:
+    -   `cff_read_cff_citation()`,
+    -   `cff_read_description()`,
+    -   `cff_read_citation()`
+    -   `cff_read_bib()`.
+-   New `cff_modify()` function for updating and modifying `cff` objects easily.
+
+## Other changes
+
+-   Minimum **R** version required now is **4.0.0**.
+-   Now `class()` of `cff` objects are `c("cff", "list")` instead of single
+    value (`"cff"`).
+-   New S3 **base** and **utils** methods added:
+    -   `as.data.frame.cff().`
+    -   `as.person.cff()`, that provides results **only** for CFF keys defined
+        as
+        [person](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsperson)
+        or
+        [entity](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsentity)
+        (e.g. `authors`, `contacts`, `editors`, `publisher,` etc.).
+    -   `head.cff()`, `tail.cff()`.
+    -   `toBibtex.cff()`.
+-   Update of BibTeX crosswalk (see `vignette("bibtex_cff", package = "cffr")`)
+    and consequently changes in the mapping performed by `as_bibtex()`
+    `cff_parse_citation()`:
+    -   **\@inbook** and **\@book** gains a new value on [CFF]{.underline} when
+        **series** is provided: [collection-type: book-series.]{.underline}
+    -   Can handle BibLaTeX **\@inbook**, that differs significantly from BibTeX
+        **\@inbook**.
 
 # cffr 0.5.0
 
@@ -27,7 +89,7 @@
 ## Enhancements
 
 -   Additional authors of a **R** package can be now included based on the role
-    on the DESCRIPTION file, via the parameter `authors_roles` (#49).
+    on the `DESCRIPTION` file, via the parameter `authors_roles` (#49).
 
 -   New message interface based on [**cli**](https://cli.r-lib.org/)
     capabilities.
@@ -55,7 +117,7 @@
 
 # cffr 0.3.0
 
--   `preferred-citation` is only produced when a CITATION (**R**) file has been
+-   `preferred-citation` is only produced when a `CITATION` **R** file has been
     provided with the package (#37).
 -   Improve email handling on authors.
 -   Add `cff_read()` function. This functionality was already implemented on
@@ -72,39 +134,29 @@
 # cffr 0.2.1
 
 -   GitHub Action now runs only on `master` or `main`branch.
-
 -   Better handling of references
 
 # cffr 0.2.0
 
 -   Now **cffr** extracts also information of the package dependencies and adds
     the main citation of the dependencies to the `references` field, using
     `citation(auto = TRUE)`.
-
     -   New `dependencies` parameter on `cff_create()` and `cff_write()`.
-
 -   Other improvements on `cff_parse_citation():`
-
     -   `cff_parse_citation()` extracts more information of authors, based on
-        the fields provided on the DESCRIPTION file.
-
+        the fields provided on the `DESCRIPTION` file.
     -   `cff_parse_citation()` does a better job extracting information from
         `bibentry()` /BibTeX and mapping it to `preferred-citation/references`
         fields of CFF.
-
 -   Add new functions for working with git pre-commit hooks
     [![Experimental](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental):
-
     -   `cff_git_hook_install()`
     -   `cff_git_hook_remove()`
-
 -   New BibTeX functions:
-
     -   `cff_extract_to_bibtex()`
     -   `cff_to_bibtex()`
     -   `cff_parse_person_bibtex()`
     -   `write_bib()`
-
 -   Add a new dependency: `lifecycle`.
 
 # cffr 0.1.1
@@ -121,16 +173,16 @@
 
 # cffr 0.0.2
 
--   `cffr` is part now of rOpenSci.
+-   **cffr** is part now of rOpenSci.
 -   Update on docs and README.
 -   Add fuzzy match on `keys` parameter.
 -   New dataset: `cran_to_spdx`.
 -   Add DOI <https://doi.org/10.5281/zenodo.5509766>
 -   Citation of installed packages extracted using `citation().`
--   Auto-generating `preferred-citation` key from DESCRIPTION.
+-   Auto-generating `preferred-citation` key from `DESCRIPTION`.
 -   Rename `cff_schema_definitions_reference()` to
     `cff_schema_definitions_refs()`.
--   "repository" key is supported.
+-   `repository` key is supported.
 -   Added vignette: `vignette("crosswalk", package = "cffr")`.
 -   Add support to Bioconductor packages.
 -   New function: `cff_gha_update()`.