ruport 0.6.0 → 0.6.1

data/lib/ruport/data/set.rb

@@ -7,6 +7,9 @@ require 'set'
 
 module Ruport::Data
   
+  #
+  # === Overview
+  #
   # This class is one of the core classes for building and working with data 
   # in Ruport. The idea is to get your data into a standard form, regardless 
   # of its source (a database, manual arrays, ActiveRecord, CSVs, etc.).
@@ -17,19 +20,29 @@ module Ruport::Data
   #
   # Once your data is in a Ruport::Data::Set object, it can be manipulated
   # to suit your needs, then used to build a report.
+  #
   class Set < Collection
     
-    # Creates a new set containing the elements of options[:data].
+    #
+    # Creates a new Set containing the elements of <tt>options[:data]</tt>.
+    #
+    # Example:
     #
     #   Set.new :data => [%w[one two three] %w[1 2 3] %w[I II III]]
+    #
     def initialize(options={})
       @data = ::Set.new
       options[:data].each {|e| self << e} if options[:data]
     end
     
-    # Adds the given object to the set and returns self.
+    #
+    # Adds the given object to the Set and returns self. 
+    #
+    # Example:
+    #
     #   set = Set.new :data => [%w[one two three]]
     #   set << [5,6,7]
+    #
     def add(other)
       case other
         when Record 
@@ -41,14 +54,18 @@ module Ruport::Data
     end
     alias_method :<<, :add
     
-    # Produces a shallow copy of the set: the same data elements are 
-    # referenced by both the old and new sets.
+    #
+    # Produces a shallow copy of the Set: the same data elements are 
+    # referenced by both the old and new Sets.
+    #
+    # Example:
     #
     #   set = Set.new :data => [%w[one two three]]
     #   set2 = set.dup
     #   set == set2 #=> true
     #   set << [8,9,10]
     #   set == set2 #=> false
+    #
     def dup
      a =  self.class.new(:data=>@data)
      a.tags = tags.dup
@@ -56,62 +73,80 @@ module Ruport::Data
     end
     alias_method :clone, :dup
 
-    # Equality. Two sets are equal if they contain the same set of objects.
+    #
+    # Two Sets are equal if they contain the same set of objects.
+    # 
+    # Example:
     #   s1 = Set.new :data => [[1,2,3]]
     #   s2 = Set.new :data => [[1,2,3]]
     #   s1 == s2 #=> true
+    #
     def ==(other)
       @data == other.data
     end
     
-    # Union. Returns a new set containing the union of the objects contained in
-    # the two sets.
+    # Returns a new Set containing the all of the objects contained in either 
+    # of the two Sets.
+    #
+    # Example:
     #
     #   s1 = Set.new :data => [[1,2,3]]
     #   s2 = Set.new :data => [[4,5,6]]
     #   s3 = s1 | s2
     #   s4 = Set.new :data => [[1,2,3], [4,5,6]]
     #   s3 == s4 #=> true
+    #
     def |(other)
       Set.new :data => (@data | other.data)
     end
     alias_method :union, :|
     alias_method :+, :|
     
-    # Intersection. Returns a new set containing the objects common to the two
-    # sets.
+    #
+    # Returns a new Set containing the objects common to the two Sets.
+    #
+    # Example:
     #
     #   s1 = Set.new :data => [%w[a b c],[1,2,3]]
     #   s2 = Set.new :data => [%w[a b c],[4,5,6]]
     #   s3 = s1 & s2
     #   s4 = Set.new :data => [%w[a b c]]
     #   s3 == s4 #=> true
+    #
     def &(other)
       Set.new :data => (@data & other.data)
     end
     alias_method :intersection, :&
     
-    # Difference. Returns a new set containing those objects present in this
-    # set but not the other.
+    #
+    # Returns a new Set containing those objects present in this Set but not 
+    # the other.
+    #
+    # Example:
     #
     #   s1 = Set.new :data => [%w[a b c],[1,2,3]]
     #   s2 = Set.new :data => [%w[a b c],[4,5,6]]
     #   s3 = s1 - s2 
     #   s4 = Set.new :data => [[1, 2, 3]]
     #   s3 == s4 #=> true 
+    #
     def -(other)
       Set.new :data => (@data - other.data)
     end
     alias_method :difference, :-
 
-    # Exclusion. Returns a new set containing those objects in this set or the
-    # other set but not in both.
+    #
+    # Returns a new Set containing those objects that are either in this Set 
+    # or the other Set but not in both.
+    #
+    # Example:
     # 
     #   s1 = Set.new :data => [%w[a b c],[1,2,3]]
     #   s2 = Set.new :data => [%w[a b c],[4,5,6]]
     #   s3 = s1 ^ s2
     #   s4 = Set.new :data => [[1, 2, 3],[4,5,6]]
     #   s3 == s4 #=> true   
+    #
     def ^(other)
       Set.new :data => (@data ^ other.data)
     end

data/lib/ruport/data/table.rb

@@ -5,10 +5,14 @@
 # Copyright 2006 by respective content owners, all rights reserved.
 
 class Array
+
+  #
   # Converts an array to a Ruport::Data::Table object, ready to
   # use in your reports.
   #
+  # Example:
   #   [[1,2],[3,4]].to_table(%w[a b])
+  #
   def to_table(options={})
     options = { :column_names => options } if options.kind_of? Array 
     Ruport::Data::Table.new({:data => self}.merge(options))
@@ -16,7 +20,10 @@ class Array
 end
 
 module Ruport::Data
-  
+
+  # 
+  # === Overview
+  #
   # This class is one of the core classes for building and working with data 
   # in Ruport. The idea is to get your data into a standard form, regardless 
   # of its source (a database, manual arrays, ActiveRecord, CSVs, etc.).
@@ -28,17 +35,21 @@ 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.
   #
-  # Included in this class are methods to create Tables manually and from CSV
-  # files.
-  #
-  # For building a table using ActiveRecord, have a look at Ruport::Reportable. 
   class Table < Collection
     include Groupable
+    
+    #
     # Creates a new table based on the supplied options.
-    # Valid options are :data and :column_names.
+    # 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]], 
+    #                     :column_names => %w[a b c]
     #
-    #   table = Table.new({:data => [1,2,3], [3,4,5], 
-    #                      :column_names => %w[a b c]})
     def initialize(options={})
       @column_names = options[:column_names] ? options[:column_names].dup : []
       @data         = []
@@ -52,44 +63,70 @@ module Ruport::Data
       end
     end
 
+    # This Table's column names.
     attr_reader :column_names
     def_delegator :@data, :[]
-    # Sets the column names for this table. The single parameter should be 
-    # an array listing the names of the columns.
+    
+    #
+    # Sets the column names for this table. <tt>new_column_names</tt> should 
+    # be an array listing the names of the columns.
+    #
+    # Example:
     #
-    #   tbl = Table.new({:data => [1,2,3], [3,4,5], :column_names => %w[a b c]})
-    #   tbl.column_names = %w[e f g]
-    def column_names=(other)
-      @column_names.replace(other.dup)
+    #   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)
+      @column_names.replace(new_column_names.dup)
     end
 
-    # Compares this table to another table and returns true if
-    # both the data and column names are equal
     #
-    #   one = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
-    #   two = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    # Compares this Table to another Table and returns <tt>true</tt> if
+    # both the <tt>data</tt> and <tt>column_names</tt> are equal.
+    #
+    # Example:
+    #
+    #   one = Table.new :data => [1,2], [3,4], 
+    #                   :column_names => %w[a b]
+    #
+    #   two = Table.new :data => [1,2], [3,4], 
+    #                   :column_names => %w[a b]
+    #
     #   one.eql?(two) #=> true
+    #
     def eql?(other)
       data.eql?(other.data) && column_names.eql?(other.column_names) 
     end
 
     alias_method :==, :eql?
 
-    # Uses Ruport's built-in text plugin to render this table into a string
+    #
+    # 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]})
+    #   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. The single parameter can be an 
-    # Array, Hash or Ruport::Data::Record.
     #
-    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    # Used to add extra data to the Table. <tt>other</tt> can be an Array, 
+    # Hash or Record.
+    #
+    # Example:
+    #
+    #   data = Table.new :data => [1,2], [3,4], 
+    #                    :column_names => %w[a b]
     #   data << [8,9]
     #   data << { :a => 4, :b => 5}
-    #   data << Ruport::Data::Record.new [5,6], :attributes => %w[a b]
+    #   data << Record.new [5,6], :attributes => %w[a b]
+    #
     def <<(other)
       case other
       when Array
@@ -108,26 +145,40 @@ module Ruport::Data
       self
     end
   
-    # Used to combine two tables. Throws an ArgumentError if the tables don't
+    #
+    # Used to combine two Tables. Throws an ArgumentError if the Tables don't
     # have identical columns.
     #
-    #   inky = Table.new(:data => [[1,2], [3,4]], :column_names => %w[a b])
-    #   blinky = Table.new(:data => [[5,6]], :column_names => %w[a b])
+    # Example:
+    #
+    #   inky = Table.new :data => [[1,2], [3,4]], 
+    #                    :column_names => %w[a b]
+    #
+    #   blinky = Table.new :data => [[5,6]], 
+    #                      :column_names => %w[a b]
+    #
     #   sue = inky + blinky
     #   sue.data #=> [[1,2],[3,4],[5,6]]
-    
+    #
     def +(other)
       raise ArgumentError unless other.column_names == @column_names
       Table.new(:column_names => @column_names, :data => @data + other.data)
     end
   
-    # Reorders the columns that exist in the table. Operates directly 
-    # on this table.
     #
-    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    # 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] }
@@ -142,21 +193,34 @@ module Ruport::Data
       }; self
     end
 
-    # Returns a copy of the table with its columns in the requested order.
     #
-    #   one = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    # Returns a copy of the Table with its columns in the requested order.
+    #
+    # Example:
+    # 
+    #   one = Table.new :data => [1,2], [3,4], 
+    #                   :column_names => %w[a b]
+    #
     #   two = one.reorder!([1,0])  
+    #
     def reorder(*indices)
       dup.reorder!(*indices)
     end
 
-    # Adds an extra column to the table. Accepts an options Hash as its
-    # only parameter which should contain 2 keys - :name and :fill.
-    # :name specifies the new columns name, and :fill the default value to 
-    # use for the column in existing rows.
+    #
+    # 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.
     #   
-    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
-    #   data.append_column({:name => 'new_column', :fill => 1)
+    # Example:
+    #
+    #   data = Table.new :data => [1,2], [3,4], 
+    #                    :column_names => %w[a b]
+    #
+    #   data.append_column :name => 'new_column', :fill => 1
+    #
     def append_column(options={})
       self.column_names += [options[:name]]  if options[:name]
       if block_given?
@@ -166,17 +230,21 @@ module Ruport::Data
       end; self
     end
 
-    # Removes a column from the table. Any values in the specified column are
+    # 
+    # Removes a column from the Table. Any values in the specified column are
     # lost.
-    #   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
-    #     
+    #
+    # 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])
@@ -190,29 +258,50 @@ module Ruport::Data
       reorder! column_names - [name]
     end
 
-    # Create a shallow copy of the table: the same data elements are referenced
-    # by both the old and new table.
     #
-    #   one = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    # 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
 
-    # Loads a CSV file directly into a table using the fasterCSV library.
+    #
+    # Loads a CSV file directly into a Table using the FasterCSV library.
+    #
+    # Example:
     #   
-    #   data = Table.load('mydata.csv')
-    def self.load(csv_file, options={})
-        get_table_from_csv(:foreach, csv_file, options)
+    #   # 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 self.parse(string, options={})
-      get_table_from_csv(:parse,string,options)
+    
+    #
+    # 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={})
+    def self.get_table_from_csv(msg,param,options={},&block) #:nodoc:
       options = {:has_names => true,
                  :csv_options => {} }.merge(options)
       require "fastercsv"
@@ -223,15 +312,16 @@ module Ruport::Data
         if first_line && options[:has_names]
           loaded_data.column_names = row
           first_line = false
-        elsif !block_given?
+        elsif !block
           loaded_data << row
         else
-          yield(loaded_data,row)
+         block[loaded_data,row]
         end
       end ; loaded_data
     end
 
-    # Allows you to split tables into multiple tables for grouping.
+    # 
+    # Allows you to split Tables into multiple Tables for grouping.
     #
     # Example:
     #
@@ -246,8 +336,8 @@ module Ruport::Data
     #   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
     #
-    # You can also pass an array to :group, and the resulting attributes in
-    # the group will be joined by an underscore. 
+    # You can also pass an Array to <tt>:group</tt>, and the resulting 
+    # attributes in the group will be joined by an underscore. 
     # 
     # Example:
     #
@@ -260,6 +350,7 @@ module Ruport::Data
     #   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
@@ -292,23 +383,22 @@ module Ruport::Data
       end; rec
     end
     
-    # Calculates sums.  If a column name or index is given, it will try to
+    # 
+    # 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 it together 
-    #
-    # If a block is given, yields each Record so that you can do a calculation.
+    # and add them together.
     #
+    # If a block is given, it yields each Record so that you can do your own 
+    # calculation.
     #
     # Example:
     #
+    #   table = [[1,2],[3,4],[5,6]].to_table(%w[col1 col2])
+    #   table.sigma("col1") #=> 9
+    #   table.sigma(0)      #=> 9
+    #   table.sigma { |r| r.col1 + r.col2 } #=> 21
+    #   table.sigma { |r| r.col2 + 1 } #=> 15
     #
-    # table = [[1,2],[3,4],[5,6]].to_table(%w[col1 col2])
-    # table.sigma("col1") #=> 9
-    # table.sigma(0)      #=> 9
-    # table.sigma { |r| r.col1 + r.col2 } #=> 21
-    # table.sigma { |r| r.col2 + 1 } #=> 15
-    #
-    # For the non-mathy, this has been aliased as Table#sum
     def sigma(column=nil)
       inject(0) { |s,r| 
         if column
@@ -329,7 +419,7 @@ module Ruport::Data
 
 end
 
-module Ruport::Data::TableHelper
+module Ruport::Data::TableHelper #:nodoc:
   def table(names=[])
     t = [].to_table(names)
     yield(t) if block_given?; t