ruport 0.8.14 → 0.10.0

data/lib/ruport/data/table.rb

@@ -5,40 +5,7 @@
 # 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
 
-    # 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
   #
@@ -53,12 +20,100 @@ module Ruport::Data
   # to suit your needs, then used to build a report.
   #
   class Table 
-    include Collection
-    include Groupable      
-    
-    require "forwardable"
-    extend Forwardable
 
+    module FromCSV
+      # 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 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 parse(string, options={},&block) 
+        get_table_from_csv(:parse,string,options,&block)
+      end
+
+      private
+      
+      def get_table_from_csv(msg,param,options={},&block) #:nodoc:
+        require "fastercsv"
+
+        options = {:has_names => true,
+                   :csv_options => {} }.merge(options)
+        
+        # if people want to use FCSV's header support, let them           
+        adjust_options_for_fcsv_headers(options)
+
+        loaded_data = self.new(options)
+
+        first_line = true
+        FasterCSV.send(msg,param,options[:csv_options]) do |row|
+
+          if first_line
+            adjust_for_headers(loaded_data,row,options)          
+            first_line = false
+            next if options[:has_names] 
+          end
+
+          if block
+            handle_csv_row_proc(loaded_data,row,options,block)
+          else
+            loaded_data << row
+          end
+
+        end
+
+        return loaded_data
+      end
+
+      def handle_csv_row_proc(data,row,options,block)
+        if options[:records]
+          row = Record.new(row, :attributes => data.column_names)
+        end
+        
+        block[data,row]
+      end
+       
+      def adjust_options_for_fcsv_headers(options)
+        options[:has_names] = false if options[:csv_options][:headers]
+      end
+
+      def adjust_for_headers(loaded,row,options)
+        if options[:has_names]
+          loaded.column_names = row
+        elsif options[:csv_options][:headers]
+          loaded.column_names = row.headers
+        end
+      end
+
+    end
+
+
+    include Enumerable             
+    extend FromCSV
+
+    include Ruport::Renderer::Hooks
+    renders_as_table
+
+    def self.inherited(base)
+      base.renders_as_table
+    end
+    
     # Creates a new table based on the supplied options.
     # Valid options: 
     # <b><tt>:data</tt></b>::         An Array of Arrays representing the 
@@ -76,22 +131,28 @@ module Ruport::Data
                       options[:record_class].name || "Ruport::Data::Record"
       @data         = []
       if options[:data]
-        if options[:data].all? { |r| r.kind_of? Record }
-          record_tags = options[:data].map { |r| r.tags.dup }
-          options[:data] = options[:data].map { |r| r.to_a } 
+        if options[:data].all? { |r| r.kind_of? Record }    
+          options[:data] = options[:data].map { |r| 
+            if @column_names.empty? or 
+               r.attributes.all? { |a| a.kind_of?(Numeric) }
+              r.to_a
+            else
+              r.to_hash  
+            end
+          }
         end 
         options[:data].each { |e| self << e }  
-        each { |r| r.tags = record_tags.shift } if record_tags
       end
     end
 
     # This Table's column names.
     attr_reader :column_names
-  
-    attr_reader :data
+    attr_reader :data        
+    
+    require "forwardable"
+    extend Forwardable
     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.
     #
@@ -115,11 +176,10 @@ module Ruport::Data
             end
           }
           r.send(:reindex, @column_names)
-       }
-     end
+        }
+      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.
     #
@@ -140,7 +200,8 @@ module Ruport::Data
     alias_method :==, :eql?
 
     # Used to add extra data to the Table. <tt>other</tt> can be an Array, 
-    # Hash or Record.
+    # Hash or Record. It also can be anything that implements a meaningful
+    # to_hash or to_ary
     #
     # Example:
     #
@@ -150,28 +211,21 @@ module Ruport::Data
     #   data << { :a => 4, :b => 5}
     #   data << Record.new [5,6], :attributes => %w[a b]
     #
-    def <<(other)
-      case other
+    def <<(row)
+      case row
       when Array
-        attributes = @column_names.empty? ? nil : @column_names
-        @data << record_class.new(other, :attributes => attributes)
+        append_array(row)
       when Hash
-        raise ArgumentError unless @column_names
-        arr = @column_names.map { |k| other[k] }
-        @data << record_class.new(arr, :attributes => @column_names)
+        append_hash(row)            
       when record_class     
-        if column_names.empty?
-          self << other.to_a
-        else
-          self << other.to_h
-        end
-        @data.last.tags = other.tags.dup
+        append_record(row)
       else
-        raise ArgumentError
-      end
-      self
-    end
+        append_hash(row) rescue append_array(row)
+      end    
+      return self
+    end    
     
+    # returns the record class constant being used by the table
     def record_class
       @record_class.split("::").inject(Class) { |c,el| c.send(:const_get,el) }
     end
@@ -199,34 +253,24 @@ module Ruport::Data
     end
   
     
-    # Reorders the table's columns.
-    #
-    # Example:
-    # 
-    #   one = Table.new :data => [[1,2], [3,4]], 
-    #                   :column_names => %w[a b]
-    #
-    #   two = one.reorder([1,0])  
-    #
     def reorder(*indices)
+      raise(ArgumentError,"Can't reorder without column names set!") if
+        @column_names.empty?
+      
       indices = indices[0] if indices[0].kind_of? Array
       
       if indices.all? { |i| i.kind_of? Integer }  
         indices.map! { |i| @column_names[i] }  
-      end    
+      end
       
-      @column_names = indices
-                 
-      @data.each { |r| 
-        r.attributes = @column_names
-      }; self
+      reduce(indices)
     end     
 
     
     # Adds an extra column to the Table. Available Options:
     #
-    # <b><tt>:fill</tt></b>:: The default value to use for the column in 
-    #                         existing rows. Set to nil if not specified.
+    # <b><tt>:default</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.
@@ -272,6 +316,15 @@ module Ruport::Data
       else
         each { |r| r[name] = options[:default] }
       end; self
+    end     
+    
+    def add_columns(names,options={})     
+      raise "Greg isn't smart enough to figure this out.\n"+
+            "Send ideas in at http://list.rubyreports.org" if block_given?           
+      need_reverse = !!(options[:after] || options[:position])
+      names = names.reverse if need_reverse
+      names.each { |n| add_column(n,options) } 
+      self
     end
     
     # Removes the given column from the table.  May use name or position.
@@ -280,6 +333,7 @@ module Ruport::Data
     #
     #    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)
@@ -292,6 +346,7 @@ module Ruport::Data
     # Example:
     # 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) }
@@ -306,11 +361,46 @@ module Ruport::Data
     #   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
-    
+
+    # Renames multiple columns.  Takes either a hash of "old" => "new"
+    # names or two arrays of names %w[old names],%w[new names].
+    # 
+    # Example:
+    #
+    #   table.column_names #=> ["a", "b"]
+    #   table.rename_columns ["a", "b"], ["c", "d"]
+    #   table.column_names #=> ["c", "d"]
+    #
+    #   table.column_names #=> ["a", "b"]
+    #   table.rename_columns {"a" => "c", "b" => "d"}
+    #   table.column_names #=> ["c", "d"]
+    #
+    def rename_columns(old_cols=nil,new_cols=nil)
+      if block_given?
+        if old_cols
+          old_cols.each { |c| rename_column(c,yield(c)) }
+        else
+          column_names.each { |c| rename_column(c,yield(c)) }
+        end
+        return
+      end
+      
+      raise ArgumentError unless old_cols
+
+      if new_cols
+        raise ArgumentError,
+          "odd number of arguments" unless old_cols.size == new_cols.size
+        h = Hash[*old_cols.zip(new_cols).flatten]
+      else
+        h = old_cols
+      end
+      h.each {|old,new| rename_column(old,new) }
+    end
     
     #  Exchanges one column with another.
     #
@@ -332,6 +422,7 @@ module Ruport::Data
     #       | 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]
@@ -359,9 +450,14 @@ module Ruport::Data
     #     | 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)
+    #
+    def replace_column(old_col,new_col=nil,&block)
+      if new_col
+        add_column(new_col,:after => old_col,&block)
+        remove_column(old_col)
+      else
+        each { |r| r[old_col] = yield(r) }
+      end
     end         
           
     #  Generates a sub table
@@ -383,39 +479,54 @@ module Ruport::Data
     #  Using column_names and a block:
     # 
     #     sub_table = table.sub_table(%w[d b]) { |r| r.a < 6 } 
-    #     sub_table == [[4,2],[8,6]].to_table(%w[d b]) #=> true
+    #     sub_table == [[4,2],[8,6]].to_table(%w[d b]) #=> true 
+    #
+    #  Using a range for row reduction:
+    #     sub_table = table.sub_table(1..-1)
+    #     sub_table == [[5,6,7,8],[9,10,11,12]].to_table(%w[a b c 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)      
-       t = self.class.new(:column_names => columns,
-                          :record_class => record_class) 
-       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
-       return t     
+    def sub_table(cor=column_names,range=nil,&block)      
+      if range                                        
+        self.class.new(:column_names => cor,:data => data[range])
+      elsif cor.kind_of?(Range)   
+        self.class.new(:column_names => column_names,:data => data[cor])    
+      elsif block        
+        self.class.new( :column_names => cor, :data => data.select(&block))
+      else
+        self.class.new( :column_names => cor, :data => data)  
+      end 
+    end
+
+    # Generates a sub table in place, modifying the receiver. See documentation
+    # for <tt>sub_table</tt>.
+    #
+    def reduce(columns=column_names,range=nil,&block)
+      t = sub_table(columns,range,&block)
+      @data = t.data
+      @column_names = t.column_names
+      self
     end
+
+    alias_method :sub_table!, :reduce
     
-    # returns an array of values for the given column name
+    # Returns an array of values for the given column name.
+    #
     def column(name)
       case(name)
       when Integer
-         unless column_names.empty?
+        unless column_names.empty?
           raise ArgumentError if name > column_names.length         
         end
       else
         raise ArgumentError unless column_names.include?(name)
       end
          
-       map { |r| r[name] }
+      map { |r| r[name] }
     end
     
     # Calculates sums. If a column name or index is given, it will try to
@@ -436,10 +547,10 @@ module Ruport::Data
     def sigma(column=nil)
       inject(0) { |s,r| 
         if column
-          s + if r[column].kind_of? Numeric
-            r[column]
+          s + if r.get(column).kind_of? Numeric
+            r.get(column)
           else
-            r[column] =~ /\./ ? r[column].to_f : r[column].to_i
+            r.get(column) =~ /\./ ? r.get(column).to_f : r.get(column).to_i
           end
         else
           s + yield(r)    
@@ -449,7 +560,6 @@ module Ruport::Data
 
     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
@@ -477,7 +587,7 @@ module Ruport::Data
         if col_names
           sort_by do |r| 
             stabilizer += 1
-            [col_names.map {|col| r[col]}, stabilizer] 
+            [Array(col_names).map {|col| r[col]}, stabilizer] 
           end
         else
           sort_by(&block)
@@ -485,12 +595,17 @@ module Ruport::Data
 
       table = self.class.new( :data => data_array, 
                               :column_names => @column_names,
-                              :record_class => record_class ) 
+                              :record_class => record_class )
 
-      table.tags = self.tags
       return table
+    end   
+    
+    # same as Table#sort_rows_by, but self modifiying
+    def sort_rows_by!(col_names=nil,&block)
+      table = sort_rows_by(col_names,&block) 
+      @data = table.data
     end
-
+    
     def rows_with(columns,&block) 
       select { |r|
         if block
@@ -509,19 +624,14 @@ module Ruport::Data
     #                   :column_names => %w[a b]
     #   two = one.dup
     #
-    def dup
-      a = self.class.new( :data => @data, 
-                          :column_names => @column_names,
-                          :record_class => record_class )
-      a.tags = tags.dup
-      return a
-    end     
-
-    # NOTE: does not respect tainted status
-    alias_method :clone, :dup
+    def initialize_copy(from)
+      @record_class = from.record_class.name
+      @column_names = from.column_names.dup
+      @data = []
+      from.data.each { |r| self << r.dup }
+    end
     
-    #
-    # Uses Ruport's built-in text plugin to render this Table into a String
+    # Uses Ruport's built-in text formatter to render this Table into a String
     # 
     # Example:
     # 
@@ -533,61 +643,45 @@ module Ruport::Data
       as(:text)
     end     
 
+    # Convert the Table into a Group using the supplied group name.
+    #
+    #   data = Table.new :data => [[1,2], [3,4]], 
+    #                    :column_names => %w[a b]
+    #   group = data.to_group("my_group")
+    #
+    def to_group(name=nil)
+      Group.new( :data => data, 
+                 :column_names => column_names,
+                 :name => name,
+                 :record_class => record_class )
+    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_(.*)/ 
+    def method_missing(id,*args,&block)
+     return as($1.to_sym,*args,&block) 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
+    def append_array(array)
+      attributes = @column_names.empty? ? nil : @column_names
+      @data << record_class.new(array.to_ary, :attributes => attributes)  
+    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)
+    def append_hash(hash_obj) 
+      hash_obj = hash_obj.to_hash 
+      raise ArgumentError unless @column_names
+      @data << record_class.new(hash_obj, :attributes => @column_names)
     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      
+    def append_record(record)        
+      self << record.send(column_names.empty? ? :to_a : :to_hash)
+    end
+  
   end
 end
 
@@ -605,8 +699,7 @@ module Kernel
   #   t = Table(%w[a b c]) { |t| t << [1,2,3] } 
   #
   #   # allows loading table from CSV
-  #   # accepts all Data::Table.load options, but block form yields table,
-  #   # not row!
+  #   # accepts all Data::Table.load options, including block (yields table,row)
   #
   #   t = Table("foo.csv")
   #   t = Table("bar.csv", :has_names => false)
@@ -617,9 +710,17 @@ module Kernel
       opts = args[1] || {}
       Ruport::Data::Table.new(f={:column_names => args[0]}.merge(opts))
     when /\.csv/
-      Ruport::Data::Table.load(*args)
+      return Ruport::Data::Table.load(*args,&block)
+    when Hash
+      if file = args[0].delete(:file)
+        return Ruport::Data::Table.load(file,args[0],&block)
+      elsif string = args[0].delete(:string)
+        return Ruport::Data::Table.parse(string,args[0],&block)
+      else
+        return Ruport::Data::Table.new(args[0])
+      end
     else
-       Ruport::Data::Table.new(:data => [],:column_names => args)
+       Ruport::Data::Table.new(:data => [], :column_names => args)
     end             
     
     block[table] if block
@@ -628,7 +729,7 @@ module Kernel
 end  
 
 class Array
-  #
+
   # Converts an array to a Ruport::Data::Table object, ready to
   # use in your reports.
   #