cff 0.9.0 → 1.0.0

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,10 +14,16 @@
 # 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
@@ -25,7 +31,6 @@ module CFF
   # 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
 
@@ -42,18 +47,18 @@ module CFF
 
     # :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
@@ -132,10 +137,10 @@ module CFF
 
     # :call-seq:
     #   write(filename, File)
-    #   write(filename, Model)
+    #   write(filename, Index)
     #   write(filename, yaml)
     #
-    # Write the supplied File, 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)
@@ -157,7 +162,7 @@ module CFF
     # 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 = (@index.validate(fail_fast: fail_fast) << valid_filename)
       result[0] &&= valid_filename if fail_on_filename
 
       result
@@ -194,7 +199,7 @@ module CFF
         @dirty = true
       end
 
-      File.write(@filename, @model, @comment) if @dirty
+      File.write(@filename, @index, @comment) if @dirty
       @dirty = false
     end
 
@@ -218,20 +223,20 @@ module CFF
     end
 
     def to_yaml # :nodoc:
-      @model.to_yaml
+      @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

data/lib/cff/formatters/bibtex.rb

@@ -0,0 +1,205 @@
+# 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 BibTeX citation string
+    class BibTeX < Formatter # :nodoc:
+      # Fields without `!` have a simple one-to-one mapping between CFF and
+      # BibTeX. Those with `!` call out to a more complex getter.
+      ENTRY_TYPE_MAP = {
+        'article' => %w[doi journal note! number! pages! volume],
+        'book' => %w[address! doi editor! isbn number! pages! publisher! volume],
+        'booklet' => %w[address! doi],
+        'inproceedings' => %w[address! booktitle! doi editor! pages! publisher! series!],
+        'manual' => %w[address! doi],
+        'mastersthesis' => %w[address! doi school! type!],
+        'misc' => %w[doi pages!],
+        'phdthesis' => %w[address! doi school! type!],
+        'proceedings' => %w[address! booktitle! doi editor! pages! publisher! series!],
+        'software' => %w[doi license version],
+        'techreport' => %w[address! doi institution! number!],
+        'unpublished' => %w[doi note!]
+      }.freeze
+
+      def self.format(model:, preferred_citation: true) # rubocop:disable Metrics/AbcSize
+        model = select_and_check_model(model, preferred_citation)
+        return if model.nil?
+
+        values = {}
+        values['author'] = actor_list(model.authors)
+        values['title'] = "{#{model.title}}"
+
+        publication_type = bibtex_type(model)
+        publication_data_from_model(model, publication_type, values)
+
+        month, year = month_and_year_from_model(model)
+        values['month'] = month
+        values['year'] = year
+
+        values['url'] = url(model)
+
+        values['note'] ||= model.notes unless model.is_a?(Index)
+
+        values.reject! { |_, v| v.empty? }
+        sorted_values = values.sort.map do |key, value|
+          "#{key} = {#{value}}"
+        end
+        sorted_values.insert(0, generate_citekey(values))
+
+        "@#{publication_type}{#{sorted_values.join(",\n")}\n}"
+      end
+
+      # Get various bits of information about the reference publication.
+      # Reference: https://www.bibtex.com/format/
+      def self.publication_data_from_model(model, type, fields)
+        ENTRY_TYPE_MAP[type].each do |field|
+          if model.respond_to?(field)
+            fields[field] = model.send(field).to_s
+          else
+            field = field.chomp('!')
+            fields[field] = send("#{field}_from_model", model)
+          end
+        end
+      end
+
+      # BibTeX 'number' is CFF 'issue'.
+      def self.number_from_model(model)
+        model.issue.to_s
+      end
+
+      # BibTeX 'address' is taken from the publisher (book, others) or the
+      # conference (inproceedings).
+      def self.address_from_model(model)
+        entity = if model.type == 'conference-paper'
+                   model.conference
+                 else
+                   model.publisher
+                 end
+        return '' if entity.empty?
+
+        [entity.city, entity.region, entity.country].reject(&:empty?).join(', ')
+      end
+
+      # BibTeX 'institution' could be grabbed from an author's affiliation, or
+      # provided explicitly.
+      def self.institution_from_model(model)
+        return model.institution.name unless model.institution.empty?
+
+        model.authors.first.affiliation
+      end
+
+      # BibTeX 'school' is CFF 'institution'.
+      def self.school_from_model(model)
+        institution_from_model(model)
+      end
+
+      # BibTeX 'type' for theses is CFF 'thesis-type'.
+      def self.type_from_model(model)
+        model.thesis_type
+      end
+
+      # BibTeX 'booktitle' is CFF 'collection-title'.
+      def self.booktitle_from_model(model)
+        model.collection_title
+      end
+
+      # BibTeX 'editor' is CFF 'editors' or 'editors-series'.
+      def self.editor_from_model(model)
+        if model.editors.empty?
+          model.editors_series.empty? ? '' : actor_list(model.editors_series)
+        else
+          actor_list(model.editors)
+        end
+      end
+
+      def self.publisher_from_model(model)
+        model.publisher.empty? ? '' : model.publisher.name
+      end
+
+      def self.series_from_model(model)
+        model.conference.empty? ? '' : model.conference.name
+      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?
+          date = model.conference.date_start
+          return month_and_year_from_date(date) unless date == ''
+        end
+
+        super
+      end
+
+      # Do what we can to map between CFF reference types and bibtex types.
+      # References:
+      #  * https://www.bibtex.com/e/entry-types/
+      #  * https://ctan.gutenberg.eu.org/macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.pdf
+      def self.bibtex_type(model) # rubocop:disable Metrics/CyclomaticComplexity
+        return 'software' if model.type.empty? || model.type.include?('software')
+
+        case model.type
+        when 'article', 'book', 'manual', 'unpublished', 'phdthesis', 'mastersthesis'
+          model.type
+        when 'conference', 'proceedings'
+          'proceedings'
+        when 'conference-paper'
+          'inproceedings'
+        when 'magazine-article', 'newspaper-article'
+          'article'
+        when 'pamphlet'
+          'booklet'
+        when 'report'
+          'techreport'
+        else
+          'misc'
+        end
+      end
+
+      def self.format_actor(author)
+        return "{#{author.name}}" if author.is_a?(Entity)
+
+        particle =
+          author.name_particle.empty? ? '' : "#{author.name_particle} "
+
+        [
+          "#{particle}#{author.family_names}",
+          author.name_suffix,
+          author.given_names
+        ].reject(&:empty?).join(', ')
+      end
+
+      def self.actor_list(actors)
+        actors.map { |actor| format_actor(actor) }.join(' and ')
+      end
+
+      def self.generate_citekey(fields)
+        reference = [
+          fields['author'].split(',', 2)[0],
+          fields['title'].split[0..2],
+          fields['year']
+        ].compact.join('_')
+
+        Util.parameterize(reference)
+      end
+    end
+  end
+end

data/lib/cff/formatters/formatter.rb

@@ -0,0 +1,98 @@
+# 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 'date'
+
+##
+module CFF
+  module Formatters # :nodoc:
+    # Formatter base class
+    class Formatter # :nodoc:
+      STATUS_TEXT_MAP = {
+        'advance-online' => 'Advance online publication',
+        'in-preparation' => 'Manuscript in preparation.',
+        'submitted' => 'Manuscript submitted for publication.'
+      }.freeze
+
+      def self.label
+        @label ||= name.split('::')[-1]
+      end
+
+      def self.select_and_check_model(model, preferred_citation)
+        if preferred_citation && model.preferred_citation.is_a?(Reference)
+          model = model.preferred_citation
+        end
+
+        # Safe to assume valid `Index`s and `Reference`s will have these fields.
+        model.authors.empty? || model.title.empty? ? nil : model
+      end
+
+      def self.initials(name)
+        name.split.map { |part| part[0].capitalize }.join('. ')
+      end
+
+      def self.note_from_model(model)
+        STATUS_TEXT_MAP[model.status]
+      end
+
+      # Prefer `repository_code` over `url`
+      def self.url(model)
+        model.repository_code.empty? ? model.url : model.repository_code
+      end
+
+      def self.month_and_year_from_model(model) # rubocop:disable Metrics
+        return ['', 'in press'] if model.respond_to?(:status) && model.status == 'in-press'
+        if model.respond_to?(:year) && !model.year.to_s.empty?
+          return [model.month, model.year].map(&:to_s)
+        end
+
+        date = month_and_year_from_date(model.date_released)
+        if date == ['', ''] && model.respond_to?(:date_published)
+          date = month_and_year_from_date(model.date_published)
+        end
+        date
+      end
+
+      def self.month_and_year_from_date(value)
+        if value.is_a?(Date)
+          [value.month, value.year].map(&:to_s)
+        else
+          begin
+            date = Date.parse(value.to_s)
+            [date.month, date.year].map(&:to_s)
+          rescue ArgumentError
+            ['', '']
+          end
+        end
+      end
+
+      # CFF 'pages' is the number of pages, which has no equivalent in BibTeX
+      # or APA. References: https://www.bibtex.com/f/pages-field/,
+      # https://apastyle.apa.org/style-grammar-guidelines/references/examples
+      def self.pages_from_model(model, dash: '--')
+        return '' if !model.respond_to?(:start) || model.start.to_s.empty?
+
+        start = model.start.to_s
+        finish = model.end.to_s
+        if finish.empty?
+          start
+        else
+          start == finish ? start : "#{start}#{dash}#{finish}"
+        end
+      end
+    end
+  end
+end

data/lib/cff/formatters.rb

@@ -0,0 +1,61 @@
+# 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.
+
+##
+module CFF
+  # A registry of output formatters for converting CFF files into citations.
+  module Formatters
+    @formatters = {}
+
+    # :call-seq:
+    #   formatters -> Array
+    #
+    # Return the list of formatters that are available.
+    def self.formatters
+      @formatters.keys
+    end
+
+    # :call-seq:
+    #   register_formatter(class)
+    #
+    # Register a citation formatter. To be registered as a formatter, a
+    # class should at least provide the following class methods:
+    #
+    # * `format`, which takes the model to be formatted
+    # as a named parameter, and the option to cite a CFF file's
+    # `preferred-citation`:
+    # ```ruby
+    # def self.format(model:, preferred_citation: true); end
+    # ```
+    # * `label`, which returns a short name for the formatter, e.g.
+    # `'BibTeX'`. If your formatter class subclasses `CFF::Formatter`,
+    # then `label` is provided for you.
+    def self.register_formatter(clazz)
+      return unless clazz.singleton_methods.include?(:format)
+      return if @formatters.has_value?(clazz)
+
+      format = clazz.label.downcase.to_sym
+      @formatters[format] = clazz
+      Citable.add_to_format_method(format) if defined?(Citable)
+    end
+
+    def self.formatter_for(format) # :nodoc:
+      @formatters[format.downcase.to_sym]
+    end
+  end
+end
+
+require_relative 'formatters/all'