ruport 0.7.2 → 0.8.0

data/lib/ruport/data/table.rb

@@ -4,9 +4,42 @@
 # This is Free Software.  For details, see LICENSE and COPYING
 # Copyright 2006 by respective content owners, all rights reserved.
 
+module Ruport::Data            
+  
+  # === Overview
+  #
+  # This class implements some base features for Ruport::Data::Table,
+  # and may be used to make interaction with Data::Table like classes
+  # easier
+  #
+  module Collection
+    include Enumerable
+    include Taggable
 
-module Ruport::Data
+    # A simple formatting tool which allows you to quickly generate a formatted
+    # table from a <tt>Collection</tt> object.
+    #
+    # If a block is given, the Renderer::Table object will be yielded
+    #
+    # Example:
+    #   my_collection.as(:csv)  #=> "1,2,3\n4,5,6"
+    #
+    #   my_collection.as(:csv) { |e| e.layout.show_table_headers = false }
+    #   
+    def as(type)
+      Ruport::Renderer::Table.render(type) do |rend|
+        rend.data = self
+        yield(rend) if block_given?
+      end
+    end
+   
+    # Converts a <tt>Collection</tt> object to a <tt>Data::Table</tt>.
+    def to_table(options={})
+      Table.new({:data => data.map { |r| r.to_a }}.merge(options))
+    end
 
+  end
+ 
   # === Overview
   #
   # This class is one of the core classes for building and working with data 
@@ -20,9 +53,13 @@ module Ruport::Data
   # Once your data is in a Ruport::Data::Table object, it can be manipulated
   # to suit your needs, then used to build a report.
   #
-  class Table < Collection
-    include Groupable
+  class Table 
+    include Collection
+    include Groupable      
     
+    require "forwardable"
+    extend Forwardable
+
     # Creates a new table based on the supplied options.
     # Valid options: 
     # <b><tt>:data</tt></b>::         An Array of Arrays representing the 
@@ -36,6 +73,8 @@ module Ruport::Data
     #
     def initialize(options={})
       @column_names = options[:column_names] ? options[:column_names].dup : []
+      @record_class = options[:record_class] &&
+                      options[:record_class].name || "Ruport::Data::Record"
       @data         = []
       if options[:data]
         if options[:data].all? { |r| r.kind_of? Record }
@@ -49,22 +88,39 @@ module Ruport::Data
 
     # This Table's column names.
     attr_reader :column_names
-    def_delegator :@data, :[]
+  
+    attr_reader :data
+    def_delegators :@data, :each, :length, :size, :empty?, :[]
     
+
     # Sets the column names for this table. <tt>new_column_names</tt> should 
     # be an array listing the names of the columns.
     #
     # Example:
-    #
+    #                     
     #   table = Table.new :data => [1,2,3], [3,4,5], 
     #                     :column_names => %w[a b c]
     #
     #   table.column_names = %w[e f g]
     #
     def column_names=(new_column_names)
+      columns = new_column_names.zip(@column_names)
       @column_names.replace(new_column_names.dup)
+      unless @data.empty?
+        each { |r|
+          columns.each_with_index { |x,i|
+            if x[1].nil?
+              r.rename_attribute(i,x[0])
+            elsif x[1] != x[0]
+              r.rename_attribute(x[1],x[0],false)
+            end
+          }
+          r.send(:reindex, @column_names)
+       }
+     end
     end
 
+    
     # Compares this Table to another Table and returns <tt>true</tt> if
     # both the <tt>data</tt> and <tt>column_names</tt> are equal.
     #
@@ -84,18 +140,6 @@ module Ruport::Data
 
     alias_method :==, :eql?
 
-    # Uses Ruport's built-in text plugin to render this Table into a String
-    # 
-    # Example:
-    # 
-    #   data = Table.new :data => [1,2], [3,4], 
-    #                    :column_names => %w[a b]
-    #   puts data.to_s
-    # 
-    def to_s
-      as(:text)
-    end
-
     # Used to add extra data to the Table. <tt>other</tt> can be an Array, 
     # Hash or Record.
     #
@@ -110,23 +154,28 @@ module Ruport::Data
     def <<(other)
       case other
       when Array
-        @data << Record.new(other, :attributes => @column_names)
+        attributes = @column_names.empty? ? nil : @column_names
+        @data << record_class.new(other, :attributes => attributes)
       when Hash
         raise ArgumentError unless @column_names
         arr = @column_names.map { |k| other[k] }
-        @data << Record.new(arr, :attributes => @column_names)
-      when Record
-        raise ArgumentError unless column_names.eql? other.attributes
-        @data << Record.new(other.data, :attributes => @column_names)
+        @data << record_class.new(arr, :attributes => @column_names)
+      when record_class
+        self << other.to_h
         @data.last.tags = other.tags.dup
       else
         raise ArgumentError
       end
       self
     end
+    
+    def record_class
+      @record_class.split("::").inject(Class) { |c,el| c.send(:const_get,el) }
+    end
   
-    # Used to combine two Tables. Throws an ArgumentError if the Tables don't
-    # have identical columns.
+    
+    # Used to merge two Tables by rows.
+    # Throws an ArgumentError if the Tables don't have identical columns.
     #
     # Example:
     #
@@ -144,34 +193,8 @@ module Ruport::Data
       Table.new(:column_names => @column_names, :data => @data + other.data)
     end
   
-    # Reorders the columns that exist in the Table. Modifies this Table 
-    # in-place.
-    #
-    # Example:
-    #
-    #   data = Table.new :data => [1,2], [3,4], 
-    #                    :column_names => %w[a b]
-    #
-    #   data.reorder!([1,0])  
-    #
-    def reorder!(*indices)
-      indices = indices[0] if indices[0].kind_of? Array
-
-      if @column_names && !@column_names.empty?
-        x = if indices.all? { |i| i.kind_of? Integer }
-          indices.map { |i| @column_names[i] }
-        else
-          indices 
-        end
-        @column_names = x
-      end
-      @data.each { |r| 
-        r.reorder_data!(*indices)
-        r.attributes = @column_names
-      }; self
-    end
-
-    # Returns a copy of the Table with its columns in the requested order.
+    
+    # Reorders the table's columns.
     #
     # Example:
     # 
@@ -181,177 +204,212 @@ module Ruport::Data
     #   two = one.reorder!([1,0])  
     #
     def reorder(*indices)
-      dup.reorder!(*indices)
-    end
+      indices = indices[0] if indices[0].kind_of? Array
+      
+      if indices.all? { |i| i.kind_of? Integer }  
+        indices.map! { |i| @column_names[i] }  
+      end    
+      
+      @column_names = indices
+                 
+      @data.each { |r| 
+        r.attributes = @column_names
+      }; self
+    end     
 
+    
     # Adds an extra column to the Table. Available Options:
     #
-    # <b><tt>:name</tt></b>:: The new column's name (required)
     # <b><tt>:fill</tt></b>:: The default value to use for the column in 
     #                         existing rows. Set to nil if not specified.
+    # 
+    # <b><tt>:position</tt></b>:: Inserts the column at the indicated position
+    #                             number.
+    #
+    # <b><tt>:before</tt></b>:: Inserts the new column before the column 
+    #                           indicated. (by name)
+    #
+    # <b><tt>:after</tt></b>:: Inserts the new column after the column
+    #                          indicated. (by name)
+    #
+    # If a block is provided, it will be used to build up the column.
+    #      
     #   
     # Example:
     #
-    #   data = Table.new :data => [1,2], [3,4], 
-    #                    :column_names => %w[a b]
+    #   data = Table("a","b") { |t| t << [1,2] << [3,4] }
+    #   
+    #    #basic usage, column full of 1's
+    #   data.add_column 'new_column', :default => 1
+    #        
+    #   #new empty column before new_column
+    #   data.add_column 'new_col2', :before => 'new_column'
     #
-    #   data.append_column :name => 'new_column', :fill => 1
+    #   # new column placed just after column a
+    #   data.add_column  'new_col3', :position => 1
     #
-    def append_column(options={})
-      self.column_names += [options[:name]]  if options[:name]
+    #   # new column built via a block, added at the end of the table
+    #   data.add_column("new_col4") { |r| r.a + r.b }
+    #   
+    def add_column(name,options={})  
+      if pos = options[:position]
+        column_names.insert(pos,name)   
+      elsif pos = options[:after]
+        column_names.insert(column_names.index(pos)+1,name)   
+      elsif pos = options[:before]
+        column_names.insert(column_names.index(pos),name)
+      else
+        column_names << name
+      end 
+
       if block_given?
-        each { |r| r.data << yield(r) || options[:fill] }
+        each { |r| r[name] = yield(r) || options[:default] }
       else
-        each { |r| r.data << options[:fill] }
+        each { |r| r[name] = options[:default] }
       end; self
     end
-
-    # Removes a column from the Table. Any values in the specified column are
-    # lost.
+    
+    # Removes the given column from the table.  May use name or position.
     #
     # Example:
     #
-    #   data = Table.new :data => [[1,2], [3,4]], :column_names => %w[a b]
-    #   data.append_column :name => 'new_column', :fill => 1
-    #   data.remove_column :name => 'new_column'
-    #   data == Table.new :data => [[1,2], [3,4]], 
-    #                     :column_names => %w[a b] #=> true
-    #   data = [[1,2],[3,4]].to_table
-    #   data.remove_column(1)
-    #   data.eql? [[1],[3]].to_table %w[a] #=> true
-    #
-    def remove_column(options={})    
-      if options.kind_of? Integer
-        return reorder!((0...data[0].length).to_a - [options])
-      elsif options.kind_of? Hash
-       name = options[:name]
-      else
-       name = options
-      end
-      
-      raise ArgumentError unless column_names.include? name
-      reorder! column_names - [name]
+    #    table.remove_column(0) #=> removes the first column
+    #    table.remove_column("apple") #=> removes column named apple
+    def remove_column(col)        
+      col = column_names[col] if col.kind_of? Fixnum           
+      column_names.delete(col)
+      each { |r| r.send(:delete,col) }
     end
-
-    # Create a copy of the Table: records will be copied as well.
+   
+    # Removes multiple columns from the table.  May use name or position
+    # Will autosplat arrays.
     #
     # Example:
-    #
-    #   one = Table.new :data => [1,2], [3,4], 
-    #                   :column_names => %w[a b]
-    #   two = one.dup
-    #
-    def dup
-      a = self.class.new(:data => @data, :column_names => @column_names)
-      a.tags = tags.dup
-      return a
+    # table.remove_columns('a','b','c')
+    # table.remove_columns([0,1])
+    def remove_columns(*cols)
+      cols = cols[0] if cols[0].kind_of? Array
+      cols.each { |col| remove_column(col) }
     end
-
-    # Loads a CSV file directly into a Table using the FasterCSV library.
-    #
+    
+    # Renames a column.  Will update Record attributes as well
+    # 
     # Example:
-    #   
-    #   # treat first row as column_names
-    #   table = Table.load('mydata.csv')
     #
-    #   # do not assume the data has column_names
-    #   table = Table.load('mydata.csv',:has_names => false)
-    #
-    #   # pass in FasterCSV options, such as column separators
-    #   table = Table.load('mydata.csv',:csv_opts => { :col_sep => "\t" })
-    #
-    def self.load(csv_file, options={},&block)
-        get_table_from_csv(:foreach, csv_file, options,&block)
+    #   old_values = table.map { |r| r.a }
+    #   table.rename_column("a","zanzibar")
+    #   new_values = table.map { |r| r.zanzibar }
+    #   old_values == new_values #=> true
+    #   table.column_names.include?("a") #=> false
+    def rename_column(old_name,new_name)
+      self.column_names[column_names.index(old_name)] = new_name
+      each { |r| r.rename_attribute(old_name,new_name,false)} 
     end
     
-    # Creates a Table from a CSV string using FasterCSV.  See Table.load for
-    # additional examples.
-    #
-    #   table = Table.parse("a,b,c\n1,2,3\n4,5,6\n")
-    #
-    def self.parse(string, options={},&block) 
-      get_table_from_csv(:parse,string,options,&block)
-    end
     
-    def self.get_table_from_csv(msg,param,options={},&block) #:nodoc:
-      options = {:has_names => true,
-                 :csv_options => {} }.merge(options)
-      require "fastercsv"
-      loaded_data = self.new
-
-      first_line = true
-      FasterCSV.send(msg,param,options[:csv_options]) do |row|
-        if first_line && options[:has_names]
-          loaded_data.column_names = row
-          first_line = false
-        elsif !block
-          loaded_data << row
-        else
-         block[loaded_data,row]
-        end
-      end ; loaded_data
+    #  Exchanges one column with another.
+    #
+    #  Example: 
+    #
+    #    >> a = Table(%w[a b c]) { |t| t << [1,2,3] << [4,5,6] } 
+    #    >> puts a
+    #       +-----------+
+    #       | a | b | c |
+    #       +-----------+
+    #       | 1 | 2 | 3 |
+    #       | 4 | 5 | 6 |
+    #       +-----------+
+    #    >> a.swap_column("a","c")
+    #    >> puts a
+    #       +-----------+
+    #       | c | b | a |
+    #       +-----------+
+    #       | 3 | 2 | 1 |
+    #       | 6 | 5 | 4 |
+    #       +-----------+
+    def swap_column(a,b)    
+      if [a,b].all? { |r| r.kind_of? Fixnum }
+       col_a,col_b = column_names[a],column_names[b]
+       column_names[a] = col_b
+       column_names[b] = col_a
+      else
+        a_ind, b_ind = [column_names.index(a), column_names.index(b)] 
+        column_names[b_ind] = a
+        column_names[a_ind] = b
+      end
     end
-
-    # Allows you to split Tables into multiple Tables for grouping.
+       
+    #  Allows you to specify a new column to replace an existing column
+    #  in your table via a block.
+    #
+    #  Example:
+    #
+    #  >> a = Table(%w[a b c]) { |t| t << [1,2,3] << [4,5,6] }
+    #  >> a.replace_column("c","c2") { |r| r.c * 2 + r.a }
+    #
+    #  >> puts a
+    #     +------------+
+    #     | a | b | c2 |
+    #     +------------+
+    #     | 1 | 2 |  7 |
+    #     | 4 | 5 | 16 |
+    #     +------------+
+    def replace_column(old_col,new_col,&block)
+      add_column(new_col,:after => old_col,&block)
+      remove_column(old_col)
+    end         
+          
+    #  Generates a sub table
+    #  
+    #  Examples:
+    #   
+    #    table = [[1,2,3,4],[5,6,7,8],[9,10,11,12]].to_table(%w[a b c d])
     #
-    # Example:
+    #  Using column_names and a range:
     #
-    #   a = Table.new(:column_name => %w[name a b c])
-    #   a << ["greg",1,2,3]
-    #   a << ["joe", 2,3,4]
-    #   a << ["greg",7,8,9]
-    #   a << ["joe", 1,2,3]
+    #     sub_table = table.sub_table(%w[a b],1..-2)
+    #     sub_table == [[1,2],[3,4]].to_table(%w[a b]) #=> true
     #
-    #   b = a.split :group => "name"
+    #  Using just column_names:
     #
-    #   b.greg.eql? [[1,2,3],[7,8,9]].to_table(%w[a b c]) #=> true
-    #   b["joe"].eql? [[2,3,4],[1,2,3]].to_table(%w[a b c]) #=> true
+    #     sub_table = table.sub_table(%w[a d])
+    #     sub_table == [[1,4],[5,8],[9,12]].to_table(%w[a d]) #=> true
     #
-    # You can also pass an Array to <tt>:group</tt>, and the resulting 
-    # attributes in the group will be joined by an underscore. 
+    #  Using column_names and a block:
     # 
-    # Example:
-    #
-    #   a = Table.new(:column_names => %w[first_name last_name x]
-    #   a << %w[greg brown foo]
-    #   a << %w[greg gibson bar]
-    #   a << %w[greg brown baz]
-    #
-    #   b = a.split :group => %w[first_name last_name]
-    #   a.greg_brown.length     #=> 2
-    #   a["greg_gibson"].length #=> 1
-    #   a.greg_brown[0].x       #=> "foo"
-    #
-    def split(options={})
-      if options[:group].kind_of? Array
-        group = map { |r| options[:group].map { |e| r[e] } }.uniq
-         data = group.inject([]) { |s,g|
-           s + [select { |r| options[:group].map { |e| r[e] }.eql?(g) }]
-         }
-         c = column_names - options[:group]
-      else
-        group = map { |r| r[options[:group]] }.uniq 
-        data = group.inject([]) { |s,g| 
-          s + [select { |r| r[options[:group]].eql?(g) }] 
-        }
-        c = column_names - [options[:group]]
-
-      end 
-      data.map! { |g| 
-        Ruport::Data::Table.new(
-          :data => g.map { |x| x.reorder(*c) },
-          :column_names => c
-        )
-      }
-      rec = if options[:group].kind_of? Array
-        Ruport::Data::Record.new(data, 
-          :attributes => group.map { |e| e.join("_") } )
+    #     sub_table = table.sub_table(%w[d b]) { |r| r.a < 6 } 
+    #     sub_table == [[4,2],[8,6]].to_table(%w[b d]) #=> true
+    #
+    #  Using just a block:
+    #      
+    #     sub_table = table.sub_table { |r| r.c > 10 }
+    #     sub_table == [[9,10,11,12]].to_table(%w[a b c d]) #=> true
+    #
+    # FIXME: loses tags
+    def sub_table(columns=column_names,range=nil)      
+       Table(columns) do |t|
+         if range
+           data[range].each { |r| t << r }
+         elsif block_given?
+           data.each { |r| t << r if yield(r) }
+         else
+           data.each { |r| t << r } 
+         end
+       end      
+    end
+    
+    # returns an array of values for the given column_name
+    def column(name)
+      case(name)
+      when Integer
+         unless column_names.empty?
+          raise ArgumentError if name > column_names.length         
+        end
       else
-        Ruport::Data::Record.new data, :attributes => group
+        raise ArgumentError unless column_names.include?(name)
       end
-      class << rec
-        def each_group; attributes.each { |a| yield(a) }; end
-      end; rec
+         
+       map { |r| r[name] }
     end
     
     # Calculates sums. If a column name or index is given, it will try to
@@ -380,11 +438,12 @@ module Ruport::Data
         else
           s + yield(r)    
         end
-      }
+      }      
     end
 
     alias_method :sum, :sigma
-    
+
+    #
     # Returns a sorted table. If col_names is specified, 
     # the block is ignored and the table is sorted by the named columns. All
     # options are used in constructing the new Table (see Array#to_table
@@ -424,9 +483,104 @@ module Ruport::Data
       table.tags = self.tags
       return table
     end
-        
-  end
 
+    def rows_with(columns,&block) 
+      select { |r|
+        if block
+          block[*(columns.map { |c| r.get(c) })]
+        else
+          columns.all? { |k,v| r.get(k) == v }
+        end
+      }
+    end
+                                                                                
+    # Create a copy of the Table: records will be copied as well.
+    #
+    # Example:
+    #
+    #   one = Table.new :data => [1,2], [3,4], 
+    #                   :column_names => %w[a b]
+    #   two = one.dup
+    #
+    def dup
+      a = self.class.new(:data => @data, :column_names => @column_names)
+      a.tags = tags.dup
+      return a
+    end     
+    
+    #
+    # Uses Ruport's built-in text plugin to render this Table into a String
+    # 
+    # Example:
+    # 
+    #   data = Table.new :data => [1,2], [3,4], 
+    #                    :column_names => %w[a b]
+    #   puts data.to_s
+    # 
+    def to_s
+      as(:text)
+    end     
+                             
+    # NOTE: does not respect tainted status
+    alias_method :clone, :dup
+
+
+    # Provides a shortcut for the <tt>as()</tt> method by converting a call to
+    # <tt>as(:format_name)</tt> into a call to <tt>to_format_name</tt>
+    def method_missing(id,*args)
+     return as($1.to_sym) if id.to_s =~ /^to_(.*)/ 
+     return rows_with($1.to_sym => args[0]) if id.to_s =~ /^rows_with_(.*)/
+     super
+    end
+    
+    # Loads a CSV file directly into a Table using the FasterCSV library.
+    #
+    # Example:
+    #   
+    #   # treat first row as column_names
+    #   table = Table.load('mydata.csv')
+    #
+    #   # do not assume the data has column_names
+    #   table = Table.load('mydata.csv',:has_names => false)
+    #
+    #   # pass in FasterCSV options, such as column separators
+    #   table = Table.load('mydata.csv',:csv_opts => { :col_sep => "\t" })
+    #
+    def self.load(csv_file, options={},&block)
+        get_table_from_csv(:foreach, csv_file, options,&block)
+    end
+    
+    #
+    # Creates a Table from a CSV string using FasterCSV.  See Table.load for
+    # additional examples.
+    #
+    #   table = Table.parse("a,b,c\n1,2,3\n4,5,6\n")
+    #
+    def self.parse(string, options={},&block) 
+      get_table_from_csv(:parse,string,options,&block)
+    end
+
+    private
+    
+    def self.get_table_from_csv(msg,param,options={},&block) #:nodoc:
+      options = {:has_names => true,
+                 :csv_options => {} }.merge(options)
+      require "fastercsv"
+      loaded_data = self.new
+
+      first_line = true
+      FasterCSV.send(msg,param,options[:csv_options]) do |row|
+        if first_line && options[:has_names]
+          loaded_data.column_names = row
+          first_line = false
+        elsif !block
+          loaded_data << row
+        else
+         block[loaded_data,row]
+        end
+      end ; loaded_data
+    end      
+  end
 end
 
 
@@ -452,21 +606,20 @@ module Kernel
     table=
     case(args[0])
     when Array
-      [].to_table(args[0])
+      opts = args[1] || {}
+      Ruport::Data::Table.new(f={:column_names => args[0]}.merge(opts))
     when /\.csv/
       Ruport::Data::Table.load(*args)
     else
        [].to_table(args)
-    end
-
+    end             
+    
     block[table] if block
-
     return table
   end
-end
+end  
 
 class Array
-
   #
   # Converts an array to a Ruport::Data::Table object, ready to
   # use in your reports.
@@ -477,5 +630,5 @@ class Array
   def to_table(column_names=nil)
     Ruport::Data::Table.new({:data => self, :column_names => column_names})
   end
-end
 
+end