ruport 0.4.23 → 0.4.99

data/lib/ruport.rb

@@ -14,7 +14,7 @@ module Ruport
   
   #begin; require 'rubygems'; rescue LoadError; nil end
   
-  VERSION = "0.4.23"
+  VERSION = "0.4.99"
   
   # Ruports logging and error interface.
   # Can generate warnings or raise fatal errors
@@ -67,6 +67,6 @@ module Ruport
 end
 
 
-%w[config meta_tools report format query data].each { |lib|
+%w[config meta_tools report format query data mailer].each { |lib|
   require "ruport/#{lib}" 
 }

data/lib/ruport/config.rb

@@ -58,46 +58,89 @@ module Ruport
   #
   module Config
     module_function
-    
-    def source(*args)
+
+
+    # create or retrieve a database source configuration.
+    #
+    # setting a source
+    #
+    #   source :default, :user => "root", :password => "clyde",
+    #                    :dsn  => "dbi:mysql:blinkybase"
+    #
+    # retrieving a source
+    #
+    #   db = source(:default) #=> <OpenStruct ..>
+    #   db.dsn #=> "dbi:mysql:blinkybase"
+    def source(*args) 
       return sources[args.first] if args.length == 1
       sources[args.first] = OpenStruct.new(*args[1..-1])
       check_source(sources[args.first],args.first)
     end
 
+    # create or retrieve a mailer configuration
+    #
+    # creating a mailer config
+    #
+    #   mailer :alternate, :host => "mail.test.com", 
+    #                      :address => "test@test.com",
+    #                      :user => "test", :password => "blinky"
+    #                      :auth_type => :cram_md5
+    #
+    # retreiving a mailer config
+    #
+    #   mail_conf = mailer(:alternate) #=> <OpenStruct ..>
+    #   mail_conf.address #=> test@test.com
     def mailer(*args)
+      return mailers[args.first] if args.length == 1
       mailers[args.first] = OpenStruct.new(*args[1..-1])
       check_mailer(mailers[args.first],args.first)
     end
 
+
+    # Sets the logger to use the specified file.
+    #
+    #   log_file "foo.log"
     def log_file(file)
       @logger = Logger.new(file)
     end
     
-    #alias_method :log_file=, :log_file
+    # Same as Config.log_file, but accessor style
     def log_file=(file)
       log_file(file)
     end
 
+    # Returns the source which is labeled :default
     def default_source
       sources[:default]
     end
 
+    # Returns the mailer which is labeled :default
     def default_mailer
       mailers[:default]
     end
 
+    # Returns an array of database source configs
     def sources; @sources ||= {}; end
 
+    # Returns an array of mailer configs
     def mailers; @mailers ||= {}; end
 
+    # Returns the currently active logger
     def logger; @logger; end
 
+    # Forces all messages marked :log_only to surface
     def enable_paranoia; @paranoid = true; end
+
+    # Disables the printing of :log_only messages to STDERR
     def disable_paranoia; @paranoid = false; end
+
+    # Sets paranoid status
     def paranoid=(val); @paranoid = val; end
+
+    # Checks to see if paranoia is enabled
     def paranoid?; !!@paranoid; end
     
+    # Verifies that you have provided a DSN for your source
     def check_source(settings,label)
       unless settings.dsn
         Ruport.complain( 
@@ -108,6 +151,7 @@ module Ruport
       end
     end
 
+    # Verifies that you have provided a host for your mailer
     def check_mailer(settings, label)
       unless settings.host
         Ruport.complain(

data/lib/ruport/data/collection.rb

@@ -1,4 +1,12 @@
+# 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 is the base class for Ruport's Data structures.
   class Collection
     require "forwardable"
     extend Forwardable
@@ -9,18 +17,26 @@ 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
+    #
+    # my_collection.as(:csv) #=> "1,2,3\n4,5,6"
     def as(type)
       Ruport::Format.table :data => self, :plugin => type
     end
 
+    # Converts any Collection object to a Data::Set
     def to_set
       Set.new :data => data
     end
-    
+   
+    # Converts any Collection object to a Data::Table
     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
     def method_missing(id,*args)
      return as($1.to_sym) if id.to_s =~ /^to_(.*)/ 
      super

data/lib/ruport/data/record.rb

@@ -1,10 +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
+
+  # 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.
   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.
+    #
+    #   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]
@@ -18,26 +50,50 @@ module Ruport::Data
         @attributes = options[:attributes]
       end
     end
-
+    
+    # The underlying data which is being stored in the record
     attr_reader :data
+    
     def_delegators :@data,:each, :length
   
+    # Allows either array or hash_like indexing
+    #
+    #   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
         @data[index]
       else
+        raise "Invalid index" unless @attributes.index(index)
         @data[@attributes.index(index)]
       end
     end
 
+
+    # Allows setting a value at an index
+    #  
+    #    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
         @data[index] = value
       else
+        raise "Invalid index" unless @attributes.index(index)
         @data[attributes.index(index)] = value
       end
     end
 
+
+    # If attributes and data are equivalent, then == evaluates to true.
+    # Otherwise, == returns false
     def ==(other)
       return false if @attributes && !other.attributes
       return false if other.attributes && !@attributes
@@ -45,20 +101,49 @@ module Ruport::Data
     end
 
     alias_method :eql?, :==
-    
+   
+    # Makes an array out of the data wrapped by Record
+    #
+    #   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
+    #
+    #   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.
+    #
+    #   a = Data::Record.new([1,2],:attributes => %w[a b])
+    #   a.attributes #=> ["a","b"]
     def attributes; @attributes && @attributes.dup; end
 
+    # Sets the attribute list for this Record
+    #
+    #   my_record.attributes = %w[foo bar baz]
     def attributes=(a); @attributes=a; end
 
+    # 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 is destructive
     def reorder!(*indices)
+      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] }
       if @attributes
         if indices.all? { |e| e.kind_of? Integer }
@@ -68,18 +153,26 @@ module Ruport::Data
         end
       end; self
     end
-
+    
+    # Makes a fresh copy of the Record
     def dup
-      self.class.new(@data,:attributes => attributes)
+      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
     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)

data/lib/ruport/data/set.rb

@@ -1,41 +1,120 @@
+# 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
+  
+  # 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.).
+  # 
+  # Set is intended to be used as the data store for unstructured data -
+  # Ruport::Data::Table is an alternate intermediary data store intended
+  # for structured, tabular 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].
+    #
+    #   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
     
-    def <<(other)
+    # 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 elements are 
+    # 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
+     return a
+    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, :&
     
-    # Set difference
+    # 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