darlingtonia 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cce55d5fc4915436a8e73be35f5944c46072a888
-  data.tar.gz: 70ca3ece0257d1d613c6986088ffbe7eddafe433
+SHA256:
+  metadata.gz: 4b822b291286cddbaf96726161ebfaf758f9491743d4b4daaf78a04182ef4ffe
+  data.tar.gz: 2c0ff5b15a5e1875acf7586754e52c79495c388f2efdde899047f372a01ca778
 SHA512:
-  metadata.gz: 705a826ca99966be26ec62c93e68c36c6ffe30ac8639f7bc61eeb023f23134506051f6f8f22fe924e8c59126d42df03ab7d7e3936c9f4e5e53f6c9804bdd2bcb
-  data.tar.gz: de85779f43db76264fa8b444066478321f915c51469674e4f60ff6d0cf8a7fad06e07bdd3d4b0881484273d870a6a60554e3ff47d2397561c275aae290ac949a
+  metadata.gz: 87891bbce7ba7f2c27d3f9a4394885ea0d8d142baf519daacd67ab2323b6b99da984458cf92457c3a469ebb137b8ff146f74f14e480ea6eeceb03f4842c58242
+  data.tar.gz: 27d66a21d1f8600cf177e31289a866d864a6f2df1106be8af42ae7b7ef4adb641915085f19fc70ab666fd126cfa8f8f026c8b948f473e61e33750696dd212530

data/.rubocop.yml

@@ -7,11 +7,14 @@ AllCops:
 Lint/HandleExceptions:
   Exclude:
     - 'spec/**/*'
+    - 'lib/darlingtonia/spec/**/*'
 
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
+    - 'lib/darlingtonia/spec/**/*'
 
 RSpec/DescribeClass:
   Exclude:
     - 'spec/integration/**/*'
+    - 'spec/*_spec.rb'

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+1.1.0 - Fri Mar 30, 2018
+------------------------
+
+Formatted message stream.
+
+  - Adds a formatted message stream to wrap other streams in a formatter.
+
 1.0.0 - Mon Jan 29, 2018
 ------------------------
 

data/README.md

@@ -1,7 +1,10 @@
 Darlingtonia
 ============
+[![Build Status](https://travis-ci.org/curationexperts/darlingtonia.svg?branch=master)](https://travis-ci.org/curationexperts/darlingtonia)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/darlingtonia)
 
-Object import for Hyrax.
+Object import for Hyrax. See the [API documentation](https://www.rubydoc.info/gems/darlingtonia) for more
+information.
 
 Usage
 -----
@@ -18,9 +21,12 @@ with your `Hyrax` application. You need to provide a `Parser` (out of the box, w
 import with `CsvParser`).
 
 ```ruby
-parser = Darlingtonia::CsvParser.new(file: File.open('path/to/import.csv'))
+file = File.open('path/to/import.csv')
+parser = Darlingtonia::CsvParser.new(file: file)
 
 Darlingtonia::Importer.new(parser: parser).import
+
+file.close # unless a block is passed to File.open, the file must be explicitly closed
 ```
 
 Development
@@ -33,3 +39,9 @@ cd darlingtonia
 bundle install
 bundle exec rake ci
 ```
+
+### RSpec Support
+
+This gem ships with RSpec shared examples and other support tools intended to ease testing and ensure
+interoperability of client code. These can be included by adding `require 'darlingtonia/spec'` to a
+`spec_helper.rb` or `rails_helper.rb` file in your application's test suite.

data/lib/darlingtonia.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
-require 'active_fedora'
-
 ##
-# Bulk object import for Hyrax.
+# Bulk object import for Samvera.
+#
+# == Importers
+#
+# {Importer} is the core class for importing records using {Darlingtonia}.
+# Importers accept a {Parser} and (optionally) a custom {RecordImporter}, and
+# process each record in the given parser (see: {Parser#records}).
+#
+# @example Importing in bulk from a file
+#   parser = Darlingtonia::Parser.for(file: File.new('path/to/file.ext'))
+#
+#   Darlingtonia::Importer.new(parser: parser).import if parser.validate
 #
 # @example A basic configuration
 #   Darlingtonia.config do |config|
-#     # error streams must respond to `#<<`
+#     # error/info streams must respond to `#<<`
 #     config.default_error_stream = MyErrorStream.new
+#     config.default_info_stream  = STDOUT
 #   end
 #
 module Darlingtonia

data/lib/darlingtonia/importer.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module Darlingtonia
+  ##
+  # The chief entry point for bulk import of records. `Importer` accepts a
+  # {Parser} on initialization and iterates through its {Parser#records}, importing
+  # each using a given {RecordImporter}.
+  #
+  # @example Importing in bulk from a CSV file
+  #   parser = Darlingtonia::Parser.for(file: File.new('path/to/import.csv'))
+  #
+  #   Darlingtonia::Importer.new(parser: parser).import if parser.validate
+  #
   class Importer
     extend Forwardable
 
@@ -17,13 +27,18 @@ module Darlingtonia
     def_delegator :parser, :records, :records
 
     ##
-    # @param parser [Parser]
+    # @param parser          [Parser] The parser to use as the source for import
+    #   records.
+    # @param record_importer [RecordImporter] An object to handle import of
+    #   each record
     def initialize(parser:, record_importer: RecordImporter.new)
       self.parser          = parser
       self.record_importer = record_importer
     end
 
     ##
+    # Import each record in {#records}.
+    #
     # @return [void]
     def import
       records.each { |record| record_importer.import(record: record) }

data/lib/darlingtonia/input_record.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Darlingtonia
+  ##
+  # @example Building an importer with the factory
+  #   record = InputRecord.from({some: :metadata}, mapper: MyMapper.new)
+  #   record.some # => :metadata
+  #
   class InputRecord
     ##
     # @!attribute [rw] mapper
@@ -8,13 +13,18 @@ module Darlingtonia
     attr_accessor :mapper
 
     ##
-    # @param metadata [Object]
-    # @param mapper   [#map_fields]
+    # @param mapper [#map_fields]
     def initialize(mapper: HashMapper.new)
       self.mapper = mapper
     end
 
     class << self
+      ##
+      # @param metadata [Object]
+      # @param mapper  [#map_fields]
+      #
+      # @return [InputRecord] an input record mapping metadata with the given
+      #   mapper
       def from(metadata:, mapper: HashMapper.new)
         mapper.metadata = metadata
         new(mapper: mapper)

data/lib/darlingtonia/metadata_mapper.rb

@@ -36,7 +36,6 @@ module Darlingtonia
   #
   #   mapper.fields.map { |field| mapper.send(field) }
   #
-  #
   # @see ImportRecord#attributes for the canonical usage of a `MetadataMapper`.
   # @see HashMapper for an example implementation with dynamically generated
   #   fields

data/lib/darlingtonia/spec.rb

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

data/{spec/support → lib/darlingtonia/spec}/fakes/fake_parser.rb

@@ -14,8 +14,6 @@ class FakeParser < Darlingtonia::Parser
   end
 end
 
-require 'support/shared_examples/a_parser'
-
 # rubocop:disable RSpec/FilePath
 describe FakeParser do
   it_behaves_like 'a Darlingtonia::Parser' do

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+shared_examples 'a Darlingtonia::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/darlingtonia/streams/formatted_message_stream.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Darlingtonia
+  ##
+  # 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    = Darlingtonia::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    = Darlingtonia::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/darlingtonia/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Darlingtonia
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/darlingtonia/formatted_message_stream_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'darlingtonia/streams/formatted_message_stream'
+
+describe Darlingtonia::FormattedMessageStream do
+  subject(:stream)     { described_class.new(stream: fake_stream) }
+  let(:fake_stream)    { [] }
+
+  it_behaves_like 'a Darlingtonia::MessageStream'
+
+  describe '#stream' do
+    subject(:stream) { described_class.new }
+
+    it 'is STDOUT by default' do
+      expect(stream.stream).to eq STDOUT
+    end
+  end
+
+  describe '#<<' do
+    it 'appends newlines by default' do
+      expect { stream << 'moomin' }
+        .to change { fake_stream }
+        .to contain_exactly("moomin\n")
+    end
+
+    it 'uses other % formatters' do
+      stream.formatter = "!!!%s!!!"
+
+      expect { stream << 'moomin' }
+        .to change { fake_stream }
+        .to contain_exactly('!!!moomin!!!')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -4,8 +4,10 @@ require 'pry' unless ENV['CI']
 ENV['environment'] ||= 'test'
 
 require 'bundler/setup'
+require 'active_fedora'
 require 'active_fedora/cleaner'
 require 'darlingtonia'
+require 'darlingtonia/spec'
 
 Dir['./spec/support/**/*.rb'].each { |f| require f }
 

data/spec/stdout_stream_spec.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'STDOUT as a MessageStream' do
+  subject(:stream) { STDOUT }
+
+  it_behaves_like 'a Darlingtonia::MessageStream'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: darlingtonia
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Tom Johnson
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-29 00:00:00.000000000 Z
+date: 2018-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active-fedora
@@ -152,12 +152,20 @@ files:
 - lib/darlingtonia/parser.rb
 - lib/darlingtonia/parsers/csv_parser.rb
 - lib/darlingtonia/record_importer.rb
+- lib/darlingtonia/spec.rb
+- lib/darlingtonia/spec/fakes/fake_parser.rb
+- lib/darlingtonia/spec/shared_examples/a_mapper.rb
+- lib/darlingtonia/spec/shared_examples/a_message_stream.rb
+- lib/darlingtonia/spec/shared_examples/a_parser.rb
+- lib/darlingtonia/spec/shared_examples/a_validator.rb
+- lib/darlingtonia/streams/formatted_message_stream.rb
 - lib/darlingtonia/validator.rb
 - lib/darlingtonia/validators/csv_format_validator.rb
 - lib/darlingtonia/validators/title_validator.rb
 - lib/darlingtonia/version.rb
 - spec/darlingtonia/csv_format_validator_spec.rb
 - spec/darlingtonia/csv_parser_spec.rb
+- spec/darlingtonia/formatted_message_stream_spec.rb
 - spec/darlingtonia/hash_mapper_spec.rb
 - spec/darlingtonia/importer_spec.rb
 - spec/darlingtonia/input_record_spec.rb
@@ -171,11 +179,8 @@ files:
 - spec/fixtures/example.csv
 - spec/integration/import_csv_spec.rb
 - spec/spec_helper.rb
-- spec/support/fakes/fake_parser.rb
+- spec/stdout_stream_spec.rb
 - spec/support/shared_contexts/with_work_type.rb
-- spec/support/shared_examples/a_mapper.rb
-- spec/support/shared_examples/a_parser.rb
-- spec/support/shared_examples/a_validator.rb
 homepage: 
 licenses:
 - Apache-2.0
@@ -196,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: Hyrax importers.