cff 0.2.0 → 0.9.0

data/Rakefile

@@ -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,22 +14,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "bundler/gem_tasks"
-require "rake/testtask"
-require "rdoc/task"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'rubocop/rake_task'
 
-task :default => :test
+task default: :test
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
 RDoc::Task.new do |r|
-  r.main = "README.md"
-  r.rdoc_files.include("README.md", "LICENCE", "lib/**/*.rb")
-  r.options << "--markup=markdown"
-  r.options << "--tab-width=2"
+  r.main = 'README.md'
+  r.rdoc_files.include('README.md', 'LICENCE', 'CHANGES.md', 'lib/**/*.rb')
+  r.options << '--markup=markdown'
+  r.options << '--tab-width=2'
   r.options << "-t Ruby CFF Library version #{::CFF::VERSION}"
 end
+
+RuboCop::RakeTask.new

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "cff"
+require 'bundler/setup'
+require 'cff'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "cff"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/cff.gemspec

@@ -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,34 +14,51 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "cff/version"
+require_relative 'lib/cff/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "cff"
+  spec.name          = 'cff'
   spec.version       = CFF::VERSION
-  spec.authors       = ["Robert Haines"]
-  spec.email         = ["robert.haines@manchester.ac.uk"]
+  spec.authors       = [
+    'Robert Haines',
+    'The Ruby Citation File Format Developers'
+  ]
+  spec.email         = ['robert.haines@manchester.ac.uk']
+
+  spec.summary       = 'A Ruby library for manipulating CITATION.cff files.'
+  spec.description   = 'See https://citation-file-format.github.io/ ' \
+                       'for more info.'
+  spec.homepage      = 'https://github.com/citation-file-format/ruby-cff'
+  spec.license       = 'Apache-2.0'
 
-  spec.summary       = "A Ruby library for manipulating CITATION.cff files."
-  spec.description   = "See https://citation-file-format.github.io/ for more info."
-  spec.homepage      = "https://github.com/hainesr/ruby-cff"
-  spec.license       = "Apache-2.0"
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/citation-file-format/ruby-cff/issues',
+    'changelog_uri' => 'https://github.com/citation-file-format/ruby-cff/blob/main/CHANGES.md',
+    'documentation_uri' => 'https://citation-file-format.github.io/ruby-cff/',
+    'source_code_uri' => 'https://github.com/citation-file-format/ruby-cff'
+  }
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^((test|spec|features)/|\.)})
   end
-  spec.bindir        = "exe"
+
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.6'
 
-  spec.required_ruby_version = ">= 2.2.0"
+  spec.add_runtime_dependency 'json_schema', '~> 0.20.0'
+  spec.add_runtime_dependency 'language_list', '~> 1.2'
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "coveralls", "~> 0.8"
-  spec.add_development_dependency "test_construct", "~> 2.0"
-  spec.add_development_dependency "rdoc", "~> 6.0"
+  spec.add_development_dependency 'minitest', '~> 5.14'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rdoc', '~> 6.3'
+  spec.add_development_dependency 'rubocop', '~> 1.15'
+  spec.add_development_dependency 'rubocop-minitest', '~> 0.13'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.11.0'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.5.0'
+  spec.add_development_dependency 'simplecov', '~> 0.20.0'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8.0'
+  spec.add_development_dependency 'test_construct', '~> 2.0'
 end

data/lib/cff.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,16 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "date"
-require "yaml"
+require 'date'
+require 'json'
+require 'yaml'
 
-require "cff/version"
-require "cff/util"
-require "cff/model-part"
-require "cff/person"
-require "cff/entity"
-require "cff/model"
-require "cff/file"
+require 'language_list'
 
 # This library provides a Ruby interface to manipulate CITATION.cff files. The
 # primary entry points are Model and File.
@@ -29,5 +26,22 @@ require "cff/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
+
+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'

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.
@@ -12,42 +14,55 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#
+##
 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 = [
-      'address',
-      'city',
-      'country',
-      'email',
-      'date-end',
-      'date-start',
-      'fax',
-      'location',
-      'name',
-      'orcid',
-      'post-code',
-      'region',
-      'tel',
-      'website'
+      'address', 'city', 'country', 'email', 'date-end', 'date-start', 'fax',
+      'location', 'name', 'orcid', 'post-code', 'region', 'tel', 'website'
     ].freeze # :nodoc:
 
     # :call-seq:
     #   new(name) -> Entity
+    #   new(name) { |entity| block } -> Entity
     #
     # Create a new Entity with the supplied name.
     def initialize(param)
-      if Hash === param
-        super(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:
@@ -56,9 +71,7 @@ module CFF
     # Set the `date-end` field. If a non-Date object is passed in it will
     # be parsed into a Date.
     def date_end=(date)
-      unless Date === date
-        date = Date.parse(date)
-      end
+      date = Date.parse(date) unless date.is_a?(Date)
 
       @fields['date-end'] = date
     end
@@ -69,12 +82,9 @@ module CFF
     # Set the `date-start` field. If a non-Date object is passed in it will
     # be parsed into a Date.
     def date_start=(date)
-      unless Date === date
-        date = Date.parse(date)
-      end
+      date = Date.parse(date) unless date.is_a?(Date)
 
       @fields['date-start'] = date
     end
-
   end
 end

data/lib/cff/errors.rb

@@ -0,0 +1,53 @@
+# 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 validation. It contains
+  # details of each failure that was detected by the underlying JsonSchema
+  # library, which is used to perform the validation.
+  #
+  # Additionally, the `invalid_filename` flag is used to indicate whether the
+  # CFF file is named correctly. This is only used when validating a File;
+  # validating a Model directly will not set this flag to `true`.
+  class ValidationError < Error
+
+    # The list of JsonSchema::ValidationErrors found by the validator.
+    attr_reader :errors
+
+    # If a File was validated, was its filename invalid?
+    attr_reader :invalid_filename
+
+    def initialize(errors, invalid_filename: false) # :nodoc:
+      super('Validation error')
+      @errors = errors
+      @invalid_filename = invalid_filename
+    end
+
+    def to_s # :nodoc:
+      "#{super}: (Invalid filename: #{@invalid_filename}) #{@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.
@@ -12,56 +14,245 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#
+##
 module CFF
 
   # File provides direct access to a CFF Model, with the addition of some
   # filesystem utilities.
+  #
+  # To be a fully compliant and valid CFF file its filename should be
+  # 'CITATION.cff'. This class allows you to create files with any filename,
+  # and to validate the contents of those files independently of the preferred
+  # filename.
   class File
 
+    # 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:
+    CFF_VALID_FILENAME = 'CITATION.cff' # :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)
-      unless Model === param
-        param = Model.new(param)
-      end
+    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:
-    #   read(file) -> File
+    #   read(filename) -> File
     #
     # 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:
-    #   write(file, model)
-    #   write(file, yaml)
+    #   open(filename) -> File
+    #   open(filename) { |cff| block }
     #
-    # Write the supplied model or yaml string to `file`.
-    def self.write(file, cff)
-      unless String === cff
-        cff = cff.to_yaml
+    # 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
 
-      ::File.write(file, cff[YAML_HEADER.length...-1])
+    # :call-seq:
+    #   validate(filename, fail_on_filename: true) -> Array
+    #
+    # Read a file and return an array with the result. The result array is a
+    # three-element array, with `true`/`false` at index 0 to indicate
+    # pass/fail, an array of schema validation errors at index 1 (if any), and
+    # `true`/`false` at index 2 to indicate whether the filename passed/failed
+    # validation.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def self.validate(file, fail_on_filename: true)
+      File.read(file).validate(fail_on_filename: fail_on_filename)
+    end
+
+    # :call-seq:
+    #   validate!(filename, fail_on_filename: true)
+    #
+    # Read a file and raise a ValidationError upon failure. If an error is
+    # raised it will contain the detected validation failures for further
+    # inspection.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def self.validate!(file, fail_on_filename: true)
+      File.read(file).validate!(fail_on_filename: fail_on_filename)
+    end
+
+    # :call-seq:
+    #   write(filename, File)
+    #   write(filename, Model)
+    #   write(filename, yaml)
+    #
+    # Write the supplied File, Model or yaml string to `file`.
+    def self.write(file, cff, comment = '')
+      comment = cff.comment if cff.respond_to?(: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
+
+    # :call-seq:
+    #   validate(fail_fast: false, fail_on_filename: true) -> Array
+    #
+    # Validate this file and return an array with the result. The result array
+    # is a three-element array, with `true`/`false` at index 0 to indicate
+    # pass/fail, an array of schema validation errors at index 1 (if any), and
+    # `true`/`false` at index 2 to indicate whether the filename passed/failed
+    # validation.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def validate(fail_fast: false, fail_on_filename: true)
+      valid_filename = (::File.basename(@filename) == CFF_VALID_FILENAME)
+      result = (@model.validate(fail_fast: fail_fast) << valid_filename)
+      result[0] &&= valid_filename if fail_on_filename
+
+      result
+    end
+
+    # :call-seq:
+    #   validate!(fail_fast: false, fail_on_filename: true)
+    #
+    # Validate this file and raise a ValidationError upon failure. If an error
+    # is raised it will contain the detected validation failures for further
+    # inspection.
+    #
+    # You can choose whether filename validation failure should cause overall
+    # validation failure with the `fail_on_filename` parameter (default: true).
+    def validate!(fail_fast: false, fail_on_filename: true)
+      result = validate(
+        fail_fast: fail_fast, fail_on_filename: fail_on_filename
+      )
+      return if result[0]
+
+      raise ValidationError.new(result[1], invalid_filename: !result[2])
+    end
+
+    # :call-seq:
+    #   write(save_as: filename)
+    #
+    # Write this CFF File. The `save_as` parameter can be used to save a new
+    # copy of this CFF File under a different filename, leaving the original
+    # file untouched. If `save_as` is used then the internal filename of the
+    # File will be updated to the supplied filename.
+    def write(save_as: nil)
+      unless save_as.nil?
+        @filename = save_as
+        @dirty = true
+      end
+
+      File.write(@filename, @model, @comment) if @dirty
+      @dirty = false
+    end
+
+    # :call-seq:
+    #   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;
+    #
+    # 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 to_yaml # :nodoc:
+      @model.to_yaml
     end
 
     def method_missing(name, *args) # :nodoc:
-      @model.send name, *args
+      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