bumblebee 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 836e600a1fb3228d7704e561fac6a6677e1944b42d624f2a2c9f740035f9c35b
-  data.tar.gz: 0f222b4d2742bf467837dd89621310b1721e9bae089dc2c69e4db7f7bdc399ba
+  metadata.gz: e63f0ffdddd7bea22fb6da178b542556cde964543a2d7c4c68ef6e85b3bb06f3
+  data.tar.gz: 28a41de9de06653b0d2d41d52818bb690d786f124e6e84be7e867a496da2a8c6
 SHA512:
-  metadata.gz: 31e3cc0c89fe47147b793a1b43e4c8e41e5a1d1580e3955073ac9019e7c45b9e1b34e5c0d1991cb39e0175b40299f612c0d22c20e0d03fffb238897d66f733b7
-  data.tar.gz: b223693ec13620e7d54ca3e4eed04c2face5774fba8c6e6645c4e44a070b0105e0f940dcc37306af479e62c7da906ca86b00bfd4737a1bd84bca21467692948c
+  metadata.gz: 3153683a9564325488926f6bde6cb77ce59d1674ac6fcb3a9e60911a21870a26905b9d14d851f660d2c0c74b7df34986eadfd488a85d21734b3a7ff515e3453c
+  data.tar.gz: 9d19b1ea86c98101bb523a8e2ab1d6e0a04230c6b6616a2ba76b0e9bf584ccf2fcb4184a9fb14980e467a5d93749a104bb2b87a26313e48b4b5d1e5653c6376e

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 2.1.0 (March 4th, 2019)
+
+* Added two domain-specific language options for configuring Column objects through Template: subclass Template class or pass in block.  This is optional and is backwards compatible.
+
 # 2.0.1 (February 5th, 2019)
 
 * Updated acts_as_hashable Dependency

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bumblebee (2.0.1)
+    bumblebee (2.1.0)
       acts_as_hashable (~> 1.0)
 
 GEM
@@ -95,10 +95,11 @@ PLATFORMS
 DEPENDENCIES
   bumblebee!
   guard-rspec (~> 4.7)
+  pry
   rspec (~> 3.8)
   rubocop (~> 0.63.1)
   simplecov (~> 0.16.1)
   simplecov-console (~> 0.4.2)
 
 BUNDLED WITH
-   1.17.2
+   1.17.3

data/README.md

@@ -244,6 +244,110 @@ The two main methods:
 
 also accept custom options that [Ruby's CSV::new](https://ruby-doc.org/stdlib-2.6/libdoc/csv/rdoc/CSV.html#method-c-new) accepts.  The only caveat is that Bumblebee needs headers for its mapping, so it overrides the header options.
 
+#### Template DSL
+
+You can choose to pass in a block for template/column specification if you would rather prefer a code-first approach over a configuration-first approach.
+
+##### Using Blocks
+
+````ruby
+csv = Bumblebee.generate_csv(objects) do |t|
+  t.column :id,    header: 'ID #',
+                   to_object: ->(o) { o['ID #'].to_i }
+
+  t.column :first, header: 'First Name',
+                   to_csv: %i[name first],
+                   to_object: ->(o) { { first: o['First Name'] } }
+end
+
+objects = Bumblebee.parse_csv(data) do |t|
+  t.column :id,    header: 'ID #',
+                   to_object: ->(o) { o['ID #'].to_i }
+
+  t.column :first, header: 'First Name',
+                   to_csv: %i[name first],
+                   to_object: ->(o) { { first: o['First Name'] } }
+end
+````
+
+##### Interacting Directly With ::Bumblebee::Template
+
+You can also choose to interact/build templates directly instead of going through the top-level API:
+
+````ruby
+template = Bumblebee::Template.new(columns)
+
+# or
+
+template = Bumblebee::Template.new do |t|
+  t.column :id,    header: 'ID #',
+                   to_object: ->(o) { o['ID #'].to_i }
+
+  t.column :first, header: 'First Name',
+                   to_csv: %i[name first],
+                   to_object: ->(o) { { first: o['First Name'] } }
+end
+````
+
+Template class has the same top-level methods:
+
+````ruby
+csv = template.generate_csv(objects)
+
+objects = template.parse_csv(data)
+````
+
+##### Subclassing ::Bumblebee::Template
+
+Another option is to subclass Template and declare your columns at the class-level:
+
+````ruby
+class PersonTemplate < Bumblebee::Template
+  column :id,    header: 'ID #',
+                 to_object: ->(o) { o['ID #'].to_i }
+
+  column :first, header: 'First Name',
+                 to_csv: %i[name first],
+                 to_object: ->(o) { { first: o['First Name'] } }
+end
+
+# Usage
+
+template  = PersonTemplate.new
+csv       = template.generate_csv(objects)
+objects   = template.parse_csv(data)
+````
+
+##### Column Precedence
+
+The preceding examples showed three ways to declare columns, and each is additive to the next (in the following order):
+
+1. Class level (parent-first)
+2. Argument level (passed into constructor)
+3. Block level
+
+To illustrate all three:
+
+````ruby
+class PersonTemplate < Bumblebee::Template # first
+  column :id,    header: 'ID #',
+                 to_object: ->(o) { o['ID #'].to_i }
+
+  column :first, header: 'First Name',
+                 to_csv: %i[name first],
+                 to_object: ->(o) { { first: o['First Name'] } }
+end
+
+# Usage
+
+template  = PersonTemplate.new({ field: :middle, header: 'Middle Name' }) do |t| # second
+  t.column :last, header: 'Last Name' # third
+end
+
+````
+
+When executed to generate a CSV, the columns would be (in order): ```ID #, First Name, Middle Name, Last Name.```
+
 ## Contributing
 
 ### Development Environment Configuration

data/bumblebee.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
   s.add_dependency('acts_as_hashable', '~>1.0')
 
   s.add_development_dependency('guard-rspec', '~>4.7')
+  s.add_development_dependency('pry')
   s.add_development_dependency('rspec', '~> 3.8')
   s.add_development_dependency('rubocop', '~>0.63.1')
   s.add_development_dependency('simplecov', '~>0.16.1')

data/lib/bumblebee/bumblebee.rb

@@ -19,12 +19,56 @@ require_relative 'template'
 # procedural way using these.
 module Bumblebee
   class << self
-    def generate_csv(columns, objects, options = {})
-      ::Bumblebee::Template.new(columns).generate_csv(objects, options)
+    # Two signatures for consumption:
+    #
+    # ::Bumblebee.generate_csv(columns = [], objects = [], options = {})
+    #
+    # or
+    #
+    # ::Bumblebee.generate_csv(objects = [], options = {}) do |t|
+    #   t.column :id, header: 'ID #'
+    #   t.column :first, header: 'First Name'
+    # end
+    def generate_csv(*args, &block)
+      if block_given?
+        objects = args[0] || []
+        options = args[1] || {}
+      else
+        objects = args[1] || []
+        options = args[2] || {}
+      end
+
+      template(args, &block).generate_csv(objects, options)
+    end
+
+    # Two signatures for consumption:
+    #
+    # ::Bumblebee.parse_csv(columns = [], string = '', options = {})
+    #
+    # or
+    #
+    # ::Bumblebee.parse_csv(string = '', options = {}) do |t|
+    #   t.column :id, header: 'ID #'
+    #   t.column :first, header: 'First Name'
+    # end
+    def parse_csv(*args, &block)
+      if block_given?
+        string  = args[0] || ''
+        options = args[1] || {}
+      else
+        string  = args[1] || ''
+        options = args[2] || {}
+      end
+
+      template(args, &block).parse_csv(string, options)
     end
 
-    def parse_csv(columns, string, options = {})
-      ::Bumblebee::Template.new(columns).parse_csv(string, options)
+    private
+
+    def template(args, &block)
+      columns = block_given? ? [] : (args[0] || [])
+
+      ::Bumblebee::Template.new(columns, &block)
     end
   end
 end

data/lib/bumblebee/template.rb

@@ -12,10 +12,42 @@ module Bumblebee
   # generate_csv: take in an array of objects and return a string (CSV contents)
   # parse_csv: take in a string and return an array of OpenStruct objects
   class Template
+    class << self
+      def columns
+        @columns ||= []
+      end
+
+      def column(field, opts = {})
+        columns << ::Bumblebee::Column.make(opts.merge(field: field))
+
+        self
+      end
+
+      def all_columns
+        ancestors.reverse_each.inject([]) do |arr, ancestor|
+          ancestor < ::Bumblebee::Template ? arr + ancestor.columns : arr
+        end
+      end
+    end
+
     attr_reader :columns
 
-    def initialize(columns = [])
-      @columns = ::Bumblebee::Column.array(columns)
+    def initialize(columns = [], &block)
+      @columns = self.class.all_columns + ::Bumblebee::Column.array(columns)
+
+      return unless block_given?
+
+      if block.arity == 1
+        yield self
+      else
+        instance_eval(&block)
+      end
+    end
+
+    # New DSL method to use for adding columns
+    def column(field, opts = {})
+      @columns << ::Bumblebee::Column.make(opts.merge(field: field))
+      self
     end
 
     # Return array of strings (headers)

data/lib/bumblebee/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Bumblebee
-  VERSION = '2.0.1'
+  VERSION = '2.1.0'
 end

data/spec/bumblebee/bumblebee_spec.rb

@@ -35,12 +35,22 @@ describe ::Bumblebee do
 
   let(:quoted_csv) { "\"name\",\"dob\"\n\"Matt\",\"1901-01-03\"\n\"Nathan\",\"1931-09-03\"\n" }
 
-  it 'should generate a csv' do
+  it 'should generate a csv using column argument' do
     actual = Bumblebee.generate_csv(columns, people)
 
     expect(actual).to eq(csv)
   end
 
+  it 'should generate a csv using block' do
+    actual = Bumblebee.generate_csv(people) do |t|
+      columns.each do |column|
+        t.column column[:field]
+      end
+    end
+
+    expect(actual).to eq(csv)
+  end
+
   it 'should generate a csv and accept options' do
     options = {
       force_quotes: true
@@ -51,12 +61,22 @@ describe ::Bumblebee do
     expect(actual).to eq(quoted_csv)
   end
 
-  it 'should parse a csv' do
+  it 'should parse a csv using columns argument' do
     objects = Bumblebee.parse_csv(columns, csv)
 
     expect(objects).to eq(people)
   end
 
+  it 'should parse a csv using columns block' do
+    objects = Bumblebee.parse_csv(csv) do |t|
+      columns.each do |column|
+        t.column column[:field]
+      end
+    end
+
+    expect(objects).to eq(people)
+  end
+
   it 'should parse a csv with columns in different order than headers' do
     objects = ::Bumblebee.parse_csv(reverse_columns, csv)
 

data/spec/bumblebee/template_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'spec_helper'
+
+describe ::Bumblebee::Template do
+  let(:field) { :id }
+  let(:opts) { { header: 'ID #' } }
+
+  context 'with a blank template' do
+    let(:template) { ::Bumblebee::Template.new }
+
+    subject { template }
+
+    it '#column should add a column' do
+      subject.column(field, opts)
+
+      expect(subject.columns.length).to eq(1)
+      expect(subject.columns.first.field).to eq(field)
+      expect(subject.columns.first.header).to eq(opts[:header])
+    end
+  end
+
+  describe '#initialize' do
+    specify 'that initialization accepts a block (with arity) for column creation' do
+      template = ::Bumblebee::Template.new do |t|
+        t.column field, opts
+      end
+
+      expect(template.columns.length).to eq(1)
+      expect(template.columns.first.field).to eq(field)
+      expect(template.columns.first.header).to eq(opts[:header])
+    end
+
+    specify 'that initialization accepts a block (without arity) for column creation' do
+      template = ::Bumblebee::Template.new do
+        column :id, header: 'ID #'
+      end
+
+      expect(template.columns.length).to eq(1)
+      expect(template.columns.first.field).to eq(field)
+      expect(template.columns.first.header).to eq(opts[:header])
+    end
+  end
+
+  describe 'subclassing' do
+    class PersonTemplate < ::Bumblebee::Template
+      column :id, header: 'ID #'
+    end
+
+    class CompletePersonTemplate < PersonTemplate
+      column :first, header: 'First Name'
+    end
+
+    it 'should use class-level declared columns in the correct parenting hierarchical order' do
+      template = CompletePersonTemplate.new
+
+      expect(template.columns.length).to eq(2)
+      expect(template.columns.first.field).to eq(:id)
+      expect(template.columns.first.header).to eq('ID #')
+
+      expect(template.columns.last.field).to eq(:first)
+      expect(template.columns.last.header).to eq('First Name')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -8,6 +8,7 @@
 #
 
 require 'stringio'
+require 'pry'
 
 require 'simplecov'
 require 'simplecov-console'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bumblebee
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-05 00:00:00.000000000 Z
+date: 2019-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acts_as_hashable
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -124,6 +138,7 @@ files:
 - lib/bumblebee/version.rb
 - spec/bumblebee/bumblebee_spec.rb
 - spec/bumblebee/column_spec.rb
+- spec/bumblebee/template_spec.rb
 - spec/fixtures/custom_readme_example.csv
 - spec/fixtures/simple_readme_example.csv
 - spec/spec_helper.rb
@@ -153,6 +168,7 @@ summary: Object/CSV Mapper
 test_files:
 - spec/bumblebee/bumblebee_spec.rb
 - spec/bumblebee/column_spec.rb
+- spec/bumblebee/template_spec.rb
 - spec/fixtures/custom_readme_example.csv
 - spec/fixtures/simple_readme_example.csv
 - spec/spec_helper.rb