cff 0.3.0 → 0.4.0

data/lib/cff/{model-part.rb → model_part.rb}

@@ -12,16 +12,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 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('='))
 
@@ -32,6 +37,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

@@ -12,7 +12,7 @@
 # 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
@@ -20,21 +20,9 @@ module CFF
   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', 'city', 'country', 'email', 'family-names',
+      'fax', 'given-names', 'name-particle', 'name-suffix', 'orcid',
+      'post-code', 'region', 'tel', 'website'
     ].freeze # :nodoc:
 
     # :call-seq:
@@ -42,7 +30,7 @@ module CFF
     #
     # Create a new Person with the supplied given and family names.
     def initialize(param, *more)
-      if Hash === param
+      if param.is_a?(Hash)
         @fields = param
       else
         @fields = Hash.new('')
@@ -50,6 +38,5 @@ module CFF
         @fields['given-names'] = param
       end
     end
-
   end
 end

data/lib/cff/reference.rb

@@ -12,7 +12,7 @@
 # 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
@@ -22,262 +22,65 @@ module CFF
   class Reference < ModelPart
 
     ALLOWED_FIELDS = [
-      'abbreviation',
-      'abstract',
-      'collection-doi',
-      'collection-title',
-      'collection-type',
-      'commit',
-      'conference',
-      'copyright',
-      'data-type',
-      'database',
-      'database-provider',
-      'date-accessed',
-      'date-downloaded',
-      'date-published',
-      'date-released',
-      'department',
-      'doi',
-      'edition',
-      'end',
-      'entry',
-      'filename',
-      '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',
-      'repository',
-      'repository-code',
-      'repository-artifact',
-      'scope',
-      'section',
-      'start',
-      'status',
-      'thesis-type',
-      'title',
-      'type',
-      'url',
-      'version',
-      'volume',
-      'volume-title',
-      'year',
+      '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', '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://citation-file-format.github.io/1.0.3/specifications/#/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'
+      '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://citation-file-format.github.io/1.0.3/specifications/#/status-strings).
     REFERENCE_STATUS_TYPES = [
-      'abstract',
-      'advance-online',
-      'in-preparation',
-      'in-press',
-      'pre-print',
-      'submitted'
+      'abstract', 'advance-online', 'in-preparation', 'in-press',
+      'pre-print', 'submitted'
     ].freeze
 
     # :call-seq:
+    #   new(title) -> Reference
     #   new(title, type) -> Reference
     #
-    # Create a new Reference with the supplied title and type. If type is not one of the [defined set of reference types](https://citation-file-format.github.io/1.0.3/specifications/#/reference-types), 'generic' will be used by default.
+    # 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://citation-file-format.github.io/1.0.3/specifications/#/reference-types),
+    # 'generic' will be used by default.
     def initialize(param, *more)
-      @authors = []
-      @contact = []
-      @editors = []
-      @editors_series = []
-      @recipients = []
-      @senders = []
-      @translators = []
-
-      if Hash === param
-        build_model(param)
+      if param.is_a?(Hash)
+        @fields = build_model(param)
       else
         @fields = Hash.new('')
-        type = more[0].downcase
+        type = more[0] &&= more[0].downcase
         @fields['type'] = REFERENCE_TYPES.include?(type) ? type : 'generic'
         @fields['title'] = param
       end
 
       [
-        'keywords',
-        'patent-states'
+        'authors', 'contact', 'editors', 'editors-series', 'keywords',
+        'patent-states', 'recipients', 'senders', 'translators'
       ].each { |field| @fields[field] = [] if @fields[field].empty? }
     end
 
-    # :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.
-    def authors
-      @authors
-    end
-
-    # :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.
-    def contact
-      @contact
-    end
-
-    # :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.
-    def editors
-      @editors
-    end
-
-    # :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.
-    def editors_series
-      @editors_series
-    end
-
-    # :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.
-    def recipients
-      @recipients
-    end
-
-    # :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.
-    def senders
-      @senders
-    end
-
-    # :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.
-    def translators
-      @translators
-    end
-
     # :call-seq:
     #   add_language language
     #
@@ -325,9 +128,7 @@ module CFF
     # Set the `date-accessed` field. If a non-Date object is passed in it will
     # be parsed into a Date.
     def date_accessed=(date)
-      unless Date === date
-        date = Date.parse(date)
-      end
+      date = Date.parse(date) unless date.is_a?(Date)
 
       @fields['date-accessed'] = date
     end
@@ -338,9 +139,7 @@ module CFF
     # Set the `date-downloaded` field. If a non-Date object is passed in it will
     # be parsed into a Date.
     def date_downloaded=(date)
-      unless Date === date
-        date = Date.parse(date)
-      end
+      date = Date.parse(date) unless date.is_a?(Date)
 
       @fields['date-downloaded'] = date
     end
@@ -351,9 +150,7 @@ module CFF
     # Set the `date-published` field. If a non-Date object is passed in it will
     # be parsed into a Date.
     def date_published=(date)
-      unless Date === date
-        date = Date.parse(date)
-      end
+      date = Date.parse(date) unless date.is_a?(Date)
 
       @fields['date-published'] = date
     end
@@ -364,9 +161,7 @@ module CFF
     # 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
+      date = Date.parse(date) unless date.is_a?(Date)
 
       @fields['date-released'] = date
     end
@@ -409,43 +204,27 @@ module CFF
 
     # Override superclass #fields as References contain model parts too.
     def fields # :nodoc:
-      ref = {}
-
-      @fields.each do |field, value|
-        if value.respond_to?(:map)
-          ref[field] = value.map { |v| v.to_s } unless value.empty?
-        else
-          ref[field] = value.respond_to?(:fields) ? value.fields : value
-        end
-      end
-
       [
-        ['authors', @authors],
-        ['contact', @contact],
-        ['editors', @editors],
-        ['editors-series', @editors_series],
-        ['recipients', @recipients],
-        ['senders', @senders],
-        ['translators', @translators]
-      ].each do |field, var|
-        ref[field] = expand_array_field(var) unless var.empty?
+        'authors', 'contact', 'editors', 'editors-series', 'recipients',
+        'senders', 'translators'
+      ].each do |field|
+        normalize_modelpart_array!(@fields[field])
       end
 
-      ref
+      fields_to_hash(@fields)
     end
 
     private
 
-    def build_model(fields)
-      build_actor_collection(@authors, fields['authors'])
-      build_actor_collection(@contact, fields['contact'])
-      build_actor_collection(@editors, fields['editors'])
-      build_actor_collection(@editors_series, fields['editors-series'])
-      build_actor_collection(@recipients, fields['recipients'])
-      build_actor_collection(@senders, fields['senders'])
-      build_actor_collection(@translators, fields['translators'])
+    def build_model(fields) # :nodoc:
+      [
+        'authors', 'contact', 'editors', 'editors-series', 'recipients',
+        'senders', 'translators'
+      ].each do |field|
+        build_actor_collection!(fields[field])
+      end
 
-      @fields = delete_from_hash(fields, 'authors', 'contact', 'editors', 'editors-series', 'recipients', 'senders', 'translators')
+      fields
     end
 
     public
@@ -453,6 +232,98 @@ module CFF
     # 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: keywords
     # :call-seq:
@@ -498,5 +369,74 @@ module CFF
     # 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