csv-mapper 0.0.4 → 0.5.0

data/lib/csv-mapper/attribute_map.rb

@@ -0,0 +1,55 @@
+module CsvMapper
+  # A CsvMapper::AttributeMap contains the instructions to parse a value from a CSV row and to know the
+  # name of the attribute it is targeting.
+  class AttributeMap
+    attr_reader :name, :index
+  
+    # Creates a new instance using the provided attribute +name+, CSV row +index+, and evaluation +map_context+
+    def initialize(name, index, map_context)
+      @name, @index, @map_context = name, index, map_context
+    end
+  
+    # Set the index that this map is targeting.
+    #
+    # Returns this AttributeMap for chainability
+    def at(index)
+      @index = index
+      self
+    end
+  
+    # Provide a lambda or the symbol name of a method on this map's evaluation context to be used when parsing
+    # the value from a CSV row.  
+    # Both the lambda or the method provided should accept a single +row+ parameter
+    #
+    # Returns this AttributeMap for chainability
+    def map(transform=nil, &block_transform)
+      @transformer = block_transform || transform
+      self
+    end
+  
+    # Given a CSV row, return the value at this AttributeMap's index using any provided map transforms (see map)
+    def parse(csv_row)
+      @transformer ? parse_transform(csv_row) : raw_value(csv_row)
+    end
+  
+    # Access the raw value of the CSV row without any map transforms applied.
+    def raw_value(csv_row)
+      csv_row[self.index]
+    end
+  
+    private
+  
+    def parse_transform(csv_row)
+      if @transformer.is_a? Symbol
+        transform_name = @transformer
+        @transformer = lambda{|row, index| @map_context.send(transform_name, row, index) }
+      end
+    
+      if @transformer.arity == 1
+        @transformer.call(csv_row) 
+      else
+        @transformer.call(csv_row, @index)
+      end
+    end
+end
+end

data/lib/csv-mapper/row_map.rb

@@ -0,0 +1,179 @@
+require 'csv-mapper/attribute_map'
+
+module CsvMapper
+  # CsvMapper::RowMap provides a simple, DSL-like interface for constructing mappings.
+  # A CsvMapper::RowMap provides the main functionality of the library. It will mostly be used indirectly through the CsvMapper API, 
+  # but may be useful to use directly for the dynamic CSV mappings.
+  class RowMap
+    #Start with a 'blank slate'
+    instance_methods.each { |m| undef_method m unless m =~ /^__||instance_eval/ }
+  
+    Infinity = 1.0/0
+    attr_reader :mapped_attributes
+  
+    # Create a new instance with access to an evaluation context 
+    def initialize(context, csv_data = nil, &map_block)
+      @context = context
+      @csv_data = csv_data
+      @before_filters = []
+      @after_filters = []
+      @parser_options = {}
+      @start_at_row = 0
+      @stop_at_row = Infinity
+      @delimited_by = FasterCSV::DEFAULT_OPTIONS[:col_sep]
+      @mapped_attributes = []
+    
+      self.instance_eval(&map_block) if block_given?
+    end
+  
+    # Each row of a CSV is parsed and mapped to a new instance of a Ruby class; Struct by default.
+    # Use this method to change the what class each row is mapped to.  
+    # The given class must respond to a parameter-less #new and all attribute mappings defined.
+    # Providing a hash of defaults will ensure that each resulting object will have the providing name and attribute values 
+    # unless overridden by a mapping
+    def map_to(klass, defaults={})
+      @map_to_klass = klass
+    
+      defaults.each do |name, value|
+        self.add_attribute(name, -99).map lambda{|row, index| value}
+      end
+    end
+  
+    # Allow us to read the first line of a csv file to automatically generate the attribute names.
+    # Spaces are replaced with underscores and non-word characters are removed.
+    #
+    # Keep in mind that there is potential for overlap in using this (i.e. you have a field named
+    # files+ and one named files- and they both get named 'files').
+    #
+    # You can specify aliases to rename fields to prevent conflicts and/or improve readability and compatibility.
+    #
+    # i.e. read_attributes_from_file('files+' => 'files_plus', 'files-' => 'files_minus)
+    def read_attributes_from_file aliases = {}
+      attributes = FasterCSV.new(@csv_data, @parser_options).readline
+      @start_at_row = [ @start_at_row, 1 ].max
+      @csv_data.rewind
+      attributes.each_with_index do |name, index|
+        name.strip!
+        use_name = aliases[name] || name.gsub(/\s+/, '_').gsub(/[\W]+/, '').downcase
+        add_attribute use_name, index
+      end
+    end
+
+    # Specify a hash of FasterCSV options to be used for CSV parsing
+    #
+    # Can be anything FasterCSV::new()[http://fastercsv.rubyforge.org/classes/FasterCSV.html#M000018] accepts
+    def parser_options(opts=nil)
+      @parser_options = opts if opts
+      @parser_options.merge :col_sep => @delimited_by 
+    end
+  
+    # Convenience method to 'move' the cursor skipping the current index.
+    def _SKIP_
+      self.move_cursor
+    end
+  
+    # Specify the CSV column delimiter. Defaults to comma.
+    def delimited_by(delimiter=nil)
+      @delimited_by = delimiter if delimiter
+      @delimited_by
+    end
+  
+    # Declare what row to begin parsing the CSV.
+    # This is useful for skipping headers and such.
+    def start_at_row(row_number=nil)
+      @start_at_row = row_number if row_number
+      @start_at_row
+    end
+  
+    # Declare the last row to be parsed in a CSV.
+    def stop_at_row(row_number=nil)
+      @stop_at_row = row_number if row_number
+      @stop_at_row
+    end
+  
+    # Declare method name symbols and/or lambdas to be executed before each row.
+    # Each method or lambda must accept to parameters: +csv_row+, +target_object+
+    # Methods names should refer to methods available within the RowMap's provided context
+    def before_row(*befores)
+      self.add_filters(@before_filters, *befores)
+    end
+  
+    # Declare method name symbols and/or lambdas to be executed before each row.
+    # Each method or lambda must accept to parameters: +csv_row+, +target_object+
+    # Methods names should refer to methods available within the RowMap's provided context
+    def after_row(*afters)
+      self.add_filters(@after_filters, *afters)
+    end
+  
+    # Add a new attribute to this map.  Mostly used internally, but is useful for dynamic map creation.
+    # returns the newly created CsvMapper::AttributeMap
+    def add_attribute(name, index=nil)
+      attr_mapping = CsvMapper::AttributeMap.new(name.to_sym, index, @context)
+      self.mapped_attributes << attr_mapping
+      attr_mapping
+    end      
+  
+    # The current cursor location
+    def cursor  # :nodoc:
+      @cursor ||= 0
+    end
+  
+    # Move the cursor relative to it's current position
+    def move_cursor(positions=1) # :nodoc:
+      self.cursor += positions
+    end
+  
+    # Given a CSV row return an instance of an object defined by this mapping
+    def parse(csv_row)
+      target = self.map_to_class.new
+      @before_filters.each {|filter| filter.call(csv_row, target) }
+      
+      self.mapped_attributes.each do |attr_map|
+        target.send("#{attr_map.name}=", attr_map.parse(csv_row))
+      end
+    
+      @after_filters.each {|filter| filter.call(csv_row, target) }
+    
+      return target
+    end
+  
+    protected # :nodoc:
+  
+    # The Hacktastic "magic"
+    # Used to dynamically create CsvMapper::AttributeMaps based on unknown method calls that 
+    # should represent the names of mapped attributes.
+    #
+    # An optional first argument is used to move this maps cursor position and as the index of the
+    # new AttributeMap
+    def method_missing(name, *args) # :nodoc:
+    
+      if index = args[0]
+        self.move_cursor(index - self.cursor)
+      else
+        index = self.cursor
+        self.move_cursor
+      end
+    
+      add_attribute(name, index)
+    end
+  
+    def add_filters(to_hook, *filters) # :nodoc:
+      (to_hook << filters.collect do |filter|
+        filter.is_a?(Symbol) ? lambda{|row, target| @context.send(filter, row, target)} : filter
+      end).flatten!
+    end
+          
+    def map_to_class # :nodoc:
+      unless @map_to_klass
+        attrs = mapped_attributes.collect {|attr_map| attr_map.name}
+        @map_to_klass = Struct.new(nil, *attrs)
+      end
+      
+      @map_to_klass
+    end
+  
+    def cursor=(value) # :nodoc:
+      @cursor=value
+    end
+  end
+end

data/spec/{csv-mapper_attribute_map_spec.rb → csv-mapper/csv-mapper_attribute_map_spec.rb}

@@ -1,9 +1,9 @@
-require File.dirname(__FILE__) + '/spec_helper.rb'
+require File.dirname(__FILE__) + '/../spec_helper.rb'
 
 describe CsvMapper::AttributeMap do
   
   class TestContext
-    def transform_it(row)
+    def transform_it(row, index)
       :transform_it_success
     end
   end
@@ -34,11 +34,26 @@ describe CsvMapper::AttributeMap do
     @row_attr.parse(@csv_row).should == @csv_row[1]
   end
 
-  it "should parse values using mapped transformer" do
+  it "should parse values using a mapped lambda transformers" do
+    @row_attr.map( lambda{|row, index| :success } )
+    @row_attr.parse(@csv_row).should == :success
+  end
+
+  it "should parse values using a mapped lambda transformer that only accepts the row" do
     @row_attr.map( lambda{|row| :success } )
     @row_attr.parse(@csv_row).should == :success
   end
   
+  it "should parse values using a mapped block transformers" do
+    @row_attr.map {|row, index| :success }
+    @row_attr.parse(@csv_row).should == :success
+  end
+
+  it "should parse values using a mapped block transformer that only accepts the row" do
+    @row_attr.map {|row, index| :success }
+    @row_attr.parse(@csv_row).should == :success
+  end
+  
   it "should parse values using a named method on the context" do
     @row_attr.map(:transform_it).parse(@csv_row).should == :transform_it_success
   end
@@ -47,4 +62,4 @@ describe CsvMapper::AttributeMap do
     @row_attr.raw_value(@csv_row).should be(@csv_row[@row_attr.index])
   end
   
-end
+end

data/spec/{csv-mapper_row_map_spec.rb → csv-mapper/csv-mapper_row_map_spec.rb}

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/spec_helper.rb'
+require File.dirname(__FILE__) + '/../spec_helper.rb'
 
 describe CsvMapper::RowMap do
   
@@ -7,7 +7,7 @@ describe CsvMapper::RowMap do
   end
   
   class TestMapContext
-    def transform(row)
+    def transform(row, index)
       :transform_success
     end
     
@@ -25,8 +25,8 @@ describe CsvMapper::RowMap do
     @row_map.parse(@csv_row).should_not be_nil
   end
 
-  it "should map to a OpenStruct by default" do
-    @row_map.parse(@csv_row).should be_instance_of(OpenStruct)
+  it "should map to a Struct by default" do
+    @row_map.parse(@csv_row).should be_kind_of(Struct)
   end
   
   it "should parse a CSV row returning the mapped result" do
@@ -78,9 +78,11 @@ describe CsvMapper::RowMap do
   end
   
   it "should allow after row processing" do
-    @row_map.after_row lambda{|row, target| target.bam = :woot}
+    filter_var = nil
+    @row_map.after_row lambda{|row, target| filter_var = :woot}
     
-    @row_map.parse(@csv_row).bam.should == :woot
+    @row_map.parse(@csv_row)
+    filter_var.should == :woot
   end
   
   it "should have a moveable cursor" do
@@ -124,7 +126,7 @@ describe CsvMapper::RowMap do
     @row_map.cursor.should be(1)
   end
   
-  it "should share it context with its mappings" do
+  it "should share its context with its mappings" do
     @row_map.first_name.map(:transform)
     @row_map.parse(@csv_row).first_name.should == :transform_success
   end

data/spec/csv-mapper_spec.rb

@@ -1,76 +1,173 @@
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
-include CsvMapper
-
 describe CsvMapper do
-    
-  before(:each) do    
-    @mapped_klass = Class.new { include CsvMapper }
-    @mapped = @mapped_klass.new
-  end
+  describe "included" do
+    before(:each) do    
+      @mapped_klass = Class.new do
+         include CsvMapper
+         def upcase_name(row, index)
+           row[index].upcase
+         end
+       end
+      @mapped = @mapped_klass.new
+    end
 
-  it "should allow the creation of CSV mappings" do
-    mapping = @mapped.map_csv do
-      start_at_row 2      
+    it "should allow the creation of CSV mappings" do
+      mapping = @mapped.map_csv do
+        start_at_row 2      
+      end
+    
+      mapping.should be_instance_of(CsvMapper::RowMap)
+      mapping.start_at_row.should == 2
     end
+  
+    it "should import a CSV IO" do
+      io = 'foo,bar,00,01'
+      results = @mapped.import(io, :type => :io) do 
+        first
+        second
+      end
     
-    mapping.should be_instance_of(CsvMapper::RowMap)
-    mapping.start_at_row.should == 2
-  end
+      results.should be_kind_of(Enumerable)
+      results.should have(1).things
+      results[0].first.should == 'foo'
+      results[0].second.should == 'bar'
+    end
   
-  it "should import a CSV IO" do
-    io = 'foo,bar,00,01'
-    results = @mapped.import(io, :type => :io) do 
-      first
-      second
+    it "should import a CSV File IO" do
+      results = @mapped.import(File.dirname(__FILE__) + '/test.csv') do
+        start_at_row 1
+        [first_name, last_name, age]
+      end
+    
+      results.size.should == 3
+    end 
+  
+    it "should stop importing at a specified row" do
+      results = @mapped.import(File.dirname(__FILE__) + '/test.csv') do
+        start_at_row 1
+        stop_at_row 2
+        [first_name, last_name, age]
+      end
+
+      results.size.should == 2
+    end
+
+    it "should be able to read attributes from a csv file" do
+      results = @mapped.import(File.dirname(__FILE__) + '/test.csv') do
+        # we'll alias age here just as an example
+        read_attributes_from_file('Age' => 'number_of_years_old')
+      end
+      results[1].first_name.should == 'Jane'
+      results[1].last_name.should == 'Doe'
+      results[1].number_of_years_old.should == '26'
+    end
+
+    it "should import non-comma delimited files" do
+      piped_io = 'foo|bar|00|01'
+    
+      results = @mapped.import(piped_io, :type => :io) do
+        delimited_by '|'
+        [first, second]
+      end
+    
+      results.should have(1).things
+      results[0].first.should == 'foo'
+      results[0].second.should == 'bar'
     end
     
-    results.should be_kind_of(Enumerable)
-    results.should have(1).things
-    results[0].first.should == 'foo'
-    results[0].second.should == 'bar'
+    it "should allow named tranformation mappings" do
+      def upcase_name(row)
+        row[0].upcase
+      end
+      
+      results = @mapped.import(File.dirname(__FILE__) + '/test.csv') do
+        start_at_row 1
+        
+        first_name.map :upcase_name
+      end
+      
+      results[0].first_name.should == 'JOHN'
+    end
   end
   
-  it "should import a CSV File IO" do
-    results = import(File.dirname(__FILE__) + '/test.csv') do
-      start_at_row 1
-      [first_name, last_name, age]
-    end
+  describe "extended" do
+    it "should allow the creation of CSV mappings" do
+      mapping = CsvMapper.map_csv do
+        start_at_row 2      
+      end
     
-    results.size.should == 3
-  end 
+      mapping.should be_instance_of(CsvMapper::RowMap)
+      mapping.start_at_row.should == 2
+    end
   
-  it "should stop importing at a specified row" do
-    results = import(File.dirname(__FILE__) + '/test.csv') do
-      start_at_row 1
-      stop_at_row 2
-      [first_name, last_name, age]
+    it "should import a CSV IO" do
+      io = 'foo,bar,00,01'
+      results = CsvMapper.import(io, :type => :io) do 
+        first
+        second
+      end
+    
+      results.should be_kind_of(Enumerable)
+      results.should have(1).things
+      results[0].first.should == 'foo'
+      results[0].second.should == 'bar'
     end
+  
+    it "should import a CSV File IO" do
+      results = CsvMapper.import(File.dirname(__FILE__) + '/test.csv') do
+        start_at_row 1
+        [first_name, last_name, age]
+      end
+    
+      results.size.should == 3
+    end 
+  
+    it "should stop importing at a specified row" do
+      results = CsvMapper.import(File.dirname(__FILE__) + '/test.csv') do
+        start_at_row 1
+        stop_at_row 2
+        [first_name, last_name, age]
+      end
 
-    results.size.should == 2
-  end
+      results.size.should == 2
+    end
 
-  it "should be able to read attributes from a csv file" do
-    results = import(File.dirname(__FILE__) + '/test.csv') do
-      # we'll alias age here just as an example
-      read_attributes_from_file('Age' => 'number_of_years_old')
+    it "should be able to read attributes from a csv file" do
+      results = CsvMapper.import(File.dirname(__FILE__) + '/test.csv') do
+        # we'll alias age here just as an example
+        read_attributes_from_file('Age' => 'number_of_years_old')
+      end
+      results[1].first_name.should == 'Jane'
+      results[1].last_name.should == 'Doe'
+      results[1].number_of_years_old.should == '26'
     end
-    results[1].first_name.should == 'Jane'
-    results[1].last_name.should == 'Doe'
-    results[1].number_of_years_old.should == '26'
-  end
 
-  it "should import non-comma delimited files" do
-    piped_io = 'foo|bar|00|01'
+    it "should import non-comma delimited files" do
+      piped_io = 'foo|bar|00|01'
     
-    results = import(piped_io, :type => :io) do
-      delimited_by '|'
-      [first, second]
+      results = CsvMapper.import(piped_io, :type => :io) do
+        delimited_by '|'
+        [first, second]
+      end
+    
+      results.should have(1).things
+      results[0].first.should == 'foo'
+      results[0].second.should == 'bar'
     end
     
-    results.should have(1).things
-    results[0].first.should == 'foo'
-    results[0].second.should == 'bar'
+    it "should not allow tranformation mappings" do
+      def upcase_name(row)
+        row[0].upcase
+      end
+      
+      (lambda do 
+        results = CsvMapper.import(File.dirname(__FILE__) + '/test.csv') do
+          start_at_row 1
+        
+          first_name.map :upcase_name
+        end
+      end).should raise_error(Exception)
+    end
   end
-  
 end