cff 0.4.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32661be9e23147731575824f34df12b82dfb6f0560af3fd4d8081958f633cac6
-  data.tar.gz: 5b525849ff1e6ff1829d70e657852377c88bf0b6e83dffff96dd6cd660fc029b
+  metadata.gz: 30519ae0956f0d4221822133c8d638170919f92a3c969af8fc9acf75146f1652
+  data.tar.gz: d50b46821a6b7711cadfa8f89628afad29c1c06c0549756c7cbbe2f50fd38507
 SHA512:
-  metadata.gz: c1df6fd36b30cdd828d9d80ae183795f9eea5a3691684ed0769bbe75b8bca026ed540611f671341bca8880352f396c727931ceb55865086b8613c016af5a7769
-  data.tar.gz: 0f3afd7def478528b073c4a9454c804731fe6c50cde9acbcdafa0fdc0d6bfba577ca812fcc34fe0b36732f5b1dafebde2b90940f81c6ddf882ac22754b01b419
+  metadata.gz: cf2c30b86d41a0450d0ece7312fb25be248cc434de332178413aea306b67ad0a7a6d5a553c7cffcd971683a224c00727ef5ad815d0e73df5c06c9c8cc3faf723
+  data.tar.gz: 9700c2ecf3fcc319bb04037081c653361c8062e35eb772881932bf7025679f5dc3d1907c042d841f2ba40b42efb1416a95a9ecff8361c02b0b74ea0c2f05b3c5

data/CHANGES.md

@@ -1,5 +1,73 @@
 # Changes log for the Ruby CFF Library
 
+## Version 0.8.0
+
+* Add a comment field to the File class.
+* Update the CITATION.cff file to add a comment.
+* Document the simple fields in Model.
+* Updating Ruby version and dependencies
+* GitHub Actions for CI
+* Update Gemspec to fix security vulnerabilities
+* Implement BibTeX output
+* Implement APA-like output
+* Update the LICENCE and the file headers.
+* Add a linter Action.
+* Adjust fixtures to reflect custom styles
+* Move latest supported ruby to be >= 2.6.
+* Dynamically create tests
+* Use the new `YAML.safe_load` API form.
+* Add a filename to `CFF::File`.
+* Fix invalid references bug
+* Allow time to be loaded from YAML
+* Add `CFF::File.open` which accepts a block.
+* `Model::new` can now accept a block.
+* `Entity::new` can now accept a block.
+* `Person::new` can now accept a block.
+* `Reference::new` can now accept a block.
+* Update README with new `Model` and `File` APIs.
+* Turn on Actions CI for all branches.
+* Turn Coveralls reporting back on after move to Actions.
+* Use `Last, First` format for BibTeX output.
+* Add `BibtexFormatter::generate_reference`.
+* Change DOI links to https in the APA formatter.
+* Set up a GitHub Action to build and deploy the docs.
+* Add metadata to the gemspec.
+* Generalize authorship of the gem a bit.
+* Document `to_*` formatting methods in `Model`.
+* Add `alias` field to `Person`.
+* `Person` no longer requires `given-names` and `family-names`.
+* The `version` field can be a number or a string.
+* Bump default spec version to 1.2.0.
+* Load and parse the CFF schema.
+* Add validation code and supporting infrastructure.
+* Add validation class methods to `CFF::File`.
+* Handle empty fields in `Reference` when reading from files.
+* Add an `Identifier` type.
+* Add the `identifiers` field to the `Model`.
+* Add the `identifiers` field to `Reference`.
+* Update the key complete CFF file in the tests.
+* Ensure `name-particle` is used in BibTex output.
+* Add `preferred-citation` to the `Model`.
+* Load the `Entity` fields in a `Reference` correctly.
+* Preserve title capitalization in BibTeX output.
+* Add `Licensable` mixin.
+* Wire `Licensable` into `Model`.
+* Wire `Licensable` into `Reference`.
+* Use the SPDX licences list in the schema to cross-check.
+* Protect `Entity` names in BibTeX output with `{}`.
+* Add support for `name-suffix` in BibTeX output.
+* Streamline the APA formatter `format_author` method.
+* Streamline BibTeX `generate_reference` method.
+* Streamline the BibTeX `format_author` method.
+* Update `1.2.0` schema.
+* Add `Formatter::month_and_year_from_date` util method.
+* Add `Formatter::url` util method.
+* Simplify `BibtexFormatter::format`.
+* Simplify and improve the APA formatter.
+* Honour `preferred_citation` when outputting citation text.
+* Only use '[Computer software]' label in APA format for software.
+* Map `Reference` types to BibTeX types when formatting.
+
 ## Version 0.4.0
 
 * Remove unused Util#expand_field method.

data/CITATION.cff

@@ -1,21 +1,26 @@
-cff-version: 1.0.3
+# This CITATION.cff file was created by ruby-cff (v 0.8.0).
+# Gem: https://rubygems.org/gems/cff
+# CFF: https://citation-file-format.github.io/
+
+cff-version: 1.2.0
 message: If you use ruby-cff in your work, please cite it using the following metadata
 title: Ruby CFF Library
-abstract: This library provides a Ruby interface to manipulate CITATION.cff files
+abstract: This library provides a Ruby interface to manipulate Citation File Format files
 authors:
 - family-names: Haines
   given-names: Robert
   orcid: https://orcid.org/0000-0002-9538-7919
   affiliation: The University of Manchester, UK
+- name: The Ruby Citation File Format Developers
 keywords:
 - ruby
 - credit
 - citation
 - metadata
 - cff
-version: 0.4.0
+version: 0.8.0
 doi: 10.5281/zenodo.1184077
-date-released: 2018-07-29
+date-released: 2021-08-08
 license: Apache-2.0
 repository-artifact: https://rubygems.org/gems/cff
 repository-code: https://github.com/citation-file-format/ruby-cff

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec

data/LICENCE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -1,44 +1,49 @@
 # Ruby CFF
-## Robert Haines
+## Robert Haines and The Ruby Citation File Format Developers
 
-A Ruby library for manipulating CITATION.cff files.
+A Ruby library for creating, editing, validating and converting CITATION.cff files.
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1184077.svg)](https://doi.org/10.5281/zenodo.1184077)
 [![Gem Version](https://badge.fury.io/rb/cff.svg)](https://badge.fury.io/rb/cff)
-[![Build Status](https://travis-ci.org/citation-file-format/ruby-cff.svg?branch=master)](https://travis-ci.org/citation-file-format/ruby-cff)
+[![Tests](https://github.com/citation-file-format/ruby-cff/actions/workflows/ruby.yml/badge.svg)](https://github.com/citation-file-format/ruby-cff/actions/workflows/ruby.yml)
+[![Linter](https://github.com/citation-file-format/ruby-cff/actions/workflows/lint.yml/badge.svg)](https://github.com/citation-file-format/ruby-cff/actions/workflows/lint.yml)
 [![Maintainability](https://api.codeclimate.com/v1/badges/6bb4c661bfb4971260ba/maintainability)](https://codeclimate.com/github/citation-file-format/ruby-cff/maintainability)
 [![Coverage Status](https://coveralls.io/repos/github/citation-file-format/ruby-cff/badge.svg)](https://coveralls.io/github/citation-file-format/ruby-cff)
 
 ### Synopsis
 
-This library provides a Ruby interface to manipulate CITATION.cff files. The primary entry points are the Model and File classes.
+This library provides a Ruby interface to create and edit Citation File Format (CFF) files. The resulting files can be validated against a formal schema to ensure correctness and can be output in a number of different citation-friendly formats.
 
-See the [CITATION.cff documentation](https://citation-file-format.github.io/) for more details.
+The primary API entry points are the `Model` and `File` classes.
+
+See the [CITATION.cff documentation](https://citation-file-format.github.io/) for more details about the Citation File Format.
+
+See the [full API documentation](https://citation-file-format.github.io/ruby-cff/) for more details about Ruby CFF.
 
 ### Quick start
 
+You can quickly build and save a CFF model like this:
+
 ```ruby
-cff = CFF::Model.new("Ruby CFF Library")
-cff.version = CFF::VERSION
-cff.date_released = Date.today
-cff.authors << CFF::Person.new("Robert", "Haines")
-cff.license = "Apache-2.0"
-cff.keywords << "ruby" << "credit" << "citation"
-cff.repository_artifact = "https://rubygems.org/gems/cff"
+model = CFF::Model.new('Ruby CFF Library') do |cff|
+  cff.version = CFF::VERSION
+  cff.date_released = Date.today
+  cff.authors << CFF::Person.new('Robert', 'Haines')
+  cff.license = 'Apache-2.0'
+  cff.keywords << 'ruby' << 'credit' << 'citation'
+  cff.repository_artifact = 'https://rubygems.org/gems/cff'
+  cff.repository_code = 'https://github.com/citation-file-format/ruby-cff'
+end
 
-CFF::File.write("CITATION.cff", cff)
+CFF::File.write('CITATION.cff', model)
 ```
 
-Will produce a file that looks something like this:
+Which will produce a file that looks something like this:
 
-```
-cff-version: 1.0.3
+```yaml
+cff-version: 1.2.0
 message: If you use this software in your work, please cite it using the following metadata
 title: Ruby CFF Library
-version: 0.3.0
-date-released: 2018-03-04
-license: Apache-2.0
-repository-artifact: https://rubygems.org/gems/cff
 authors:
 - family-names: Haines
   given-names: Robert
@@ -46,8 +51,107 @@ keywords:
 - ruby
 - credit
 - citation
+version: 0.8.0
+date-released: 2021-08-08
+license: Apache-2.0
+repository-artifact: https://rubygems.org/gems/cff
+repository-code: https://github.com/citation-file-format/ruby-cff
+```
+
+`CFF::File` can be used to create a file directly, and it exposes the underlying `CFF::Model` directly. If using a block with `CFF::File::open` the file will get written on closing it:
+
+```ruby
+CFF::File.open('CITATION.cff') do |cff|
+  cff.version = CFF::VERSION
+  cff.date_released = Date.today
+  cff.authors << CFF::Person.new('Robert', 'Haines')
+  cff.license = 'Apache-2.0'
+  cff.keywords << 'ruby' << 'credit' << 'citation'
+  cff.repository_artifact = 'https://rubygems.org/gems/cff'
+  cff.repository_code = 'https://github.com/citation-file-format/ruby-cff'
+end
+```
+
+### Validating CFF files
+
+To quickly validate a file and raise an error on failure, you can use `CFF::File` directly:
+
+```ruby
+begin
+  CFF::File.validate!('CITATION.cff')
+rescue CFF::ValidationError => e
+  # Handle validation errors here...
+end
+```
+
+Both `CFF::File` and `CFF::Model` have instance methods to validate CFF files as well:
+
+```ruby
+cff = CFF::File.read('CITATION.cff')
+begin
+  cff.validate!(fail_fast: true)
+rescue CFF::ValidationError => e
+  # Handle validation errors here...
+end
+```
+
+Non-bang methods (`validate`) return a two-element array, with `true`/`false` at index 0 to indicate pass/fail, and an array of errors at index 1 (if any).
+
+Passing `fail_fast: true` (default: `false`) will cause the validator to abort on the first error it encounters and report just that. Only the instance methods on `CFF::File` and `CFF::Model` provide the `fail_fast` option.
+
+### Outputting citation text
+
+This library can use CFF data to output text suitable for use when citing software. Currently the output formats supported are:
+
+* BibTeX; and
+* an APA-like format.
+
+You can use this feature as follows:
+```ruby
+cff = CFF::File.read('CITATION.cff')
+
+cff.to_bibtex
+cff.to_apalike
+```
+
+These methods assume that the CFF data is valid - see the notes on validation above.
+
+Assuming the same CFF data as above, the two formats will look something like this:
+
+#### BibTeX format
+
+```tex
+@misc{Haines_Ruby_CFF_Library_2021,
+author = {Haines, Robert},
+month = {8},
+title = {{Ruby CFF Library}},
+url = {https://github.com/citation-file-format/ruby-cff},
+year = {2021}
+}
+```
+
+#### APA-like format
+
+```
+Haines, R. (2021). Ruby CFF Library (Version 0.8.0) [Computer software]. https://github.com/citation-file-format/ruby-cff
 ```
 
+#### Citing a paper rather than software
+
+The CFF has been designed with direct citation of software in mind. We'd like software to be considered a first-class research output, like journal articles and conference papers. If you would rather that your citation text points to a paper that describes your software, rather than the software itself, you can use the `preferred-citation` field for that paper. When producing citation text this library will honour `preferred-citation`, if present, by default. If you would like to specify a `preferred-citation` and still produce a direct citation to the software then you can configure the formatter as follows:
+
+```ruby
+cff = CFF::File.read('CITATION.cff')
+
+cff.to_bibtex(preferred_citation: false)
+cff.to_apalike(preferred_citation: false)
+
+```
+
+#### A note on citation formats
+
+Due to the different expectations of different publication venues, the citation text may need minor tweaking to be used in specific situations. If you spot a major, or general, error in the output please [let us know](https://github.com/citation-file-format/ruby-cff/issues).
+
 ### Library versions
 
 Until this library reaches version 1.0.0 the API may be subject to breaking changes. When version 1.0.0 is released, then the principles of [semantic versioning](https://semver.org/) will be applied.
@@ -55,3 +159,15 @@ Until this library reaches version 1.0.0 the API may be subject to breaking chan
 ### Licence
 
 [Apache 2.0](http://www.apache.org/licenses/). See LICENCE for details.
+
+### Research notice
+
+Please note that this repository is participating in a study into sustainability
+ of open source projects. Data will be gathered about this repository for
+ approximately the next 12 months, starting from June 2021.
+
+Data collected will include number of contributors, number of PRs, time taken to
+ close/merge these PRs, and issues closed.
+
+For more information, please visit
+[our informational page](https://sustainable-open-science-and-software.github.io/) or download our [participant information sheet](https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf).

data/Rakefile

@@ -1,4 +1,6 @@
-# Copyright (c) 2018 Robert Haines.
+# frozen_string_literal: true
+
+# Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'cff'

data/cff.gemspec

@@ -1,4 +1,6 @@
-# Copyright (c) 2018 Robert Haines.
+# frozen_string_literal: true
+
+# Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,14 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'cff/version'
+require_relative 'lib/cff/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'cff'
   spec.version       = CFF::VERSION
-  spec.authors       = ['Robert Haines']
+  spec.authors       = [
+    'Robert Haines',
+    'The Ruby Citation File Format Developers'
+  ]
   spec.email         = ['robert.haines@manchester.ac.uk']
 
   spec.summary       = 'A Ruby library for manipulating CITATION.cff files.'
@@ -28,23 +31,34 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/citation-file-format/ruby-cff'
   spec.license       = 'Apache-2.0'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/citation-file-format/ruby-cff/issues',
+    'changelog_uri' => 'https://github.com/citation-file-format/ruby-cff/blob/main/CHANGES.md',
+    'documentation_uri' => 'https://citation-file-format.github.io/ruby-cff/',
+    'source_code_uri' => 'https://github.com/citation-file-format/ruby-cff'
+  }
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^((test|spec|features)/|\.)})
   end
+
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.2.0'
+  spec.required_ruby_version = '>= 2.6'
 
+  spec.add_runtime_dependency 'json_schema', '~> 0.21.0'
   spec.add_runtime_dependency 'language_list', '~> 1.2'
-  spec.add_runtime_dependency 'spdx-licenses', '~> 1.1'
-
-  spec.add_development_dependency 'bundler', '~> 1.16'
-  spec.add_development_dependency 'coveralls', '~> 0.8'
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rdoc', '~> 6.0'
-  spec.add_development_dependency 'rubocop', '~> 0.54'
+
+  spec.add_development_dependency 'minitest', '~> 5.14'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rdoc', '~> 6.3'
+  spec.add_development_dependency 'rubocop', '~> 1.15'
+  spec.add_development_dependency 'rubocop-minitest', '~> 0.13'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.11.0'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.5.0'
+  spec.add_development_dependency 'simplecov', '~> 0.20.0'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8.0'
   spec.add_development_dependency 'test_construct', '~> 2.0'
 end

data/lib/cff.rb

@@ -1,4 +1,6 @@
-# Copyright (c) 2018 Robert Haines.
+# frozen_string_literal: true
+
+# Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,23 +15,33 @@
 # limitations under the License.
 
 require 'date'
+require 'json'
 require 'yaml'
+
 require 'language_list'
-require 'spdx-licenses'
+
+# This library provides a Ruby interface to manipulate CITATION.cff files. The
+# primary entry points are Model and File.
+#
+# See the [CITATION.cff documentation](https://citation-file-format.github.io/)
+# for more details.
+module CFF
+  SCHEMA_PATH = ::File.join(__dir__, 'schema', '1.2.0.json') # :nodoc:
+  SCHEMA_FILE = JSON.parse(::File.read(SCHEMA_PATH))         # :nodoc:
+end
 
 require 'cff/version'
+require 'cff/errors'
 require 'cff/util'
+require 'cff/licensable'
+require 'cff/validatable'
 require 'cff/model_part'
 require 'cff/person'
 require 'cff/entity'
+require 'cff/identifier'
 require 'cff/reference'
 require 'cff/model'
 require 'cff/file'
-
-# This library provides a Ruby interface to manipulate CITATION.cff files. The
-# primary entry points are Model and File.
-#
-# See the [CITATION.cff documentation](https://citation-file-format.github.io/)
-# for more details.
-module CFF
-end
+require 'cff/formatter/formatter'
+require 'cff/formatter/apa_formatter'
+require 'cff/formatter/bibtex_formatter'