active_importer 0.2.1 → 0.2.2

data/README.md

@@ -123,6 +123,8 @@ The supported events are:
   before the first row is processed.
 - **row_processing:** Fired while the row is being processed to be imported
   into a model instance.
+- **row_skipped:** Fired once for each row that matches the `skip_rows_if`
+  condition, if any.
 - **row_processed:** Fired once for each row that has been processed,
   regardless of whether it resulted in success or error.
 - **row_success:** Fired once for each row that was imported successfully into
@@ -130,6 +132,8 @@ The supported events are:
 - **row_error:** Fired once for each row that was **not** imported successfully
   into the data model.
 - **import_finished:** Fired once **after** all rows have been processed.
+- **import_aborted:** Fired once if the import process is aborted by invoking
+  `abort!`.
 
 More than one block of code can be provided for each of these events, and they
 will all be invoked in the same order in which they were declared.  All blocks
@@ -169,6 +173,39 @@ find an existing model for the employee with the first and last name in the row
 being processed.  If this record exist, the row data will be used to update the
 given model instance.  Otherwise, a new employee record will be created.
 
+### Selecting the sheet to get data from
+
+Spreadsheet files often have more than one sheet of data, so it is desirable to
+select which sheet to use when importing.
+
+```ruby
+class EmployeeImporter
+  imports Employee
+
+  sheet "Employees"
+
+  # ...
+end
+```
+
+The importer defined above specifies that data should be read from a sheet
+named "Employees".  By default an importer will read from the first sheet in
+the spreadsheet.
+
+Also, sheets can be specified by name or by index, starting by 1, which is the
+first sheet.  For instance, the following importer will read data from the
+third sheet, no matter what's its name.
+
+```ruby
+class EmployeeImporter
+  imports Employee
+
+  sheet 3
+
+  # ...
+end
+```
+
 ## Contributing
 
 1. Fork it

data/lib/active_importer/base.rb

@@ -7,6 +7,12 @@ module ActiveImporter
     # DSL and class variables
     #
 
+    @aborted = false
+
+    def abort!
+      @aborted = true
+    end
+
     @model_class = nil
     @columns = {}
 
@@ -26,6 +32,10 @@ module ActiveImporter
       self.class.model_class
     end
 
+    def self.sheet(index)
+      @sheet_index = index
+    end
+
     def self.fetch_model(&block)
       @fetch_model_block = block
     end
@@ -34,6 +44,14 @@ module ActiveImporter
       @fetch_model_block
     end
 
+    def self.skip_rows_if(&block)
+      @skip_rows_block = block
+    end
+
+    def self.skip_rows_block
+      @skip_rows_block
+    end
+
     def self.column(title, field = nil, &block)
       title = title.strip
       if columns[title]
@@ -54,10 +72,12 @@ module ActiveImporter
       :row_success,
       :row_error,
       :row_processing,
+      :row_skipped,
       :row_processed,
       :import_started,
       :import_finished,
       :import_failed,
+      :import_aborted,
     ]
 
     def self.event_handlers
@@ -103,6 +123,7 @@ module ActiveImporter
       @context = options.delete(:context)
 
       @book = Roo::Spreadsheet.open(file, options)
+      load_sheet
       load_header
 
       @data_row_indices = ((@header_index+1)..@book.last_row)
@@ -132,7 +153,15 @@ module ActiveImporter
       @data_row_indices.each do |index|
         @row_index = index
         @row = row_to_hash @book.row(index)
+        if skip_row?
+          fire_event :row_skipped
+          next
+        end
         import_row
+        if @aborted
+          fire_event :import_aborted
+          break
+        end
       end
       fire_event :import_finished
     end
@@ -157,6 +186,19 @@ module ActiveImporter
       self.class.columns
     end
 
+    def skip_row?
+      block = self.class.skip_rows_block
+      block.nil? || self.instance_exec(&block)
+    end
+
+    def load_sheet
+      sheet_index = self.class.instance_variable_get(:@sheet_index)
+      if sheet_index
+        sheet_index = @book.sheets[sheet_index-1] if sheet_index.is_a?(Fixnum)
+        @book.default_sheet = sheet_index.to_s
+      end
+    end
+
     def find_header_index
       (1..@book.last_row).each do |index|
         row = @book.row(index).map { |cell| cell.to_s.strip }
@@ -178,7 +220,7 @@ module ActiveImporter
       begin
         @model = fetch_model
         build_model
-        model.save!
+        model.save! unless @aborted
       rescue => e
         @row_errors << { row_index: row_index, error_message: e.message }
         fire_event :row_error, e
@@ -197,7 +239,7 @@ module ActiveImporter
         field_name = column_def[:field_name]
         transform = column_def[:transform]
         value = self.instance_exec(value, &transform) if transform
-        model[field_name] = value
+        model.send("#{field_name}=", value)
       end
       fire_event :row_processing
     end

data/lib/active_importer/version.rb

@@ -1,3 +1,3 @@
 module ActiveImporter
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/spec/active_importer/base_spec.rb

@@ -24,8 +24,9 @@ describe ActiveImporter::Base do
   let(:importer) { EmployeeImporter.new('/dummy/file') }
 
   before do
-    expect(Roo::Spreadsheet).to receive(:open).and_return { Spreadsheet.new(spreadsheet_data) }
+    expect(Roo::Spreadsheet).to receive(:open).at_least(:once).and_return { Spreadsheet.new(spreadsheet_data) }
     EmployeeImporter.instance_variable_set(:@fetch_model_block, nil)
+    EmployeeImporter.instance_variable_set(:@sheet_index, nil)
   end
 
   it 'imports all data from the spreadsheet into the model' do
@@ -153,4 +154,78 @@ describe ActiveImporter::Base do
       EmployeeImporter.import('/dummy/file')
     end
   end
+
+  context 'when spreadsheet has multiple sheets' do
+    let(:spreadsheet_data) do
+      {
+        "Employees" => [
+          [' Name ', 'Birth Date', 'Department', 'Manager'],
+          ['John Doe', '2013-10-25', 'IT'],
+          ['Jane Doe', '2013-10-26', 'Sales'],
+        ],
+        "Outstanding employees" => [
+          [' Name ', 'Birth Date', 'Department', 'Manager'],
+          ['Jane Doe', '2013-10-26', 'Sales'],
+        ],
+      }
+    end
+
+    it 'uses the first sheet by default' do
+      expect { EmployeeImporter.import('/dummy/file') }.to change(Employee, :count).by(2)
+    end
+
+    it 'uses another sheet if instructed to do so' do
+      EmployeeImporter.sheet 1
+      expect { EmployeeImporter.import('/dummy/file') }.to change(Employee, :count).by(2)
+      EmployeeImporter.sheet "Outstanding employees"
+      expect { EmployeeImporter.import('/dummy/file') }.to change(Employee, :count).by(1)
+    end
+
+    it 'fails if the specified sheet cannot be found' do
+      expect_any_instance_of(EmployeeImporter).to receive(:import_failed)
+      EmployeeImporter.sheet 5
+      EmployeeImporter.import('/dummy/file')
+    end
+  end
+
+  describe '#abort!' do
+    let(:spreadsheet_data) do
+      [
+        [' Name ', 'Birth Date', 'Department', 'Manager'],
+        ['John Doe', '2013-10-25', 'IT'],
+        ['Abort', '2013-10-25', 'IT'],
+        ['Jane Doe', '2013-10-26', 'Sales'],
+      ]
+    end
+
+    it 'causes the import process to abort without processing any more rows' do
+      expect { EmployeeImporter.import('/dummy/file') }.to change(Employee, :count).by(1)
+    end
+
+    it 'does not report an error for the row where the abortion occured' do
+      expect(importer).not_to receive(:row_error)
+      EmployeeImporter.import('/dummy/file')
+    end
+  end
+
+  describe '.skip_rows_if' do
+    let(:spreadsheet_data) do
+      [
+        [' Name ', 'Birth Date', 'Department', 'Manager'],
+        ['Skip', '2013-10-25', 'IT'],
+        ['John Doe', '2013-10-25', 'IT'],
+        ['Jane Doe', '2013-10-26', 'Sales'],
+      ]
+    end
+
+    it 'skips processing the current row' do
+      expect { EmployeeImporter.import('/dummy/file') }.to change(Employee, :count).by(2)
+    end
+
+    it 'invokes event :row_skipped for each skipped row' do
+      expect(EmployeeImporter).to receive(:new).once.and_return(importer)
+      expect(importer).to receive(:row_skipped).once
+      EmployeeImporter.import('/dummy/file')
+    end
+  end
 end

data/spec/stubs/employee.rb

@@ -28,6 +28,14 @@ class EmployeeImporter < EmployeeBaseImporter
     find_department(value)
   end
 
+  on :row_processing do
+    abort! if row['Name'] == 'Abort'
+  end
+
+  skip_rows_if do
+    row['Name'] == 'Skip'
+  end
+
   def find_department(name)
     name.length # Quick dummy way to get an integer out of a string
   end

data/spec/stubs/spreadsheet.rb

@@ -1,13 +1,27 @@
 class Spreadsheet
   def initialize(data)
+    data = { "Default" => data } unless data.is_a?(Hash)
     @data = data
   end
 
+  def sheets
+    @sheets ||= @data.keys
+  end
+
+  def default_sheet
+    @default_sheet ||= sheets.first
+  end
+
+  def default_sheet=(value)
+    raise "Invalid sheet '#{value}'" unless sheets.include?(value)
+    @default_sheet = value
+  end
+
   def last_row
-    @data.count
+    @data[default_sheet].count
   end
 
   def row(index)
-    @data[index-1]
+    @data[default_sheet][index-1]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_importer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-13 00:00:00.000000000 Z
+date: 2013-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roo
@@ -112,7 +112,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3865447106793864810
+      hash: -4188845756724848083
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -121,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3865447106793864810
+      hash: -4188845756724848083
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23