cff 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30519ae0956f0d4221822133c8d638170919f92a3c969af8fc9acf75146f1652
-  data.tar.gz: d50b46821a6b7711cadfa8f89628afad29c1c06c0549756c7cbbe2f50fd38507
+  metadata.gz: c4c306916ccaa887479febca758c7d8d5e9272229ee9eedb88663649e3d6c15c
+  data.tar.gz: 798151267eba0eab166fc104660a5a87f15ecafdd336c0e9819ab9922a58b516
 SHA512:
-  metadata.gz: cf2c30b86d41a0450d0ece7312fb25be248cc434de332178413aea306b67ad0a7a6d5a553c7cffcd971683a224c00727ef5ad815d0e73df5c06c9c8cc3faf723
-  data.tar.gz: 9700c2ecf3fcc319bb04037081c653361c8062e35eb772881932bf7025679f5dc3d1907c042d841f2ba40b42efb1416a95a9ecff8361c02b0b74ea0c2f05b3c5
+  metadata.gz: 2834d89f3fac5714b9708cd4c15999c5df41c50bfc9bab3fa6b208cca46fff333b6d619fb7e84cb6faaec5a42219ae3a37db9830c2f788179a926d66e6ac1c33
+  data.tar.gz: 82bc7dffa78909c49c0c035ab6b8823852a1ce5e8c9486ce81f09d7a88fb530c09e2a0c486274d282ae963a737bc6cef272dd1be00509c2d65053a6ff1f2c827

data/CHANGES.md

@@ -1,5 +1,23 @@
 # Changes log for the Ruby CFF Library
 
+## Version 0.9.0
+
+* Update to final released version of schema 1.2.0.
+* Add `description` field to `Identifier`.
+* Add `Model::read` to parse a CFF file from memory.
+* Add `Model::open`. Same as `read` but can take a block.
+* Override `File#to_yaml`.
+* Allow `File::write` to write File objects.
+* Add `save_as` parameter to `File#write`.
+* Add `Reference::from_cff`.
+* Update CITATION.cff file to reference CFF repo.
+* Fix `File` docs to be explicit about filenames.
+* Validate the filename of a CFF file.
+* Surface the `fail_fast` options on the `File` validatation methods.
+* Reduce json_schema dependency to ~0.20.0.
+* Fix APA-like formatter when a reference is missing a volume.
+* APA: don't emit journal data if there's no journal.
+
 ## Version 0.8.0
 
 * Add a comment field to the File class.

data/CITATION.cff

@@ -1,4 +1,4 @@
-# This CITATION.cff file was created by ruby-cff (v 0.8.0).
+# This CITATION.cff file was created by ruby-cff (v 0.9.0).
 # Gem: https://rubygems.org/gems/cff
 # CFF: https://citation-file-format.github.io/
 
@@ -15,12 +15,69 @@ authors:
 keywords:
 - ruby
 - credit
-- citation
+- software citation
+- research software
+- software sustainability
 - metadata
-- cff
-version: 0.8.0
+- citation file format
+- CFF
+version: 0.9.0
 doi: 10.5281/zenodo.1184077
-date-released: 2021-08-08
+date-released: 2021-08-18
 license: Apache-2.0
 repository-artifact: https://rubygems.org/gems/cff
 repository-code: https://github.com/citation-file-format/ruby-cff
+references:
+- type: software
+  title: Citation File Format
+  authors:
+  - family-names: Druskat
+    given-names: Stephan
+    orcid: https://orcid.org/0000-0003-4925-7248
+  - family-names: Spaaks
+    given-names: Jurriaan H.
+    orcid: https://orcid.org/0000-0002-7064-4069
+  - family-names: Chue Hong
+    given-names: Neil
+    orcid: https://orcid.org/0000-0002-8876-7606
+  - family-names: Haines
+    given-names: Robert
+    orcid: https://orcid.org/0000-0002-9538-7919
+  - family-names: Baker
+    given-names: James
+    orcid: https://orcid.org/0000-0002-2682-6922
+  - family-names: Bliven
+    given-names: Spencer
+    orcid: https://orcid.org/0000-0002-1200-1698
+    email: spencer.bliven@gmail.com
+  - family-names: Willighagen
+    given-names: Egon
+    orcid: https://orcid.org/0000-0001-7542-0286
+  - family-names: Pérez-Suárez
+    given-names: David
+    orcid: https://orcid.org/0000-0003-0784-6909
+    website: https://dpshelio.github.io
+  - family-names: Konovalov
+    given-names: Alexander
+    orcid: https://orcid.org/0000-0001-5299-3292
+  identifiers:
+  - type: doi
+    value: 10.5281/zenodo.1003149
+    description: The concept DOI for the collection containing all versions of the Citation File Format.
+  - type: doi
+    value: 10.5281/zenodo.5171937
+    description: The versioned DOI for the version 1.2.0 of the Citation File Format.
+  keywords:
+  - citation file format
+  - CFF
+  - citation files
+  - software citation
+  - file format
+  - YAML
+  - software sustainability
+  - research software
+  - credit
+  abstract: CITATION.cff files are plain text files with human- and machine-readable citation information for software. Code developers can include them in their repositories to let others know how to correctly cite their software. This is the specification for the Citation File Format.
+  date-released: 2021-08-09
+  license: CC-BY-4.0
+  version: 1.2.0

data/README.md

@@ -51,8 +51,8 @@ keywords:
 - ruby
 - credit
 - citation
-version: 0.8.0
-date-released: 2021-08-08
+version: 0.9.0
+date-released: 2021-08-18
 license: Apache-2.0
 repository-artifact: https://rubygems.org/gems/cff
 repository-code: https://github.com/citation-file-format/ruby-cff
@@ -72,6 +72,38 @@ CFF::File.open('CITATION.cff') do |cff|
 end
 ```
 
+You can read a CFF file quickly with `CFF::File::read`:
+
+```ruby
+cff = CFF::File.read('CITATION.cff')
+```
+
+And you can read a CFF file from memory with `CFF::Model::read` or `CFF::Model::open` - as with `CFF::File` a block can be passed in to `open`:
+
+```ruby
+cff_string = ::File.read('CITATION.cff')
+cff = CFF::Model.read(cff_string)
+
+CFF::Model.open(cff_string) do |cff|
+  # Edit cff here...
+end
+```
+
+To quickly reference other software from your own CFF file, you can use `CFF::Reference.from_cff`. This example uses the CFF file from the core CFF repository as a reference for the Ruby CFF repository:
+
+```ruby
+require 'open-uri'
+
+uri = 'https://raw.githubusercontent.com/citation-file-format/citation-file-format/main/CITATION.cff'
+other_cff = URI.open(uri).read
+
+ref = CFF::Reference.from_cff(CFF::Model.read(other_cff))
+
+CFF::File.open('CITATION.cff') do |cff|
+  cff.references = [ref]
+end
+```
+
 ### Validating CFF files
 
 To quickly validate a file and raise an error on failure, you can use `CFF::File` directly:
@@ -95,10 +127,12 @@ rescue CFF::ValidationError => e
 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).
+Non-bang methods (`validate`) return an 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.
 
+The validation methods (both class and instance) on `File` also validate the filename of a CFF file; in normal circumstances a CFF file should be named 'CITATION.cff'. You can switch this behaviour off by passing `fail_on_filename: false`. The non-bang methods (`validate`) on `File` return an extra value in the result array: `true`/`false` at index 2 to indicate whether the filename passed/failed validation.
+
 ### Outputting citation text
 
 This library can use CFF data to output text suitable for use when citing software. Currently the output formats supported are:
@@ -133,7 +167,7 @@ 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
+Haines, R. (2021). Ruby CFF Library (Version 0.9.0) [Computer software]. https://github.com/citation-file-format/ruby-cff
 ```
 
 #### Citing a paper rather than software

data/cff.gemspec

@@ -48,7 +48,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.6'
 
-  spec.add_runtime_dependency 'json_schema', '~> 0.21.0'
+  spec.add_runtime_dependency 'json_schema', '~> 0.20.0'
   spec.add_runtime_dependency 'language_list', '~> 1.2'
 
   spec.add_development_dependency 'minitest', '~> 5.14'

data/lib/cff/errors.rb

@@ -25,21 +25,29 @@ module CFF
     end
   end
 
-  # ValidationError is raised when a CFF file fails validatedation. It
-  # contains details of each failure that was detected by the underlying
-  # JsonSchema library, which is used to perform the validation.
+  # ValidationError is raised when a CFF file fails validation. It contains
+  # details of each failure that was detected by the underlying JsonSchema
+  # library, which is used to perform the validation.
+  #
+  # Additionally, the `invalid_filename` flag is used to indicate whether the
+  # CFF file is named correctly. This is only used when validating a File;
+  # validating a Model directly will not set this flag to `true`.
   class ValidationError < Error
 
     # The list of JsonSchema::ValidationErrors found by the validator.
     attr_reader :errors
 
-    def initialize(errors) # :nodoc:
+    # If a File was validated, was its filename invalid?
+    attr_reader :invalid_filename
+
+    def initialize(errors, invalid_filename: false) # :nodoc:
       super('Validation error')
       @errors = errors
+      @invalid_filename = invalid_filename
     end
 
     def to_s # :nodoc:
-      "#{super}: #{@errors.join(' ')}"
+      "#{super}: (Invalid filename: #{@invalid_filename}) #{@errors.join(' ')}"
     end
   end
 end

data/lib/cff/file.rb

@@ -19,6 +19,11 @@ module CFF
 
   # File provides direct access to a CFF Model, with the addition of some
   # filesystem utilities.
+  #
+  # To be a fully compliant and valid CFF file its filename should be
+  # 'CITATION.cff'. This class allows you to create files with any filename,
+  # and to validate the contents of those files independently of the preferred
+  # filename.
   class File
 
     # A comment to be inserted at the top of the resultant CFF file.
@@ -33,6 +38,7 @@ module CFF
       'Gem: https://rubygems.org/gems/cff',
       'CFF: https://citation-file-format.github.io/'
     ].freeze # :nodoc:
+    CFF_VALID_FILENAME = 'CITATION.cff' # :nodoc:
 
     # :call-seq:
     #   new(filename, title) -> File
@@ -53,7 +59,7 @@ module CFF
     end
 
     # :call-seq:
-    #   read(file) -> File
+    #   read(filename) -> File
     #
     # Read a file and parse it for subsequent manipulation.
     def self.read(file)
@@ -66,8 +72,8 @@ module CFF
     end
 
     # :call-seq:
-    #   open(file) -> File
-    #   open(file) {|cff| block }
+    #   open(filename) -> File
+    #   open(filename) { |cff| block }
     #
     # With no associated block, File.open is a synonym for ::read. If the
     # optional code block is given, it will be passed the opened file as an
@@ -97,31 +103,41 @@ module CFF
     end
 
     # :call-seq:
-    #   validate(file) -> Array
+    #   validate(filename, fail_on_filename: true) -> Array
     #
     # Read a file and return an array with the result. The result array is a
-    # two-element array, with `true`/`false` at index 0 to indicate pass/fail,
-    # and an array of errors at index 1 (if any).
-    def self.validate(file)
-      File.read(file).validate
+    # three-element array, with `true`/`false` at index 0 to indicate
+    # pass/fail, an array of schema validation errors at index 1 (if any), and
+    # `true`/`false` at index 2 to indicate whether the filename passed/failed
+    # validation.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def self.validate(file, fail_on_filename: true)
+      File.read(file).validate(fail_on_filename: fail_on_filename)
     end
 
     # :call-seq:
-    #   validate!(file)
+    #   validate!(filename, fail_on_filename: true)
     #
     # Read a file and raise a ValidationError upon failure. If an error is
     # raised it will contain the detected validation failures for further
     # inspection.
-    def self.validate!(file)
-      File.read(file).validate!
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def self.validate!(file, fail_on_filename: true)
+      File.read(file).validate!(fail_on_filename: fail_on_filename)
     end
 
     # :call-seq:
-    #   write(file, model)
-    #   write(file, yaml)
+    #   write(filename, File)
+    #   write(filename, Model)
+    #   write(filename, yaml)
     #
-    # Write the supplied model or yaml string to `file`.
+    # Write the supplied File, Model or yaml string to `file`.
     def self.write(file, cff, comment = '')
+      comment = cff.comment if cff.respond_to?(:comment)
       cff = cff.to_yaml unless cff.is_a?(String)
       content = File.format_comment(comment) + cff[YAML_HEADER.length...-1]
 
@@ -129,10 +145,55 @@ module CFF
     end
 
     # :call-seq:
-    #   write
+    #   validate(fail_fast: false, fail_on_filename: true) -> Array
+    #
+    # Validate this file and return an array with the result. The result array
+    # is a three-element array, with `true`/`false` at index 0 to indicate
+    # pass/fail, an array of schema validation errors at index 1 (if any), and
+    # `true`/`false` at index 2 to indicate whether the filename passed/failed
+    # validation.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def validate(fail_fast: false, fail_on_filename: true)
+      valid_filename = (::File.basename(@filename) == CFF_VALID_FILENAME)
+      result = (@model.validate(fail_fast: fail_fast) << valid_filename)
+      result[0] &&= valid_filename if fail_on_filename
+
+      result
+    end
+
+    # :call-seq:
+    #   validate!(fail_fast: false, fail_on_filename: true)
+    #
+    # Validate this file and raise a ValidationError upon failure. If an error
+    # is raised it will contain the detected validation failures for further
+    # inspection.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def validate!(fail_fast: false, fail_on_filename: true)
+      result = validate(
+        fail_fast: fail_fast, fail_on_filename: fail_on_filename
+      )
+      return if result[0]
+
+      raise ValidationError.new(result[1], invalid_filename: !result[2])
+    end
+
+    # :call-seq:
+    #   write(save_as: filename)
     #
-    # Write this CFF File.
-    def write
+    # Write this CFF File. The `save_as` parameter can be used to save a new
+    # copy of this CFF File under a different filename, leaving the original
+    # file untouched. If `save_as` is used then the internal filename of the
+    # File will be updated to the supplied filename.
+    def write(save_as: nil)
+      unless save_as.nil?
+        @filename = save_as
+        @dirty = true
+      end
+
       File.write(@filename, @model, @comment) if @dirty
       @dirty = false
     end
@@ -156,6 +217,10 @@ module CFF
       @comment = comment
     end
 
+    def to_yaml # :nodoc:
+      @model.to_yaml
+    end
+
     def method_missing(name, *args) # :nodoc:
       if @model.respond_to?(name)
         @dirty = true if name.to_s.end_with?('=') # Remove to_s when Ruby >2.6.

data/lib/cff/formatter/apa_formatter.rb

@@ -40,9 +40,9 @@ module CFF
     end
 
     def self.publication_data_from_model(model)
-      return '' unless model.respond_to?(:journal)
+      return '' unless model.respond_to?(:journal) && !model.journal.empty?
 
-      vol = "#{model.volume}(#{model.issue})" unless model.volume.to_s.empty?
+      vol = model.volume.to_s.empty? ? '' : "#{model.volume}(#{model.issue})"
 
       [model.journal, vol, model.start.to_s].reject(&:empty?).join(', ')
     end

data/lib/cff/identifier.rb

@@ -25,11 +25,12 @@ module CFF
   # will return the empty string. The simple fields are (with defaults in
   # parentheses):
   #
+  # * `description`
   # * `type`
   # * `value`
   class Identifier < ModelPart
 
-    ALLOWED_FIELDS = ['type', 'value'].freeze # :nodoc:
+    ALLOWED_FIELDS = ['description', 'type', 'value'].freeze # :nodoc:
 
     # The [defined set of identifier types](https://github.com/citation-file-format/citation-file-format/blob/main/README.md#identifier-type-strings).
     IDENTIFIER_TYPES = ['doi', 'url', 'swh', 'other'].freeze

data/lib/cff/licensable.rb

@@ -20,8 +20,7 @@ module CFF
   # Functionality to add licence(s) to parts of the CFF model.
   module Licensable
 
-    # :nodoc:
-    LICENSES = SCHEMA_FILE['definitions']['license-enum']['enum'].dup.freeze
+    LICENSES = SCHEMA_FILE['definitions']['license-enum']['enum'].dup.freeze # :nodoc:
 
     # :call-seq:
     #   license = license

data/lib/cff/model.rb

@@ -83,6 +83,29 @@ module CFF
       yield self if block_given?
     end
 
+    # :call-seq:
+    #   read(String) -> Model
+    #
+    # Read a CFF Model from a String and parse it for subsequent manipulation.
+    def self.read(model)
+      new(YAML.safe_load(model, permitted_classes: [Date, Time]))
+    end
+
+    # :call-seq:
+    #   open(String) -> Model
+    #   open(String) { |cff| block } -> Model
+    #
+    # With no associated block, Model.open is a synonym for ::read. If the
+    # optional code block is given, it will be passed the parsed model as an
+    # argument and the Model will be returned when the block terminates.
+    def self.open(model)
+      cff = Model.read(model)
+
+      yield cff if block_given?
+
+      cff
+    end
+
     # :call-seq:
     #   date_released = date
     #

data/lib/cff/reference.rb

@@ -160,6 +160,29 @@ module CFF
       yield self if block_given?
     end
 
+    # :call-seq:
+    #   from_cff(File, type: 'software') -> Reference
+    #   from_cff(Model, type: 'software') -> Reference
+    #
+    # Create a Reference from another CFF File or Model. This is useful for
+    # easily adding a reference to something with its own CITATION.cff file
+    # already.
+    #
+    # This method assumes that the type of the Reference should be `software`,
+    # but this can be overridden with the `type` parameter.
+    def self.from_cff(model, type: 'software')
+      new(model.title, type) do |ref|
+        %w[
+          abstract authors contact commit date_released doi
+          identifiers keywords license license_url repository
+          repository_artifact repository_code url version
+        ].each do |field|
+          value = model.send(field)
+          ref.send("#{field}=", value.dup) unless value == ''
+        end
+      end
+    end
+
     # :call-seq:
     #   add_language language
     #

data/lib/cff/validatable.rb

@@ -22,8 +22,7 @@ module CFF
   # Methods to validate CFF files/models against a formal schema.
   module Validatable
 
-    # :nodoc:
-    SCHEMA = JsonSchema.parse!(SCHEMA_FILE)
+    SCHEMA = JsonSchema.parse!(SCHEMA_FILE) # :nodoc:
 
     # :call-seq:
     #   validate!(fail_fast: false)

data/lib/cff/version.rb

@@ -17,7 +17,7 @@
 ##
 module CFF
   # :nodoc:
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
   DEFAULT_SPEC_VERSION = '1.2.0'
   MIN_VALIDATABLE_VERSION = '1.2.0'
 end

data/lib/schema/1.2.0.json

@@ -1,5 +1,5 @@
 {
-    "$id": "https://citation-file-format.github.io/1.2.0/schema",
+    "$id": "https://citation-file-format.github.io/1.2.0/schema.json",
     "$schema": "http://json-schema.org/draft-07/schema",
     "additionalProperties": false,
     "definitions": {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cff
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Robert Haines
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-08 00:00:00.000000000 Z
+date: 2021-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schema
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 0.20.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 0.20.0
 - !ruby/object:Gem::Dependency
   name: language_list
   requirement: !ruby/object:Gem::Requirement