artforge-csv-mapper 1.0.1

data/History.txt

@@ -0,0 +1,25 @@
+== 0.5.0 2010-05-12
+* Parsing performance is now approximately 8x-10x faster when not specifying a custom map_to class.
+* Default class mapping is now Struct instead of OpenStruct
+* Recommended usage is now "CsvMapper.import(...)"
+  * Fixes recurring problem with using CsvMapper in rake tasks
+  * Keeps everything a little cleaner
+* #map transformations now prefer blocks over lambdas or symbols. 
+* Converted from using newgem to jeweler for managing the library itself.
+
+== 0.0.4 2009-08-05
+* Merged contributions from Jeffrey Chupp - http://semanticart.com
+  * Added support for "Automagical Attribute Discovery"
+  * Added Ruby 1.9 compatibility
+
+== 0.0.3 2008-12-22
+* Fixed specs to work with RSpec 1.1.9 and later where Modules aren't auto included
+
+== 0.0.2 2008-12-15
+
+* Added #stop_at_row method to RowMap
+
+== 0.0.1 2008-12-05
+
+* 1 major enhancement:
+  * Initial release

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2009 Luke Pillow
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,90 @@
+= csv-mapper
+
+== DESCRIPTION:
+
+CsvMapper is a small library intended to simplify the common steps involved with importing CSV files to a usable form in Ruby.  CsvMapper is compatible with recent 1.8 versions of Ruby as well as Ruby 1.9+
+
+== EXAMPLES:
+
+The following example will import a CSV file to an Array of Struct[http://www.ruby-doc.org/core/classes/Struct.html] instances.
+
+==== Example CSV File Structure
+
+  First Name,Last Name,Age
+  John,Doe,27
+  Jane,Doe,26
+  Bat,Man,52
+  ...etc...
+
+==== Simple Usage Example
+  results = CsvMapper.import('/path/to/file.csv') do
+    start_at_row 1
+    [first_name, last_name, age]
+  end
+
+  results.first.first_name  # John
+  results.first.last_name   # Doe
+  results.first.age         # 27
+
+==== Automagical Attribute Discovery Example
+  results = CsvMapper.import('/path/to/file.csv') do
+    read_attributes_from_file
+  end
+
+  results.first.first_name  # John
+  results.first.last_name   # Doe
+  results.first.age         # 27
+
+==== Named Columns Example
+Columns which aren't mentioned won't appear in the results.
+
+  # Don't mention first name
+  results = CsvMapper.import('/path/to/file_with_header_row.csv') do
+    named_columns
+
+    surname('last_name')
+    age
+  end
+
+  results.first.surname     # Doe
+  results.first.age         # 27
+  results.first.first_name  # nil
+  results.first.last_name   # nil
+
+==== Import to ActiveRecord Example
+Although CsvMapper has no dependency on ActiveRecord; it's easy to import a CSV file to ActiveRecord models and save them.
+
+  # Define an ActiveRecord model
+  class Person < ActiveRecord::Base; end
+
+  results = CsvMapper.import('/path/to/file.csv') do
+    map_to Person # Map to the Person ActiveRecord class (defined above) instead of the default Struct.
+    after_row lambda{|row, person| person.save }  # Call this lambda and save each record after it's parsed.
+		
+    start_at_row 1
+    [first_name, last_name, age]
+  end
+	
+See CsvMapper for a more detailed description
+	
+== REQUIREMENTS:
+
+FasterCSV[http://fastercsv.rubyforge.org/] on pre 1.9 versions of Ruby
+
+== INSTALL:
+
+* sudo gem install csv-mapper
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009 Luke Pillow. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "artforge-csv-mapper"
+    gem.summary = %Q{artforge-CsvMapper is a fork of a small library intended to simplify the common steps involved with importing CSV files to a usable form in Ruby. It has support for null column names. When this is merged, this gem will be removed.}
+    gem.description = %Q{CSV Mapper makes it easy to import data from CSV files directly to a collection of any type of Ruby object. The simplest way to create mappings is declare the names of the attributes in the order corresponding to the CSV file column order.}
+    gem.email = "adam@artforge.com"
+    gem.homepage = "http://github.com/Artforge/csv-mapper"
+    gem.authors = ["Luke Pillow", "Russell Garner", "Adam Singer"]
+    gem.add_development_dependency "rspec", ">= 2.0.0"
+    gem.add_dependency "fastercsv"  
+    gem.extra_rdoc_files << "History.txt"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "artforge-csv-mapper #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/lib/csv-mapper.rb

@@ -0,0 +1,131 @@
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
+
+require 'rubygems'
+
+# the following is slightly modified from Gregory Brown's
+# solution on the Ruport Blaag:
+# http://ruport.blogspot.com/2008/03/fastercsv-api-shim-for-19.html
+
+if RUBY_VERSION > "1.9"
+ require "csv"
+ unless defined? FCSV
+   class Object
+     FasterCSV = CSV
+     alias_method :FasterCSV, :CSV
+   end
+ end
+else
+ require "fastercsv"
+end
+
+# This module provides the main interface for importing CSV files & data to mapped Ruby objects.
+# = Usage
+# Including CsvMapper will provide two methods:
+# - +import+
+# - +map_csv+
+#
+# See csv-mapper.rb[link:files/lib/csv-mapper_rb.html] for method docs.
+#
+# === Import From File
+#   results = import('/path/to/file.csv') do
+#     # declare mapping here
+#   end
+#
+# === Import From String or IO
+#   results = import(csv_data, :type => :io) do
+#     # declare mapping here
+#   end
+#
+# === Mapping
+# Mappings are built inside blocks.  All three of CsvMapper's main API methods accept a block containing a mapping.
+# Maps are defined by using +map_to+, +start_at_row+, +before_row+, and +after_row+ (methods on CsvMapper::RowMap) and
+# by defining your own mapping attributes.
+# A mapping block uses an internal cursor to keep track of the order the mapping attributes are declared and use that order to 
+# know the corresponding CSV column index to associate with the attribute.
+# 
+# ===== The Basics
+# * +map_to+ - Override the default Struct target. Accepts a class and an optional hash of default attribute names and values.
+# * +named_columns+ - Enables named columns mode. Headers are required. See "Named Column Mappings" below.
+# * +start_at_row+ - Specify what row to begin parsing at.  Use this to skip headers. When +named_columns+ is used, headers are assumed to be one line above this row.
+# * +before_row+ - Accepts an Array of method name symbols or lambdas to be invoked before parsing each row.
+# * +after_row+ - Accepts an Array of method name symbols or lambdas to be invoked after parsing each row.
+# * +delimited_by+ - Accepts a character to be used to delimit columns. Use this to specify pipe-delimited files.
+# * <tt>\_SKIP_</tt> - Use as a placehold to skip a CSV column index.
+# * +parser_options+ - Accepts a hash of FasterCSV options.  Can be anything FasterCSV::new()[http://fastercsv.rubyforge.org/classes/FasterCSV.html#M000018] understands
+# 
+# ===== Attribute Mappings
+# Attribute mappings are created by using the name of the attribute to be mapped to.  
+# The order in which attribute mappings are declared determines the index of the corresponding CSV row.  
+# All mappings begin at the 0th index of the CSV row.
+#   foo  # maps the 0th CSV row position value to the value of the 'foo' attribute on the target object.
+#   bar  # maps the 1st row position to 'bar'
+# This could also be a nice one liner for easy CSV format conversion
+#   [foo, bar]  # creates the same attribute maps as above.
+# The mapping index may be specifically declared in two additional ways:
+#   foo(2)     # maps the 2nd CSV row position value to 'foo' and moves the cursor to 3
+#   bar        # maps the 3rd CSV row position to 'bar' due to the current cursor position
+#   baz.at(0)  # maps the 0th CSV row position to 'baz' but only increments the cursor 1 position to 4
+# Each attribute mapping may be configured to parse the record using a lambda or a method name
+#   foo.map lambda{|row| row[2].strip } # maps the 2nd row position value with leading and trailing whitespace removed to 'foo'.
+#   bar.map :clean_bar  # maps the result of the clean_bar method to 'bar'. clean_bar must accept the row as a parameter.
+# Attribute mapping declarations and "modifiers" may be chained
+#   foo.at(4).map :some_transform
+#
+# === Named Columns Mappings
+# When +named_columns+ is called, column names will be read from one row above +start_at_row+.  This allows
+# you to map cell properties to named columns in the CSV.  For example:
+#   surname('Last Name') # Where 'Last Name' is the name of a column in the CSV
+#
+# Columns which go unmentioned will be omitted from the results.
+#
+# === Create Reusable Mappings
+# The +import+ method accepts an instance of RowMap as an optional mapping parameter.  
+# The easiest way to create an instance of a RowMap is by using +map_csv+.
+#   a_row_map = map_csv do 
+#     # declare mapping here
+#   end
+# Then you can reuse the mapping
+#   results = import(some_string, :type => :io, :map => a_row_map)
+#   other_results = import('/path/to/file.csv', :map => a_row_map)
+#
+module CsvMapper
+
+  # Create a new RowMap instance from the definition in the given block.
+  def map_csv(&map_block)
+    CsvMapper::RowMap.new(self, &map_block)
+  end
+  
+  # Load CSV data and map the values according to the definition in the given block.
+  # Accepts either a file path, String, or IO as +data+.  Defaults to file path.
+  # 
+  # The following +options+ may be used:
+  # <tt>:type</tt>:: defaults to <tt>:file_path</tt>. Use <tt>:io</tt> to specify data as String or IO.
+  # <tt>:map</tt>:: Specify an instance of a RowMap to take presidence over a given block defintion.
+  #
+  def import(data, options={}, &map_block)
+    csv_data = options[:type] == :io ? data : File.new(data, 'r')
+
+    config = { :type => :file_path,
+               :map => map_csv_with_data(csv_data, &map_block) }.merge!(options)
+
+    map = config[:map]
+    
+    results = []
+    FasterCSV.new(csv_data, map.parser_options ).each_with_index do |row, i|
+      results << map.parse(row) if i >= map.start_at_row && i <= map.stop_at_row
+    end
+    
+    results
+  end  
+
+  protected
+  # Create a new RowMap instance from the definition in the given block and pass the csv_data.
+  def map_csv_with_data(csv_data, &map_block) # :nodoc:
+    CsvMapper::RowMap.new(self, csv_data, &map_block)
+  end
+  
+  extend self
+end
+
+require 'csv-mapper/row_map'

data/lib/csv-mapper/attribute_map.rb

@@ -0,0 +1,59 @@
+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
+
+    def to_s
+      "#{@index}: #{@name}"
+    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,224 @@
+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 :context
+    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 = []
+      @named_columns = false
+      @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 = {}
+      unnamed_number = 1
+      iterate_headers do |name, index|
+        if name.nil?
+          name = "_field_#{unnamed_number}"
+          unnamed_number += 1
+        end
+        name.strip!
+        use_name = aliases[name] || attributize_field_name(name)
+        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
+
+    # Default csv_mapper behaviour is to use the ordinal position of a mapped attribute.
+    # If you prefer to look for a column with the name of the attribute, use this method.
+    def named_columns
+      @named_columns = true
+    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:
+      existing_map = self.mapped_attributes.find {|attr| attr.name == name}
+      return existing_map if existing_map
+
+      # Effectively add an alias when we see new_field('With/Aliased/Name')
+      if args[0].is_a? String
+        return add_attribute(name, headers_to_indices.fetch(args[0].downcase)) 
+      end
+      
+      if @named_columns
+        return add_attribute(name, headers_to_indices.fetch(name.to_s))
+      end
+
+      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 iterate_headers
+      @start_at_row = [ @start_at_row, 1 ].max
+
+      csv = FasterCSV.new(@csv_data, @parser_options)
+
+      # Header is for now assumed to be one row above data
+      (@start_at_row - 1).times { csv.readline } if @start_at_row > 1
+
+      attributes = csv.readline
+      @csv_data.rewind
+      attributes.each_with_index { |name, index| yield name, index }
+    end
+
+    def headers_to_indices
+      return @h_to_i if @h_to_i
+      @h_to_i = {}
+      iterate_headers { |name, index| @h_to_i[name.strip.downcase] = index if name }
+      @h_to_i
+    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
+
+    def attributize_field_name(name)
+      name.gsub(/\s+/, '_').gsub(/[\W]+/, '').downcase
+    end
+  end
+end

data/spec/csv-mapper/attribute_map_spec.rb

@@ -0,0 +1,65 @@
+require File.dirname(__FILE__) + '/../spec_helper.rb'
+
+describe CsvMapper::AttributeMap do
+  
+  class TestContext
+    def transform_it(row, index)
+      :transform_it_success
+    end
+  end
+    
+  before(:each) do
+    @row_attr = CsvMapper::AttributeMap.new('foo', 1, TestContext.new)
+    @csv_row = ['first_name', 'last_name']
+  end
+  
+  it "should map a destination attribute name" do
+    @row_attr.name.should == 'foo'
+  end
+
+  it "should map a CSV column index" do
+    @row_attr.index.should be(1)
+  end
+  
+  it "should map a transformation between the CSV value and destination value and chain method calls" do
+    @row_attr.map(:named_transform).should be(@row_attr)
+  end
+  
+  it "should provide ability to set the index and chain method calls" do
+    @row_attr.at(9).should be(@row_attr)
+    @row_attr.index.should be(9)
+  end
+  
+  it "should parse values" do
+    @row_attr.parse(@csv_row).should == @csv_row[1]
+  end
+
+  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
+  
+  it "should provide access to the raw value" do
+    @row_attr.raw_value(@csv_row).should be(@csv_row[@row_attr.index])
+  end
+  
+end

data/spec/csv-mapper/row_map_spec.rb

@@ -0,0 +1,139 @@
+require File.dirname(__FILE__) + '/../spec_helper.rb'
+
+describe CsvMapper::RowMap do
+  
+  class TestMapToClass
+    attr_accessor :foo, :bar, :baz
+  end
+  
+  class TestMapContext
+    def transform(row, index)
+      :transform_success
+    end
+    
+    def change_name(row, target)
+      row[0] = :changed_name
+    end
+  end
+
+  let(:test_context) { TestMapContext.new }
+
+  before(:each) do
+    @row_map = CsvMapper::RowMap.new(test_context)
+    @csv_row = ['first_name', 'last_name']
+  end
+
+  it "should provide access to the context" do
+    @row_map.context.should == test_context
+  end
+
+  it "should parse a CSV row" do
+    @row_map.parse(@csv_row).should_not be_nil
+  end
+
+  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
+    @row_map.fname
+    @row_map.lname
+    
+    result = @row_map.parse(@csv_row)
+    result.fname.should == @csv_row[0]
+    result.lname.should == @csv_row[1]
+  end
+
+  it "should map to a ruby class with optional default attribute values" do
+    @row_map.map_to TestMapToClass, :baz => :default_baz
+    
+    @row_map.foo
+    @row_map.bar
+    
+    (result = @row_map.parse(@csv_row)).should be_instance_of(TestMapToClass)
+    result.foo.should == @csv_row[0]
+    result.bar.should == @csv_row[1]
+    result.baz.should == :default_baz
+  end
+
+  it "should define Infinity" do
+    CsvMapper::RowMap::Infinity.should == 1.0/0
+  end
+    
+  it "should start at the specified CSV row" do
+    @row_map.start_at_row.should == 0
+    @row_map.start_at_row(1)
+    @row_map.start_at_row.should == 1
+  end
+  
+  it "should stop at the specified row" do
+    @row_map.stop_at_row.should be(CsvMapper::RowMap::Infinity)
+    @row_map.stop_at_row(6)
+    @row_map.stop_at_row.should == 6
+  end
+  
+  it "should allow before row processing" do
+    @row_map.before_row :change_name, lambda{|row, target| row[1] = 'bar'}
+    
+    @row_map.first_name
+    @row_map.foo
+    
+    result = @row_map.parse(@csv_row)
+    result.first_name.should == :changed_name
+    result.foo.should == 'bar'
+  end
+  
+  it "should allow after row processing" do
+    filter_var = nil
+    @row_map.after_row lambda{|row, target| filter_var = :woot}
+    
+    @row_map.parse(@csv_row)
+    filter_var.should == :woot
+  end
+  
+  it "should have a moveable cursor" do
+    @row_map.cursor.should be(0)
+    @row_map.move_cursor
+    @row_map.cursor.should be(1)
+    @row_map.move_cursor 3
+    @row_map.cursor.should be(4)
+  end
+  
+  it "should skip indexes" do
+    pre_cursor = @row_map.cursor
+    @row_map._SKIP_
+    @row_map.cursor.should be(pre_cursor + 1)
+  end
+  
+  it "should accept FasterCSV parser options" do
+    @row_map.parser_options :row_sep => :auto
+    @row_map.parser_options[:row_sep].should == :auto
+  end
+  
+  it "should have a configurable the column delimiter" do
+    @row_map.delimited_by '|'
+    @row_map.delimited_by.should == '|'
+  end
+  
+  it "should maintain a collection of attribute mappings" do
+    @row_map.mapped_attributes.should be_kind_of(Enumerable)
+  end
+  
+  it "should lazy initialize attribute maps and move the cursor" do
+    pre_cursor = @row_map.cursor
+    (attr_map = @row_map.first_name).should be_instance_of(CsvMapper::AttributeMap)
+    attr_map.index.should be(pre_cursor)
+    @row_map.cursor.should be(pre_cursor + 1)
+  end
+  
+  it "should lazy initialize attribute maps with optional cursor position" do
+    pre_cursor = @row_map.cursor
+    @row_map.last_name(1).index.should be(1)
+    @row_map.cursor.should be(1)
+  end
+  
+  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
+end

data/spec/csv-mapper_spec.rb

@@ -0,0 +1,238 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe CsvMapper do
+  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
+      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
+
+      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 = @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
+
+    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
+
+  describe "extended" do
+    it "should allow the creation of CSV mappings" do
+      mapping = CsvMapper.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 = 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
+
+    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
+
+    describe "Adding only certain attributes by name or alias" do
+      context "A file with headers and empty column names" do
+        before :all do
+          @results = CsvMapper.import(File.dirname(__FILE__) + '/test_with_empty_column_names.csv') do
+            named_columns
+            surname('Last Name')
+            age.map { |row, index| row[index].to_i }
+          end
+        end
+
+        it "should have Last name aliased as surname" do
+          @results[1].surname.should == 'Doe'
+        end
+
+        it "should transform age to 26 (a Fixnum)" do
+          @results[1].age.should == 26
+        end
+
+        it "should not have First Name at all" do
+          lambda { @results[1].first_name }.should raise_error(NoMethodError)
+        end
+
+        it "should raise IndexError when adding non-existent fields" do
+          lambda {
+            @results = CsvMapper.import(File.dirname(__FILE__) + '/test_with_empty_column_names.csv') do
+              add_attributes_by_name('doesnt_exist')
+            end
+          }.should raise_error(IndexError)
+        end
+
+        it "should raise IndexError when adding non-existent aliases" do
+          lambda {
+            @results = CsvMapper.import(File.dirname(__FILE__) + '/test_with_empty_column_names.csv') do
+              my_new_field('doesnt_exist')
+            end
+          }.should raise_error(IndexError)
+        end
+      end
+
+      context "A crazy not-really CSV file with some lines to ignore at the top" do
+        before :all do
+          @results = CsvMapper.import(File.dirname(__FILE__) + '/test_with_pushed_down_header.csv') do
+            start_at_row 5
+            named_columns
+            surname('Last Name')
+            age.map { |row, index| row[index].to_i }
+          end
+        end
+
+        it "should transform age to 26" do
+          @results[1].age.should == 26
+        end
+
+      end
+    end
+
+    it "should be able to assign default column names when column names are null" do
+      results = CsvMapper.import(File.dirname(__FILE__) + '/test_with_empty_column_names.csv') do
+        read_attributes_from_file
+      end
+
+      results[1]._field_1.should == 'unnamed_value'
+    end
+
+    it "should import non-comma delimited files" do
+      piped_io = 'foo|bar|00|01'
+
+      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
+
+    it "should not allow transformation 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

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'csv-mapper'

data/spec/test.csv

@@ -0,0 +1,4 @@
+First Name, Last Name, Age
+John,Doe,27
+Jane,Doe,26
+Bat,Man,52

data/spec/test_with_empty_column_names.csv

@@ -0,0 +1,4 @@
+First Name, Last Name, Age,,,
+John,Doe,27,,,
+Jane,Doe,26,unnamed_value,,
+Bat,Man,52,,,

data/spec/test_with_pushed_down_header.csv

@@ -0,0 +1,8 @@
+"Some data"
+
+This is a test file whose header line starts at the 0-indexed 4th row and the data starts at the 5th.  I know. It's not a CSV as such, but they exist...
+
+First Name, Last Name, Age,,,
+John,Doe,27,,,
+Jane,Doe,26,unnamed_value,,
+Bat,Man,52,,,

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: artforge-csv-mapper
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Luke Pillow
+- Russell Garner
+- Adam Singer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: fastercsv
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: CSV Mapper makes it easy to import data from CSV files directly to a
+  collection of any type of Ruby object. The simplest way to create mappings is declare
+  the names of the attributes in the order corresponding to the CSV file column order.
+email: adam@artforge.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- History.txt
+- LICENSE
+- README.rdoc
+files:
+- History.txt
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- artforge-csv-mapper-1.0.1.gem
+- lib/csv-mapper.rb
+- lib/csv-mapper/attribute_map.rb
+- lib/csv-mapper/row_map.rb
+- spec/csv-mapper/attribute_map_spec.rb
+- spec/csv-mapper/row_map_spec.rb
+- spec/csv-mapper_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/test.csv
+- spec/test_with_empty_column_names.csv
+- spec/test_with_pushed_down_header.csv
+homepage: http://github.com/Artforge/csv-mapper
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: artforge-CsvMapper is a fork of a small library intended to simplify the
+  common steps involved with importing CSV files to a usable form in Ruby. It has
+  support for null column names. When this is merged, this gem will be removed.
+test_files: []