cff 0.2.0 → 0.9.0

data/lib/cff/formatter/apa_formatter.rb

@@ -0,0 +1,77 @@
+# 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.
+# 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
+  # Generates an APALIKE citation string
+  class ApaFormatter < 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) }
+      )
+
+      _, year = month_and_year_from_model(model)
+      output << "(#{year})" unless year.empty?
+
+      version = " (Version #{model.version})" unless model.version.to_s.empty?
+      output << "#{model.title}#{version}#{software_label(model)}"
+      output << publication_data_from_model(model)
+      output << url(model)
+
+      output.reject(&:empty?).join('. ')
+    end
+
+    def self.publication_data_from_model(model)
+      return '' unless model.respond_to?(:journal) && !model.journal.empty?
+
+      vol = model.volume.to_s.empty? ? '' : "#{model.volume}(#{model.issue})"
+
+      [model.journal, vol, model.start.to_s].reject(&:empty?).join(', ')
+    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.software_label(model)
+      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

data/lib/cff/formatter/bibtex_formatter.rb

@@ -0,0 +1,122 @@
+# 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.
+# 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
+  # Generates an BibTex citation string
+  class BibtexFormatter < 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?
+
+      values = {}
+      values['author'] = combine_authors(
+        model.authors.map { |author| format_author(author) }
+      )
+      values['title'] = "{#{model.title}}"
+
+      publication_data_from_model(model, values)
+
+      month, year = month_and_year_from_model(model)
+      values['month'] = month
+      values['year'] = year
+
+      values['url'] = url(model)
+
+      values.reject! { |_, v| v.empty? }
+      sorted_values = values.sort.map do |key, value|
+        "#{key} = {#{value}}"
+      end
+      sorted_values.insert(0, generate_reference(values))
+
+      "@#{bibtex_type(model)}{#{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, fields)
+      %w[doi journal volume].each do |field|
+        fields[field] = model.send(field).to_s if model.respond_to?(field)
+      end
+
+      # BibTeX 'number' is CFF 'issue'.
+      fields['number'] = model.issue.to_s if model.respond_to?(:issue)
+
+      fields['pages'] = pages_from_model(model)
+    end
+
+    # CFF 'pages' is the number of pages, which has no equivalent in BibTeX.
+    # Reference: https://www.bibtex.com/f/pages-field/
+    def self.pages_from_model(model)
+      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}--#{finish}"
+      end
+    end
+
+    # Do what we can to map between CFF reference types and bibtex types.
+    # Reference: https://www.bibtex.com/e/entry-types/
+    def self.bibtex_type(model)
+      return 'misc' unless model.is_a?(Reference)
+
+      case model.type
+      when 'article', 'book', 'manual', 'unpublished'
+        model.type
+      when 'conference', 'proceedings'
+        'proceedings'
+      when 'conference-paper'
+        'inproceedings'
+      when 'magazine-article', 'newspaper-article'
+        'article'
+      when 'pamphlet'
+        'booklet'
+      else
+        'misc'
+      end
+    end
+
+    def self.format_author(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.combine_authors(authors)
+      authors.join(' and ')
+    end
+
+    def self.generate_reference(fields)
+      [
+        fields['author'].split(',', 2)[0].tr(' -', '_'),
+        fields['title'].split[0..2],
+        fields['year']
+      ].compact.join('_').tr('-$£%&(){}+!?/\\:;\'"~#', '')
+    end
+  end
+end

data/lib/cff/formatter/formatter.rb

@@ -0,0 +1,63 @@
+# 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.
+# 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
+  # Formatter base class
+  class Formatter # :nodoc:
+
+    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 `Model`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
+
+    # 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)
+      if model.respond_to?(:year)
+        result = [model.month, model.year].map(&:to_s)
+
+        return result unless result.any?(&:empty?)
+      end
+
+      month_and_year_from_date(model.date_released)
+    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
+  end
+end

data/lib/cff/identifier.rb

@@ -0,0 +1,72 @@
+# 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.
+# 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
+
+  # An Identifier represents an identifier in a CITATION.cff file.
+  #
+  # Identifier implements all of the fields listed in the
+  # [CFF standard](https://citation-file-format.github.io/). All 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):
+  #
+  # * `description`
+  # * `type`
+  # * `value`
+  class Identifier < ModelPart
+
+    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
+
+    # :call-seq:
+    #   new -> Identifier
+    #   new { |id| block } -> Identifier
+    #   new(type, value) -> Identifier
+    #   new(type, value) { |id| block } -> Identifier
+    #
+    # 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)
+      if param.is_a?(Hash)
+        @fields = param
+        @fields.default = ''
+      else
+        @fields = Hash.new('')
+
+        unless param.nil?
+          self.type = param
+          @fields['value'] = more[0] unless @fields['type'].empty?
+        end
+      end
+
+      yield self if block_given?
+    end
+
+    # :call-seq:
+    #   type = type
+    #
+    # Sets the type of this Identifier. The type is restricted to a
+    # [defined set of identifier types](https://github.com/citation-file-format/citation-file-format/blob/main/README.md#identifier-type-strings).
+    def type=(type)
+      type = type.downcase
+      @fields['type'] = type if IDENTIFIER_TYPES.include?(type)
+    end
+  end
+end

data/lib/cff/licensable.rb

@@ -0,0 +1,45 @@
+# 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.
+# 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
+
+  # Functionality to add licence(s) to parts of the CFF model.
+  module Licensable
+
+    LICENSES = SCHEMA_FILE['definitions']['license-enum']['enum'].dup.freeze # :nodoc:
+
+    # :call-seq:
+    #   license = license
+    #   license = Array
+    #
+    # Set the license, or licenses, of this work. Only licenses that conform
+    # to the [SPDX License List](https://spdx.org/licenses/) will be accepted.
+    # If you need specify a different license you should set `license-url`
+    # with a link to the license instead.
+    def license=(lic)
+      list = [*lic].select { |l| LICENSES.include?(l) }
+      @fields['license'] = case list.length
+                           when 0
+                             @fields['license']
+                           when 1
+                             list[0]
+                           else
+                             list
+                           end
+    end
+  end
+end

data/lib/cff/model.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.
@@ -12,54 +14,176 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#
+##
 module CFF
 
   # Model is the core data structure for a CITATION.cff file. It can be
   # accessed direcly, or via File.
-  class Model
+  #
+  # Model 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):
+  #
+  # * `abstract`
+  # * `cff_version`
+  # * `commit`
+  # * `date_released` - *Note:* returns a `Date` object
+  # * `doi`
+  # * `license`
+  # * `license_url`
+  # * `message` (If you use this software in your work, please cite it using
+  # the following metadata)
+  # * `repository`
+  # * `repository_artifact`
+  # * `repository_code`
+  # * `title`
+  # * `url`
+  # * `version`
+  class Model < ModelPart
 
-    include Util
+    include Licensable
+    include Validatable
 
     ALLOWED_FIELDS = [
-      'abstract',
-      'cff-version',
-      'commit',
-      'date-released',
-      'doi',
-      'license',
-      'license-url',
-      'message',
-      'repository',
-      'repository-artifact',
-      'repository-code',
-      'title',
-      'url',
-      'version'
-  ].freeze # :nodoc:
+      '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:
 
     # 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"
+    DEFAULT_MESSAGE = 'If you use this software in your work, please cite ' \
+                      'it using the following metadata'
 
     # :call-seq:
     #   new(title) -> Model
+    #   new(title) { |model| block } -> Model
     #
     # Initialize a new Model with the supplied title.
     def initialize(param)
-      @authors = []
-      @contact = []
-      @keywords = []
-
-      if Hash === param
-        build_model(param)
+      if param.is_a?(Hash)
+        @fields = build_model(param)
+        @fields.default = ''
       else
         @fields = Hash.new('')
         @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?
+      end
+
+      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
+    #
+    # 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
+    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).
+    #
+    # *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
+      )
+    end
+
+    # :call-seq:
+    #   to_bibtex(preferred_citation: true) -> String
+    #
+    # 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
+      )
+    end
+
+    private
+
+    def fields
+      %w[authors contact identifiers references].each do |field|
+        normalize_modelpart_array!(@fields[field])
+      end
+
+      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'] || [])
+      (fields['identifiers'] || []).map! do |i|
+        Identifier.new(i)
+      end
+      (fields['references'] || []).map! do |r|
+        Reference.new(r)
+      end
+      fields['preferred-citation'] &&=
+        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
+    end
+
+    public
+
+    # Some documentation of "hidden" methods is provided here, out of the
+    # way of the main class code.
+
+    ##
+    # :method: authors
     # :call-seq:
     #   authors -> Array
     #
@@ -71,10 +195,18 @@ module CFF
     # ```
     #
     # Authors can be a Person or Entity.
-    def authors
-      @authors
-    end
 
+    ##
+    # :method: authors=
+    # :call-seq:
+    #   authors = array_of_authors -> Array
+    #
+    # Replace the list of authors for this citation.
+    #
+    # Authors can be a Person or Entity.
+
+    ##
+    # :method: contact
     # :call-seq:
     #   contact -> Array
     #
@@ -86,23 +218,37 @@ module CFF
     # ```
     #
     # Contacts can be a Person or Entity.
-    def contact
-      @contact
-    end
 
+    ##
+    # :method: contact=
     # :call-seq:
-    #   date_released = date
+    #   contact = array_of_contacts -> Array
     #
-    # Set the `date-released` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_released=(date)
-      unless Date === date
-        date = Date.parse(date)
-      end
+    # Replace the list of contacts for this citation.
+    #
+    # Contacts can be a Person or Entity.
 
-      @fields['date-released'] = date
-    end
+    ##
+    # :method: identifiers
+    # :call-seq:
+    #   identifiers -> Array
+    #
+    # Return the list of identifiers for this citation. To add a identifier to
+    # the list, use:
+    #
+    # ```
+    # model.identifiers << identifier
+    # ```
 
+    ##
+    # :method: identifiers=
+    # :call-seq:
+    #   identifiers = array_of_identifiers -> Array
+    #
+    # Replace the list of identifiers for this citation.
+
+    ##
+    # :method: keywords
     # :call-seq:
     #   keywords -> Array
     #
@@ -113,60 +259,48 @@ module CFF
     # model.keywords << keyword
     # ```
     #
-    # Keywords will be converted to Strings on output to a CFF file.
-    def keywords
-      @keywords
-    end
+    # Keywords will be converted to Strings on output.
 
+    ##
+    # :method: keywords=
     # :call-seq:
-    #   version = version
+    #   keywords = array_of_keywords -> Array
     #
-    # Set the `version` field.
-    def version=(version)
-      @fields['version'] = version.to_s
-    end
-
-    def to_yaml # :nodoc:
-      fields = @fields.dup
-      fields['authors'] = array_field_to_yaml(@authors) unless @authors.empty?
-      fields['contact'] = array_field_to_yaml(@contact) unless @contact.empty?
-      fields['keywords'] = @keywords.map { |k| k.to_s } unless @keywords.empty?
-
-      YAML.dump fields, :line_width => -1, :indentation => 2
-    end
-
-    def method_missing(name, *args) # :nodoc:
-      n = method_to_field(name.id2name)
-      super unless ALLOWED_FIELDS.include?(n.chomp('='))
-
-      if n.end_with?('=')
-        @fields[n.chomp('=')] = args[0] || ''
-      else
-        @fields[n]
-      end
-    end
-
-    private
-
-    def build_model(fields)
-      build_entity_collection(@authors, fields['authors'])
-      build_entity_collection(@contact, fields['contact'])
-      @keywords = fields['keywords']
+    # Replace the list of keywords for this citation.
+    #
+    # Keywords will be converted to Strings on output.
 
-      @fields = delete_from_hash(fields, 'authors', 'contact', 'keywords')
-    end
+    ##
+    # :method: preferred_citation
+    # :call-seq:
+    #   preferred_citation -> Reference
+    #
+    # Return the preferred citation for this citation.
 
-    def build_entity_collection(field, source)
-      source.each do |s|
-        field << (s.has_key?('given-names') ? Person.new(s) : Entity.new(s))
-      end
-    end
+    ##
+    # :method: preferred_citation=
+    # :call-seq:
+    #   preferred_citation = Reference
+    #
+    # Replace the preferred citation for this citation.
 
-    def array_field_to_yaml(field)
-      field.reject do |f|
-        !f.respond_to?(:fields)
-      end.map { |f| f.fields }
-    end
+    ##
+    # :method: references
+    # :call-seq:
+    #   references -> Array
+    #
+    # Return the list of references for this citation. To add a reference to the
+    # list, use:
+    #
+    # ```
+    # model.references << reference
+    # ```
 
+    ##
+    # :method: references=
+    # :call-seq:
+    #   references = array_of_references -> Array
+    #
+    # Replace the list of references for this citation.
   end
 end