ruport 0.10.0 → 0.11.0

data/lib/ruport/data/grouping.rb

@@ -1,13 +1,27 @@
+# Ruport : Extensible Reporting System                                
+#
+# data/grouping.rb provides group and grouping data structures for Ruport.
+#     
+# Created by Michael Milner / Gregory Brown, 2007     
+# Copyright (C) 2007 Michael Milner / Gregory Brown, All Rights Reserved.  
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.   
+#
 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.
+  # simply a subclass of Table that adds a <tt>:name</tt> attribute.
   # 
   class Group < Table
     
-    attr_reader :name, :subgroups
+    # The name of the group
+    attr_reader :name
+    
+    # A hash of subgroups
+    attr_reader :subgroups
 
     # Creates a new Group based on the supplied options.
     #
@@ -33,11 +47,11 @@ module Ruport::Data
     include Ruport::Renderer::Hooks
     renders_as_group
 
-    def self.inherited(base)
+    def self.inherited(base) #:nodoc:
       base.renders_as_group
     end
 
-    # Create a copy of the Group: records will be copied as well.
+    # Create a copy of the Group. Records will be copied as well.
     #
     # Example:
     #
@@ -94,7 +108,7 @@ module Ruport::Data
 
     protected
 
-    attr_writer :name, :subgroups
+    attr_writer :name, :subgroups #:nodoc:
     
     private
     
@@ -153,7 +167,10 @@ module Ruport::Data
       end
     end
     
-    attr_accessor :data 
+    # The grouping's data
+    attr_accessor :data
+    
+    # The name of the column used to group the data
     attr_reader :grouped_by
     
     require "forwardable"
@@ -171,7 +188,7 @@ module Ruport::Data
         raise(IndexError,"Group Not Found")
     end 
     
-    # Used to add extra data to the Grouping. <tt>other</tt> should be a Group.
+    # Used to add extra data to the Grouping. <tt>group</tt> should be a Group.
     #
     # Example:
     #
@@ -211,10 +228,11 @@ module Ruport::Data
     # 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.
+    # the sum for the attributes or methods <tt>:opened</tt> and
+    # <tt>:closed</tt> and order them by the <tt>:order</tt> array.
     #
-    # If :order is not specified, you cannot depend on predictable column order
+    # If <tt>:order</tt> is not specified, you cannot depend on predictable
+    # column order.
     #
     #   grouping.summary :date,
     #     :opened => lambda { |g| g.sigma(:opened) },
@@ -254,12 +272,11 @@ module Ruport::Data
     include Ruport::Renderer::Hooks
     renders_as_grouping
 
-    def self.inherited(base)
+    def self.inherited(base) #:nodoc:
       base.renders_as_grouping
     end
-
     
-    # Create a copy of the Grouping: groups will be copied as well.
+    # Create a copy of the Grouping. Groups will be copied as well.
     #
     # Example:
     #

data/lib/ruport/data/record.rb

@@ -1,14 +1,18 @@
-# The Ruport Data Collections.
-# Authors: Gregory Brown / Dudley Flanders
+# Ruport : Extensible Reporting System
+#
+# data/record.rb provides a record data structure for Ruport.
+# 
+# Created by Gregory Brown / Dudley Flanders, 2006
+# Copyright (C) 2006 Gregory Brown / Dudley Flanders, All Rights Reserved.  
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.   
 #
-# This is Free Software.  For details, see LICENSE and COPYING
-# Copyright 2006 by respective content owners, all rights reserved.
 module Ruport::Data
 
-  #
   # === Overview
   # 
-  # Data::Records are the work horse of Ruport's data model. These can behave
+  # Data::Records are the work-horse of Ruport's data model. These can behave
   # as Array-like, Hash-like, or Struct-like objects.  They are used as the 
   # base element for Data::Table
   #
@@ -16,7 +20,6 @@ module Ruport::Data
 
     include Enumerable  
     
-    # 
     # Creates a new Record object.  If the <tt>:attributes</tt> 
     # keyword is specified, Hash-like and Struct-like 
     # access will be enabled.  Otherwise, Record elements may be 
@@ -55,7 +58,6 @@ module Ruport::Data
       end
     end        
     
-    
     ##############
     # Delegators #
     ##############
@@ -71,17 +73,14 @@ module Ruport::Data
       @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   
+    # The data for the record
+    attr_reader :data
+    
+    # The size of the record (the number of items in the record's data).
     def size; @data.size; end
     alias_method :length, :size
     
@@ -89,7 +88,6 @@ module Ruport::Data
     # Access Methods #
     ##################
     
-    #
     # Allows either Array or Hash-like indexing.
     #
     # Examples:
@@ -106,7 +104,6 @@ module Ruport::Data
       end
     end
         
-    # 
     # Allows setting a <tt>value</tt> at an <tt>index</tt>.
     # 
     # Examples:
@@ -134,6 +131,7 @@ module Ruport::Data
     #   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
@@ -149,7 +147,6 @@ module Ruport::Data
     #  Conversions #
     ################
     
-    #
     # Converts a Record into an Array.
     #
     # Example:
@@ -167,6 +164,7 @@ module Ruport::Data
     #
     #   a = Data::Record.new([1,2],:attributes => %w[a b])
     #   a.to_hash #=> {"a" => 1, "b" => 2}
+    #
     def to_hash
       @data.dup
     end
@@ -175,7 +173,6 @@ module Ruport::Data
     #  Comparisons #
     ################
     
-    #
     # If <tt>attributes</tt> and <tt>to_a</tt> are equivalent, then 
     # <tt>==</tt> evaluates to true. Otherwise, <tt>==</tt> returns false.
     #
@@ -184,14 +181,13 @@ 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
+    # Yields each element of the Record.  Does not provide attribute names.
     def each 
       to_a.each { |e| yield(e) }
     end   
@@ -208,7 +204,6 @@ module Ruport::Data
       @data[new_name] = @data.delete(old_name)
     end
     
-    #
     # Allows you to change the order of or reduce the number of columns in a
     # Record.  
     #
@@ -237,11 +232,10 @@ module Ruport::Data
     include Ruport::Renderer::Hooks
     renders_as_row
 
-    def self.inherited(base)
+    def self.inherited(base) #:nodoc:
       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
     # they are not the same object. This is similar to the way Array works, 
@@ -251,6 +245,13 @@ module Ruport::Data
       @attributes.hash + to_a.hash
     end
     
+    # Create a copy of the Record.
+    #
+    # Example:
+    #
+    #   one = Record.new([1,2,3,4],:attributes => %w[a b c d])
+    #   two = one.dup
+    #
     def initialize_copy(from)
        @data = from.data.dup
        @attributes = from.attributes.dup

data/lib/ruport/data/table.rb

@@ -1,11 +1,14 @@
-# The Ruport Data Collections.
-# Authors: Gregory Brown / Dudley Flanders
+# Ruport : Extensible Reporting System
 #
-# This is Free Software.  For details, see LICENSE and COPYING
-# Copyright 2006 by respective content owners, all rights reserved.
-
-module Ruport::Data            
-
+# data/table.rb provides a table data structure for Ruport.
+# 
+# Created by Gregory Brown / Dudley Flanders, 2006
+# Copyright (C) 2006 Gregory Brown / Dudley Flanders, All Rights Reserved.  
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.   
+#
+module Ruport::Data
  
   # === Overview
   #
@@ -16,11 +19,15 @@ module Ruport::Data
   # Table is intended to be used as the data store for structured, tabular
   # data.
   #
-  # Once your data is in a Ruport::Data::Table object, it can be manipulated
+  # Once your data is in a Table object, it can be manipulated
   # to suit your needs, then used to build a report.
   #
   class Table 
 
+    # === Overview
+    #
+    # This module provides facilities for creating tables from csv data.
+    #
     module FromCSV
       # Loads a CSV file directly into a Table using the FasterCSV library.
       #
@@ -83,7 +90,8 @@ module Ruport::Data
 
       def handle_csv_row_proc(data,row,options,block)
         if options[:records]
-          row = Record.new(row, :attributes => data.column_names)
+          rc = options[:record_class] || Record
+          row = rc.new(row, :attributes => data.column_names)
         end
         
         block[data,row]
@@ -100,26 +108,25 @@ module Ruport::Data
           loaded.column_names = row.headers
         end
       end
-
     end
 
-
     include Enumerable             
     extend FromCSV
 
     include Ruport::Renderer::Hooks
     renders_as_table
 
-    def self.inherited(base)
+    def self.inherited(base) #:nodoc:
       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 
-    #                                 records in this Table
-    # <b><tt>:column_names</tt></b>:: An Array containing the column names 
-    #                                 for this Table.
+    #
+    # Valid options:
+    # <b><tt>:data</tt></b>::           An Array of Arrays representing the 
+    #                                   records in this Table.
+    # <b><tt>:column_names</tt></b>::   An Array containing the column names 
+    #                                   for this Table.
     # Example:
     #
     #   table = Table.new :data => [[1,2,3], [3,4,5]], 
@@ -145,8 +152,10 @@ module Ruport::Data
       end
     end
 
-    # This Table's column names.
+    # This Table's column names
     attr_reader :column_names
+    
+    # This Table's data
     attr_reader :data        
     
     require "forwardable"
@@ -199,9 +208,9 @@ module Ruport::Data
 
     alias_method :==, :eql?
 
-    # Used to add extra data to the Table. <tt>other</tt> can be an Array, 
+    # Used to add extra data to the Table. <tt>row</tt> can be an Array, 
     # Hash or Record. It also can be anything that implements a meaningful
-    # to_hash or to_ary
+    # to_hash or to_ary.
     #
     # Example:
     #
@@ -225,14 +234,13 @@ module Ruport::Data
       return self
     end    
     
-    # returns the record class constant being used by the table
+    # 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
-  
     
     # Used to merge two Tables by rows.
-    # Throws an ArgumentError if the Tables don't have identical columns.
+    # Raises an ArgumentError if the Tables don't have identical columns.
     #
     # Example:
     #
@@ -252,7 +260,23 @@ module Ruport::Data
                       :record_class => record_class )
     end
   
-    
+    # Allows you to change the order of, or reduce the number of columns in a
+    # Table.
+    #
+    # Example:
+    #
+    #   a = Table.new :data => [[1,2,3],[4,5,6]], :column_names => %w[a b c]
+    #   a.reorder("b","c","a")
+    #   a.column_names #=> ["b","c","a"]
+    #
+    #   a = Table.new :data => [[1,2,3],[4,5,6]], :column_names => %w[a b c]
+    #   a.reorder(1,2,0)
+    #   a.column_names #=> ["b","c","a"]
+    #
+    #   a = Table.new :data => [[1,2,3],[4,5,6]], :column_names => %w[a b c]
+    #   a.reorder(0,2)
+    #   a.column_names #=> ["a","c"]
+    #
     def reorder(*indices)
       raise(ArgumentError,"Can't reorder without column names set!") if
         @column_names.empty?
@@ -264,11 +288,11 @@ module Ruport::Data
       end
       
       reduce(indices)
-    end     
-
+    end
     
-    # Adds an extra column to the Table. Available Options:
+    # Adds an extra column to the Table.
     #
+    # Available Options:
     # <b><tt>:default</tt></b>:: The default value to use for the column in 
     #                            existing rows. Set to nil if not specified.
     # 
@@ -276,13 +300,12 @@ module Ruport::Data
     #                             number.
     #
     # <b><tt>:before</tt></b>:: Inserts the new column before the column 
-    #                           indicated. (by name)
+    #                           indicated (by name).
     #
     # <b><tt>:after</tt></b>:: Inserts the new column after the column
-    #                          indicated. (by name)
+    #                          indicated (by name).
     #
     # If a block is provided, it will be used to build up the column.
-    #      
     #   
     # Example:
     #
@@ -318,6 +341,15 @@ module Ruport::Data
       end; self
     end     
     
+    # Add multiple extra columns to the Table. See <tt>add_column</tt> for
+    # a list of available options.
+    #   
+    # Example:
+    #
+    #   data = Table("a","b") { |t| t << [1,2] << [3,4] }
+    #   
+    #   data.add_columns ['new_column_1','new_column_2'], :default => 1
+    #
     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?           
@@ -352,7 +384,7 @@ module Ruport::Data
       cols.each { |col| remove_column(col) }
     end
     
-    # Renames a column.  Will update Record attributes as well
+    # Renames a column.  Will update Record attributes as well.
     # 
     # Example:
     #
@@ -516,6 +548,11 @@ module Ruport::Data
     
     # Returns an array of values for the given column name.
     #
+    # Example:
+    #
+    #   table = [[1,2],[3,4],[5,6]].to_table(%w[col1 col2])
+    #   table.column("col1")   #=> [1,3,5]
+    #
     def column(name)
       case(name)
       when Integer
@@ -600,12 +637,25 @@ module Ruport::Data
       return table
     end   
     
-    # same as Table#sort_rows_by, but self modifiying
+    # 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) 
       @data = table.data
     end
     
+    # Get an array of records from the Table limited by the criteria specified.
+    #
+    # Example:
+    #
+    #   table = Table.new :data => [[1,2,3], [1,4,6], [4,5,6]], 
+    #                     :column_names => %w[a b c]
+    #   table.rows_with(:a => 1)           #=> [[1,2,3], [1,4,6]]
+    #   table.rows_with(:a => 1, :b => 4)  #=> [[1,4,6]]
+    #   table.rows_with_a(1)               #=> [[1,2,3], [1,4,6]]
+    #   table.rows_with(%w[a b]) {|a,b| [a,b] == [1,4] }  #=> [[1,4,6]]
+    #
     def rows_with(columns,&block) 
       select { |r|
         if block
@@ -616,7 +666,7 @@ module Ruport::Data
       }
     end
                                                                                 
-    # Create a copy of the Table: records will be copied as well.
+    # Create a copy of the Table. Records will be copied as well.
     #
     # Example:
     #
@@ -631,7 +681,7 @@ module Ruport::Data
       from.data.each { |r| self << r.dup }
     end
     
-    # Uses Ruport's built-in text formatter to render this Table into a String
+    # Uses Ruport's built-in text formatter to render this Table into a String.
     # 
     # Example:
     # 
@@ -661,23 +711,30 @@ module Ruport::Data
 
     # 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>
+    #
+    # Also converts a call to <tt>rows_with_columnname</tt> to a call to
+    # <tt>rows_with(:columnname => args[0])</tt>.
+    #
     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
     
+    # 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      
     
+    # Appends a hash as a record in the Table.
     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
     
+    # Appends a record to the Table.
     def append_record(record)        
       self << record.send(column_names.empty? ? :to_a : :to_hash)
     end