ruport 0.4.23 → 0.4.99

data/lib/ruport/data/set.rb.rej

@@ -0,0 +1,147 @@
+***************
+*** 8,27 ****
+  module Ruport::Data
+    class Set < Collection
+      
+      def initialize(options={})
+        @data = ::Set.new
+        options[:data].each {|e| self << e} if options[:data]
+      end
+      
+-     def <<(other)
+        case other
+          when Record 
+            @data << other
+          when Array
+            @data << Record.new(other)
+        end
+      end
+      
+      def dup
+       a =  self.class.new(:data=>@data)
+       a.tags = tags.dup
+--- 8,42 ----
+  module Ruport::Data
+    class Set < Collection
+      
++     # Creates a new set containing the elements of options[:data].
++     #
++     #   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.
++     #   set = Set.new :data => [%w[one two three]]
++     #   set << [5,6,7]
++     def add(other)
+        case other
+          when Record 
+            @data << other
+          when Array
+            @data << Record.new(other)
+        end
++       self
+      end
++     alias_method :<<, :add
+      
++     # Produces a shallow copy of the set: the same data is referenced by both
++     # the old and new sets.
++     #   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
+***************
+*** 29,53 ****
+      end
+      alias_method :clone, :dup
+  
+      def ==(other)
+        @data == other.data
+      end
+      
+      def |(other)
+        Set.new :data => (@data | other.data)
+      end
+      alias_method :union, :|
+      
+      def &(other)
+        Set.new :data => (@data & other.data)
+      end
+      alias_method :intersection, :&
+      
+-     # Set difference
+      def -(other)
+        Set.new :data => (@data - other.data)
+      end
+      alias_method :difference, :-
+      
+      def_delegators :@data, :each
+    end
+--- 44,104 ----
+      end
+      alias_method :clone, :dup
+  
++     # Equality. Two sets are equal if they contain the same set of objects.
++     #   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.
++     #   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.
++     #   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.
++     #   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.
++     #   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
+      
+      def_delegators :@data, :each
+    end

data/lib/ruport/data/set.rb~

@@ -0,0 +1,73 @@
+# The Ruport Data Collections.
+# Authors: Gregory Brown / Dudley Flanders
+#
+# This is Free Software.  For details, see LICENSE and COPYING
+# Copyright 2006 by respective content owners, all rights reserved.
+require 'set'
+
+module Ruport::Data
+  class Set < Collection
+    
+    # Creates a new set containing the elements of options[:data].
+    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.
+    def add(other)
+      case other
+        when Record 
+          @data << other
+        when Array
+          @data << Record.new(other)
+      end
+      self
+    end
+    alias_method :<<, :add
+    
+    # Produces a shallow copy of the set: the same data is referenced by both
+    # the old and new sets.
+    def dup
+     a =  self.class.new(:data=>@data)
+     a.tags = tags.dup
+     return a
+    end
+    alias_method :clone, :dup
+
+    # Equality. Two sets are equal if they contain the same set of objects.
+    def ==(other)
+      @data == other.data
+    end
+    
+    # Union. Returns a new set containing the union of the objects contained in
+    # the two sets.
+    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.
+    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.
+    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.
+    def ^(other)
+      Set.new :data => (@data ^ other.data)
+    end
+    
+    def_delegators :@data, :each
+  end
+end

data/lib/ruport/data/table.rb

@@ -1,4 +1,14 @@
+# The Ruport Data Collections.
+# Authors: Gregory Brown / Dudley Flanders
+#
+# This is Free Software.  For details, see LICENSE and COPYING
+# 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.
+  #
+  #   [[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))
@@ -6,7 +16,29 @@ class Array
 end
 
 module Ruport::Data
+  
+  # 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.).
+  # 
+  # Table is intended to be used as the data store for structured, tabular
+  # data - Ruport::Data::Set is an alternate intermediary data store intended
+  # for less structured 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
+
+    # Creates a new table based on the supplied options.
+    # Valid options are :data and :column_names.
+    #
+    #   table = Table.new({:data => [1,2,3], [3,4,5], 
+    #                      :column_names => %w[a b c]})
     def initialize(options={})
       @column_names = options[:column_names].dup if options[:column_names]
       @data         = []
@@ -15,20 +47,42 @@ module Ruport::Data
 
     attr_reader :column_names
 
+    # Sets the column names for this table. The single parameter should be 
+    # an array listing the names of the columns.
+    #
+    #   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 = other.dup
       map { |r| r.attributes = @column_names }
     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]})
+    #   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
+    # 
+    #   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]})
+    #   data << [8,9]
+    #   data << { :a => 4, :b => 5}
+    #   data << Ruport::Data::Record.new [5,6], :attributes => %w[a b]
     def <<(other)
       case other
       when Array
@@ -39,12 +93,19 @@ module Ruport::Data
         @data << Record.new(arr, :attributes => @column_names)
       when Record
         raise ArgumentError unless column_names.eql? other.attributes
-        @data << Record.new(other.to_a, :attributes => @column_names)
+        @data << Record.new(other.data, :attributes => @column_names)
+        @data.last.tags = other.tags.dup
       end
       self
     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]})
+    #   data.reorder!([1,0])  
     def reorder!(*indices)
+      indices = indices[0] if indices[0].kind_of? Array
       @column_names = if indices.all? { |i| i.kind_of? Integer }
         indices.map { |i| @column_names[i] }
       else
@@ -53,10 +114,21 @@ module Ruport::Data
       @data.each { |r| r.reorder! *indices }; 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]})
+    #   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.
+    #   
+    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   data.append_coulmn({:name => 'new_column', :fill => 1)
     def append_column(options={})
       self.column_names += [options[:name]]  if options[:name]
       if block_given?
@@ -66,10 +138,32 @@ module Ruport::Data
       end
     end
 
+   # 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
+   def remove_column(options={})
+     raise ArgumentError unless column_names.include? options[:name]
+     reorder! column_names - [options[: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]})
+    #   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.
+    #   
+    #   data = Table.load('mydata.csv')
     def self.load(csv_file, options = {})
       options = {:has_names => true}.merge(options)
       require "fastercsv"
@@ -88,6 +182,37 @@ module Ruport::Data
       end ; loaded_data
     end
 
+    
+
+    # Allows you to split tables into multiple tables for grouping.
+    #
+    # Example:
+    #
+    #   a = Table.new(:column_name => %w[name a b c])
+    #   a << ["greg",1,2,3]
+    #   a << ["joe", 2,3,4]
+    #   a << ["greg",7,8,9]
+    #   a << ["joe", 1,2,3]
+    #
+    #   b = a.split :group => "name"
+    #
+    #   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. 
+    # 
+    # Example:
+    #
+    #   a = Table.new(:column_names => %w[first_name last_name x]
+    #   a << %w[greg brown foo]
+    #   a << %w[greg gibson bar]
+    #   a << %w[greg brown baz]
+    #
+    #   b = a.split :group => %w[first_name last_name]
+    #   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

data/lib/ruport/data/taggable.rb

@@ -1,23 +1,42 @@
+# The Ruport Data Collections.
+# Authors: Gregory Brown / Dudley Flanders
+#
+# This is Free Software.  For details, see LICENSE and COPYING
+# Copyright 2006 by respective content owners, all rights reserved.
 module Ruport::Data
   
+  # This module provides a simple mechanism for tagging arbitrary objects.  This
+  # provides the necessary methods to set and retrieve tags which can consist of
+  # any Ruby object.  This is used by Data::Record and the Ruport Data
+  # Collections.
   module Taggable
 
+    # Adds a tag to the object 
+    #   taggable_obj.tag :spiffy
     def tag(tag_name)
       tags << tag_name unless has_tag? tag_name
     end
-
+    
+    # Removes a tag
+    #   taggable_obj.delete_tag :not_so_spiffy
     def delete_tag(tag_name)
       tags.delete tag_name
     end
   
+    # Checks to see if a tag is present
+    #   taggable_obj.has_tag? :spiffy #=> true
     def has_tag?(tag_name)
       tags.include? tag_name
     end
   
+    # Returns an array of tags.
+    #   taggable_obj.tags #=> [:spiffy, :kind_of_spiffy]
     def tags
       @ruport_tags ||= []
     end
-    
+   
+    # Sets the tags to some array
+    #   taggable_obj.tags = [:really_dang_spiffy, :the_most_spiffy]
     def tags=(tags_list)
       @ruport_tags = tags_list
     end