csv-mapper 0.0.4 → 0.5.0

data/.gitignore

@@ -0,0 +1,2 @@
+pkg/*
+doc/*

data/History.txt

@@ -1,3 +1,12 @@
+== 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"

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

@@ -1,4 +1,4 @@
-= README
+= csv-mapper
 
 == DESCRIPTION:
 
@@ -6,7 +6,7 @@ CsvMapper is a small library intended to simplify the common steps involved with
 
 == EXAMPLES:
 
-The following example will import a CSV file to an Array of OpenStruct[http://ruby-doc.org/core/classes/OpenStruct.html] instances.
+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
 
@@ -17,9 +17,7 @@ The following example will import a CSV file to an Array of OpenStruct[http://ru
   ...etc...
 
 ==== Simple Usage Example
-  include CsvMapper
-
-  results = import('/path/to/file.csv') do
+  results = CsvMapper.import('/path/to/file.csv') do
     start_at_row 1
     [first_name, last_name, age]
   end
@@ -29,9 +27,7 @@ The following example will import a CSV file to an Array of OpenStruct[http://ru
   results.first.age         # 27
 
 ==== Automagical Attribute Discovery Example
-  include CsvMapper
-
-  results = import('/path/to/file.csv') do
+  results = CsvMapper.import('/path/to/file.csv') do
     read_attributes_from_file
   end
 
@@ -45,10 +41,8 @@ Although CsvMapper has no dependency on ActiveRecord; it's easy to import a CSV
   # Define an ActiveRecord model
   class Person < ActiveRecord::Base; end
 
-  include CsvMapper
-  
-  results = import('/path/to/file.csv') do
-    map_to Person # Map to the Person ActiveRecord class (defined above) instead of the default OpenStruct.
+  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
@@ -65,27 +59,16 @@ FasterCSV[http://fastercsv.rubyforge.org/] on pre 1.9 versions of Ruby
 
 * sudo gem install csv-mapper
 
-== LICENSE:
-
-(The MIT License)
-
-Copyright (c) 2008 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:
+== 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.
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+== Copyright
 
-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.
+Copyright (c) 2009 Luke Pillow. See LICENSE for details.

data/Rakefile

@@ -1,28 +1,47 @@
-%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
-require File.dirname(__FILE__) + '/lib/csv-mapper'
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.new('csv-mapper', CsvMapper::VERSION) do |p|
-  p.developer('Luke Pillow', 'lpillow@gmail.com')
-  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  # p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
-  p.rubyforge_name       = p.name # TODO this is default value
-  p.extra_deps         = [
-    ['fastercsv','>= 1.4.0'],
-  ]
-  p.extra_dev_deps = [
-    ['newgem', ">= #{::Newgem::VERSION}"]
-  ]
-  
-  p.clean_globs |= %w[**/.DS_Store tmp *.log]
-  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
-  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
-  p.rsync_args = '-av --delete --ignore-errors'
-end
-
-require 'newgem/tasks' # load /tasks/*.rake
-Dir['tasks/**/*.rake'].each { |t| load t }
-
-# TODO - want other tests/tasks run by default? Add them to the list
-# task :default => [:spec, :features]
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "csv-mapper"
+    gem.summary = %Q{CsvMapper is a small library intended to simplify the common steps involved with importing CSV files to a usable form in Ruby.}
+    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 = "lpillow@gmail.com"
+    gem.homepage = "http://github.com/pillowfactory/csv-mapper"
+    gem.authors = ["Luke Pillow"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    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 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.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 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "csv-mapper #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/lib/csv-mapper.rb

@@ -1,7 +1,7 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
 
-require 'ostruct'
+require 'rubygems'
 
 # the following is slightly modified from Gregory Brown's
 # solution on the Ruport Blaag:
@@ -44,7 +44,7 @@ end
 # know the corresponding CSV column index to associate with the attribute.
 # 
 # ===== The Basics
-# * +map_to+ - Override the default OpenStruct target. Accepts a class and an optional hash of default attribute names and values.
+# * +map_to+ - Override the default Struct target. Accepts a class and an optional hash of default attribute names and values.
 # * +start_at_row+ - Specify what row to begin parsing at.  Use this to skip headers.
 # * +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.
@@ -81,7 +81,6 @@ end
 #   other_results = import('/path/to/file.csv', :map => a_row_map)
 #
 module CsvMapper
-  VERSION = '0.0.4'
 
   # Create a new RowMap instance from the definition in the given block.
   def map_csv(&map_block)
@@ -111,234 +110,13 @@ module CsvMapper
     results
   end  
 
-  # 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; OpenStruct 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| 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.inject(target) do |result, attr_map|
-        result.send("#{attr_map.name}=".to_sym, attr_map.parse(csv_row))
-        result
-      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:
-      @map_to_klass || OpenStruct
-    end
-    
-    def cursor=(value) # :nodoc:
-      @cursor=value
-    end
-    
-    
-  end
-  
-  # 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)
-      @transformer = 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) : csv_row[self.index]
-    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| @map_context.send(transform_name, row) }
-      end
-      
-      @transformer.call(csv_row)
-    end
-    
-  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
-end
+  
+  extend self
+end
+
+require 'csv-mapper/row_map'