Skip to content

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
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
.gitignore
.travis.yml
Gemfile
Gemfile.lock
LICENSE
README
Rakefile
tabular.gemspec

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.

Tabular can read Excel files if you add the spreadsheet gem to your project.

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

Or, Gemfile:
gem "tabular"


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

For Excel: Roo gem (https://github.com/Empact/roo)
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.3.0 Revise Table creation methods to something sensible. Use Roo to read
      spreadsheets. Support for xlsx.
0.2.7 Add Table#to_space_delimited for space-padded fixed layout
0.2.6 Add :except option for delete_blank_columns!
0.2.5 Use modern gemspec with no runtime dependencies. Make spreadsheet gem optional.
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 deprecated

0.0.5 Parse 'invalid' m/d/yy dates


Copyright
---------

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