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()`.