cff 0.2.0 → 0.9.0

data/lib/cff/{model-part.rb → 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.
@@ -12,20 +14,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#
+##
 module CFF
 
-  # :stopdoc:
+  # ModelPart is the superclass of anything that makes up part of the CFF Model.
+  # This includes Model, Person, Entity and Reference.
+  #
+  # ModelPart does not provide any methods or fields for the public API.
   class ModelPart
+
+    # :stopdoc:
     include Util
 
     attr_reader :fields
 
-    def initialize(fields)
-      @fields = fields
-    end
-
-    def method_missing(name, *args) # :nodoc:
+    def method_missing(name, *args)
       n = method_to_field(name.id2name)
       super unless self.class::ALLOWED_FIELDS.include?(n.chomp('='))
 
@@ -36,6 +39,11 @@ module CFF
       end
     end
 
+    def respond_to_missing?(name, *)
+      n = method_to_field(name.id2name)
+      self.class::ALLOWED_FIELDS.include?(n.chomp('=')) || super
+    end
+
+    # :startdoc:
   end
-  # :startdoc:
 end

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.
@@ -12,44 +14,63 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#
+##
 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)
-      if Hash === param
-        super(param)
+    # 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
-    end
 
+      yield self if block_given?
+    end
   end
 end

data/lib/cff/reference.rb

@@ -0,0 +1,564 @@
+# 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
+
+  # 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
+  # the software version, etc.
+  #
+  # Reference implements all of the fields listed in the
+  # [CFF standard](https://citation-file-format.github.io/). Complex
+  # fields - `authors`, `contact`, `editors`, `editors_series`, `identifiers`,
+  # `keywords`, `languages`, `patent_states`, `recipients`, `senders` and
+  # `translators` - 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):
+  #
+  # * `abbreviation`
+  # * `abstract`
+  # * `collection_doi`
+  # * `collection_title`
+  # * `collection_type`
+  # * `commit`
+  # * `conference`
+  # * `copyright`
+  # * `data-type`
+  # * `database`
+  # * `database_provider`
+  # * `date_accessed` - *Note:* returns a `Date` object
+  # * `date_downloaded` - *Note:* returns a `Date` object
+  # * `date_published` - *Note:* returns a `Date` object
+  # * `date_released` - *Note:* returns a `Date` object
+  # * `department`
+  # * `doi`
+  # * `edition`
+  # * `end`
+  # * `entry`
+  # * `filename`
+  # * `format`
+  # * `institution`
+  # * `isbn`
+  # * `issn`
+  # * `issue`
+  # * `issue_date` - *Note:* returns a `Date` object
+  # * `issue_title`
+  # * `journal`
+  # * `license` - *Note:* see documentation for `license =` below
+  # * `license_url`
+  # * `loc_end`
+  # * `loc_start`
+  # * `location`
+  # * `medium`
+  # * `month`
+  # * `nihmsid`
+  # * `notes`
+  # * `number`
+  # * `number_volumes`
+  # * `pages`
+  # * `pmcid`
+  # * `publisher`
+  # * `repository`
+  # * `repository_code`
+  # * `repository_artifact`
+  # * `scope`
+  # * `section`
+  # * `start`
+  # * `status` - *Note:* see documentation for `status =` below
+  # * `thesis_type`
+  # * `title`
+  # * `type` - *Note:* see documentation for `type =` below
+  # * `url`
+  # * `version`
+  # * `volume`
+  # * `volume_title`
+  # * `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
+
+    # :call-seq:
+    #   new(title) -> Reference
+    #   new(title) { |ref| block } -> Reference
+    #   new(title, type) -> Reference
+    #   new(title, type) { |ref| block } -> Reference
+    #
+    # 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),
+    # 'generic' will be used by default.
+    def initialize(param, *more) # rubocop:disable Metrics/AbcSize
+      if param.is_a?(Hash)
+        @fields = build_model(param)
+        @fields.default = ''
+      else
+        @fields = Hash.new('')
+        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'
+      ].each do |field|
+        @fields[field] = [] if @fields[field].empty?
+      end
+
+      yield self if block_given?
+    end
+
+    # :call-seq:
+    #   from_cff(File, type: 'software') -> Reference
+    #   from_cff(Model, type: 'software') -> Reference
+    #
+    # Create a Reference from another CFF File or Model. This is useful for
+    # easily adding a reference to something with its own CITATION.cff file
+    # already.
+    #
+    # This method assumes that the type of the Reference should be `software`,
+    # but this can be overridden with the `type` parameter.
+    def self.from_cff(model, type: 'software')
+      new(model.title, type) do |ref|
+        %w[
+          abstract authors contact commit date_released doi
+          identifiers keywords license license_url repository
+          repository_artifact repository_code url version
+        ].each do |field|
+          value = model.send(field)
+          ref.send("#{field}=", value.dup) unless value == ''
+        end
+      end
+    end
+
+    # :call-seq:
+    #   add_language language
+    #
+    # Add a language to this Reference. Input is converted to the ISO 639-3
+    # 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?
+      lang = LanguageList::LanguageInfo.find(lang)
+      return if lang.nil?
+
+      lang = lang.iso_639_3
+      @fields['languages'] << lang unless @fields['languages'].include? lang
+    end
+
+    # :call-seq:
+    #   reset_languages
+    #
+    # Reset the list of languages for this Reference to be empty.
+    def reset_languages
+      @fields.delete('languages')
+    end
+
+    # :call-seq:
+    #   languages -> Array
+    #
+    # 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
+    end
+
+    # Returns the format of this Reference.
+    #
+    # This method is explicitly defined to override the private format method
+    # that all objects seem to have.
+    def format # :nodoc:
+      @fields['format']
+    end
+
+    # Sets the format of this Reference.
+    #
+    # This method is explicitly defined to override the private format method
+    # that all objects seem to have.
+    def format=(fmt) # :nodoc:
+      @fields['format'] = fmt
+    end
+
+    # :call-seq:
+    #   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).
+    def status=(status)
+      status = status.downcase
+      @fields['status'] = status if REFERENCE_STATUS_TYPES.include?(status)
+    end
+
+    # :call-seq:
+    #   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).
+    def type=(type)
+      type = type.downcase
+      @fields['type'] = type if REFERENCE_TYPES.include?(type)
+    end
+
+    # Override superclass #fields as References contain model parts too.
+    def fields # :nodoc:
+      [
+        'authors', 'contact', 'editors', 'editors-series', 'identifiers',
+        'recipients', 'senders', 'translators'
+      ].each do |field|
+        normalize_modelpart_array!(@fields[field])
+      end
+
+      fields_to_hash(@fields)
+    end
+
+    private
+
+    def build_model(fields) # :nodoc:
+      [
+        'authors', 'contact', 'editors', 'editors-series', 'recipients',
+        'senders', 'translators'
+      ].each do |field|
+        build_actor_collection!(fields[field]) if fields.include?(field)
+      end
+
+      [
+        'conference', 'database-provider', 'institution', 'location',
+        'publisher'
+      ].each do |field|
+        fields[field] &&= Entity.new(fields[field])
+      end
+
+      (fields['identifiers'] || []).map! do |i|
+        Identifier.new(i)
+      end
+
+      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
+    #
+    # Return the list of authors for this Reference. To add an author to the
+    # list, use:
+    #
+    # ```
+    # reference.authors << author
+    # ```
+    #
+    # Authors can be a Person or Entity.
+
+    ##
+    # :method: authors=
+    # :call-seq:
+    #   authors = array_of_authors -> Array
+    #
+    # Replace the list of authors for this reference.
+    #
+    # Authors can be a Person or Entity.
+
+    ##
+    # :method: contact
+    # :call-seq:
+    #   contact -> Array
+    #
+    # Return the list of contacts for this Reference. To add a contact to the
+    # list, use:
+    #
+    # ```
+    # reference.contact << contact
+    # ```
+    #
+    # Contacts can be a Person or Entity.
+
+    ##
+    # :method: contact=
+    # :call-seq:
+    #   contact = array_of_contacts -> Array
+    #
+    # Replace the list of contacts for this reference.
+    #
+    # Contacts can be a Person or Entity.
+
+    ##
+    # :method: editors
+    # :call-seq:
+    #   editors -> Array
+    #
+    # Return the list of editors for this Reference. To add an editor to the
+    # list, use:
+    #
+    # ```
+    # reference.editors << editor
+    # ```
+    #
+    # An editor can be a Person or Entity.
+
+    ##
+    # :method: editors=
+    # :call-seq:
+    #   editors = array_of_editors -> Array
+    #
+    # Replace the list of editors for this reference.
+    #
+    # Editors can be a Person or Entity.
+
+    ##
+    # :method: editors_series
+    # :call-seq:
+    #   editors_series -> Array
+    #
+    # Return the list of series editors for this Reference. To add a series
+    # editor to the list, use:
+    #
+    # ```
+    # reference.editors_series << editor
+    # ```
+    #
+    # An editor can be a Person or Entity.
+
+    ##
+    # :method: editors_series=
+    # :call-seq:
+    #   editors_series = array_of_series_editors -> Array
+    #
+    # Replace the list of series editors for this reference.
+    #
+    # Series editors 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:
+    #   keywords -> Array
+    #
+    # Return the list of keywords for this reference. To add a keyword to the
+    # list, use:
+    #
+    # ```
+    # model.keywords << keyword
+    # ```
+    #
+    # Keywords will be converted to Strings on output.
+
+    ##
+    # :method: keywords=
+    # :call-seq:
+    #   keywords = array_of_keywords -> Array
+    #
+    # Replace the list of keywords for this reference.
+    #
+    # Keywords will be converted to Strings on output.
+
+    ##
+    # :method: patent_states
+    # :call-seq:
+    #   patent_states -> Array
+    #
+    # Return the list of patent states for this reference. To add a patent
+    # state to the list, use:
+    #
+    # ```
+    # model.patent_states << patent_state
+    # ```
+    #
+    # Patent states will be converted to Strings on output.
+
+    ##
+    # :method: patent_states=
+    # :call-seq:
+    #   patent_states = array_of_states -> Array
+    #
+    # Replace the list of patent states for this reference.
+    #
+    # Patent states will be converted to Strings on output.
+
+    ##
+    # :method: recipients
+    # :call-seq:
+    #   recipients -> Array
+    #
+    # Return the list of recipients for this Reference. To add a recipient
+    # to the list, use:
+    #
+    # ```
+    # reference.recipients << recipient
+    # ```
+    #
+    # Recipients can be a Person or Entity.
+
+    ##
+    # :method: recipients=
+    # :call-seq:
+    #   recipients = array_of_recipients -> Array
+    #
+    # Replace the list of recipients for this reference.
+    #
+    # Recipients can be a Person or Entity.
+
+    ##
+    # :method: senders
+    # :call-seq:
+    #   senders -> Array
+    #
+    # Return the list of senders for this Reference. To add a sender to the
+    # list, use:
+    #
+    # ```
+    # reference.senders << sender
+    # ```
+    #
+    # Senders can be a Person or Entity.
+
+    ##
+    # :method: senders=
+    # :call-seq:
+    #   senders = array_of_senders -> Array
+    #
+    # Replace the list of senders for this reference.
+    #
+    # Senders can be a Person or Entity.
+
+    ##
+    # :method: translators
+    # :call-seq:
+    #   translators -> Array
+    #
+    # Return the list of translators for this Reference. To add a translator
+    # to the list, use:
+    #
+    # ```
+    # reference.translators << translator
+    # ```
+    #
+    # Translators can be a Person or Entity.
+
+    ##
+    # :method: translators=
+    # :call-seq:
+    #   translators = array_of_translators -> Array
+    #
+    # Replace the list of translators for this reference.
+    #
+    # Translators can be a Person or Entity.
+  end
+end