tabular 0.2.0 → 0.2.1

data/README

@@ -2,6 +2,12 @@ Tabular is a Ruby library for reading, writing, and manipulating CSV, tab-delimi
 
 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
@@ -38,7 +44,7 @@ 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.
+Table.new accepts an Array of Arrays or an Array of Hashes.
 
 Table.new also accepts an options hash.
 
@@ -56,6 +62,25 @@ There's basic test coverage. More comprehensive test coverage needs to be extrac
 
 Changes
 -------
+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
 
 

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/tabular/column.rb

@@ -2,6 +2,9 @@ module Tabular
   class Column
     attr_reader :key, :column_type
 
+    # +table+ -- parent Table
+    # +column+ -- parent Columns
+    # +key+ is normalized to a downcase, underscored symbol
     def initialize(table, columns, key = nil, columns_map = {})
       @columns = columns
       @table = table
@@ -26,42 +29,31 @@ module Tabular
       end
     end
 
-    def symbolize(key)
-      return nil if key.blank?
-
-      begin
-        key.to_s.strip.gsub(/::/, '/').
-          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-          gsub(/([a-z\d])([A-Z])/,'\1_\2').
-          tr("-", "_").
-          gsub(/ +/, "_").
-          downcase.
-          to_sym
-      rescue
-        nil
-      end
-    end
-
     def rows
       @table.rows
     end
 
+    # All cells value under this Column
     def cells
       rows.map { |r| r[key] }
     end
 
+    # Maximum value for cells in the Column. Determine with Ruby #max
     def max
       cells.compact.max
     end
 
+    # Number of zeros to the right of the decimal point. Useful for formtting time data.
     def precision
       @precision || cells.map(&:to_f).map {|n| n.round(3) }.map {|n| n.to_s.split(".").last.gsub(/0+$/, "").length }.max
     end
 
+    # Human-friendly header string. Delegate to +renderer+'s render_header method.
     def render
       renderer.render_header self
     end
 
+    # Renderer
     def renderer
       @columns.renderer(key)
     end
@@ -73,5 +65,23 @@ module Tabular
     def to_s
       key.to_s
     end
+    
+    private
+
+    def symbolize(key)
+      return nil if key.blank?
+
+      begin
+        key.to_s.strip.gsub(/::/, '/').
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          tr("-", "_").
+          gsub(/ +/, "_").
+          downcase.
+          to_sym
+      rescue
+        nil
+      end
+    end
   end
 end

data/lib/tabular/columns.rb

@@ -6,6 +6,7 @@ module Tabular
 
     attr_accessor :renderer
 
+    # +table+ -- Table
     # +data+ -- array of header names
     # +columns_map+ -- see Table. Maps column names and type conversion.
     def initialize(table, names, columns_map = {})
@@ -69,18 +70,17 @@ module Tabular
       end
     end
 
+    # Count of Columns#columns
     def size
       @columns.size
     end
 
-    def max
-      cells.compact.max
-    end
-
+    # Renderer for Column +key+. Default to Table#renderer.
     def renderer(key)
       renderers[key] || @renderer || Renderer
     end
 
+    # List of Renderers
     def renderers
       @renderers ||= {}
     end

data/lib/tabular/keys.rb

@@ -1,5 +1,6 @@
 module Tabular
   module Keys
+    # Return Symbol for +key+. Translate Column and String. Return +key+ unmodified for anything else.
     def key_to_sym(key)
       _key = case key
       when Column

data/lib/tabular/renderer.rb

@@ -1,4 +1,8 @@
 module Tabular
+  # Custom display of cells. By default, return to_s.
+  #
+  # Create your own Renders by implementing a class that responds to render(column, row) for cells
+  # and/or render_header(column) for Column headers.
   class Renderer
     def self.render(column, row)
       row[column.key]

data/lib/tabular/row.rb

@@ -56,6 +56,7 @@ module Tabular
       hash.each(&block)
     end
     
+    # Keys for all columns
     def keys
       hash.keys
     end
@@ -70,16 +71,19 @@ module Tabular
       hash.delete key
     end
 
+    # Previous Row
     def previous
       if index > 0
         @table.rows[index - 1]
       end
     end
 
+    # Tabluar::Columns
     def columns
       @table.columns
     end
 
+    # By default, return self[key]. Customize by setting Table#renderer or Column#renderers[key]
     def render(key)
       column = columns[key]
       column.renderer.render column, self

data/lib/tabular/table.rb

@@ -1,5 +1,6 @@
 module Tabular
-  # Simple Enumerable list of Hashes. Use Table.read(file_path) to read file.
+  # Simple Enumerable list of Hashes. Use Table.read(file_path) to read file. Can also create a Table with Table.new. Either
+  # pass in data or set options and then call row=.
   class Table
     include Tabular::Keys
 
@@ -63,6 +64,8 @@ module Tabular
     #
     # Options:
     # :columns => { :original_name => :preferred_name, :column_name => { :column_type => :boolean } }
+    #
+    # The :columns option will likely be deprecated and options for mappers and renderers added
     def initialize(rows = [], *options)
       @options = Table.extract_options(options)
       self.rows = rows
@@ -72,6 +75,7 @@ module Tabular
       @rows ||= []
     end
     
+    # Set table rows. Calls row <<, which creates columns and links the source rows to Row#source.
     def rows=(source_rows = [])
       return [] unless source_rows
       
@@ -87,6 +91,9 @@ module Tabular
       rows[index]
     end
 
+    # Add row to end of table. Create missing columns and link the source row to Row#source.
+    # To control how source data is added to the Table, use Table#mapper= to set a class that 
+    # implements map(row) and returns a Hash.
     def <<(row)
       if row_mapper
         cells = row_mapper.map(row)
@@ -111,10 +118,12 @@ module Tabular
       rows.map { |row| row.join(",") }.join("\n")
     end
 
+    # Instance of Tabular::Columns
     def columns
       @columns ||= Tabular::Columns.new(self, [])
     end
 
+    # Remove all columns that only contain a blank string, zero, or nil
     def delete_blank_columns!
       columns.map(&:key).each do |key|
         if rows.all? { |row| row[key].blank? || row[key].zero? }
@@ -123,6 +132,7 @@ module Tabular
       end
     end
     
+    # Remove all columns that contain the same value in all rows
     def delete_homogenous_columns!
       return if rows.size < 2
       
@@ -134,6 +144,8 @@ module Tabular
       end
     end
     
+    # Remove preceding and trailing whitespace from all cells. By default, Table does not
+    # strip whitespace from cells.
     def strip!
       rows.each do |row|
         columns.each do |column|
@@ -152,10 +164,12 @@ module Tabular
       columns.delete key
     end
 
+    # Set default Renderer. If present, will be used for all cells and Column headers.
     def renderer=(value)
       columns.renderer = value
     end
 
+    # List of Renderers
     def renderers
       columns.renderers
     end

data/tabular.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "tabular"
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Scott Willson"]

data/test/columns_test.rb

@@ -33,7 +33,7 @@ module Tabular
     end
 
     def test_render
-      columns = Columns.new(nil, ["date", "first name", "LastName"])
+      columns = Columns.new(Table.new, ["date", "first name", "LastName"])
       assert_equal "date", columns.first.render
     end
 

metadata

@@ -2,7 +2,7 @@
 name: tabular
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Scott Willson
@@ -105,7 +105,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      hash: -1721544850789134153
+      hash: -2217103212522653909
       segments:
       - 0
       version: '0'