csvobj 1.0

data/LICENSE

@@ -0,0 +1,27 @@
+
+Copyright 2010 Martin Carpenter. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY Martin Carpenter ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Martin Carpenter OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the
+authors and should not be interpreted as representing official policies, either expressed
+or implied, of Martin Carpenter.
+

data/README.rdoc

@@ -0,0 +1,53 @@
+
+= CSVobj
+
+== Aims
+
+CSVobj has two simple aims in the processing of CSV files:
+
+* clarity
+* robustness
+
+It achieves these aims by automatically instantiating a class with
+dynamic attributes that can be used to refer to each column of the CSV
+by name. Each attribute name is derived in a predictable fashion from
+the column headers (the first row of the CSV).
+
+=== Clarity
+
+Rather than referring programatically to the "third element of the row"
+("row[2]") one can simply say "row.last_name".
+
+=== Robustness
+
+Any change to the CSV format (eg by inserting a new column between two
+existing columns) will not require a program change: you do not need to
+hunt down all references to "row[2]" and make them "row[3]"; they remain
+"row.last_name".
+
+== Example
+
+Given the following CSV file:
+
+    First Name,Last Name
+    Cheryl,James
+    Sandra,Denton
+    Deidra,Roper
+
+we can extract just the last names as follows:
+
+    # Get the gem
+    require 'rubygems'
+    require 'csvobj'
+
+    # Subclass because #parse defines methods on the class
+    class MyCsv < CSVobj ; end
+    
+    # First command line argument is CSV file to read
+    csv_file = File.new( ARGV[0] )
+
+    # Parse the file, print the "last name" column of each row
+    MyCsv.parse(csv_file).each do |row|
+      puts row.last_name
+    end
+

data/Rakefile

@@ -0,0 +1,40 @@
+
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+desc 'Default task (test)'
+task :default => [:test]
+
+desc 'Run unit tests'
+Rake::TestTask.new('test') do |test|
+  test.pattern = 'test/*.rb'
+  test.warning = true
+end
+
+task :gem
+spec = eval( File.read('csvobj.gemspec') )
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end
+
+desc 'Generate rdoc'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'csvobj.rb'
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--inline-source'
+  rdoc.options << '-A cattr_accessor=object'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.options << '--all'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/csvobj.rb')
+  rdoc.rdoc_files.include( Dir.glob( File.join('test', '*.rb') ) )
+end
+
+desc 'Clean up'
+task :clean do
+  FileUtils.rm( Dir.glob( File.join('pkg', '*') ) )
+  FileUtils.rm_r( Dir.glob( File.join('rdoc', '*') ) )
+end

data/lib/csvobj.rb

@@ -0,0 +1,130 @@
+
+require 'csv'
+
+# Generic exception for CSVobj class: actual exceptions are subclassed.
+class CSVobjException < Exception ; end
+
+# Raised if the read CSV header row contains a duplicate field.
+class CSVobjDuplicateHeader < CSVobjException ; end
+
+# This class represents each row of a CSV file as an object in an array.
+# Object attributes are automatically created from the header (first)
+# row in the CSV. Note that this class dynamically redefines its own
+# attributes and constructor so you should subclass it for any remotely
+# serious work.
+class CSVobj
+
+  # Parse the given CSV, which may be a multi-line string or
+  # IO object (see #parse_s) or an array of row arrays (see
+  # #parse_a) and return an array of CSVobjs.
+  # Expects the first row to be the headers (these are used
+  # for the objects' attributes).
+  def self.parse(csv)
+    csv.is_a?(Array) ? parse_a(csv) : parse_s(csv)
+  end
+
+  # Interpret the given multi-line string or IO object of
+  # CSV records and return an array of CSVobjs.
+  # Expects the first row to be the headers (these are used
+  # for the objects' attributes).
+  def self.parse_s(csv)
+    rows = s_to_a(csv)
+    parse_a(rows)
+  end
+
+  # Interpret an array (rows) of arrays (cells) and return
+  # an array of CSVobjs.
+  # Expects the first row to be the headers (these are used 
+  # for the objects' attributes).
+  def self.parse_a(rows)
+    return [] if rows.empty?
+
+    # Get attributes from first row.
+    headers = rows.shift
+    attr_symbols = headers.map{ |header| header_to_attr(header) }
+    dupes = attr_symbols.uniq!
+    raise CSVobjDuplicateHeader, "Duplicate derived headers\n#{dupes}" if dupes
+
+    # Declare attributes and constructor. This will take the form:
+    #     #new(header1, header2, ...).
+    instance_variables = attr_symbols.map{ |attr| "@#{attr}" }
+    class_eval do
+      attr_accessor(*attr_symbols)
+      define_method :initialize do |*args|
+        instance_variables.zip(args).each do |instance_variable, arg|
+          instance_variable_set(instance_variable, arg)
+        end
+      end
+    end
+
+    # Define class method #headers to return an array of the (unmangled)
+    # CSV headers by defining the method on the metaclass.
+    (class << self ; self end).send(:define_method, :headers) { headers }
+
+    # Create and return array of CSVobj, one element for each CSV row
+    # (minus the headers).
+    rows.map { |row| new(*row) }
+  end
+
+  # Convert a header (string) value to a an attribute symbol:
+  # Remove leading and trailing whitespace;
+  # replace (repeated) non-word characters with a single underscore;
+  # prefix leading digit with underscore;
+  # remove repeated adjacent underscores;
+  # convert to a lower-case symbol.
+  def self.header_to_attr(header)
+    header.strip. # remove trailing and leading whitespace
+      gsub(/\W+/, '_').  # substitute underscore for non-word/digit characters
+      sub(/^(\d)/, '_\1'). # if starts with a digit insert a leading underscore
+      gsub(/_+/, '_'). # remove duplicate adjacent underscores
+      downcase. # convert to lower case
+      to_sym # convert to symbol
+  end
+
+  # Return an array of (string) values for this CSV object in the order
+  # that they were given. See dynamically defined method +headers+ to get
+  # the equivalent array of headers.
+  def to_a
+    self.class.headers.map do |header|
+      attr = self.class.header_to_attr(header)
+      send(attr)
+    end
+  end
+
+  # Return a CSV string representing this object. Does not include headers
+  # (see #to_s_with_headers).
+  def to_s
+    a_to_s(to_a)
+  end
+
+  # Return a CSV string representing this object including an initial line
+  # of headers as originally given on object creation.
+  def to_s_with_headers
+    a_to_s(self.class.headers) + to_s
+  end
+
+  private
+
+  # Abstraction to deal with ruby 1.8/1.9 CSV incompatibilities.
+  # Takes an IO-like object or a string, returns an array of CSV objects.
+  def self.s_to_a(io_or_string)
+    if CSV.const_defined?(:Reader) # ruby 1.8
+      CSV::Reader.create( io_or_string ).to_a
+    else # ruby 1.9 and beyond
+      CSV.parse( io_or_string )
+    end
+  end
+
+  # Abstraction to deal with ruby 1.8/1.9 CSV class incompatibilities.
+  # Takes an array of values and returns a CSV-encoded string.
+  def a_to_s(a)
+    if CSV.const_defined?(:Reader) # ruby 1.8
+      (CSV::Writer.generate(s='') << a).close
+      s
+    else # ruby 1.9 and beyond
+      CSV.generate { |csv| csv << a }
+    end
+  end
+
+end
+

data/test/test_header_to_attr.rb

@@ -0,0 +1,33 @@
+
+require 'test/unit'
+
+require 'csvobj'
+
+class TestHeaderToAttr < Test::Unit::TestCase
+
+  def test_lowercase
+    assert_equal(:header, CSVobj.header_to_attr('HEADER'))
+  end
+
+  def test_remove_leading_whitespace
+    assert_equal(:header, CSVobj.header_to_attr(' header'))
+  end
+
+  def test_remove_trailing_whitespace
+    assert_equal(:header, CSVobj.header_to_attr('header '))
+  end
+
+  def test_substitute_underscore_for_non_word_char
+    assert_equal(:_hea_der_, CSVobj.header_to_attr('^hea&der('))
+  end
+
+  def test_no_repeated_adjacent_underscores
+    assert_equal(:hea_der, CSVobj.header_to_attr('hea^&*der'))
+  end
+
+  def test_leading_digit
+    assert_equal(:_9header, CSVobj.header_to_attr('9header'))
+  end
+
+end
+

data/test/test_headers.rb

@@ -0,0 +1,29 @@
+
+require 'test/unit'
+
+require 'csvobj'
+
+class TestHeaders < Test::Unit::TestCase
+
+  def setup
+    @parser = Class.new(CSVobj)
+  end
+
+  def teardown
+    @parser = nil 
+  end
+
+  def test_simple
+    s = 'foo,bar,baz'
+    objs = @parser.parse(s)
+    assert_equal(%w[ foo bar baz ], @parser.headers)
+  end
+
+  def test_not_mangled
+    s = 'Header one,!Header two'
+    objs = @parser.parse(s)
+    assert_equal([ 'Header one', '!Header two' ], @parser.headers)
+  end
+
+end
+

data/test/test_parse.rb

@@ -0,0 +1,118 @@
+
+require 'test/unit'
+require 'stringio'
+
+require 'csvobj'
+
+class TestParse < Test::Unit::TestCase
+
+  def setup
+    @parser = Class.new(CSVobj)
+  end
+
+  def teardown
+    @parser = nil
+  end
+
+  def test_duplicate_header
+    s = "foo,bar,bar,baz\n1,2,3,4\n"
+    assert_raise CSVobjDuplicateHeader do
+      @parser.parse(s)
+    end
+  end
+
+  def test_one_obj_from_string
+    s = "foo,bar,baz\n1,2,3\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_equal('3', objs[0].baz)
+  end
+
+  def test_two_objs_from_string
+    s = "foo,bar,baz\n1,2,3\n4,5,6\n"
+    objs = @parser.parse(s)
+    assert_equal(2, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_equal('3', objs[0].baz)
+    assert_equal('4', objs[1].foo)
+    assert_equal('5', objs[1].bar)
+    assert_equal('6', objs[1].baz)
+  end
+
+  def test_two_objs_from_file
+    s = "foo,bar,baz\n1,2,3\n4,5,6\n"
+    fileish = StringIO.new(s)
+    objs = @parser.parse(fileish)
+    assert_equal(2, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_equal('3', objs[0].baz)
+    assert_equal('4', objs[1].foo)
+    assert_equal('5', objs[1].bar)
+    assert_equal('6', objs[1].baz)
+  end
+
+  def test_no_trailing_newline
+    s = "foo,bar,baz\n1,2,3"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_equal('3', objs[0].baz)
+  end
+
+  def test_missing_data_cell
+    s = "foo,bar,baz\n1,2\n4,5,6\n"
+    objs = @parser.parse(s)
+    assert_equal(2, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_equal(nil, objs[0].baz)
+    assert_equal('4', objs[1].foo)
+    assert_equal('5', objs[1].bar)
+    assert_equal('6', objs[1].baz)
+  end
+
+  def test_missing_header_cell
+    s = "foo,bar\n1,2,3\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_raise NoMethodError do
+      objs[0].baz
+    end
+  end
+
+  def test_missing_data
+    s = "foo,bar,baz\n"
+    objs = @parser.parse(s)
+    assert_equal([], objs)
+  end
+
+  def test_empty
+    objs = @parser.parse('')
+    assert_equal([], objs)
+  end
+
+  def test_array
+    a = [
+      [ 'foo', 'bar', 'baz' ],
+      [ '1', '2', '3' ],
+      [ '4', '5', '6' ]
+    ]
+    objs = @parser.parse(a)
+    assert_equal(2, objs.size)
+    assert_equal('1', objs[0].foo)
+    assert_equal('2', objs[0].bar)
+    assert_equal('3', objs[0].baz)
+    assert_equal('4', objs[1].foo)
+    assert_equal('5', objs[1].bar)
+    assert_equal('6', objs[1].baz)
+  end
+
+end
+

data/test/test_to_a.rb

@@ -0,0 +1,38 @@
+
+require 'test/unit'
+
+require 'csvobj'
+
+class TestToA < Test::Unit::TestCase
+
+  def setup
+    @parser = Class.new(CSVobj)
+  end
+
+  def teardown
+    @parser = nil 
+  end
+
+  def test_one_complete_object
+    s = "foo,bar,baz\n1,2,3\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal(%w[ 1 2 3 ], objs[0].to_a)
+  end
+
+  def test_one_object_missing_data_cell
+    s = "foo,bar,baz\n1,2\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal([ '1', '2', nil ], objs[0].to_a)
+  end
+
+  def test_one_object_missing_header
+    s = "foo,bar\n1,2,3\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal(%w[ 1 2 ], objs[0].to_a)
+  end
+
+end
+

data/test/test_to_csv.rb

@@ -0,0 +1,31 @@
+
+require 'test/unit'
+
+require 'csvobj'
+
+class TestToCsv < Test::Unit::TestCase
+
+  def setup
+    @parser = Class.new(CSVobj)
+  end
+
+  def teardown
+    @parser = nil 
+  end
+
+  def test_one_object_sans_headers
+    s = "foo,bar,baz\n1,2,3\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal("1,2,3\n", objs.first.to_s)
+  end
+
+  def test_one_object_with_headers
+    s = "foo,bar,baz\n1,2,3\n"
+    objs = @parser.parse(s)
+    assert_equal(1, objs.size)
+    assert_equal(s, objs.first.to_s_with_headers)
+  end
+
+end
+

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: csvobj
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Martin Carpenter
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-25 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: CSVobj provides a legible and maintainable mechanism to manipulate CSV files by creating an array of objects from a file or string of CSV information. The resulting object's attributes are defined dynamically and are based on the CSV column name.
+email: martin.carpenter@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- Rakefile
+- README.rdoc
+files: 
+- lib/csvobj.rb
+- test/test_headers.rb
+- test/test_parse.rb
+- test/test_header_to_attr.rb
+- test/test_to_a.rb
+- test/test_to_csv.rb
+- LICENSE
+- Rakefile
+- README.rdoc
+has_rdoc: true
+homepage: http://mcarpenter.org/projects/csvobj
+licenses: 
+- BSD
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Convert CSV files to an array of objects with friendly "column name" attributes
+test_files: []
+