cff 0.4.0 → 0.8.0

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,71 @@
+# 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):
+  #
+  # * `type`
+  # * `value`
+  class Identifier < ModelPart
+
+    ALLOWED_FIELDS = ['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,46 @@
+# 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
+
+    # :nodoc:
+    LICENSES = SCHEMA_FILE['definitions']['license-enum']['enum'].dup.freeze
+
+    # :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.
@@ -17,21 +19,50 @@ module CFF
 
   # Model 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
+  # [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 Licensable
+    include Validatable
+
     ALLOWED_FIELDS = [
       'abstract', 'authors', 'cff-version', 'contact', 'commit',
-      'date-released', 'doi', 'keywords', 'license', 'license-url', 'message',
-      'references', 'repository', 'repository-artifact', 'repository-code',
-      'title', 'url', 'version'
+      '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'.freeze
+                      '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)
@@ -45,9 +76,11 @@ module CFF
         @fields['title'] = param
       end
 
-      %w[authors contact keywords references].each do |field|
+      %w[authors contact identifiers keywords references].each do |field|
         @fields[field] = [] if @fields[field].empty?
       end
+
+      yield self if block_given?
     end
 
     # :call-seq:
@@ -61,34 +94,62 @@ module CFF
       @fields['date-released'] = date
     end
 
+    def to_yaml # :nodoc:
+      YAML.dump fields, line_width: -1, indentation: 2
+    end
+
     # :call-seq:
-    #   version = version
+    #   to_apalike(preferred_citation: true) -> String
     #
-    # Set the `version` field.
-    def version=(version)
-      @fields['version'] = version.to_s
+    # 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
 
-    def to_yaml # :nodoc:
-      YAML.dump fields, line_width: -1, indentation: 2
+    # :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 references].each do |field|
+      %w[authors contact identifiers references].each do |field|
         normalize_modelpart_array!(@fields[field])
       end
 
       fields_to_hash(@fields)
     end
 
-    def build_model(fields)
+    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
@@ -144,6 +205,25 @@ module CFF
     #
     # Contacts can be a Person or Entity.
 
+    ##
+    # :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:
@@ -167,6 +247,20 @@ module CFF
     #
     # Keywords will be converted to Strings on output.
 
+    ##
+    # :method: preferred_citation
+    # :call-seq:
+    #   preferred_citation -> Reference
+    #
+    # Return the preferred citation for this citation.
+
+    ##
+    # :method: preferred_citation=
+    # :call-seq:
+    #   preferred_citation = Reference
+    #
+    # Replace the preferred citation for this citation.
+
     ##
     # :method: references
     # :call-seq:

data/lib/cff/model_part.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.

data/lib/cff/person.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.
@@ -17,26 +19,58 @@ module CFF
 
   # A Person represents a person in a CITATION.cff file. A Person might have a
   # number of roles, such as author, contact, editor, etc.
+  #
+  # Person 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):
+  #
+  # * `address`
+  # * `affiliation`
+  # * `alias`
+  # * `city`
+  # * `country`
+  # * `email`
+  # * `family_names`
+  # * `fax`
+  # * `given_names`
+  # * `name_particle`
+  # * `name_suffix`
+  # * `orcid`
+  # * `post_code`
+  # * `region`
+  # * `tel`
+  # * `website`
   class Person < ModelPart
 
     ALLOWED_FIELDS = [
-      'address', 'affiliation', 'city', 'country', 'email', 'family-names',
-      'fax', 'given-names', 'name-particle', 'name-suffix', 'orcid',
-      'post-code', 'region', 'tel', 'website'
+      'address', 'affiliation', 'alias', 'city', 'country', 'email',
+      'family-names', 'fax', 'given-names', 'name-particle', 'name-suffix',
+      'orcid', 'post-code', 'region', 'tel', 'website'
     ].freeze # :nodoc:
 
     # :call-seq:
+    #   new -> Person
+    #   new { |person| block } -> Person
     #   new(given_name, family_name) -> Person
+    #   new(given_name, family_name) { |person| block } -> Person
     #
-    # Create a new Person with the supplied given and family names.
-    def initialize(param, *more)
+    # Create a new Person with the optionally supplied given and family names.
+    def initialize(param = nil, *more)
       if param.is_a?(Hash)
         @fields = param
+        @fields.default = ''
       else
         @fields = Hash.new('')
-        @fields['family-names'] = more[0]
-        @fields['given-names'] = param
+
+        unless param.nil?
+          @fields['family-names'] = more[0]
+          @fields['given-names'] = param
+        end
       end
+
+      yield self if block_given?
     end
   end
 end