cff 0.4.0 → 0.8.0

data/lib/cff/entity.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.
@@ -18,6 +20,27 @@ module CFF
   # An Entity can represent different types of entities, e.g., a publishing
   # company, or conference. Like a Person, an Entity might have a number of
   # roles, such as author, contact, editor, etc.
+  #
+  # Entity 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`
+  # * `city`
+  # * `country`
+  # * `email`
+  # * `date_end` - *Note:* returns a `Date` object
+  # * `date_start` - *Note:* returns a `Date` object
+  # * `fax`
+  # * `location`
+  # * `name`
+  # * `orcid`
+  # * `post_code`
+  # * `region`
+  # * `tel`
+  # * `website`
   class Entity < ModelPart
 
     ALLOWED_FIELDS = [
@@ -27,15 +50,19 @@ module CFF
 
     # :call-seq:
     #   new(name) -> Entity
+    #   new(name) { |entity| block } -> Entity
     #
     # Create a new Entity with the supplied name.
     def initialize(param)
       if param.is_a?(Hash)
         @fields = param
+        @fields.default = ''
       else
         @fields = Hash.new('')
         @fields['name'] = param
       end
+
+      yield self if block_given?
     end
 
     # :call-seq:

data/lib/cff/errors.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
+
+  # Error is the base class for all errors raised by this library.
+  class Error < RuntimeError
+
+    def initialize(message = nil) # :nodoc:
+      super
+    end
+  end
+
+  # ValidationError is raised when a CFF file fails validatedation. It
+  # contains details of each failure that was detected by the underlying
+  # JsonSchema library, which is used to perform the validation.
+  class ValidationError < Error
+
+    # The list of JsonSchema::ValidationErrors found by the validator.
+    attr_reader :errors
+
+    def initialize(errors) # :nodoc:
+      super('Validation error')
+      @errors = errors
+    end
+
+    def to_s # :nodoc:
+      "#{super}: #{@errors.join(' ')}"
+    end
+  end
+end

data/lib/cff/file.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.
@@ -19,21 +21,35 @@ module CFF
   # filesystem utilities.
   class File
 
-    YAML_HEADER = "---\n".freeze # :nodoc:
+    # A comment to be inserted at the top of the resultant CFF file.
+    attr_reader :comment
+
+    # The filename of this CFF file.
+    attr_reader :filename
+
+    YAML_HEADER = "---\n" # :nodoc:
+    CFF_COMMENT = [
+      "This CITATION.cff file was created by ruby-cff (v #{CFF::VERSION}).",
+      'Gem: https://rubygems.org/gems/cff',
+      'CFF: https://citation-file-format.github.io/'
+    ].freeze # :nodoc:
 
     # :call-seq:
-    #   new(title) -> File
-    #   new(model) -> File
+    #   new(filename, title) -> File
+    #   new(filename, model) -> File
     #
     # Create a new File. Either a pre-existing Model can be passed in or, as
     # with Model itself, a title can be supplied to initalize a new File.
     #
     # All methods provided by Model are also available directly on File
     # objects.
-    def initialize(param)
+    def initialize(filename, param, comment = CFF_COMMENT, create: false)
       param = Model.new(param) unless param.is_a?(Model)
 
+      @filename = filename
       @model = param
+      @comment = comment
+      @dirty = create
     end
 
     # :call-seq:
@@ -41,7 +57,63 @@ module CFF
     #
     # Read a file and parse it for subsequent manipulation.
     def self.read(file)
-      new(YAML.load_file(file))
+      content = ::File.read(file)
+      comment = File.parse_comment(content)
+
+      new(
+        file, YAML.safe_load(content, permitted_classes: [Date, Time]), comment
+      )
+    end
+
+    # :call-seq:
+    #   open(file) -> File
+    #   open(file) {|cff| block }
+    #
+    # With no associated block, File.open is a synonym for ::read. If the
+    # optional code block is given, it will be passed the opened file as an
+    # argument and the File object will automatically be written (if edited)
+    # and closed when the block terminates.
+    #
+    # File.open will create a new file if one does not already exist with the
+    # provided file name.
+    def self.open(file)
+      if ::File.exist?(file)
+        content = ::File.read(file)
+        comment = File.parse_comment(content)
+        yaml = YAML.safe_load(content, permitted_classes: [Date, Time])
+      else
+        comment = CFF_COMMENT
+        yaml = ''
+      end
+
+      cff = new(file, yaml, comment, create: (yaml == ''))
+      return cff unless block_given?
+
+      begin
+        yield cff
+      ensure
+        cff.write
+      end
+    end
+
+    # :call-seq:
+    #   validate(file) -> Array
+    #
+    # Read a file 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).
+    def self.validate(file)
+      File.read(file).validate
+    end
+
+    # :call-seq:
+    #   validate!(file)
+    #
+    # Read a file and raise a ValidationError upon failure. If an error is
+    # raised it will contain the detected validation failures for further
+    # inspection.
+    def self.validate!(file)
+      File.read(file).validate!
     end
 
     # :call-seq:
@@ -49,26 +121,73 @@ module CFF
     #   write(file, yaml)
     #
     # Write the supplied model or yaml string to `file`.
-    def self.write(file, cff)
+    def self.write(file, cff, comment = '')
       cff = cff.to_yaml unless cff.is_a?(String)
+      content = File.format_comment(comment) + cff[YAML_HEADER.length...-1]
+
+      ::File.write(file, content)
+    end
 
-      ::File.write(file, cff[YAML_HEADER.length...-1])
+    # :call-seq:
+    #   write
+    #
+    # Write this CFF File.
+    def write
+      File.write(@filename, @model, @comment) if @dirty
+      @dirty = false
     end
 
     # :call-seq:
-    #   write(file)
+    #   comment = string or array
+    #
+    # A comment to be inserted at the top of the resultant CFF file. This can
+    # be supplied as a simple string or an array of strings. When the file is
+    # saved this comment is formatted as follows:
+    #
+    # * a simple string is split into 75 character lines and `'# '` is prepended
+    # to each line;
+    # * an array of strings is joined into a single string with `'\n'` and
+    # `'# '` is prepended to each line;
     #
-    # Write this CFF File to `file`.
-    def write(file)
-      File.write(file, @model)
+    # If you care about formatting, use an array of strings for your comment,
+    # if not, use a single string.
+    def comment=(comment)
+      @dirty = true
+      @comment = comment
     end
 
     def method_missing(name, *args) # :nodoc:
-      @model.respond_to?(name) ? @model.send(name, *args) : super
+      if @model.respond_to?(name)
+        @dirty = true if name.to_s.end_with?('=') # Remove to_s when Ruby >2.6.
+        @model.send(name, *args)
+      else
+        super
+      end
     end
 
     def respond_to_missing?(name, *all) # :nodoc:
       @model.respond_to?(name, *all)
     end
+
+    def self.format_comment(comment) # :nodoc:
+      return '' if comment.empty?
+
+      comment = comment.scan(/.{1,75}/) if comment.is_a?(String)
+      c = comment.map do |l|
+        l.empty? ? '#' : "# #{l}"
+      end.join("\n")
+
+      "#{c}\n\n"
+    end
+
+    def self.parse_comment(content) # :nodoc:
+      content = content.split("\n")
+
+      content.reduce([]) do |acc, line|
+        break acc unless line.start_with?('#')
+
+        acc << line.sub(/^#+/, '').strip
+      end
+    end
   end
 end

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)
+
+      vol = "#{model.volume}(#{model.issue})" unless model.volume.to_s.empty?
+
+      [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