Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Ruby library for reading, writing, and manipulating CSV, tab-delimited and Excel data

branch: master
README
Tabular is a Ruby library for reading, writing, and manipulating CSV, tab-delimited and Excel data.

I extracted it from production code. Still extracting it, actually. I need to read structured data and manipulate it via a common interface before persisting it with ActiveRecord.

Tabular is also handy for display table-like data. For example, I want to display a bike race's results in HTML. I need to drop empty columns: sometimes there are points or times; sometimes not. I need find the most precise time to format all the times in the results correctly.

Much of the API is a copy of FasterCSV without the focus on CSV.

Import and display can be configured with Mappers and Renderers. It's a OOP-heavy design that is fast and test-able.

Install
-------
sudo gem install tabular

(The gem is hosted on Gemcutter, not RubyForge)


Dependencies
------------
For tab-delimited data: Ruby standard lib

For CSV: FasterCSV (http://fastercsv.rubyforge.org/)
sudo gem install fastercsv

For Excel: Spreadsheet gem (http://spreadsheet.rubyforge.org/)
sudo gem install spreadsheet


Examples
--------
>> table = Table.read("test/fixtures/sample.csv")
>> table.rows.size
=> 4

Access Table Rows by index:
>> table[0]

And Row cells as a Hash:
>> table[0][:last_name]
=> "Willson"


Usage
-----
Table.read assumes that .txt files are tab-delimited, .csv files are comma-delimited, and .xls files are Excel. It assumes that the first row is the header row, and normalizes the header to lower-case with underscores. E.g., "Last Name" becomes "last_name".

Table.new accepts an Array of Arrays or an Array of Hashes.

Table.new also accepts an options hash.

:columns option to map columns to a different key or type:
:city_state => :location -- Maps :city_state column to :location. A column with a "City State" header would be accessed as row[:location]
:flyer_approved  => { :column_type => :boolean } -- Coerce :flyer_approved column cells to booleans.

:as => [:csv, :xls, :txt] to override file format


Tests
-----
There's basic test coverage. More comprehensive test coverage needs to be extracted from original projects. Run 'rake test'.


Changes
-------
0.2.3 Add :except option for delete_homogenous_columns!
0.2.1 Documentation!
0.2.0 Add several new features that break previous API
 * New public accessors for Table, Columns, Row, and Column
 * Mapper to translate source data to Rows
 * Renderer to control display of Row cells and Column headers
 * Table#delete_blank_columns! to delete columns that are blank. Zero is considered blank.
 * Table#delete_homogenous_columns! to delete columns that are all the same value. E.g.,
   A | B | C
   =========
   1 | 2 | 3
   1 | 6 | 
   1 | * | 5
   
   Column A would be deleted
 * Table#strip! to remove whitespace around cell values. By default, Tabular::Table preserves cell whitespace.
 * Column#max
 * Column#precision
 * Ruby 1.8 support is deprcated

0.0.5 Parse 'invalid' m/d/yy dates


Copyright
---------

Copyright (c) 2010 Scott Willson. See LICENSE for details.
Something went wrong with that request. Please try again.