zizia 1.0.1

data/lib/zizia/parser.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Zizia
+  ##
+  # A generic parser.
+  #
+  # `Parser` implementations provide a stream of `InputRecord`s, derived from an
+  # input object (`file`), through `Parser#records`. This method should be
+  # implemented efficiently for repeated access, generating records lazily if
+  # possible, and caching if appropriate.
+  #
+  # Input validation is handled by an array of `#validators`, which are run in
+  # sequence when `#validate` (or `#validate!`) is called. Errors caught in
+  # validation are accessible via `#errors`, and inputs generating errors result
+  # in `#valid? # => false`.
+  #
+  # A factory method `.for` is provided, and each implementation should
+  # provides a `.match?(**)` which returns `true` if the options passed
+  # indicate the parser can handle the given input. Parsers are checked for
+  # `#match?` in the reverse of load order (i.e. the most recently loaded
+  # `Parser` classes are given precedence).
+  #
+  # @example Getting a parser for a file input
+  #   file = File.open('path/to/import/manifest.csv')
+  #
+  #   Parser.for(file: file).records
+  #
+  # @example Validating a parser
+  #   parser = Parser.for(file: invalid_input)
+  #
+  #   parser.valid?   # => true (always true before validation)
+  #   parser.validate # => false
+  #   parser.valid?   # => false
+  #   parser.errors   # => an array of Validation::Error-like structs
+  #
+  #   parser.validate! # ValidationError
+  #
+  # rubocop:disable Style/ClassVars
+  class Parser
+    DEFAULT_VALIDATORS = [].freeze
+    @@subclasses = [] # @private
+
+    ##
+    # @!attribute [rw] file
+    #   @return [File]
+    # @!attribute [rw] validators
+    #   @return [Array<Validator>]
+    # @!attribute [r] errors
+    #   @return [Array]
+    attr_accessor :file, :validators
+    attr_reader   :errors
+
+    ##
+    # @param file [File]
+    def initialize(file:, **_opts)
+      self.file     = file
+      @errors       = []
+      @validators ||= self.class::DEFAULT_VALIDATORS
+
+      yield self if block_given?
+    end
+
+    class << self
+      ##
+      # @param file [Object]
+      #
+      # @return [Zizia::Parser] a parser instance appropriate for
+      #   the arguments
+      #
+      # @raise [NoParserError]
+      def for(file:)
+        klass =
+          @@subclasses.find { |k| k.match?(file: file) } ||
+          raise(NoParserError)
+
+        klass.new(file: file)
+      end
+
+      ##
+      # @abstract
+      # @return [Boolean]
+      def match?(**_opts); end
+
+      private
+
+      ##
+      # @private Register a new class when inherited
+      def inherited(subclass)
+        @@subclasses.unshift subclass
+        super
+      end
+    end
+
+    ##
+    # @abstract
+    #
+    # @yield [record] gives each record in the file to the block
+    # @yieldparam record [ImportRecord]
+    #
+    # @return [Enumerable<ImportRecord>]
+    def records
+      raise NotImplementedError
+    end
+
+    ##
+    # @return [Boolean] true if the file input is valid
+    def valid?
+      errors.empty?
+    end
+
+    ##
+    # @return [Boolean] true if the file input is valid
+    def validate
+      validators.each_with_object(errors) do |validator, errs|
+        errs.concat(validator.validate(parser: self))
+      end
+
+      valid?
+    end
+
+    ##
+    # @return [true] always true, unless an error is raised.
+    #
+    # @raise [ValidationError] if the file to parse is invalid
+    def validate!
+      validate || raise(ValidationError)
+    end
+
+    class NoParserError < TypeError; end
+    class ValidationError < RuntimeError; end
+  end # rubocop:enable Style/ClassVars
+end

data/lib/zizia/parsers/csv_parser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'csv'
+
+module Zizia
+  ##
+  # A parser for CSV files. A single `InputRecord` is returned for each row
+  # parsed from the input.
+  #
+  # Validates the format of the CSV, generating a single error the file is
+  # malformed. This error gives the line number and a message for the first
+  # badly formatted row.
+  #
+  # @see CsvFormatValidator
+  class CsvParser < Parser
+    DEFAULT_VALIDATORS = [CsvFormatValidator.new].freeze
+    EXTENSION = '.csv'
+
+    class << self
+      ##
+      # Matches all '.csv' filenames.
+      def match?(file:, **_opts)
+        File.extname(file) == EXTENSION
+      rescue TypeError
+        false
+      end
+    end
+
+    ##
+    # Gives a record for each line in the .csv
+    #
+    # @see Parser#records
+    def records
+      return enum_for(:records) unless block_given?
+
+      file.rewind
+
+      CSV.parse(file.read, headers: true).each do |row|
+        yield InputRecord.from(metadata: row)
+      end
+    rescue CSV::MalformedCSVError
+      []
+    end
+  end
+end

data/lib/zizia/record_importer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Zizia
+  class RecordImporter
+    ##
+    # @!attribute [rw] error_stream
+    #   @return [#<<]
+    # @!attribute [rw] info_stream
+    #   @return [#<<]
+    # @!attribute [rw] batch_id
+    #   @return [String] an optional batch id for this import run
+    # @!attribute [rw] success_count
+    #   @return [Integer] a count of the records that were successfully created
+    # @!attribute [rw] failure_count
+    #   @return [Integer] a count of the records that failed import
+    attr_accessor :error_stream, :info_stream, :batch_id, :success_count, :failure_count
+
+    ##
+    # @param error_stream [#<<]
+    def initialize(error_stream: Zizia.config.default_error_stream,
+                   info_stream: Zizia.config.default_info_stream)
+      self.error_stream = error_stream
+      self.info_stream  = info_stream
+    end
+
+    ##
+    # @param record [ImportRecord]
+    #
+    # @return [void]
+    def import(record:)
+      create_for(record: record)
+    rescue Faraday::ConnectionFailed, Ldp::HttpError => e
+      error_stream << e
+    rescue RuntimeError => e
+      error_stream << e
+      raise e
+    end
+
+    def import_type
+      raise 'No curation_concern found for import' unless
+        defined?(Hyrax) && Hyrax&.config&.curation_concerns&.any?
+
+      Hyrax.config.curation_concerns.first
+    end
+
+    private
+
+      def create_for(record:)
+        info_stream << 'Creating record: ' \
+                       "#{record.respond_to?(:title) ? record.title : record}."
+
+        created = import_type.create(record.attributes)
+
+        info_stream << "Record created at: #{created.id}"
+      end
+  end
+end

data/lib/zizia/spec/fakes/fake_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class FakeParser < Zizia::Parser
+  METADATA = [{ 'title' => '1' }, { 'title' => '2' }, { 'title' => '3' }].freeze
+
+  def initialize(file: METADATA)
+    super
+  end
+
+  def records
+    return enum_for(:records) unless block_given?
+
+    file.each { |hsh| yield Zizia::InputRecord.from(metadata: hsh) }
+  end
+end
+
+describe FakeParser do
+  it_behaves_like 'a Zizia::Parser' do
+    subject(:parser)   { described_class.new }
+    let(:record_count) { 3 }
+  end
+end

data/lib/zizia/spec/shared_examples/a_mapper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+shared_examples 'a Zizia::Mapper' do
+  subject(:mapper) { described_class.new }
+
+  before { mapper.metadata = metadata }
+
+  describe '#metadata' do
+    it 'can be set' do
+      expect { mapper.metadata = nil }
+        .to change { mapper.metadata }
+    end
+  end
+
+  describe '#field?' do
+    it 'does not have bogus fields' do
+      expect(mapper.field?(:NOT_A_REAL_FIELD)).to be_falsey
+    end
+
+    it 'has fields that are expected' do
+      if defined?(expected_fields)
+        expected_fields.each do |field|
+          expect(mapper.field?(field)).to be_truthy
+        end
+      end
+    end
+  end
+
+  describe '#fields' do
+    it { expect(mapper.fields).to contain_exactly(*expected_fields) }
+  end
+end

data/lib/zizia/spec/shared_examples/a_message_stream.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+shared_examples 'a Zizia::MessageStream' do
+  describe '#<<' do
+    it { is_expected.to respond_to(:<<) }
+
+    it 'accepts a string argument' do
+      expect { stream << 'some string' }.not_to raise_error
+    end
+  end
+end

data/lib/zizia/spec/shared_examples/a_parser.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'zizia/always_invalid_validator'
+
+shared_examples 'a Zizia::Parser' do
+  describe '#file' do
+    it 'is an accessor' do
+      expect { parser.file = :a_new_file }
+        .to change { parser.file }
+        .to(:a_new_file)
+    end
+  end
+
+  describe '#records' do
+    it 'yields records' do
+      unless described_class == Zizia::Parser
+        expect { |b| parser.records(&b) }
+          .to yield_control.exactly(record_count).times
+      end
+    end
+  end
+
+  describe '#valid?' do
+    it 'is valid' do
+      expect(parser).to be_valid
+    end
+
+    context 'when not valid' do
+      before do
+        parser.validators = [Zizia::AlwaysInvalidValidator.new]
+      end
+
+      it 'is invalid' do
+        expect { parser.validate }
+          .to change { parser.valid? }
+          .to be_falsey
+      end
+    end
+  end
+
+  describe '#validate' do
+    it 'is true when valid' do
+      expect(parser.validate).to be_truthy
+    end
+
+    context 'when not valid' do
+      before do
+        parser.validators = [Zizia::AlwaysInvalidValidator.new]
+      end
+
+      it 'is invalid' do
+        expect(parser.validate).to be_falsey
+      end
+    end
+  end
+
+  describe '#validate!' do
+    it 'is true when valid' do
+      expect(parser.validate).to be_truthy
+    end
+
+    context 'when not valid' do
+      before do
+        parser.validators = [Zizia::AlwaysInvalidValidator.new]
+      end
+
+      it 'raises a ValidationError' do
+        expect { parser.validate! }
+          .to raise_error Zizia::Parser::ValidationError
+      end
+    end
+  end
+end

data/lib/zizia/spec/shared_examples/a_validator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+shared_examples 'a Zizia::Validator' do
+  subject(:validator) { described_class.new(error_stream: error_stream) }
+  let(:error_stream)  { [] }
+
+  define :be_a_validator_error do # |expected|
+    match { false } # { |actual| some_condition }
+  end
+
+  describe '#validate' do
+    context 'without a parser' do
+      it 'raises ArgumentError' do
+        expect { validator.validate }.to raise_error ArgumentError
+      end
+    end
+
+    it 'gives an empty error collection for a valid parser' do
+      expect(validator.validate(parser: valid_parser)).not_to be_any if
+        defined?(valid_parser)
+    end
+
+    context 'for an invalid parser' do
+      it 'gives an non-empty error collection' do
+        expect(validator.validate(parser: invalid_parser)).to be_any if
+          defined?(invalid_parser)
+      end
+
+      it 'gives usable errors' do
+        pending 'we need to clarify the error type and usage'
+
+        validator.validate(parser: invalid_parser).each do |error|
+          expect(error).to be_a_validator_error
+        end
+      end
+
+      it 'writes errors to the error stream' do
+        if defined?(invalid_parser)
+          expect { validator.validate(parser: invalid_parser) }
+            .to change { error_stream }
+            .to include(an_instance_of(Zizia::Validator::Error))
+        end
+      end
+    end
+  end
+end

data/lib/zizia/spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zizia
+  ##
+  # RSpec test support for {Zizia} importers.
+  #
+  # @see https://relishapp.com/rspec/rspec-core/docs/
+  module Spec
+    require 'zizia/spec/shared_examples/a_mapper'
+    require 'zizia/spec/shared_examples/a_message_stream'
+    require 'zizia/spec/shared_examples/a_parser'
+    require 'zizia/spec/shared_examples/a_validator'
+    require 'zizia/spec/fakes/fake_parser'
+  end
+end

data/lib/zizia/streams/formatted_message_stream.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Zizia
+  ##
+  # A message stream that formats a message before forwarding it to an
+  # underlying {#stream} (STDOUT by default). Messages are formatted using
+  # the `#%` method; the formatter can be a string format specification like
+  # "Message received: %s".
+  #
+  # @example Using a simple formatter
+  #   formatter = "Message received: %s\n"
+  #   stream    = Zizia::FormattedMessageStream.new(formatter: formatter)
+  #
+  #   stream << "a message"
+  #   # Message received: a message
+  #   # => #<IO:<STDOUT>>
+  #
+  # @example A more complex formatter use case
+  #   class MyFormatter
+  #     def %(arg)
+  #       "#{Time.now}: %s\n" % arg
+  #     end
+  #   end
+  #
+  #   formatter = MyFormatter.new
+  #   stream    = Zizia::FormattedMessageStream.new(formatter: formatter)
+  #
+  #   stream << 'a message'
+  #   # 2018-02-02 16:10:52 -0800: a message
+  #   # => #<IO:<STDOUT>>
+  #
+  #   stream << 'another message'
+  #   # 2018-02-02 16:10:55 -0800: another message
+  #   # => #<IO:<STDOUT>>
+  #
+  class FormattedMessageStream
+    ##
+    # @!attribute [rw] formatter
+    #   @return [#%] A format specification
+    #   @see https://ruby-doc.org/core-2.4.0/String.html#method-i-25
+    # @!attribute [rw] stream
+    #   @return [#<<] an underlying stream to forward messages to after
+    #     formatting
+    attr_accessor :formatter, :stream
+
+    ##
+    # @param formatter [#%] A format specification
+    # @param stream    [#<<] an underlying stream to forward messages to after
+    #   formatting
+    #
+    # @see https://ruby-doc.org/core-2.4.0/String.html#method-i-25
+    def initialize(stream: STDOUT, formatter: "%s\n")
+      self.formatter = formatter
+      self.stream    = stream
+    end
+
+    ##
+    def <<(msg)
+      stream << format_message(msg)
+    end
+
+    ##
+    # @param msg [#to_s]
+    #
+    # @return [String] the input, cast to a string and formatted using
+    def format_message(msg)
+      formatter % msg
+    end
+  end
+end

data/lib/zizia/validator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Zizia
+  ##
+  # @abstract A null validator; always returns an empty error collection
+  #
+  # Validators are used to ensure the correctness of input to a parser. Each
+  # validator must respond to `#validate` and return a collection of errors
+  # found during validation. If the input is valid, this collection must be
+  # empty. Otherwise, it contains any number of `Validator::Error` structs
+  # which should be sent to the `#error_stream` by the validator.
+  #
+  # The validation process accepts an entire `Parser` and is free to inspect
+  # the input `#file` content, or view its individual `#records`.
+  #
+  # The base class provides infrastructure for the key behavior, relying on a
+  # private `#run_validation` method to provide the core behavior. In most cases
+  # implementers will want to simply override this method.
+  #
+  # @example validating a parser
+  #   validator = MyValidator.new
+  #   validator.validate(parser: myParser)
+  #
+  # @example validating an invalid parser
+  #   validator = MyValidator.new
+  #   validator.validate(parser: invalidParser)
+  #   # => Error<#... validator: MyValidator,
+  #                   name: 'An Error Name',
+  #                   description: '...'
+  #                   lineno: 37>
+  #
+  # @example Implementing a custom Validator and using it in a Parser
+  #   # Validator checks that the title, when downcased is equal to `moomin`
+  #   class TitleIsMoominValidator
+  #     def run_validation(parser:)
+  #       parser.records.each_with_object([]) do |record, errors|
+  #         errors << Error.new(self, :title_is_not_moomin) unless
+  #           title_is_moomin?(record)
+  #       end
+  #     end
+  #
+  #     def title_is_moomin?(record)
+  #       return false unless record.respond_to?(:title)
+  #       return true if record.title.downcase == 'moomin
+  #       true
+  #     end
+  #   end
+  #
+  #   parser = MyParser.new(some_content)
+  #   parser.validations << TitleIsMoominvalidator.new
+  #   parser.validate
+  #   parser.valid? # => false (unless all the records match the title)
+  #
+  # @see Parser#validate
+  class Validator
+    ##
+    # A representation of an error encountered in validation.
+    Error = Struct.new(:validator, :name, :description, :lineno) do
+      ##
+      # @!attribute [rw] validator
+      #   @return [#to_s] the validator that generated this error
+      # @!attribute [rw] name
+      #   @return [#to_s] a short descriptive name for the given error
+      # @!attribute [rw] description
+      #   @return [#to_s] a long form description or message
+      # @!attribute [rw] lineno
+      #   @return [#to_s] the line number, or other indication of the location
+      #     where the error was encountered
+
+      ##
+      # @return [Boolean]
+      def validator_error?
+        true
+      end
+
+      ##
+      # @return [String]
+      def to_s
+        "#{name}: #{description} (#{validator})"
+      end
+    end
+
+    ##
+    # @!attribute [rw] error_stream
+    #   @return [#<<]
+    attr_accessor :error_stream
+
+    ##
+    # @param error_stream [#<<]
+    def initialize(error_stream: Zizia.config.default_error_stream)
+      self.error_stream = error_stream
+    end
+
+    ##
+    # @param parser [Parser]
+    #
+    # @return [Enumerator<Error>] a collection of errors found in validation
+    def validate(parser:)
+      run_validation(parser: parser).tap do |errors|
+        errors.map { |error| error_stream << error }
+      end
+    end
+
+    private
+
+      # rubocop:disable Lint/UnusedMethodArgument
+
+      ##
+      # @return [Enumerator<Error>]
+      #
+      def run_validation(parser:)
+        [].to_enum
+      end
+
+    # rubocop:enable Lint/UnusedMethodArgument
+  end
+end

data/lib/zizia/validators/csv_format_validator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Zizia
+  ##
+  # A validator for correctly formatted CSV.
+  #
+  # @example
+  #   parser = Parser.new(file: File.open('path/to/my.csv'))
+  #
+  #   CsvFormatValidator.new.validate(parser: parser)
+  #
+  # @see http://ruby-doc.org/stdlib-2.0.0/libdoc/csv/rdoc/CSV/MalformedCSVError.html
+  class CsvFormatValidator < Validator
+    ##
+    # @private
+    #
+    # @see Validator#validate
+    def run_validation(parser:, **)
+      return [] if CSV.parse(parser.file.read)
+    rescue CSV::MalformedCSVError => e
+      [Error.new(self.class, e.class, e.message)]
+    ensure
+      parser.file.rewind
+    end
+  end
+end

data/lib/zizia/validators/title_validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Zizia
+  class TitleValidator < Validator
+    ##
+    # @private
+    #
+    # @see Validator#validate
+    def run_validation(parser:, **)
+      parser.records.each_with_object([]) do |record, errors|
+        titles = record.respond_to?(:title) ? record.title : []
+
+        errors << error_for(record: record) if Array(titles).empty?
+      end
+    end
+
+    protected
+
+      ##
+      # @private
+      # @param record [InputRecord]
+      #
+      # @return [Error]
+      def error_for(record:)
+        Error.new(self,
+                  :missing_title,
+                  "Title is required; got #{record.mapper.metadata}")
+      end
+  end
+end

data/lib/zizia/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Zizia
+  VERSION = '1.0.1'
+end