cff 0.9.0 → 1.0.0

data/lib/cff/reference.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,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require_relative 'licensable'
+require_relative 'model_part'
+require_relative 'schema'
+require_relative 'util'
+
 ##
 module CFF
-
   # Reference provides a reference pertaining to the software version or the
   # software itself, e.g., a software paper describing the abstract concepts of
   # the software, a paper describing an algorithm that has been implemented in
@@ -74,12 +78,13 @@ module CFF
   # * `pmcid`
   # * `publisher`
   # * `repository`
-  # * `repository_code`
   # * `repository_artifact`
+  # * `repository_code`
   # * `scope`
   # * `section`
   # * `start`
   # * `status` - *Note:* see documentation for `status =` below
+  # * `term`
   # * `thesis_type`
   # * `title`
   # * `type` - *Note:* see documentation for `type =` below
@@ -90,44 +95,24 @@ module CFF
   # * `year`
   # * `year_original`
   class Reference < ModelPart
-
     include Licensable
 
-    ALLOWED_FIELDS = [
-      'abbreviation', 'abstract', 'authors', 'collection-doi',
-      'collection-title', 'collection-type', 'commit', 'conference', 'contact',
-      'copyright', 'data-type', 'database', 'database-provider',
-      'date-accessed', 'date-downloaded', 'date-published', 'date-released',
-      'department', 'doi', 'edition', 'editors', 'editors-series', 'end',
-      'entry', 'filename', 'identifiers', 'institution', 'isbn', 'issn',
-      'issue', 'issue-date', 'issue-title', 'journal', 'keywords', 'license',
-      'license-url', 'loc-end', 'loc-start', 'location', 'medium', 'month',
-      'nihmsid', 'notes', 'number', 'number-volumes', 'pages', 'patent-states',
-      'pmcid', 'publisher', 'recipients', 'repository', 'repository-code',
-      'repository-artifact', 'scope', 'section', 'senders', 'start', 'status',
-      'thesis-type', 'title', 'translators', 'type', 'url', 'version',
-      'volume', 'volume-title', 'year', 'year-original'
-    ].freeze # :nodoc:
-
-    # The [defined set of reference types](https://github.com/citation-file-format/citation-file-format#reference-types).
-    REFERENCE_TYPES = [
-      'art', 'article', 'audiovisual', 'bill', 'blog', 'book', 'catalogue',
-      'conference', 'conference-paper', 'data', 'database', 'dictionary',
-      'edited-work', 'encyclopedia', 'film-broadcast', 'generic',
-      'government-document', 'grant', 'hearing', 'historical-work',
-      'legal-case', 'legal-rule', 'magazine-article', 'manual', 'map',
-      'multimedia', 'music', 'newspaper-article', 'pamphlet', 'patent',
-      'personal-communication', 'proceedings', 'report', 'serial', 'slides',
-      'software', 'software-code', 'software-container', 'software-executable',
-      'software-virtual-machine', 'sound-recording', 'standard', 'statute',
-      'thesis', 'unpublished', 'video', 'website'
-    ].freeze
-
-    # The [defined set of reference status types](https://github.com/citation-file-format/citation-file-format#status-strings).
-    REFERENCE_STATUS_TYPES = [
-      'abstract', 'advance-online', 'in-preparation', 'in-press',
-      'pre-print', 'submitted'
-    ].freeze
+    # This list does not include `format` for reasons explained below, where
+    # the `format` method is defined!
+    ALLOWED_FIELDS = (
+      SCHEMA_FILE['definitions']['reference']['properties'].keys - %w[format languages]
+    ).freeze # :nodoc:
+
+    # The [defined set of reference types](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreferencetype).
+    REFERENCE_TYPES =
+      SCHEMA_FILE['definitions']['reference']['properties']['type']['enum'].dup.freeze
+
+    # The [defined set of reference status types](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreferencestatus).
+    REFERENCE_STATUS_TYPES =
+      SCHEMA_FILE['definitions']['reference']['properties']['status']['enum'].dup.freeze
+
+    attr_date :date_accessed, :date_downloaded, :date_published,
+              :date_released, :issue_date
 
     # :call-seq:
     #   new(title) -> Reference
@@ -137,24 +122,25 @@ module CFF
     #
     # Create a new Reference with the supplied title and, optionally, type.
     # If type is not given, or is not one of the
-    # [defined set of reference types](https://github.com/citation-file-format/citation-file-format#reference-types),
+    # [defined set of reference types](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreferencetype),
     # 'generic' will be used by default.
-    def initialize(param, *more) # rubocop:disable Metrics/AbcSize
+    def initialize(param, *more) # rubocop:disable Metrics
+      super()
+
       if param.is_a?(Hash)
         @fields = build_model(param)
-        @fields.default = ''
       else
-        @fields = Hash.new('')
+        @fields = {}
         type = more[0] &&= more[0].downcase
         @fields['type'] = REFERENCE_TYPES.include?(type) ? type : 'generic'
         @fields['title'] = param
       end
 
-      [
-        'authors', 'contact', 'editors', 'editors-series', 'identifiers',
-        'keywords', 'patent-states', 'recipients', 'senders', 'translators'
+      %w[
+        authors contact editors editors-series identifiers
+        keywords patent-states recipients senders translators
       ].each do |field|
-        @fields[field] = [] if @fields[field].empty?
+        @fields[field] = [] if @fields[field].nil? || @fields[field].empty?
       end
 
       yield self if block_given?
@@ -162,9 +148,9 @@ module CFF
 
     # :call-seq:
     #   from_cff(File, type: 'software') -> Reference
-    #   from_cff(Model, type: 'software') -> Reference
+    #   from_cff(Index, type: 'software') -> Reference
     #
-    # Create a Reference from another CFF File or Model. This is useful for
+    # Create a Reference from another CFF File or Index. This is useful for
     # easily adding a reference to something with its own CITATION.cff file
     # already.
     #
@@ -190,12 +176,13 @@ module CFF
     # three letter language code, so `GER` becomes `deu`, `french` becomes
     # `fra` and `en` becomes `eng`.
     def add_language(lang)
-      @fields['languages'] = [] if @fields['languages'].empty?
+      require 'language_list'
+      @fields['languages'] = [] if @fields['languages'].nil? || @fields['languages'].empty?
       lang = LanguageList::LanguageInfo.find(lang)
       return if lang.nil?
 
       lang = lang.iso_639_3
-      @fields['languages'] << lang unless @fields['languages'].include? lang
+      @fields['languages'] << lang unless @fields['languages'].include?(lang)
     end
 
     # :call-seq:
@@ -211,51 +198,7 @@ module CFF
     #
     # Return the list of languages associated with this Reference.
     def languages
-      @fields['languages'].empty? ? [] : @fields['languages'].dup
-    end
-
-    # :call-seq:
-    #   date_accessed = date
-    #
-    # Set the `date-accessed` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_accessed=(date)
-      date = Date.parse(date) unless date.is_a?(Date)
-
-      @fields['date-accessed'] = date
-    end
-
-    # :call-seq:
-    #   date_downloaded = date
-    #
-    # Set the `date-downloaded` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_downloaded=(date)
-      date = Date.parse(date) unless date.is_a?(Date)
-
-      @fields['date-downloaded'] = date
-    end
-
-    # :call-seq:
-    #   date_published = date
-    #
-    # Set the `date-published` field. If a non-Date object is passed in it will
-    # be parsed into a Date.
-    def date_published=(date)
-      date = Date.parse(date) unless date.is_a?(Date)
-
-      @fields['date-published'] = date
-    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
+      @fields['languages'].nil? || @fields['languages'].empty? ? [] : @fields['languages'].dup
     end
 
     # Returns the format of this Reference.
@@ -263,7 +206,7 @@ module CFF
     # This method is explicitly defined to override the private format method
     # that all objects seem to have.
     def format # :nodoc:
-      @fields['format']
+      @fields['format'].nil? ? '' : @fields['format']
     end
 
     # Sets the format of this Reference.
@@ -278,7 +221,7 @@ module CFF
     #   status = status
     #
     # Sets the status of this Reference. The status is restricted to a
-    # [defined set of status types](https://github.com/citation-file-format/citation-file-format#status-strings).
+    # [defined set of status types](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreferencestatus).
     def status=(status)
       status = status.downcase
       @fields['status'] = status if REFERENCE_STATUS_TYPES.include?(status)
@@ -288,7 +231,7 @@ module CFF
     #   type = type
     #
     # Sets the type of this Reference. The type is restricted to a
-    # [defined set of reference types](https://github.com/citation-file-format/citation-file-format#reference-types).
+    # [defined set of reference types](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsreferencetype).
     def type=(type)
       type = type.downcase
       @fields['type'] = type if REFERENCE_TYPES.include?(type)
@@ -296,29 +239,27 @@ module CFF
 
     # Override superclass #fields as References contain model parts too.
     def fields # :nodoc:
-      [
-        'authors', 'contact', 'editors', 'editors-series', 'identifiers',
-        'recipients', 'senders', 'translators'
+      %w[
+        authors contact editors editors-series identifiers
+        recipients senders translators
       ].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
 
     private
 
     def build_model(fields) # :nodoc:
-      [
-        'authors', 'contact', 'editors', 'editors-series', 'recipients',
-        'senders', 'translators'
+      %w[
+        authors contact editors editors-series recipients senders translators
       ].each do |field|
-        build_actor_collection!(fields[field]) if fields.include?(field)
+        Util.build_actor_collection!(fields[field]) if fields.include?(field)
       end
 
-      [
-        'conference', 'database-provider', 'institution', 'location',
-        'publisher'
+      %w[
+        conference database-provider institution location publisher
       ].each do |field|
         fields[field] &&= Entity.new(fields[field])
       end
@@ -436,7 +377,7 @@ module CFF
     # the list, use:
     #
     # ```
-    # model.identifiers << identifier
+    # reference.identifiers << identifier
     # ```
 
     ##
@@ -455,7 +396,7 @@ module CFF
     # list, use:
     #
     # ```
-    # model.keywords << keyword
+    # reference.keywords << keyword
     # ```
     #
     # Keywords will be converted to Strings on output.
@@ -478,7 +419,7 @@ module CFF
     # state to the list, use:
     #
     # ```
-    # model.patent_states << patent_state
+    # reference.patent_states << patent_state
     # ```
     #
     # Patent states will be converted to Strings on output.

data/lib/cff/schema.rb

@@ -0,0 +1,23 @@
+# 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 'json'
+
+##
+module CFF
+  SCHEMA_PATH = ::File.join(__dir__, 'schemas', '1.2.0.json') # :nodoc:
+  SCHEMA_FILE = JSON.parse(::File.read(SCHEMA_PATH))          # :nodoc:
+end

data/lib/cff/util.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,17 +14,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require_relative 'entity'
+require_relative 'person'
+require_relative 'version'
+
 require 'rubygems'
 
 ##
 module CFF
-
   # Util provides utility methods useful throughout the rest of the CFF library.
   #
   # Util does not provide any methods or fields for the public API.
   module Util
     # :stopdoc:
 
+    module_function
+
     def update_cff_version(version)
       return '' if version.nil? || version.empty?
 
@@ -35,10 +40,6 @@ module CFF
       end
     end
 
-    def method_to_field(name)
-      name.tr('_', '-')
-    end
-
     def build_actor_collection!(source)
       source.map! do |s|
         s.has_key?('given-names') ? Person.new(s) : Entity.new(s)
@@ -67,6 +68,62 @@ module CFF
       hash
     end
 
+    DEFAULT_CHAR_APPROXIMATIONS = {
+      'À' => 'A', 'Á' => 'A', 'Â' => 'A', 'Ã' => 'A', 'Ä' => 'A', 'Å' => 'A',
+      'Æ' => 'AE', 'Ç' => 'C', 'È' => 'E', 'É' => 'E', 'Ê' => 'E', 'Ë' => 'E',
+      'Ì' => 'I', 'Í' => 'I', 'Î' => 'I', 'Ï' => 'I', 'Ð' => 'D', 'Ñ' => 'N',
+      'Ò' => 'O', 'Ó' => 'O', 'Ô' => 'O', 'Õ' => 'O', 'Ö' => 'O', '×' => 'x',
+      'Ø' => 'O', 'Ù' => 'U', 'Ú' => 'U', 'Û' => 'U', 'Ü' => 'U', 'Ý' => 'Y',
+      'Þ' => 'Th', 'ß' => 'ss', 'à' => 'a', 'á' => 'a', 'â' => 'a',
+      'ã' => 'a', 'ä' => 'a', 'å' => 'a', 'æ' => 'ae', 'ç' => 'c', 'è' => 'e',
+      'é' => 'e', 'ê' => 'e', 'ë' => 'e', 'ì' => 'i', 'í' => 'i', 'î' => 'i',
+      'ï' => 'i', 'ð' => 'd', 'ñ' => 'n', 'ò' => 'o', 'ó' => 'o', 'ô' => 'o',
+      'õ' => 'o', 'ö' => 'o', 'ø' => 'o', 'ù' => 'u', 'ú' => 'u', 'û' => 'u',
+      'ü' => 'u', 'ý' => 'y', 'þ' => 'th', 'ÿ' => 'y', 'Ā' => 'A', 'ā' => 'a',
+      'Ă' => 'A', 'ă' => 'a', 'Ą' => 'A', 'ą' => 'a', 'Ć' => 'C', 'ć' => 'c',
+      'Ĉ' => 'C', 'ĉ' => 'c', 'Ċ' => 'C', 'ċ' => 'c', 'Č' => 'C', 'č' => 'c',
+      'Ď' => 'D', 'ď' => 'd', 'Đ' => 'D', 'đ' => 'd', 'Ē' => 'E', 'ē' => 'e',
+      'Ĕ' => 'E', 'ĕ' => 'e', 'Ė' => 'E', 'ė' => 'e', 'Ę' => 'E', 'ę' => 'e',
+      'Ě' => 'E', 'ě' => 'e', 'ệ' => 'e', 'Ĝ' => 'G', 'ĝ' => 'g', 'Ğ' => 'G',
+      'ğ' => 'g', 'Ġ' => 'G', 'ġ' => 'g', 'Ģ' => 'G', 'ģ' => 'g', 'Ĥ' => 'H',
+      'ĥ' => 'h', 'Ħ' => 'H', 'ħ' => 'h', 'Ĩ' => 'I', 'ĩ' => 'i', 'Ī' => 'I',
+      'ī' => 'i', 'Ĭ' => 'I', 'ĭ' => 'i', 'Į' => 'I', 'į' => 'i', 'İ' => 'I',
+      'ı' => 'i', 'IJ' => 'IJ', 'ij' => 'ij', 'Ĵ' => 'J', 'ĵ' => 'j',
+      'Ķ' => 'K', 'ķ' => 'k', 'ĸ' => 'k', 'Ĺ' => 'L', 'ĺ' => 'l', 'Ļ' => 'L',
+      'ļ' => 'l', 'Ľ' => 'L', 'ľ' => 'l', 'Ŀ' => 'L', 'ŀ' => 'l', 'Ł' => 'L',
+      'ł' => 'l', 'Ń' => 'N', 'ń' => 'n', 'Ņ' => 'N', 'ņ' => 'n', 'Ň' => 'N',
+      'ň' => 'n', 'ʼn' => "'n", 'Ŋ' => 'NG', 'ŋ' => 'ng', 'Ō' => 'O',
+      'ō' => 'o', 'Ŏ' => 'O', 'ŏ' => 'o', 'Ő' => 'O', 'ő' => 'o', 'Œ' => 'OE',
+      'œ' => 'oe', 'Ŕ' => 'R', 'ŕ' => 'r', 'Ŗ' => 'R', 'ŗ' => 'r', 'Ř' => 'R',
+      'ř' => 'r', 'Ś' => 'S', 'ś' => 's', 'Ŝ' => 'S', 'ŝ' => 's', 'Ş' => 'S',
+      'ş' => 's', 'Š' => 'S', 'š' => 's', 'Ţ' => 'T', 'ţ' => 't', 'Ť' => 'T',
+      'ť' => 't', 'Ŧ' => 'T', 'ŧ' => 't', 'Ũ' => 'U', 'ũ' => 'u', 'Ū' => 'U',
+      'ū' => 'u', 'Ŭ' => 'U', 'ŭ' => 'u', 'Ů' => 'U', 'ů' => 'u', 'Ű' => 'U',
+      'ű' => 'u', 'Ų' => 'U', 'ų' => 'u', 'Ŵ' => 'W', 'ŵ' => 'w', 'Ŷ' => 'Y',
+      'ŷ' => 'y', 'Ÿ' => 'Y', 'Ź' => 'Z', 'ź' => 'z', 'Ż' => 'Z', 'ż' => 'z',
+      'Ž' => 'Z', 'ž' => 'z'
+    }.freeze
+
+    def transliterate(string, fallback: '')
+      string.gsub(/[^\x00-\x7f]/u) do |char|
+        DEFAULT_CHAR_APPROXIMATIONS[char] || fallback
+      end
+    end
+
+    def parameterize(string, separator: '_')
+      # Normalize into ASCII.
+      param = transliterate(string)
+
+      # Remove unwanted chars by turning them into the separator.
+      param.gsub!(/[^a-z0-9\-_]+/i, separator)
+
+      # Only one separator at a time.
+      param.gsub!(/#{separator}{2,}/, separator)
+
+      # No leading/trailing separators.
+      param.gsub(/^#{separator}|#{separator}$/i, '')
+    end
+
     # :startdoc:
   end
 end

data/lib/cff/validatable.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,24 +14,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require_relative 'errors'
+require_relative 'schema'
+
 require 'json_schema'
 
 ##
 module CFF
-
   # Methods to validate CFF files/models against a formal schema.
   module Validatable
-
     SCHEMA = JsonSchema.parse!(SCHEMA_FILE) # :nodoc:
 
     # :call-seq:
     #   validate!(fail_fast: false)
     #
-    # Validate a CFF file or model and raise a ValidationError upon failure.
-    # If an error is raised it will contain the detected validation failures
-    # for further inspection. Setting `fail_fast` to true will fail validation
-    # at the first detected failure, rather than gathering and returning all
-    # failures.
+    # Validate a CFF file or model (Index) and raise a ValidationError upon
+    # failure. If an error is raised it will contain the detected validation
+    # failures for further inspection. Setting `fail_fast` to true will fail
+    # validation at the first detected failure, rather than gathering and
+    # returning all failures.
     def validate!(fail_fast: false)
       result = validate(fail_fast: fail_fast)
       return if result[0]
@@ -42,9 +43,9 @@ module CFF
     # :call-seq:
     #   validate(fail_fast: false) -> Array
     #
-    # Validate a CFF file or model 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).
+    # Validate a CFF file or model (Index) 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).
     # Setting `fail_fast` to true will fail validation at the first detected
     # failure, rather than gathering and returning all failures.
     def validate(fail_fast: false)

data/lib/cff/version.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.
@@ -17,7 +17,7 @@
 ##
 module CFF
   # :nodoc:
-  VERSION = '0.9.0'
+  VERSION = '1.0.0'
   DEFAULT_SPEC_VERSION = '1.2.0'
   MIN_VALIDATABLE_VERSION = '1.2.0'
 end

data/lib/cff.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,34 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'date'
-require 'json'
-require 'yaml'
-
-require 'language_list'
-
 # This library provides a Ruby interface to manipulate CITATION.cff files. The
-# primary entry points are Model and File.
+# primary entry points are Index and File.
 #
 # See the [CITATION.cff documentation](https://citation-file-format.github.io/)
 # for more details.
-module CFF
-  SCHEMA_PATH = ::File.join(__dir__, 'schema', '1.2.0.json') # :nodoc:
-  SCHEMA_FILE = JSON.parse(::File.read(SCHEMA_PATH))         # :nodoc:
-end
+module CFF; end
 
-require 'cff/version'
-require 'cff/errors'
-require 'cff/util'
-require 'cff/licensable'
-require 'cff/validatable'
-require 'cff/model_part'
-require 'cff/person'
-require 'cff/entity'
-require 'cff/identifier'
-require 'cff/reference'
-require 'cff/model'
-require 'cff/file'
-require 'cff/formatter/formatter'
-require 'cff/formatter/apa_formatter'
-require 'cff/formatter/bibtex_formatter'
+require_relative 'cff/file'