ruport 1.0.2 → 1.2.0

data/lib/ruport/data/grouping.rb

@@ -51,16 +51,7 @@ module Ruport::Data
       base.renders_as_group
     end
 
-    # Create a copy of the Group. Records will be copied as well.
-    #
-    # Example:
-    #
-    #   one = Group.new :name => 'test',
-    #                   :data => [[1,2], [3,4]],
-    #                   :column_names => %w[a b]
-    #   two = one.dup
-    #
-    def initialize_copy(from)
+    def initialize_copy(from) #:nodoc:
       super
       @name = from.name
       @subgroups = from.subgroups.inject({}) { |h,d|
@@ -149,20 +140,34 @@ module Ruport::Data
     #
     # Valid options:
     # <b><tt>:by</tt></b>::  A column name or array of column names that the
-    #                        data will be grouped on.
+    #                        data will be grouped on. 
+    # <b><tt>:order</tt></b>:: Determines the iteration and presentation order
+    #                          of a Grouping object.  Set to :name to order by 
+    #                          Group names.  You can also provide a lambda which
+    #                          will be passed Group objects, and use semantics
+    #                          similar to Enumerable#group_by    
     #
-    # Example:
-    #
-    #   table = [[1,2,3],[4,5,6]].to_table(%w[a b c])
+    # Examples:
     #
+    #   table = [[1,2,3],[4,5,6],[1,1,2]].to_table(%w[a b c])
+    #   
+    #   # unordered 
     #   grouping = Grouping.new(table, :by => "a")
+    #               
+    #   # ordered by group name
+    #   grouping = Grouping.new(table, :by => "a", :order => :name)
     #
+    #   # ordered by group size
+    #   grouping = Grouping.new(table, :by => "a", 
+    #                                  :order => lambda { |g| g.size } )
     def initialize(data={},options={})
       if data.kind_of?(Hash)
-        @grouped_by = data[:by] 
+        @grouped_by = data[:by]
+        @order = data[:order] 
         @data = {}
       else
-        @grouped_by = options[:by] 
+        @grouped_by = options[:by]    
+        @order = options[:order]
         cols = Array(options[:by]).dup
         @data = data.to_group.send(:grouped_data, cols.shift)
         cols.each do |col|
@@ -192,9 +197,35 @@ module Ruport::Data
     
     # Iterates through the Grouping, yielding each group name and Group object
     #
-    def each
-      @data.each { |name,group| yield(name,group) }
-    end 
+    def each 
+      if @order.respond_to?(:call) 
+        @data.sort_by { |n,g| @order[g] }.each { |n,g| yield(n,g) }
+      elsif @order == :name
+        @data.sort_by { |n,g| n }.each { |name,group| yield(name,group) } 
+      else
+        @data.each { |name,group| yield(name,group) }
+      end
+    end                                                                       
+    
+    
+    # Returns a new grouping with the specified sort order.
+    # You can sort by Group name or an arbitrary block
+    #
+    #   by_name = grouping.sort_grouping_by(:name) 
+    #   by_size = grouping.sort_grouping_by { |g| g.size }
+    def sort_grouping_by(type=nil,&block)
+      a = Grouping.new(:by => @grouped_by, :order => type || block)
+      each { |n,g| a << g }
+      return a
+    end
+                                                          
+    # Applies the specified sort order to an existing Grouping object.
+    #
+    #   grouping.sort_grouping_by!(:name)
+    #   grouping.sort_grouping_by! { |g| g.size }
+    def sort_grouping_by!(type=nil,&block)
+      @order = type || block
+    end  
     
     # Used to add extra data to the Grouping. <tt>group</tt> should be a Group.
     #
@@ -217,7 +248,7 @@ module Ruport::Data
       @data.merge!({ group.name => group })
     end
 
-    alias_method :append, :<<
+    alias_method :append, :<< 
 
     # Provides access to the subgroups of a particular group in the Grouping.
     # Supply the name of a group and it returns a Grouping created from the
@@ -259,7 +290,7 @@ module Ruport::Data
             s.merge(r[0] => r[1].call(group))
           end 
         end
-        t.reorder(cols)     
+        t.data.reorder(cols)     
       }   
     end
 
@@ -277,6 +308,37 @@ module Ruport::Data
       as(:text)
     end
     
+    # Calculates sums. If a column name or index is given, it will try to
+    # convert each element of that column to an integer or float 
+    # and add them together.  The sum is calculated across all groups in
+    # the grouping.
+    #
+    # If a block is given, it yields each Record in each Group so that you can
+    # do your own calculation.
+    #
+    # Example:
+    #
+    #   table = [[1,2,3],[3,4,5],[5,6,7]].to_table(%w[col1 col2 col3])
+    #   grouping = Grouping(table, :by => "col1")
+    #   grouping.sigma("col2") #=> 12
+    #   grouping.sigma(0)      #=> 12
+    #   grouping.sigma { |r| r.col2 + r.col3 } #=> 27
+    #   grouping.sigma { |r| r.col2 + 1 } #=> 15
+    #
+    def sigma(column=nil)
+      inject(0) do |s, (group_name, group)|
+        if column
+          s + group.sigma(column)
+        else
+          s + group.sigma do |r|
+            yield(r)
+          end
+        end
+      end
+    end
+
+    alias_method :sum, :sigma
+
     include Ruport::Renderer::Hooks
     renders_as_grouping
 
@@ -293,7 +355,7 @@ module Ruport::Data
     #
     #   two = one.dup
     #
-    def initialize_copy(from)
+    def initialize_copy(from)  #:nodoc:
       @grouped_by = from.grouped_by
       @data = from.data.inject({}) { |h,d| h.merge!({ d[0] => d[1].dup }) }
     end

data/lib/ruport/data/record.rb

@@ -252,7 +252,7 @@ module Ruport::Data
     #   one = Record.new([1,2,3,4],:attributes => %w[a b c d])
     #   two = one.dup
     #
-    def initialize_copy(from)
+    def initialize_copy(from) #:nodoc:
        @data = from.data.dup
        @attributes = from.attributes.dup
     end

data/lib/ruport/data/table.rb

@@ -22,7 +22,7 @@ module Ruport::Data
   # Once your data is in a Table object, it can be manipulated
   # to suit your needs, then used to build a report.
   #
-  class Table 
+  class Table
 
     # === Overview
     #
@@ -51,7 +51,7 @@ module Ruport::Data
       #
       #   table = Table.parse("a,b,c\n1,2,3\n4,5,6\n")
       #
-      def parse(string, options={},&block) 
+      def parse(string, options={},&block)
         get_table_from_csv(:parse,string,options,&block)
       end
 
@@ -66,35 +66,33 @@ module Ruport::Data
         # 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
+        table = self.new(options) do |feeder|
+          first_line = true
+          FasterCSV.send(msg,param,options[:csv_options]) do |row|
+            if first_line
+              adjust_for_headers(feeder.data,row,options)
+              first_line = false
+              next if options[:has_names]
+            end
+               
+            if block
+              handle_csv_row_proc(feeder,row,options,block)
+            else
+              feeder << row
+            end  
           end
-
         end
-
-        return loaded_data
+        
+        return table
       end
 
-      def handle_csv_row_proc(data,row,options,block)
+      def handle_csv_row_proc(feeder,row,options,block)
         if options[:records]
           rc = options[:record_class] || Record
-          row = rc.new(row, :attributes => data.column_names)
+          row = rc.new(row, :attributes => feeder.data.column_names)
         end
         
-        block[data,row]
+        block[feeder,row]
       end
        
       def adjust_options_for_fcsv_headers(options)
@@ -127,6 +125,15 @@ module Ruport::Data
     #                                   records in this Table.
     # <b><tt>:column_names</tt></b>::   An Array containing the column names 
     #                                   for this Table.
+    # <b><tt>:filters</tt></b>::        A proc or array of procs that set up
+    #                                   conditions to filter the data being
+    #                                   added to the table.
+    # <b><tt>:transforms</tt></b>::     A proc or array of procs that perform
+    #                                   transformations on the data being added
+    #                                   to the table.
+    # <b><tt>:record_class</tt></b>::   Specify the class of the table's
+    #                                   records.
+    #
     # Example:
     #
     #   table = Table.new :data => [[1,2,3], [3,4,5]], 
@@ -136,20 +143,30 @@ module Ruport::Data
       @column_names = options[:column_names] ? options[:column_names].dup : []
       @record_class = options[:record_class] &&
                       options[:record_class].name || "Ruport::Data::Record"
-      @data         = []
+      @data         = []  
+      
+      feeder = Feeder.new(self)
+     
+      Array(options[:filters]).each { |f| feeder.filter(&f) }
+      Array(options[:transforms]).each { |t| feeder.transform(&t) }
+      
       if options[:data]
-        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
+        options[:data].each do |e|
+          if e.kind_of?(Record)
+            e = if @column_names.empty? or 
+                   e.attributes.all? { |a| a.kind_of?(Numeric) }
+              e.to_a
             else
-              r.to_hash.values_at(*@column_names)  
+              e.to_hash.values_at(*@column_names)  
             end
-          }
-        end 
-        options[:data].each { |e| self << e }  
-      end
+          end
+          r = recordize(e)
+                                                     
+          feeder << r
+        end  
+      end    
+      
+      yield(feeder) if block_given?  
     end
 
     # This Table's column names
@@ -221,17 +238,8 @@ module Ruport::Data
     #   data << Record.new [5,6], :attributes => %w[a b]
     #
     def <<(row)
-      case row
-      when Array
-        append_array(row)
-      when Hash
-        append_hash(row)            
-      when record_class     
-        append_record(row)
-      else
-        append_hash(row) rescue append_array(row)
-      end    
-      return self
+      @data << recordize(row)
+      return self   
     end    
     
     # Returns the record class constant being used by the table.
@@ -323,7 +331,7 @@ module Ruport::Data
     #   # 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={})  
+    def add_column(name,options={})
       if pos = options[:position]
         column_names.insert(pos,name)   
       elsif pos = options[:after]
@@ -352,7 +360,7 @@ module Ruport::Data
     #
     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?           
+            "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) } 
@@ -366,8 +374,8 @@ 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           
+    def remove_column(col)
+      col = column_names[col] if col.kind_of? Fixnum
       column_names.delete(col)
       each { |r| r.send(:delete,col) }
     end
@@ -522,12 +530,12 @@ module Ruport::Data
     #     sub_table = table.sub_table { |r| r.c > 10 }
     #     sub_table == [[9,10,11,12]].to_table(%w[a b c d]) #=> true
     #
-    def sub_table(cor=column_names,range=nil,&block)      
-      if range                                        
+    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        
+      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)  
@@ -590,7 +598,7 @@ module Ruport::Data
             r.get(column) =~ /\./ ? r.get(column).to_f : r.get(column).to_i
           end
         else
-          s + yield(r)    
+          s + yield(r)
         end
       }      
     end
@@ -598,9 +606,11 @@ 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
-    # for details).
+    # the block is ignored and the table is sorted by the named columns.
+    #
+    # The second argument specifies sorting options. Currently only
+    # :order is supported. Default order is ascending, to sort decending
+    # use :order => :descending
     #
     # Example:
     #
@@ -609,26 +619,42 @@ module Ruport::Data
     #   # returns a new table sorted by col1
     #   table.sort_rows_by {|r| r["col1"]}
     #
+    #   # returns a new table sorted by col1, in descending order
+    #   table.sort_rows_by(nil, :order => :descending) {|r| r["col1"]}
+    #
     #   # returns a new table sorted by col2
-    #   table.sort_rows_by ["col2"]
+    #   table.sort_rows_by(["col2"])
+    #
+    #   # returns a new table sorted by col2, descending order
+    #   table.sort_rows_by("col2", :order => :descending)
     #
     #   # returns a new table sorted by col1, then col2
-    #   table.sort_rows_by ["col1", "col2"]
+    #   table.sort_rows_by(["col1", "col2"])
+    #
+    #   # returns a new table sorted by col1, then col2, in descending order
+    #   table.sort_rows_by(["col1", "col2"], :order => descending)
     #
-    def sort_rows_by(col_names=nil, &block)
+    def sort_rows_by(col_names=nil, options={}, &block)
       # stabilizer is needed because of 
       # http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/170565
       stabilizer = 0
+      
+      nil_rows, sortable = partition do |r| 
+        Array(col_names).any? { |c| r[c].nil? } 
+      end
 
       data_array =
         if col_names
-          sort_by do |r| 
+          sortable.sort_by do |r| 
             stabilizer += 1
             [Array(col_names).map {|col| r[col]}, stabilizer] 
           end
         else
-          sort_by(&block)
-        end
+          sortable.sort_by(&block)
+        end                 
+                                                               
+      data_array += nil_rows
+      data_array.reverse! if options[:order] == :descending    
 
       table = self.class.new( :data => data_array, 
                               :column_names => @column_names,
@@ -640,8 +666,8 @@ module Ruport::Data
     # Same as Table#sort_rows_by, but self modifying.
     # See <tt>sort_rows_by</tt> for documentation.
     #
-    def sort_rows_by!(col_names=nil,&block)
-      table = sort_rows_by(col_names,&block) 
+    def sort_rows_by!(col_names=nil,options={},&block)
+      table = sort_rows_by(col_names,options,&block) 
       @data = table.data
     end
     
@@ -665,7 +691,7 @@ module Ruport::Data
         end
       }
     end
-                                                                                
+
     # Create a copy of the Table. Records will be copied as well.
     #
     # Example:
@@ -721,24 +747,39 @@ module Ruport::Data
      super
     end
     
-    # Appends an array as a record in the Table.
-    def append_array(array)
-      attributes = @column_names.empty? ? nil : @column_names
-      @data << record_class.new(array.to_ary, :attributes => attributes)  
-    end      
+    def feed_element(row)
+       recordize(row)
+    end
+    
+    private    
     
-    # Appends a hash as a record in the Table.
-    def append_hash(hash_obj) 
+    def recordize(row)
+      case row
+      when Array
+        normalize_array(row)
+      when Hash
+        normalize_hash(row)            
+      when record_class     
+        recordize(normalize_record(row))
+      else
+        normalize_hash(row) rescue normalize_array(row)
+      end    
+    end  
+    
+    def normalize_hash(hash_obj)
       hash_obj = hash_obj.to_hash 
       raise ArgumentError unless @column_names
-      @data << record_class.new(hash_obj, :attributes => @column_names)
-    end
+      record_class.new(hash_obj, :attributes => @column_names)
+    end 
     
-    # Appends a record to the Table.
-    def append_record(record)        
-      self << record.send(column_names.empty? ? :to_a : :to_hash)
-    end
-  
+    def normalize_record(record)
+      record.send(column_names.empty? ? :to_a : :to_hash)
+    end  
+    
+    def normalize_array(array)
+      attributes = @column_names.empty? ? nil : @column_names 
+      record_class.new(array.to_ary, :attributes => attributes)                             
+    end                                            
   end
 end
 
@@ -765,7 +806,7 @@ module Kernel
     case(args[0])
     when Array
       opts = args[1] || {}
-      Ruport::Data::Table.new(f={:column_names => args[0]}.merge(opts))
+      Ruport::Data::Table.new(f={:column_names => args[0]}.merge(opts),&block)
     when /\.csv/
       return Ruport::Data::Table.load(*args,&block)
     when Hash
@@ -774,13 +815,12 @@ module Kernel
       elsif string = args[0].delete(:string)
         return Ruport::Data::Table.parse(string,args[0],&block)
       else
-        return Ruport::Data::Table.new(args[0])
+        return Ruport::Data::Table.new(args[0],&block)
       end
     else
-       Ruport::Data::Table.new(:data => [], :column_names => args)
+       Ruport::Data::Table.new(:data => [], :column_names => args,&block)
     end             
     
-    block[table] if block
     return table
   end
 end  
@@ -793,8 +833,8 @@ class Array
   # Example:
   #   [[1,2],[3,4]].to_table(%w[a b])
   #
-  def to_table(column_names=nil)
-    Ruport::Data::Table.new({:data => self, :column_names => column_names})
+  def to_table(column_names=nil,&b)
+    Ruport::Data::Table.new({:data => self, :column_names => column_names},&b)
   end
 
 end