ruport 0.6.0 → 0.6.1

data/lib/ruport/data.rb

@@ -1 +1,6 @@
-%w[groupable taggable record collection table set ].each { |l| require "ruport/data/#{l}" }
+require "ruport/data/groupable" 
+require "ruport/data/taggable" 
+require "ruport/data/record" 
+require "ruport/data/collection" 
+require "ruport/data/table" 
+require "ruport/data/set"

data/lib/ruport/data/collection.rb

@@ -6,7 +6,13 @@
 
 module Ruport::Data
   
-  # This is the base class for Ruport's Data structures.
+  #
+  # === Overview
+  #
+  # This is the base class for Ruport's Data structures. It mixes in the 
+  # <tt>Taggable</tt> module and provides methods for converting between 
+  # <tt>Data::Set</tt>s and <tt>Data::Table</tt>s.
+  #
   class Collection
     require "forwardable"
     extend Forwardable
@@ -17,28 +23,29 @@ module Ruport::Data
       @data = data.dup if data
     end
 
-    # Simple formatting tool which allows you to quickly generate a formatted
-    # table from a Collection object, eg
+    # A simple formatting tool which allows you to quickly generate a formatted
+    # table from a <tt>Collection</tt> object.
     #
-    # my_collection.as(:csv) #=> "1,2,3\n4,5,6"
+    # Example:
+    #   my_collection.as(:csv)  #=> "1,2,3\n4,5,6"
     def as(type)
       eng = Ruport::Format.table_object :data => self, :plugin => type
       yield(eng) if block_given?
       eng.render
     end
 
-    # Converts any Collection object to a Data::Set
+    # Converts a <tt>Collection</tt> object to a <tt>Data::Set</tt>.
     def to_set
       Set.new :data => data
     end
    
-    # Converts any Collection object to a Data::Table
+    # Converts a <tt>Collection</tt> object to a <tt>Data::Table</tt>.
     def to_table(options={})
       Table.new({:data => data.map { |r| r.to_a }}.merge(options))
     end
 
-    # Provides a shortcut for the as() method by converting as(:format_name)
-    # into to_format_name
+    # 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>
     def method_missing(id,*args)
       return as($1.to_sym) if id.to_s =~ /^to_(.*)/ 
       super

data/lib/ruport/data/groupable.rb

@@ -1,20 +1,82 @@
 module Ruport::Data
+
+  #
+  # === Overview
+  #
+  # This module provides a simple mechanism for grouping objects based on 
+  # tags.
+  #
   module Groupable
 
+    #
+    # Creates a <tt>Record</tt> made up of <tt>Table</tt>s containing all the
+    # records in the original table with the same tag. 
+    #
+    # Example:
+    #   table = [['inky',  1], 
+    #            ['blinky',2], 
+    #            ['pinky', 3],
+    #            ['clyde', 4]].to_table(['name','score'])
+    #
+    #   table[0].tag(:winners)
+    #   table[1].tag(:losers)
+    #   table[2].tag(:winners)
+    #   table[3].tag(:losers)
+    #
+    #   r = table.group_by_tag
+    #   puts r[:winners]
+    #   => +---------------+
+    #      | name  | score |
+    #      +---------------+
+    #      | inky  |   1   |
+    #      | pinky |   3   |
+    #      +---------------+
+    #
+    #   puts r[:losers]  
+    #   => +----------------+
+    #      |  name  | score |
+    #      +----------------+
+    #      | blinky |   2   |
+    #      | clyde  |   4   |
+    #      +----------------+
+    #
     def group_by_tag
-      r_tags = data.map {|row| row.tags}.flatten.uniq
-      d = r_tags.map do |t| 
-	      select {|row| row.tags.include? t }.to_table(column_names)      
-      end
-      r = Record.new d, :attributes => r_tags
+      r_tags = map { |r| r.tags }.flatten.uniq
+      tables_hash = Hash.new { |h,k| h[k] = [].to_table(column_names) }
+      each { |row|
+        row.tags.each { |t| tables_hash[t] << row }
+      }
+      r = Record.new tables_hash, :attributes => r_tags
       class << r
         def each_group; attributes.each { |a| yield(a) }; end
       end; r
     end
 
+    #
+    # Tags each row of the <tt>Table</tt> for which the <tt>block</tt> is not 
+    # false with <tt>label</tt>.
+    # 
+    # Example:
+    #   table = [['inky',  1], 
+    #            ['blinky',2], 
+    #            ['pinky', 3]].to_table(['name','score'])
+    #   
+    #   table.create_tag_group(:cool_kids) {|r| r.score > 1}
+    #   groups = table.group_by_tag(:cool_kids)
+    #   
+    #   puts group[:cool_kids]
+    #   => +----------------+
+    #      |  name  | score |
+    #      +----------------+
+    #      | blinky |   2   |
+    #      | pinky  |   3   |
+    #      +----------------+
+    #
     def create_tag_group(label,&block)
-      select(&block).each { |r| r.tag label }
+      each { |r| block[r] && r.tag(label) }
+      #select(&block).each { |r| r.tag label }
     end
+    alias_method :tag_group, :create_tag_group
 
   end
 end

data/lib/ruport/data/record.rb

@@ -5,21 +5,28 @@
 # Copyright 2006 by respective content owners, all rights reserved.
 module Ruport::Data
 
-  # 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
-  # record for both Tables and Sets in Ruport.
+  #
+  # === Overview
+  # 
+  # 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 in both Tables and Sets.
+  #
   class Record
     require "forwardable"
     extend Forwardable
     include Enumerable
     include Taggable
 
-    # 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 accessed ordinally, like an Array.
     # 
-    # Records accept either Hashes or Arrays as their data.
+    # 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 
+    # accessed ordinally, like an Array.
+    # 
+    # A Record can accept either a Hash or an Array as its <tt>data</tt>.
     #
+    # Examples:
     #   a = Record.new [1,2,3]
     #   a[1] #=> 2
     #
@@ -37,6 +44,7 @@ module Ruport::Data
     #   b[1]   #=> ? (without attributes, you cannot rely on order)
     #   b['a'] #=> 1
     #   b.c    #=> 3
+    #
     def initialize(data,options={})
       if data.kind_of?(Hash)
         if options[:attributes]
@@ -55,18 +63,19 @@ module Ruport::Data
       end
     end
     
-    # The underlying data which is being stored in the record
+    # The underlying <tt>data</tt> which is being stored in the record.
     attr_reader :data
     
     def_delegators :@data,:each, :length
   
-    # Allows either array or hash_like indexing
+    #
+    # Allows either Array or Hash-like indexing.
+    #
+    # Examples:
     #
     #   my_record[1] 
     #   my_record["foo"]
     #
-    # Also, this provides a feature via method_missing which allows
-    #   my_record.foo
     def [](index)
       if index.kind_of? Integer
         raise "Invalid index" unless index < @data.length
@@ -78,13 +87,14 @@ module Ruport::Data
     end
 
 
-    # Allows setting a value at an index
-    #  
+    # 
+    # Allows setting a <tt>value</tt> at an <tt>index</tt>.
+    # 
+    # Examples:
+    #
     #    my_record[1] = "foo" 
     #    my_record["bar"] = "baz"
     #
-    # And via method_missing
-    #    my_record.ghost = "blinky"
     def []=(index, value)
       if index.kind_of? Integer
         raise "Invalid index" unless index < @data.length
@@ -95,9 +105,10 @@ module Ruport::Data
       end
     end
 
-
-    # If attributes and data are equivalent, then == evaluates to true.
-    # Otherwise, == returns false
+    #
+    # If <tt>attributes</tt> and <tt>data</tt> are equivalent, then 
+    # <tt>==</tt> evaluates to true. Otherwise, <tt>==</tt> returns false.
+    #
     def ==(other)
       return false if attributes && !other.attributes
       return false if other.attributes && !attributes
@@ -106,43 +117,62 @@ module Ruport::Data
 
     alias_method :eql?, :==
    
-    # Makes an array out of the data wrapped by Record
+    #
+    # Converts a Record into an Array.
+    #
+    # Example:
     #
     #   a = Data::Record.new([1,2],:attributes => %w[a b])
     #   a.to_a #=> [1,2]
+    #
     def to_a; @data.dup; end
-   
-    # Makes a hash out of the data wrapped by Record
-    # Only works if attributes are specified
+    
+    #
+    # Converts a Record into a Hash. This only works if <tt>attributes</tt> 
+    # are specified in the Record.
+    #
+    # Example:
     #
     #   a = Data::Record.new([1,2],:attributes => %w[a b])
     #   a.to_h #=> {"a" => 1, "b" => 2}
+    #
     def to_h; Hash[*attributes.zip(data).flatten] end
   
-    # Returns a copy of the list of attribute names associated with this Record.
+    #
+    # 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.map { |a| a.to_s }; end
 
-    # Sets the attribute list for this Record
+    #
+    # Sets the <tt>attribute</tt> list for this Record.
+    #
+    # Example:
     #
     #   my_record.attributes = %w[foo bar baz]
+    #
     attr_writer :attributes
 
-
+    #
     # Allows you to change the order of or reduce the number of columns in a
-    # Record.  Example:
+    # Record.  
+    #
+    # Example:
     #
     #   a = Data::Record.new([1,2,3,4],:attributes => %w[a b c d])
     #   b = a.reorder("a","d","b")
     #   b.attributes #=> ["a","d","b"]
     #   b.data #=> [1,4,2]
+    #
     def reorder(*indices)
       dup.reorder!(*indices)
     end
     
-    # Same as Record#reorder but is destructive
+    # Same as Record#reorder but modifies its reciever in place.
     def reorder!(*indices)
       indices = reorder_data!(*indices)
       if attributes
@@ -154,7 +184,7 @@ module Ruport::Data
       end; self
     end
 
-    def reorder_data!(*indices)
+    def reorder_data!(*indices) # :nodoc:
       indices = indices[0] if indices[0].kind_of?(Array) 
       indices.each do |i| 
         self[i] rescue raise ArgumentError, 
@@ -165,7 +195,7 @@ module Ruport::Data
     end
 
     
-    # Makes a fresh copy of the Record
+    # Makes a fresh copy of the Record.
     def dup
       copy = self.class.new(@data,:attributes => attributes)
       copy.tags = self.tags.dup
@@ -175,21 +205,30 @@ module Ruport::Data
     #FIXME: This does not take into account frozen / tainted state
     alias_method :clone, :dup
     
-    # provides a unique hash value
+    #
+    # 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, 
+    # but different from Hash and other objects.
+    #
     def hash
       (attributes.to_a + data.to_a).hash
     end
 
-    # provides accessor style methods for attribute access, Example
+    #
+    # Provides accessor style methods for attribute access.
+    #
+    # Example:
     #
     #   my_record.foo = 2
     #   my_record.foo #=> 2
-    def method_missing(id,*args)
-      id = id.to_s.gsub(/=$/,"")
+    #
+    def method_missing(mname, *args)
+      id = mname.to_s.gsub(/=$/,"")
       if attributes.include?(id)
         args.empty? ? self[id] : self[id] = args.first
       else
-        super
+        super(mname, *args)
       end
     end
 

data/lib/ruport/data/record.rb~

@@ -0,0 +1,236 @@
+# 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
+
+  #
+  # === Overview
+  # 
+  # 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 in both Tables and Sets.
+  #
+  class Record
+    require "forwardable"
+    extend Forwardable
+    include Enumerable
+    include Taggable
+
+    # 
+    # 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 
+    # accessed ordinally, like an Array.
+    # 
+    # A Record can accept either a Hash or an Array as its <tt>data</tt>.
+    #
+    # Examples:
+    #   a = Record.new [1,2,3]
+    #   a[1] #=> 2
+    #
+    #   b = Record.new [1,2,3], :attributes => %w[a b c]
+    #   b[1]   #=> 2  
+    #   b['a'] #=> 1
+    #   b.c    #=> 3
+    #
+    #   c = Record.new {"a" => 1, "c" => 3, "b" => 2}, :attributes => %w[a b c]
+    #   b[1]   #=> 2
+    #   b['a'] #=> 1
+    #   b.c    #=> 3
+    #
+    #   c = Record.new { "a" => 1, "c" => 3, "b" => 2 }
+    #   b[1]   #=> ? (without attributes, you cannot rely on order)
+    #   b['a'] #=> 1
+    #   b.c    #=> 3
+    #
+    def initialize(data,options={})
+      if data.kind_of?(Hash)
+        if options[:attributes]
+          @attributes = options[:attributes]
+          @data = options[:attributes].map { |k| data[k] }
+        else
+          @attributes, @data = data.to_a.transpose
+        end
+      else
+        @data = data.dup
+        @attributes = if options[:attributes] 
+          options[:attributes]
+        else 
+          []
+        end
+      end
+    end
+    
+    # The underlying <tt>data</tt> which is being stored in the record.
+    attr_reader :data
+    
+    def_delegators :@data,:each, :length
+  
+    #
+    # Allows either Array or Hash-like indexing.
+    #
+    # Examples:
+    #
+    #   my_record[1] 
+    #   my_record["foo"]
+    #
+    def [](index)
+      if index.kind_of? Integer
+        raise "Invalid index" unless index < @data.length
+        @data[index]
+      else
+        raise "Invalid index" unless attributes.index(index.to_s)
+        @data[attributes.index(index.to_s)]
+      end
+    end
+
+
+    # 
+    # Allows setting a <tt>value</tt> at an <tt>index</tt>.
+    # 
+    # Examples:
+    #
+    #    my_record[1] = "foo" 
+    #    my_record["bar"] = "baz"
+    #
+    def []=(index, value)
+      if index.kind_of? Integer
+        raise "Invalid index" unless index < @data.length
+        @data[index] = value
+      else
+        raise "Invalid index" unless attributes.index(index.to_s)
+        @data[attributes.index(index.to_s)] = value
+      end
+    end
+
+    #
+    # If <tt>attributes</tt> and <tt>data</tt> are equivalent, then 
+    # <tt>==</tt> evaluates to true. Otherwise, <tt>==</tt> returns false.
+    #
+    def ==(other)
+      return false if attributes && !other.attributes
+      return false if other.attributes && !attributes
+      attributes == other.attributes && @data == other.data
+    end
+
+    alias_method :eql?, :==
+   
+    #
+    # Converts a Record into an Array.
+    #
+    # Example:
+    #
+    #   a = Data::Record.new([1,2],:attributes => %w[a b])
+    #   a.to_a #=> [1,2]
+    #
+    def to_a; @data.dup; end
+    
+    #
+    # Converts a Record into a Hash. This only works if <tt>attributes</tt> 
+    # are specified in the Record.
+    #
+    # Example:
+    #
+    #   a = Data::Record.new([1,2],:attributes => %w[a b])
+    #   a.to_h #=> {"a" => 1, "b" => 2}
+    #
+    def to_h; Hash[*attributes.zip(data).flatten] end
+  
+    #
+    # 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.map { |a| a.to_s }; end
+
+    #
+    # Sets the <tt>attribute</tt> list for this Record.
+    #
+    # Example:
+    #
+    #   my_record.attributes = %w[foo bar baz]
+    #
+    attr_writer :attributes
+
+    #
+    # Allows you to change the order of or reduce the number of columns in a
+    # Record.  
+    #
+    # Example:
+    #
+    #   a = Data::Record.new([1,2,3,4],:attributes => %w[a b c d])
+    #   b = a.reorder("a","d","b")
+    #   b.attributes #=> ["a","d","b"]
+    #   b.data #=> [1,4,2]
+    #
+    def reorder(*indices)
+      dup.reorder!(*indices)
+    end
+    
+    # Same as Record#reorder but modifies its reciever in place.
+    def reorder!(*indices)
+      indices = reorder_data!(*indices)
+      if attributes
+        if indices.all? { |e| e.kind_of? Integer }
+          @attributes = indices.map { |i| attributes[i] }
+        else
+          @attributes = indices
+        end
+      end; self
+    end
+
+    def reorder_data!(*indices) # :nodoc:
+      indices = indices[0] if indices[0].kind_of?(Array) 
+      indices.each do |i| 
+        self[i] rescue raise ArgumentError, 
+                "you may have specified an invalid column" 
+      end
+      @data = indices.map { |i| self[i] }
+      return indices;
+    end
+
+    
+    # Makes a fresh copy of the Record.
+    def dup
+      copy = self.class.new(@data,:attributes => attributes)
+      copy.tags = self.tags.dup
+      return copy
+    end 
+    
+    #FIXME: This does not take into account frozen / tainted state
+    alias_method :clone, :dup
+    
+    #
+    # 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, 
+    # but different from Hash and other objects.
+    #
+    def hash
+      (attributes.to_a + data.to_a).hash
+    end
+
+    #
+    # Provides accessor style methods for attribute access.
+    #
+    # Example:
+    #
+    #   my_record.foo = 2
+    #   my_record.foo #=> 2
+    #
+    def method_missing(id,*args)
+      id = id.to_s.gsub(/=$/,"")
+      if attributes.include?(id)
+        args.empty? ? self[id] : self[id] = args.first
+      else
+        super
+      end
+    end
+
+  end
+end