ruport 0.8.14 → 0.10.0

data/lib/ruport/data.rb

@@ -1,4 +1,3 @@
-require "ruport/data/groupable" 
-require "ruport/data/taggable" 
 require "ruport/data/record" 
 require "ruport/data/table" 
+require "ruport/data/grouping"

data/lib/ruport/data/grouping.rb

@@ -0,0 +1,311 @@
+module Ruport::Data
+
+  # === Overview
+  #
+  # This class implements a group data structure for Ruport. Group is
+  # simply a subclass of Table that adds a :name attribute.
+  # 
+  class Group < Table
+    
+    attr_reader :name, :subgroups
+
+    # Creates a new Group based on the supplied options.
+    #
+    # Valid options:
+    # <b><tt>:name</tt></b>::         The name of the Group
+    # <b><tt>:data</tt></b>::         An Array of Arrays representing the 
+    #                                 records in this Group
+    # <b><tt>:column_names</tt></b>:: An Array containing the column names 
+    #                                 for this Group.
+    #
+    # Example:
+    #
+    #   group = Group.new :name => 'My Group',
+    #                     :data => [[1,2,3], [3,4,5]], 
+    #                     :column_names => %w[a b c]
+    #
+    def initialize(options={})
+      @name = options.delete(:name)
+      @subgroups = {}
+      super
+    end
+          
+    include Ruport::Renderer::Hooks
+    renders_as_group
+
+    def self.inherited(base)
+      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)
+      super
+      @name = from.name
+      @subgroups = from.subgroups.inject({}) { |h,d|
+        h.merge!({ d[0] => d[1].dup }) }
+    end
+
+    # Compares this Group to another Group and returns <tt>true</tt> if
+    # the <tt>name</tt>, <tt>data</tt>, and <tt>column_names</tt> are equal.
+    #
+    # Example:
+    #
+    #   one = Group.new :name => 'test',
+    #                   :data => [[1,2], [3,4]], 
+    #                   :column_names => %w[a b]
+    #
+    #   two = Group.new :name => 'test',
+    #                   :data => [[1,2], [3,4]], 
+    #                   :column_names => %w[a b]
+    #
+    #   one.eql?(two) #=> true
+    #
+    def eql?(other)
+      name.eql?(other.name) && super
+    end
+
+    alias_method :==, :eql?
+
+    # Creates subgroups for the group based on the supplied column name.  Each
+    # subgroup is a hash whose keys are the unique values in the column.
+    #
+    # Example:
+    #
+    #   main_group = Group.new :name => 'test',
+    #                          :data => [[1,2,3,4,5], [3,4,5,6,7]], 
+    #                          :column_names => %w[a b c d e]
+    #   main_group.create_subgroups("a")
+    #
+    def create_subgroups(group_column)
+      if @subgroups.empty?
+        @subgroups = grouped_data(group_column)
+      else
+        @subgroups.each {|name,group| group.create_subgroups(group_column) }
+      end
+    end
+
+    protected
+
+    attr_writer :name, :subgroups
+    
+    private
+    
+    def grouped_data(group_column) #:nodoc:
+      data = {}
+      group_names = column(group_column).uniq
+      columns = column_names.dup
+      columns.delete(group_column)
+      group_names.each do |name|
+        group_data = sub_table(columns) {|r|
+          r.send(group_column) == name
+        }
+        data[name] = Group.new(:name => name, :data => group_data,
+                               :column_names => columns,
+                               :record_class => record_class)
+      end      
+      data
+    end
+
+  end
+  
+  
+  # === Overview
+  #
+  # This class implements a grouping data structure for Ruport.  A grouping is
+  # a collection of groups. It allows you to group the data in a table by one
+  # or more columns that you specify.
+  #   
+  # The data for a grouping is a hash of groups, keyed on each unique data
+  # point from the grouping column.
+  #
+  class Grouping
+    
+    include Enumerable
+    
+    # Creates a new Grouping based on the supplied options.
+    #
+    # Valid options:
+    # <b><tt>:by</tt></b>::  A column name or array of column names that the
+    #                        data will be grouped on.
+    #
+    # Example:
+    #
+    #   table = [[1,2,3],[4,5,6]].to_table(%w[a b c])
+    #
+    #   grouping = Grouping.new(table, :by => "a")
+    #
+    def initialize(data,options={})
+      @grouped_by = options[:by] 
+      cols = Array(options[:by]).dup
+      @data = data.to_group.send(:grouped_data, cols.shift)
+      cols.each do |col|
+        @data.each do |name,group|
+          group.create_subgroups(col)
+        end
+      end
+    end
+    
+    attr_accessor :data 
+    attr_reader :grouped_by
+    
+    require "forwardable"
+    extend Forwardable
+    def_delegator :@data, :each
+    
+    # Allows Hash-like indexing of the grouping data.
+    #
+    # Examples:
+    #
+    #   my_grouping["foo"]
+    #
+    def [](name)
+      @data[name] or 
+        raise(IndexError,"Group Not Found")
+    end 
+    
+    # Used to add extra data to the Grouping. <tt>other</tt> should be a Group.
+    #
+    # Example:
+    #
+    #   table = [[1,2,3],[4,5,6]].to_table(%w[a b c])
+    #
+    #   grouping = Grouping.new(table, :by => "a")
+    #
+    #   group = Group.new :name => 7,
+    #                     :data => [[8,9]], 
+    #                     :column_names => %w[b c]
+    #
+    #   grouping << group
+    #
+    def <<(group)        
+      if data.has_key? group.name
+        raise(ArgumentError, "Group '#{group.name}' exists!") 
+      end
+      @data.merge!({ group.name => group })
+    end
+
+    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
+    # subgroups of the group.
+    #
+    def subgrouping(name)
+      grouping = dup
+      grouping.send(:data=, @data[name].subgroups)
+      return grouping
+    end
+    
+    alias_method :/, :subgrouping
+   
+    # Useful for creating basic summaries from Grouping objects.
+    # Takes a field to summarize on, and then for each group,
+    # runs the specified procs and returns the results as a Table.
+    #     
+    # The following example would show for each date group,
+    # the sum for the attributes or methods :opened and :closed
+    # and order them by the :order array.
+    #
+    # If :order is not specified, you cannot depend on predictable column order
+    #
+    #   grouping.summary :date,
+    #     :opened => lambda { |g| g.sigma(:opened) },
+    #     :closed => lambda { |g| g.sigma(:closed) },
+    #     :order => [:date,:opened,:closed]
+    #
+    def summary(field,procs)     
+      if procs[:order].kind_of?(Array)
+        cols = procs.delete(:order) 
+      else 
+        cols = procs.keys + [field]   
+      end
+      expected = Table(cols) { |t|
+        each do |name,group|
+          t << procs.inject({field => name}) do |s,r|
+            s.merge(r[0] => r[1].call(group))
+          end 
+        end
+        t.reorder(cols)     
+      }   
+    end
+
+    # Uses Ruport's built-in text formatter to render this Grouping
+    # 
+    # Example:
+    # 
+    #   table = [[1,2,3],[4,5,6]].to_table(%w[a b c])
+    #
+    #   grouping = Grouping.new(table, :by => "a")
+    #
+    #   puts grouping.to_s
+    #
+    def to_s
+      as(:text)
+    end
+    
+    include Ruport::Renderer::Hooks
+    renders_as_grouping
+
+    def self.inherited(base)
+      base.renders_as_grouping
+    end
+
+    
+    # Create a copy of the Grouping: groups will be copied as well.
+    #
+    # Example:
+    #
+    #   table = [[1,2,3],[4,5,6]].to_table(%w[a b c])
+    #   one = Ruport::Data::Grouping.new(a, :by => "a")
+    #
+    #   two = one.dup
+    #
+    def initialize_copy(from)
+      @grouped_by = from.grouped_by
+      @data = from.data.inject({}) { |h,d| h.merge!({ d[0] => d[1].dup }) }
+    end
+
+    # Provides a shortcut for the <tt>as()</tt> method by converting a call to
+    # <tt>to_format_name</tt> into a call to <tt>as(:format_name)</tt>.
+    #
+    def method_missing(id,*args)
+      return as($1.to_sym,*args) if id.to_s =~ /^to_(.*)/ 
+      super
+    end
+    
+  end
+  
+end     
+
+module Kernel 
+
+  # Shortcut interface for creating Data::Grouping
+  #
+  # Example:
+  #
+  #   a = [[1,2,3],[4,5,6]].to_table(%w[a b c])
+  #   b = Grouping(a, :by => "a")   #=> creates a new grouping on column "a"
+  #
+  def Grouping(*args)
+    Ruport::Data::Grouping.new(*args)
+  end       
+  
+  # Shortcut interface for creating Data::Group
+  #
+  # Example:
+  #
+  #   g = Group('mygroup', :data => [[1,2,3],[4,5,6]],
+  #         :column_names => %w[a b c])   #=> creates a new group named mygroup
+  #
+  def Group(name,opts={})
+    Ruport::Data::Group.new(opts.merge(:name => name))  
+  end
+end

data/lib/ruport/data/record.rb

@@ -14,7 +14,6 @@ module Ruport::Data
   #
   class Record
 
-    include Taggable
     include Enumerable  
     
     # 
@@ -54,7 +53,41 @@ module Ruport::Data
         @data = data.dup
         @attributes = options[:attributes] || data.keys
       end
-    end 
+    end        
+    
+    
+    ##############
+    # Delegators #
+    ##############
+    
+    # Returns a copy of the <tt>attributes</tt> from this Record.
+    #
+    # Example:
+    #
+    #   a = Data::Record.new([1,2],:attributes => %w[a b])
+    #   a.attributes #=> ["a","b"]
+    #
+    def attributes
+      @attributes.dup
+    end
+    
+    #
+    # Sets the <tt>attribute</tt> list for this Record. 
+    # (Dangerous when used within Table objects!)
+    #
+    # Example:
+    #
+    #   my_record.attributes = %w[foo bar baz]
+    #
+    attr_writer :attributes        
+ 
+    attr_reader :data   
+    def size; @data.size; end
+    alias_method :length, :size
+    
+    ##################
+    # Access Methods #
+    ##################
     
     #
     # Allows either Array or Hash-like indexing.
@@ -90,11 +123,31 @@ module Ruport::Data
         @attributes << index unless @attributes.include? index
       end
     end
-
-    def size
-      @data.size
-    end
-    alias_method :length, :size
+    
+    # Indifferent access to attributes.
+    #  
+    # Examples:
+    #          
+    #   record.get(:foo) # looks for an attribute "foo" or :foo,
+    #                      or calls the method <tt>foo</tt>
+    #
+    #   record.get("foo") # looks for an attribute "foo" or :foo
+    #
+    #   record.get(0) # Gets the first element
+    def get(name)
+      case name
+      when String,Symbol
+        self[name] || send(name)
+      when Fixnum
+        self[name]
+      else
+        raise ArgumentError, "Whatchu Talkin' Bout, Willis?"
+      end
+    end          
+    
+    ################
+    #  Conversions #
+    ################
     
     #
     # Converts a Record into an Array.
@@ -104,47 +157,23 @@ module Ruport::Data
     #   a = Data::Record.new([1,2],:attributes => %w[a b])
     #   a.to_a #=> [1,2]
     #
-    # Note: in earlier versions of Ruport, to_a was aliased to data.
-    #       From now on to_a only for array representation! 
     def to_a
       @attributes.map { |a| @data[a] }
     end
-       
-     attr_reader :data
-    
-     #
-     # Converts a Record into a Hash. 
-     #
-     # Example:
-     #
-     #   a = Data::Record.new([1,2],:attributes => %w[a b])
-     #   a.to_h #=> {"a" => 1, "b" => 2}
-    def to_h
-      @data.dup
-    end          
-    
-    #alias_method :data,:to_a
-     
-    # Returns a copy of the <tt>attributes</tt> from this Record.
+         
+    # Converts a Record into a Hash. 
     #
     # Example:
     #
     #   a = Data::Record.new([1,2],:attributes => %w[a b])
-    #   a.attributes #=> ["a","b"]
-    #
-    def attributes
-      @attributes.dup
+    #   a.to_hash #=> {"a" => 1, "b" => 2}
+    def to_hash
+      @data.dup
     end
-    
-    #
-    # Sets the <tt>attribute</tt> list for this Record. 
-    # (Dangerous when used within Table objects!)
-    #
-    # Example:
-    #
-    #   my_record.attributes = %w[foo bar baz]
-    #
-    attr_writer :attributes
+        
+    ################
+    #  Comparisons #
+    ################
     
     #
     # If <tt>attributes</tt> and <tt>to_a</tt> are equivalent, then 
@@ -155,11 +184,28 @@ module Ruport::Data
        to_a == other.to_a
     end
     
-    alias_method :eql?, :==
+    alias_method :eql?, :==  
+    
+    
+    #############
+    # Iterators #
+    #############
     
     # Yields each element of the Record.  Does not provide attribute names
     def each 
       to_a.each { |e| yield(e) }
+    end   
+    
+    #################
+    # Manipulations #
+    ################# 
+    
+    # Takes an old name and a new name and renames an attribute.  
+    #
+    # The third option, update_index is for internal use.    
+    def rename_attribute(old_name,new_name,update_index=true)
+      @attributes[@attributes.index(old_name)] = new_name if update_index
+      @data[new_name] = @data.delete(old_name)
     end
     
     #
@@ -182,16 +228,19 @@ module Ruport::Data
         self.attributes = indices
       end
       self
-    end  
-     
-    # Takes an old name and a new name and renames an attribute.  
-    #
-    # The third option, update_index is for internal use.    
-    def rename_attribute(old_name,new_name,update_index=true)
-      @attributes[@attributes.index(old_name)] = new_name if update_index
-      @data[new_name] = @data.delete(old_name)
     end
-    
+       
+    ####################### 
+    # Internals / Helpers #
+    #######################       
+
+    include Ruport::Renderer::Hooks
+    renders_as_row
+
+    def self.inherited(base)
+      base.renders_as_row
+    end
+
     #
     # Provides a unique hash value. If a Record contains the same data and
     # attributes as another Record, they will hash to the same value, even if
@@ -202,13 +251,11 @@ module Ruport::Data
       @attributes.hash + to_a.hash
     end
     
-    # Makes a fresh copy of the Record. 
-    def dup
-      r = Record.new(@data.dup,:attributes => @attributes.dup)
-      r.tags = tags.dup
-      return r
+    def initialize_copy(from)
+       @data = from.data.dup
+       @attributes = from.attributes.dup
     end
-        
+
     # Provides accessor style methods for attribute access.
     #
     # Example:
@@ -216,37 +263,20 @@ module Ruport::Data
     #   my_record.foo = 2
     #   my_record.foo #=> 2
     #
-    def method_missing(id,*args)
+    # Also provides a shortcut for the <tt>as()</tt> method by converting a
+    # call to <tt>to_format_name</tt> into a call to <tt>as(:format_name)</tt>
+    #
+    def method_missing(id,*args,&block)
       k = id.to_s.gsub(/=$/,"")
-      if(key = @attributes.find { |r| r.to_s.eql?(k) })
-        args[0] ? @data[key] = args[0] : @data[key]
-      else
-       super
-     end
-    end 
+      key_index = @attributes.index(k) || @attributes.index(k.to_sym)
 
-    # Indifferent access to attributes.
-    #  
-    # Examples:
-    #          
-    #   record.get(:foo) # looks for an attribute "foo" or :foo,
-    #                      or calls the method <tt>foo</tt>
-    #
-    #   record.get("foo") # looks for an attribute "foo" or :foo
-    #
-    #   record.get(0) # Gets the first element
-    def get(name)
-      case name
-      when Symbol
-        send(name)
-      when String
-        self[attributes.find { |a| a.to_s.eql?(name)}]
-      when Fixnum
-        self[name]
+      if key_index
+        args[0] ? self[key_index] = args[0] : self[key_index]
       else
-        raise "Whatchu Talkin' Bout, Willis?"
+        return as($1.to_sym,*args,&block) if id.to_s =~ /^to_(.*)/ 
+        super
       end
-    end
+    end 
     
     private
     
@@ -255,7 +285,6 @@ module Ruport::Data
       @attributes.delete(key)
     end
 
-
     def reindex(new_attributes)
       @attributes = new_attributes
     end