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 (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

And Row cells as a Hash: >> table[: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 :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 © 2014 Scott Willson. See LICENSE for details.