cff 0.8.0 → 1.0.0

data/lib/cff/entity.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2022 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.
@@ -14,9 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require_relative 'model_part'
+require_relative 'schema'
+
 ##
 module CFF
-
   # An Entity can represent different types of entities, e.g., a publishing
   # company, or conference. Like a Person, an Entity might have a number of
   # roles, such as author, contact, editor, etc.
@@ -28,11 +30,12 @@ module CFF
   # parentheses):
   #
   # * `address`
+  # * `alias`
   # * `city`
   # * `country`
-  # * `email`
   # * `date_end` - *Note:* returns a `Date` object
   # * `date_start` - *Note:* returns a `Date` object
+  # * `email`
   # * `fax`
   # * `location`
   # * `name`
@@ -42,11 +45,9 @@ module CFF
   # * `tel`
   # * `website`
   class Entity < ModelPart
+    ALLOWED_FIELDS = SCHEMA_FILE['definitions']['entity']['properties'].keys.freeze # :nodoc:
 
-    ALLOWED_FIELDS = [
-      'address', 'city', 'country', 'email', 'date-end', 'date-start', 'fax',
-      'location', 'name', 'orcid', 'post-code', 'region', 'tel', 'website'
-    ].freeze # :nodoc:
+    attr_date :date_end, :date_start
 
     # :call-seq:
     #   new(name) -> Entity
@@ -54,37 +55,16 @@ module CFF
     #
     # Create a new Entity with the supplied name.
     def initialize(param)
+      super()
+
       if param.is_a?(Hash)
         @fields = param
-        @fields.default = ''
       else
-        @fields = Hash.new('')
+        @fields = {}
         @fields['name'] = param
       end
 
       yield self if block_given?
     end
-
-    # :call-seq:
-    #   date_end = date
-    #
-    # Set the `date-end` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_end=(date)
-      date = Date.parse(date) unless date.is_a?(Date)
-
-      @fields['date-end'] = date
-    end
-
-    # :call-seq:
-    #   date_start = date
-    #
-    # Set the `date-start` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_start=(date)
-      date = Date.parse(date) unless date.is_a?(Date)
-
-      @fields['date-start'] = date
-    end
   end
 end

data/lib/cff/errors.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2022 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.
@@ -16,30 +16,35 @@
 
 ##
 module CFF
-
   # Error is the base class for all errors raised by this library.
   class Error < RuntimeError
-
     def initialize(message = nil) # :nodoc:
       super
     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 Index 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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2021 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2022 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.
@@ -14,13 +14,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require_relative 'errors'
+require_relative 'index'
+require_relative 'version'
+
+require 'date'
+require 'yaml'
+
 ##
 module CFF
-
-  # File provides direct access to a CFF Model, with the addition of some
+  # File provides direct access to a CFF Index, 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.
     attr_reader :comment
 
@@ -33,27 +43,28 @@ 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
-    #   new(filename, model) -> File
+    #   new(filename, index) -> File
     #
-    # Create a new File. Either a pre-existing Model can be passed in or, as
-    # with Model itself, a title can be supplied to initalize a new File.
+    # Create a new File. Either a pre-existing Index can be passed in or, as
+    # with Index itself, a title can be supplied to initalize a new File.
     #
-    # All methods provided by Model are also available directly on File
+    # All methods provided by Index are also available directly on File
     # objects.
     def initialize(filename, param, comment = CFF_COMMENT, create: false)
-      param = Model.new(param) unless param.is_a?(Model)
+      param = Index.new(param) unless param.is_a?(Index)
 
       @filename = filename
-      @model = param
+      @index = param
       @comment = comment
       @dirty = create
     end
 
     # :call-seq:
-    #   read(file) -> File
+    #   read(filename) -> File
     #
     # Read a file and parse it for subsequent manipulation.
     def self.read(file)
@@ -66,8 +77,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 +108,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, Index)
+    #   write(filename, yaml)
     #
-    # Write the supplied model or yaml string to `file`.
+    # Write the supplied File, Index 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,11 +150,56 @@ 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 = (@index.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)
     #
-    # Write this CFF File.
-    def write
-      File.write(@filename, @model, @comment) if @dirty
+    # 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. 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, @index, @comment) if @dirty
       @dirty = false
     end
 
@@ -156,17 +222,21 @@ module CFF
       @comment = comment
     end
 
+    def to_yaml # :nodoc:
+      @index.to_yaml
+    end
+
     def method_missing(name, *args) # :nodoc:
-      if @model.respond_to?(name)
+      if @index.respond_to?(name)
         @dirty = true if name.to_s.end_with?('=') # Remove to_s when Ruby >2.6.
-        @model.send(name, *args)
+        @index.send(name, *args)
       else
         super
       end
     end
 
     def respond_to_missing?(name, *all) # :nodoc:
-      @model.respond_to?(name, *all)
+      @index.respond_to?(name, *all)
     end
 
     def self.format_comment(comment) # :nodoc:

data/lib/cff/formatters/all.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018-2022 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.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'apalike'
+require_relative 'bibtex'
+
+##
+module CFF
+  module Formatters # :nodoc:
+    register_formatter(APALike)
+    register_formatter(BibTeX)
+  end
+end

data/lib/cff/formatters/apalike.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018-2022 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.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'formatter'
+
+##
+module CFF
+  module Formatters # :nodoc:
+    # Generates an APALIKE citation string
+    class APALike < Formatter # :nodoc:
+      def self.format(model:, preferred_citation: true) # rubocop:disable Metrics/AbcSize
+        model = select_and_check_model(model, preferred_citation)
+        return if model.nil?
+
+        output = []
+        output << combine_authors(
+          model.authors.map { |author| format_author(author) }
+        )
+
+        date = month_and_year_from_model(model)
+        output << "(#{date})" unless date.empty?
+
+        version = " (Version #{model.version})" unless model.version.to_s.empty?
+        output << "#{model.title}#{version}#{type_label(model)}"
+        output << publication_data_from_model(model)
+        output << url(model)
+
+        output.reject(&:empty?).join('. ')
+      end
+
+      def self.publication_data_from_model(model) # rubocop:disable Metrics
+        case model.type
+        when 'article'
+          [
+            model.journal,
+            volume_from_model(model),
+            pages_from_model(model, dash: '–'),
+            note_from_model(model) || ''
+          ].reject(&:empty?).join(', ')
+        when 'book'
+          model.publisher.empty? ? '' : model.publisher.name
+        when 'conference-paper'
+          [
+            model.collection_title,
+            volume_from_model(model),
+            pages_from_model(model, dash: '–')
+          ].reject(&:empty?).join(', ')
+        when 'report'
+          if model.institution.empty?
+            model.authors.first.affiliation
+          else
+            model.institution.name
+          end
+        when 'phdthesis'
+          type_and_school_from_model(model, 'Doctoral dissertation')
+        when 'mastersthesis'
+          type_and_school_from_model(model, "Master's thesis")
+        when 'unpublished'
+          note_from_model(model) || ''
+        else
+          ''
+        end
+      end
+
+      def self.type_and_school_from_model(model, type)
+        type = model.thesis_type == '' ? type : model.thesis_type
+        school = model.institution.empty? ? model.authors.first.affiliation : model.institution.name
+        "[#{type}, #{school}]"
+      end
+
+      def self.volume_from_model(model)
+        issue = model.issue.to_s.empty? ? '' : "(#{model.issue})"
+        model.volume.to_s.empty? ? '' : "#{model.volume}#{issue}"
+      end
+
+      # If we're citing a conference paper, try and use the date of the
+      # conference. Otherwise use the specified month and year, or the date
+      # of release.
+      def self.month_and_year_from_model(model)
+        if model.type == 'conference-paper' && !model.conference.empty?
+          start = model.conference.date_start
+          unless start == ''
+            finish = model.conference.date_end
+            return month_and_year_from_date(start)[1] if finish == '' || start >= finish
+
+            return date_range(start, finish)
+          end
+        end
+
+        super[1]
+      end
+
+      def self.date_range(start, finish)
+        start_str = '%Y, %B %-d'
+        finish_str = '%-d'
+        finish_str = "%B #{finish_str}" unless start.month == finish.month
+        finish_str = "%Y, #{finish_str}" unless start.year == finish.year
+
+        "#{start.strftime(start_str)}–#{finish.strftime(finish_str)}"
+      end
+
+      # Prefer a DOI over the other URI options.
+      def self.url(model)
+        model.doi.empty? ? super : "https://doi.org/#{model.doi}"
+      end
+
+      def self.type_label(model)
+        return ' [Data set]' if model.type.include?('data')
+        return ' [Conference paper]' if model.type.include?('conference')
+        return '' if model.is_a?(Reference) && !model.type.include?('software')
+
+        ' [Computer software]'
+      end
+
+      def self.combine_authors(authors)
+        return authors[0].chomp('.') if authors.length == 1
+
+        "#{authors[0..-2].join(', ')}, & #{authors[-1]}".chomp('.')
+      end
+
+      def self.format_author(author)
+        return author.name if author.is_a?(Entity)
+
+        particle =
+          author.name_particle.empty? ? '' : "#{author.name_particle} "
+        suffix = author.name_suffix.empty? ? '.' : "., #{author.name_suffix}"
+
+        "#{particle}#{author.family_names}, #{initials(author.given_names)}#{suffix}"
+      end
+    end
+  end
+end