cff 0.8.0 → 1.0.0

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'

data/lib/cff/identifier.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 Identifier represents an identifier in a CITATION.cff file.
   #
   # Identifier implements all of the fields listed in the
@@ -25,14 +27,17 @@ 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 = # :nodoc:
+      SCHEMA_FILE['definitions']['identifier']['anyOf'].first['properties'].keys.dup.freeze
 
     # 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
+    IDENTIFIER_TYPES = SCHEMA_FILE['definitions']['identifier']['anyOf'].map do |id|
+      id['properties']['type']['enum'].first
+    end.freeze
 
     # :call-seq:
     #   new -> Identifier
@@ -43,15 +48,16 @@ module CFF
     # Create a new Identifier with the optionally supplied type and value.
     # If the supplied type is invalid, then neither the type or value are set.
     def initialize(param = nil, *more)
+      super()
+
       if param.is_a?(Hash)
         @fields = param
-        @fields.default = ''
       else
-        @fields = Hash.new('')
+        @fields = {}
 
         unless param.nil?
           self.type = param
-          @fields['value'] = more[0] unless @fields['type'].empty?
+          @fields['value'] = more[0] unless @fields['type'].nil?
         end
       end
 

data/lib/cff/{model.rb → index.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,19 +14,31 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require_relative 'util'
+require_relative 'model_part'
+require_relative 'entity'
+require_relative 'identifier'
+require_relative 'licensable'
+require_relative 'person'
+require_relative 'reference'
+require_relative 'schema'
+require_relative 'validatable'
+require_relative 'citable'
+
+require 'yaml'
+
 ##
 module CFF
-
-  # Model is the core data structure for a CITATION.cff file. It can be
+  # Index is the core data structure for a CITATION.cff file. It can be
   # accessed direcly, or via File.
   #
-  # Model implements all of the fields listed in the
+  # Index implements all of the fields listed in the
   # [CFF standard](https://citation-file-format.github.io/). Complex
   # fields - `authors`, `contact`, `identifiers`, `keywords`,
-  # `preferred-citation` and `references` - are documented below. All other
-  # fields are simple strings and can be set as such. A field which has not
-  # been set will return the empty string. The simple fields are (with defaults
-  # in parentheses):
+  # `preferred-citation`, `references` and `type` - are documented below. All
+  # other fields are simple strings and can be set as such. A field which has
+  # not been set will return the empty string. The simple fields are (with
+  # defaults in parentheses):
   #
   # * `abstract`
   # * `cff_version`
@@ -43,102 +55,97 @@ module CFF
   # * `title`
   # * `url`
   # * `version`
-  class Model < ModelPart
-
+  class Index < ModelPart
+    include Citable
     include Licensable
     include Validatable
 
-    ALLOWED_FIELDS = [
-      'abstract', 'authors', 'cff-version', 'contact', 'commit',
-      'date-released', 'doi', 'identifiers', 'keywords', 'license',
-      'license-url', 'message', 'preferred-citation', 'references',
-      'repository', 'repository-artifact', 'repository-code', 'title',
-      'url', 'version'
-    ].freeze # :nodoc:
+    ALLOWED_FIELDS = SCHEMA_FILE['properties'].keys.freeze # :nodoc:
+
+    # The allowed CFF [types](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#type).
+    MODEL_TYPES = SCHEMA_FILE['properties']['type']['enum'].dup.freeze
 
     # The default message to use if none is explicitly set.
     DEFAULT_MESSAGE = 'If you use this software in your work, please cite ' \
                       'it using the following metadata'
 
+    attr_date :date_released
+
     # :call-seq:
-    #   new(title) -> Model
-    #   new(title) { |model| block } -> Model
+    #   new(title) -> Index
+    #   new(title) { |index| block } -> Index
     #
-    # Initialize a new Model with the supplied title.
+    # Initialize a new Index with the supplied title.
     def initialize(param)
+      super()
+
       if param.is_a?(Hash)
-        @fields = build_model(param)
-        @fields.default = ''
+        @fields = build_index(param)
       else
-        @fields = Hash.new('')
+        @fields = {}
         @fields['cff-version'] = DEFAULT_SPEC_VERSION
         @fields['message'] = DEFAULT_MESSAGE
         @fields['title'] = param
       end
 
       %w[authors contact identifiers keywords references].each do |field|
-        @fields[field] = [] if @fields[field].empty?
+        @fields[field] = [] if @fields[field].nil? || @fields[field].empty?
       end
 
       yield self if block_given?
     end
 
     # :call-seq:
-    #   date_released = date
+    #   read(String) -> Index
     #
-    # Set the `date-released` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_released=(date)
-      date = Date.parse(date) unless date.is_a?(Date)
-
-      @fields['date-released'] = date
-    end
-
-    def to_yaml # :nodoc:
-      YAML.dump fields, line_width: -1, indentation: 2
+    # Read a CFF Index from a String and parse it for subsequent manipulation.
+    def self.read(index)
+      new(YAML.safe_load(index, permitted_classes: [Date, Time]))
     end
 
     # :call-seq:
-    #   to_apalike(preferred_citation: true) -> String
-    #
-    # Output this Model in an APA-like format. Setting
-    # `preferred_citation: true` will honour the `preferred_citation` field in
-    # the model if one is present (default).
+    #   open(String) -> Index
+    #   open(String) { |cff| block } -> Index
     #
-    # *Note:* This method assumes that this Model is valid when called.
-    def to_apalike(preferred_citation: true)
-      CFF::ApaFormatter.format(
-        model: self, preferred_citation: preferred_citation
-      )
+    # With no associated block, Index.open is a synonym for ::read. If the
+    # optional code block is given, it will be passed the parsed index as an
+    # argument and the Index will be returned when the block terminates.
+    def self.open(index)
+      cff = Index.read(index)
+
+      yield cff if block_given?
+
+      cff
     end
 
     # :call-seq:
-    #   to_bibtex(preferred_citation: true) -> String
+    #   type = type
     #
-    # Output this Model in BibTeX format. Setting
-    # `preferred_citation: true` will honour the `preferred_citation` field in
-    # the model if one is present (default).
-    #
-    # *Note:* This method assumes that this Model is valid when called.
-    def to_bibtex(preferred_citation: true)
-      CFF::BibtexFormatter.format(
-        model: self, preferred_citation: preferred_citation
-      )
+    # Sets the type of this CFF Index. The type is currently restricted to one
+    # of `software` or `dataset`. If this field is not set then you should
+    # assume that the type is `software`.
+    def type=(type)
+      type = type.downcase
+      @fields['type'] = type if MODEL_TYPES.include?(type)
+    end
+
+    def to_yaml # :nodoc:
+      YAML.dump fields, line_width: -1, indentation: 2
     end
 
     private
 
     def fields
       %w[authors contact identifiers references].each do |field|
-        normalize_modelpart_array!(@fields[field])
+        Util.normalize_modelpart_array!(@fields[field])
       end
 
-      fields_to_hash(@fields)
+      Util.fields_to_hash(@fields)
     end
 
-    def build_model(fields) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
-      build_actor_collection!(fields['authors'] || [])
-      build_actor_collection!(fields['contact'] || [])
+    def build_index(fields) # rubocop:disable Metrics
+      Util.build_actor_collection!(fields['authors'] || [])
+      Util.build_actor_collection!(fields['contact'] || [])
       (fields['identifiers'] || []).map! do |i|
         Identifier.new(i)
       end
@@ -149,7 +156,7 @@ module CFF
         Reference.new(fields['preferred-citation'])
 
       # Only attempt an update of the `cff-version` field if it is present.
-      fields['cff-version'] &&= update_cff_version(fields['cff-version'])
+      fields['cff-version'] &&= Util.update_cff_version(fields['cff-version'])
 
       fields
     end
@@ -168,7 +175,7 @@ module CFF
     # list, use:
     #
     # ```
-    # model.authors << author
+    # index.authors << author
     # ```
     #
     # Authors can be a Person or Entity.
@@ -191,7 +198,7 @@ module CFF
     # list, use:
     #
     # ```
-    # model.contact << contact
+    # index.contact << contact
     # ```
     #
     # Contacts can be a Person or Entity.
@@ -214,7 +221,7 @@ module CFF
     # the list, use:
     #
     # ```
-    # model.identifiers << identifier
+    # index.identifiers << identifier
     # ```
 
     ##
@@ -233,7 +240,7 @@ module CFF
     # list, use:
     #
     # ```
-    # model.keywords << keyword
+    # index.keywords << keyword
     # ```
     #
     # Keywords will be converted to Strings on output.
@@ -270,7 +277,7 @@ module CFF
     # list, use:
     #
     # ```
-    # model.references << reference
+    # index.references << reference
     # ```
 
     ##