from_excel 1.0.0

data/README.rdoc

@@ -0,0 +1,168 @@
+== Overview
+
+Import excel spreadsheet rows to ruby objects.
+For how to use it, see examples below or see unit tests
+
+== Install
+
+  gem install from_excel
+
+== Dependencies
+
+gem 'nokogiri'
+gem 'roo'
+gem 'rubyzip'
+gem 'spreadsheet'
+gem 'google-spreadsheet-ruby'
+
+(also require 'active_support/inflector')
+
+== Usage
+
+data = Model.from_excel(spreadsheet_file, options)
+
+Include module in your model : include ExcelImport
+
+
+ 
+spreadsheet_file : File object as spreadsheet (ie :File.new ("path_to_spreadsheet"))
+ 
+options :
+ :mapping => hash mapping attribute <=> <column name or column index>
+ :title => true|false . Pass false to indicate that columns have no title. True by default.
+ :limits => :start => [first_row, first_column], :end => [last_row, last_column]
+ :rules => Procs rules to convert data in cell sheet to desired data for object attribute.
+ For example, transform a string to association id (see example below)
+ 
+
+<b>Note: If columns have title, by default the row of columns titles is supposed to be the first row before the first row
+of data which will be convert to ruby object.</b>
+ 
+== Basic spreadsheet 
+
+Suppose you have this kind of Excel sheet:
+      A           B         C
+   1 First name	Last name	 Age
+   2 Albert	    Einstein	 131
+   3 Leonard	  De Vinci	 558
+   
+and a class:
+
+   User (:first_name, last_name, :age)
+
+You can retrieve users, the simple way like that :
+
+   users = User.from_excel(File.new ("path_to_spreadsheet"))
+   
+You get theses users :
+  
+   [User.new(:first_name => 'Albert', :last_name =>	'Einstein', :age => 131),
+    User.new(:first_name => 'Leonard', :last_name =>	'De Vinci', :age => 558),
+    User.new(:first_name => 'Martin', :last_name =>	'Heidegger', :age => 121)]
+   
+By default, attributes model are retrieved from columns title with the following simple rule :
+o spaces are converted to "_"
+o words are downcased
+   
+   First Name => :first_name
+   Last Name => :last_name
+      
+
+== Mapping attribute - column names
+  
+If a column name can't be simply mapped to attribute model, you can pass a map to.    
+If, with the last spreadsheet example, "First name" column had "Prenom" instead as title and you want this column
+to map :first_name attribute of User model, do like this :
+
+   users = User.from_excel sheet, :mapping => {:first_name => 'Prenom'}
+
+== Spreadsheet whithout columns title
+
+Suppose your spreadsheet has no columns title.
+You can then map columns <=> model attribute via index of column.
+You can also pass the starting cell of data (the first cell of data (excluded title when there is one))
+
+   users = User.from_excel sheet,  :mapping => {:first_name => 1, :last_name => 2, :age => 3}, :limits => {:start => [2, 1]}
+
+== Limits : Extraction of part of the spreadsheet
+
+If you want to extract just a part of the spreadsheet, just pass start and end limits.
+   users = User.from_excel(sheet, :limits => {:start => [3, 3], :end => [5, 5] })
+
+<b>Note</b> : The row which contains the columns titles (for default attributes mapping) is, here, supposed to be begining
+at [2,3] and end at [2,5] (one row before the first row of data).
+If not, you must pass a mapping with :attribute => column_index
+
+== Object associations handling
+
+Suppose user has one adress of class Adress(:street, :town, :zip_code)
+And you have this spreadsheet :
+        A            B            C      D                  E     F
+  1  First name	Last name	     Age	    Street	          Town	   Zip Code
+  2  Albert	     Einstein	     131	    17 rue de Brest	  Quimper	 29000
+So, you want user with user.adress = Adress.new(:stret => ..., :town => ... , :zip_code => ....)
+Just pass the following mapping :
+
+  mapping = {[:adress, :street] => 'Street', [:adress, :town] => 'Town', [:adress, :zip_code] => 'Zip Code'}
+
+  users = User.from_excel sheet, :mapping => mapping
+
+And you will get :
+
+   users.first.first_name => 'Albert'
+   users.first.adress.street => '17 rue de Brest'
+  
+   users.first.adress => Adress.new(:street => '17 rue de Brest', :town => 'Quimper' .....)
+  
+== Rules 
+
+
+Suppose you have to transform value of cells column to value for your object attribute, make a rule!
+
+For example, in the sheet you have a value that represents an association attribute id:
+You have roles predifined in your database :
+ Roles :
+  id : 1 , name => 'Admin'
+  id : 2 , name => 'Reader' ....
+
+  Sheet :
+
+    First name	Last name	Rôle
+    Bobby	      Lapointe	Admin
+    Gaston	     Lagaffe	Reader
+
+  
+'Admin' value must be retrieved as a Role with id 1 
+Make the rules like that :
+
+  rules = {[:role, :id] => rule}
+
+Where rule is a Proc.
+
+  mapping = {[:role, :id] => 'Rôle'}
+  rules = {[:role, :id] => rule}
+  users = User.from_excel sheet, :mapping => mapping, :rules => rules
+
+
+  def rule
+    lambda do |cell_value|
+      case cell_value
+      when 'Admin' then 1
+      when 'Reader' then 2
+      end
+    end
+  end
+  
+  
+That's it !
+You get user.first.role => Role(:id => 1) 
+   
+You may use rules for other purpose. Rule proc aim to transform value sheet cell to value you need for
+your model.
+   
+   
+
+== TO DO
+
+Option for other spreadsheet than Excel (LibreOffice ...)
+Handle has_many associations

data/lib/excel_import.rb

@@ -0,0 +1,166 @@
+module ExcelImport
+  
+  class Bounds
+    DEFAULT_OFFSET_FROM_TITLE = 1
+    
+    attr_accessor :first_row, :last_row, :first_column, :last_column, :offset_from_title
+    
+    def initialize sheet, options={} 
+      @options = options
+      @offset_from_title = title_offset
+      bounds(sheet)
+    end
+    
+    def bounds sheet
+      limits = @options[:limits] || limits_from(sheet)
+      @first_column =  limits[:start] ? limits[:start][1] : sheet.first_column 
+      @first_row = limits[:start] ? limits[:start][0] : sheet.first_row + offset_from_title
+      @last_column = limits[:end] ? limits[:end][1] : sheet.last_column
+      @last_row = limits[:end] ? limits[:end][0] : sheet.last_row
+    end
+    
+    def limits_from sheet
+      {:start => [sheet.first_row + offset_from_title, sheet.first_column], :end => [sheet.last_row, sheet.last_column]}
+    end
+    
+    def title_offset
+      @options[:title] = true if @options[:title].nil?
+      @options[:title] ?  @options[:offset_from_title] || DEFAULT_OFFSET_FROM_TITLE : 0
+    end
+    
+  end
+  
+  class Mapping
+    
+    attr_accessor :map, :has_one_associations
+    
+    def initialize sheet, map, bounds
+      @map = map
+      @sheet = sheet
+      @bounds = bounds 
+      @map ? indexation : default
+      @has_one_associations = extract_has_one_associations
+    end
+    
+    def extract_has_one_associations
+      @map.inject({}) do |associations, (attribute, index)|
+        next(associations) unless attribute.is_a?(Array)
+        association = attribute.first
+        next(associations) if associations.has_key?(association)
+        associations.merge({association => klass_of(association)})
+      end
+    end
+    
+    def attributes_of association
+      @map.select {|attribute,| attribute.is_a?(Array) && attribute.first == association}
+    end
+    
+    def indexation
+      return self if @map.all? {|key, value| value.is_a?(Integer)}
+      @bounds.first_column.upto(@bounds.last_column) do |index|
+        @map[attribute column_name_at(index)] = index
+      end
+      self
+    end
+    
+    def default
+      @map = {}
+      @bounds.first_column.upto(@bounds.last_column) do |index|
+        @map[Mapping.default_attribute_for column_name_at(index)] = index
+      end
+    end
+    
+    def attribute column
+      @map.each_pair {|key, value| return key if value == column}
+      Mapping.default_attribute_for(column)
+    end
+    
+    def column_name_at column_index
+        @sheet.cell(@bounds.first_row - @bounds.offset_from_title, column_index)
+     end
+    
+    def self.default_attribute_for column_name
+      column_name.downcase.gsub(' ', '_').to_sym
+    end
+    
+    private
+    
+    def klass_of attribute
+      attribute.to_s.camelize.constantize 
+    end
+ 
+  end
+  
+  class Rules
+    
+    def initialize rules
+      @rules = rules || {}
+    end
+    
+    def for attribute
+      @rules[attribute] || default
+    end
+    
+    def default
+      lambda {|value| value}
+    end
+    
+  end
+ 
+  class Integrator
+    
+    def initialize sheet, klass, options
+      @sheet = sheet
+      @klass = klass
+      @bounds = Bounds.new(sheet, options)
+      @rules = Rules.new(options[:rules])
+      @mapping = Mapping.new(sheet, options[:mapping], @bounds)
+    end
+    
+    def cell_value row_index, column_index
+      @rules.for(@mapping.attribute(column_index)).call(@sheet.cell(row_index, column_index))
+    end
+    
+    def primary_attributes_hash row_index
+      @mapping.map.select{|attribute,| attribute.is_a? Symbol}.inject({}) do |hash, (attribute, index)|
+        hash[attribute] = cell_value(row_index, index)
+        hash
+      end
+    end
+    
+    def object_from_columns_for_association association, row_index, klass
+      attributes = @mapping.attributes_of(association)
+      attributes.inject(klass.new) do |object, ((association, attribute), index)|
+        object.send(attribute.to_s + '=', cell_value(row_index, index))
+        object
+      end
+    end
+    
+    def has_one_associations_attributes_hash row_index
+      @mapping.has_one_associations.inject({}) do |hash, (association, klass)|
+        hash[association] = object_from_columns_for_association(association, row_index, klass)
+        hash
+      end
+    end
+    
+    def row_to_hash row_index
+      hash = primary_attributes_hash(row_index)
+      hash.merge(has_one_associations_attributes_hash row_index)
+    end
+    
+    def rows_to_objects
+      @bounds.first_row.upto(@bounds.last_row).inject([]) {|objects, row_index| objects << @klass.new(row_to_hash(row_index)); objects}
+    end
+    
+  end
+  
+  def self.included(base)
+    class << base
+      def from_excel spreadsheet, opt={}
+        integrator = Integrator.new(Excel.new(spreadsheet.path), self, opt)
+        integrator.rows_to_objects
+      end
+    end
+  end
+  
+end

data/lib/from_excel.rb

@@ -0,0 +1,5 @@
+require 'nokogiri'
+require 'roo'
+require 'rubygems'
+require 'active_support/inflector'
+require 'excel_import'

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '../lib/from_excel')
+
+require 'model/user'
+require 'model/adress'
+require 'model/role'
+
+
+require 'mocha'

data/test/model/adress.rb

@@ -0,0 +1,17 @@
+class Adress
+  attr_accessor :street, :town, :zip_code
+  
+  def initialize args={}
+    @street = args[:street]
+    @town = args[:town]
+    @zip_code = args[:zip_code]
+  end
+  
+  def ==(other)
+    return false unless other
+    street == other.street &&
+    town == other.town &&
+    zip_code == other.zip_code
+  end
+  
+end

data/test/model/role.rb

@@ -0,0 +1,13 @@
+class Role
+  attr_accessor :id, :title
+  
+  def initialize args={}
+    @id = args[:id]
+    @name = args[:title]
+  end
+  
+  def ==(other)
+    id == other.id
+  end
+  
+end

data/test/model/user.rb

@@ -0,0 +1,21 @@
+class User
+  include ExcelImport
+  attr_accessor :first_name, :last_name, :age, :adress, :role
+  
+  def initialize args={}
+    @first_name = args[:first_name]
+    @last_name = args[:last_name]
+    @age = args[:age]
+    @adress = args[:adress]
+    @role = args[:role]
+  end
+  
+  def ==(other)
+    first_name == other.first_name &&
+    last_name == other.last_name &&
+    age == other.age &&
+    adress == other.adress &&
+    role == other.role
+  end
+  
+end

data/test/test_bounds.rb

@@ -0,0 +1,68 @@
+require 'helper'
+
+class TestBounds < Test::Unit::TestCase
+  
+  
+  def test_default_bounds
+    sheet = stubbed_sheet_with_bounds
+    bounds = ExcelImport::Bounds.new(sheet)
+    assert_equal 1, bounds.first_column
+    assert_equal 10, bounds.last_column
+    assert_equal 2, bounds.first_row #have a title line by default so first row is after title line
+    assert_equal 10, bounds.last_row
+  end
+  
+  def test_bounds_with_limits_changed
+    sheet = stub
+    bounds = ExcelImport::Bounds.new(sheet, :limits => {:start => [3, 4], :end => [5, 20]})
+    assert_equal 4, bounds.first_column
+    assert_equal 20, bounds.last_column
+    assert_equal 3, bounds.first_row
+    assert_equal 5, bounds.last_row
+  end
+  
+  def test_bounds_without_title_for_columns
+    sheet = stubbed_sheet_with_bounds
+    bounds = ExcelImport::Bounds.new(sheet, :title => false)
+    assert_equal 1, bounds.first_column
+    assert_equal 10, bounds.last_column
+    assert_equal 1, bounds.first_row # No title so first row is the first row of sheet
+    assert_equal 10, bounds.last_row
+  end
+  
+  def test_bounds_with_only_start_key_should_take_sheet_end_cell_coordinates
+    sheet = stubbed_sheet_with_bounds
+    bounds = ExcelImport::Bounds.new(sheet, :limits => {:start => [3, 4]})
+    assert_equal 4, bounds.first_column
+    assert_equal 10, bounds.last_column
+    assert_equal 3, bounds.first_row
+    assert_equal 10, bounds.last_row
+  end
+  
+  def test_bounds_with_only_end_key_should_take_sheet_start_cell_coordinates_with_1_added_to_first_row_if_title
+    sheet = stubbed_sheet_with_bounds
+    bounds = ExcelImport::Bounds.new(sheet, :limits => {:end => [10, 5]})
+    assert_equal 1, bounds.first_column
+    assert_equal 5, bounds.last_column
+    assert_equal 2, bounds.first_row
+    assert_equal 10, bounds.last_row
+  end
+  
+  def test_bounds_with_offset_from_title
+    sheet = stubbed_sheet_with_bounds
+    bounds = ExcelImport::Bounds.new(sheet, :offset_from_title => 4)
+    assert_equal 1, bounds.first_column
+    assert_equal 10, bounds.last_column
+    assert_equal 5, bounds.first_row
+    assert_equal 10, bounds.last_row
+  end
+  
+  
+  
+  private
+  
+  def stubbed_sheet_with_bounds
+    stub(:first_column => 1, :last_column => 10, :first_row => 1, :last_row => 10)
+  end
+  
+end

data/test/test_from_excel.rb

@@ -0,0 +1,84 @@
+require 'helper'
+
+class TestFromExcel < Test::Unit::TestCase
+  SIMPLE_SHEET= File.join(File.dirname(__FILE__), 'spreadsheets/simple_sheet.xls')
+  SHEET_WITH_COLUMN_NAME_DIFFERENT_FROM_ATTRIBUTE = File.join(File.dirname(__FILE__), 'spreadsheets/sheet_with_column_name_different_from_attribute.xls')
+  SHEET_WITHOUT_COLUMNS_NAMES =  File.join(File.dirname(__FILE__), 'spreadsheets/sheet_without_columns_names.xls')
+  SHEET_WITH_START_END_COLUMNS_ROWS =  File.join(File.dirname(__FILE__), 'spreadsheets/sheet_with_start_end_columns_rows.xls')
+  SHEET_WITH_COLUMNS_FROM_ASSOCIATION = File.join(File.dirname(__FILE__), 'spreadsheets/sheet_with_columns_from_association.xls')
+  SHEET_WITH_COLUMN_VALUE_TO_ASSOCIATION_ID = File.join(File.dirname(__FILE__), 'spreadsheets/sheet_with_column_value_to_association_id.xls')
+
+  def test_import_with_simple_sheet
+    assert users = User.from_excel(File.new SIMPLE_SHEET)
+    assert_equal sheet_users, users
+  end
+  
+  def test_import_with_simple_sheet_with_some_attributes_mapped_with_columns_names
+    sheet = File.new(SHEET_WITH_COLUMN_NAME_DIFFERENT_FROM_ATTRIBUTE)
+    users = User.from_excel sheet, :mapping => {:first_name => 'Prenom'}
+    assert_equal sheet_users, users
+  end
+  
+  def test_should_be_able_to_import_with_attributes_mapped_with_columns_index
+    sheet =  File.new(SHEET_WITHOUT_COLUMNS_NAMES)
+    users = User.from_excel sheet,  :mapping => {:first_name => 1, :last_name => 2, :age => 3},
+                                    :limits => {:start => [2, 1]}
+    assert_equal sheet_users, users
+  end
+  
+  def test_should_be_able_to_import_simple_sheet_with_given_start_and_end_columns_and_rows
+    assert users = User.from_excel(File.new(SHEET_WITH_START_END_COLUMNS_ROWS), :limits => {:start => [3, 3], :end => [5, 5] })
+    assert_equal sheet_users, users
+  end
+  
+  def test_should_import_columns_on_associations_attributes_with_mapping_on_columns_names
+    sheet =  File.new(SHEET_WITH_COLUMNS_FROM_ASSOCIATION)
+    mapping = {[:adress, :street] => 'Street', [:adress, :town] => 'Town', [:adress, :zip_code] => 'Zip Code'}
+    users = User.from_excel sheet, :mapping => mapping
+
+    assert_equal users_with_adresses, users
+  end
+  
+  def test_should_be_able_to_apply_rule_on_column_cells_to_transform_data_from_sheet_to_object_attribute_value
+    sheet =  File.new(SHEET_WITH_COLUMN_VALUE_TO_ASSOCIATION_ID)
+    mapping = {[:role, :id] => 'Rôle'}
+    rules = {[:role, :id] => rule_to_retrieve_id}
+    users = User.from_excel sheet, :mapping => mapping, :rules => rules
+    
+    assert_equal users_with_role, users
+  end
+  
+  private
+  
+  def rule_to_retrieve_id
+    lambda do |cell_value|
+      case cell_value
+      when 'Admin' then 1
+      when 'Reader' then 2
+      end
+    end
+  end
+  
+  def sheet_users
+   [User.new(:first_name => 'Albert', :last_name =>	'Einstein', :age => 131),
+    User.new(:first_name => 'Leonard', :last_name =>	'De Vinci', :age => 558),
+    User.new(:first_name => 'Martin', :last_name =>	'Heidegger', :age => 121)]
+  end
+  
+  def users_with_adresses
+    adresses = [ Adress.new(:street => '17 rue de Brest', :town => 'Quimper', :zip_code => 29000),
+                 Adress.new(:street => '26 rue des Lilas', :town => 'Paris', :zip_code => 75017),
+                 Adress.new(:street => '13 rue du port', :town => 'Vannes', :zip_code => 56000)]
+    users = sheet_users             
+    users.each_with_index {|user, index| user.adress = adresses[index]}
+    users
+  end
+  
+  def users_with_role
+    [ User.new(:first_name => 'Bobby', :last_name =>	'Lapointe', :role => Role.new(:id => 1)),
+      User.new(:first_name => 'Gaston', :last_name =>	'Lagaffe', :role => Role.new(:id => 2)) ]
+  end
+  
+  
+  
+end

data/test/test_mapping.rb

@@ -0,0 +1,55 @@
+require 'helper'
+
+class TestMapping < Test::Unit::TestCase
+  
+  def test_mapping_should_make_default_attribute_name_from_columns_title
+    sheet = stubbed_sheet
+    bounds = ExcelImport::Bounds.new(sheet)
+    mapping = ExcelImport::Mapping.new(sheet, {}, bounds )
+
+    assert_equal :first_name, mapping.attribute('First Name')
+    assert_equal :last_name, mapping.attribute('Last Name')
+  end
+  
+  def test_mapping_should__attribute_name
+    sheet = stubbed_sheet
+    bounds = ExcelImport::Bounds.new(sheet)
+    mapping = ExcelImport::Mapping.new(sheet, {:name => 'First Name'}, bounds )
+
+    assert_equal :name, mapping.attribute(1)
+  end
+  
+  def test_should_handle_association_attributes
+    sheet = stubbed_sheet_with_adress_columns
+    mapping = {[:adress, :street] => 'Street', [:adress, :town] => 'Town'}
+    bounds = ExcelImport::Bounds.new(sheet)
+    mapping = ExcelImport::Mapping.new(sheet, mapping, bounds )
+
+    assert_equal [:adress, :street], mapping.attribute(4)
+    assert_equal [:adress, :town], mapping.attribute(5)
+    assert_equal 5, mapping.map[[:adress, :town]]
+    assert_equal ({:adress => Adress}), mapping.has_one_associations
+    
+  end
+  
+  private
+  
+  def stubbed_sheet
+    sheet = stub(:first_column => 1, :last_column => 3, :first_row => 1, :last_row => 2)
+    sheet.stubs(:cell).with(1,1).returns('First Name')
+    sheet.stubs(:cell).with(1,2).returns('Last Name')
+    sheet.stubs(:cell).with(1,3).returns('Age')
+    sheet
+  end
+  
+  def stubbed_sheet_with_adress_columns
+    sheet = stub(:first_column => 1, :last_column => 5, :first_row => 1, :last_row => 2)
+    sheet.stubs(:cell).with(1,1).returns('First Name')
+    sheet.stubs(:cell).with(1,2).returns('Last Name')
+    sheet.stubs(:cell).with(1,3).returns('Age')
+    sheet.stubs(:cell).with(1,4).returns('Street')
+    sheet.stubs(:cell).with(1,5).returns('Town')
+    sheet
+  end
+  
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: from_excel
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Philippe Cantin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-08 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Import Excel spreadsheet rows to ruby objects
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/excel_import.rb
+- lib/from_excel.rb
+- README.rdoc
+- test/helper.rb
+- test/model/adress.rb
+- test/model/role.rb
+- test/model/user.rb
+- test/test_bounds.rb
+- test/test_from_excel.rb
+- test/test_mapping.rb
+has_rdoc: true
+homepage: http://github.com/anoiaque/from_excel
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Import Excel spreadsheet rows to ruby objects
+test_files: 
+- test/helper.rb
+- test/model/adress.rb
+- test/model/role.rb
+- test/model/user.rb
+- test/test_bounds.rb
+- test/test_from_excel.rb
+- test/test_mapping.rb