ruport 0.6.0 → 0.6.1

data/lib/ruport/format.rb

@@ -79,7 +79,7 @@ module Ruport
        require "ruport/format/#{lib}" 
     }
 
-    @@filters = Hash.new
+    @@filters ||= Hash.new
     
     # To hook up a Format object to your current class, you need to pass it a
     # binding.  This way, when filters are being processed, they will be

data/lib/ruport/mailer.rb

@@ -6,37 +6,47 @@
 #  See LICENSE for details
 require "net/smtp"
 require "forwardable"
-module Ruport  
 
-    # This class uses SMTP to provide a simple mail sending mechanism.
-    # It also uses MailFactory to provide attachment and HTML email support. 
-    #
-    # Here is a simple example of a message which attaches a readme file:
-    #
-    #   require "ruport"
-    #     
-    #   Ruport.configure do |conf| 
-    #     conf.mailer :default, 
-    #       :host => "mail.adelphia.net", :address => "gregory.t.brown@gmail.com"
-    #   end
-    #
-    #   mailer = Ruport::Mailer.new
-    #
-    #   mailer.attach "README"
-    #
-    #   mailer.deliver :to      => "gregory.t.brown@gmail.com",
-    #                  :from    => "gregory.t.brown@gmail.com",
-    #                  :subject => "Hey there",               
-    #                  :text    => "This is what you asked for"
+module Ruport
+  
+  #
+  # === Overview
+  #
+  # This class uses SMTP to provide a simple mail sending mechanism.
+  # It also uses MailFactory to provide attachment and HTML email support. 
+  #
+  # === Example
+  #
+  # Here is a simple example of a message which attaches a README file:
+  #
+  #   require "ruport"
+  #     
+  #   Ruport.configure do |config| 
+  #     config.mailer :default, 
+  #                   :host    => "mail.adelphia.net", 
+  #                   :address => "gregory.t.brown@gmail.com"
+  #   end
+  #
+  #   mailer = Ruport::Mailer.new
+  #
+  #   mailer.attach "README"
+  #
+  #   mailer.deliver :to      => "gregory.t.brown@gmail.com",
+  #                  :from    => "gregory.t.brown@gmail.com",
+  #                  :subject => "Hey there",               
+  #                  :text    => "This is what you asked for"
+  #
   class Mailer
     extend Forwardable
    
-    
-    # Creates a new Mailer object.  Optionally, can select a mailer specified
-    # by Ruport::Config.
     #
-    #   a = Mailer.new # uses the :default mailer
-    #   a = Mailer.new :foo # uses :foo mail config from Ruport::Config
+    # Creates a new Mailer object. Optionally, you can select a mailer 
+    # specified by Ruport::Config.
+    #
+    # Example:
+    #
+    #   a = Mailer.new        # uses the :default mailer
+    #   a = Mailer.new :foo   # uses :foo mail config from Ruport::Config
     #
     def initialize( mailer_label=:default )
       select_mailer(mailer_label); 
@@ -49,10 +59,14 @@ module Ruport
                            :subject, :subject=, :attach, 
                            :text, :text=, :html, :html= )
    
-    # sends the message
+    # 
+    # Sends the message.
+    #
+    # Example:
     #
     #   mailer.deliver :from => "gregory.t.brown@gmail.com",
     #                  :to   => "greg7224@gmail.com"
+    #
     def deliver(options={})
       options.each { |k,v| send("#{k}=",v) if respond_to? "#{k}=" }
       

data/lib/ruport/meta_tools.rb

@@ -1,11 +1,18 @@
+# Gets raised if you try to add the same action to an object more than once. 
 class ActionAlreadyDefinedError < RuntimeError; end
+
 module Ruport
+
+  # 
+  # === Overview
+  #
   # This module provides a few tools for doing some manipulations of the
-  # eigenclass on an object.  These are used in the implementation of Ruport's
-  # formatting system, and might be helpful for other things.
+  # singleton class of an object.  These are used in the implementation of 
+  # Ruport's formatting system, and might be useful for other things.
   #
   module MetaTools
-    # Allows you to define an attribute accessor on the singleton_class.
+    #
+    # Allows you to define an attribute accessor on the singleton class.
     #
     # Example:
     # 
@@ -14,21 +21,27 @@ module Ruport
     #     attribute :foo
     #  end
     #
-    #  A.foo #=> nil
-    #  A.foo = 7 #=> 7 
+    #  A.foo      #=> nil
+    #  A.foo = 7  #=> 7 
+    #
     def attribute(sym,value = nil)
       singleton_class.send(:attr_accessor, sym )
       self.send("#{sym}=",value)
     end
 
-    # Same as attribute, but takes an array of attributes
     #
-    # e.g. attributes [:foo,:bar,:baz]
+    # Same as <tt>attribute</tt>, but takes an Array of attributes.
+    #
+    # Example:
+    # 
+    #   attributes [:foo,:bar,:baz]
+    #
     def attributes(syms)
       syms.each { |s| attribute s }
     end
     
-    # Allows you to define a method on the singleton_class
+    #
+    # Allows you to define a method on the singleton class.
     #
     # Example:
     #
@@ -37,15 +50,17 @@ module Ruport
     #     action(:bar) { |x| x + 1 }
     #   end
     #
-    #   A.bar(3) #=> 4
+    #   A.bar(3)  #=> 4
+    #
     def action(name,&block)
       raise ActionAlreadyDefinedError if respond_to? name
       singleton_class.send(:define_method, name, &block)
     end
+    
   end
 end
 
 class Module
-    # provides the singleton_class object
-    def singleton_class; (class << self; self; end); end
+  # Provides the singleton_class object.
+  def singleton_class; (class << self; self; end); end
 end

data/lib/ruport/query.rb

@@ -3,49 +3,59 @@ require "ruport/query/sql_split"
 
 module Ruport
   
-  # Query offers a way to interact with databases via DBI.  It supports
-  # returning result sets in either Ruport's native Data::Table, or in their raw
-  # form as DBI::Rows.
   #
-  # It offers basic caching support, the ability to instantiate a generator for
-  # a result set, and the ability to quickly and easily swap between data
+  # === Overview
+  # 
+  # Query offers a way to interact with databases via DBI. It supports
+  # returning result sets in either Ruport's native Data::Table, or in their 
+  # raw form as DBI::Rows.
+  #
+  # It offers basic caching support, the ability to instantiate a generator 
+  # for a result set, and the ability to quickly and easily swap between data
   # sources.
+  #
   class Query 
     
     
     include Enumerable
     
-    # Queries are initialized with some SQL and a number of options that effect
-    # their operation.  They are NOT executed at initialization.  
     #
-    # This is important to note as they will not query the database until either
-    # Query#result, Query#execute, Query#generator, or an enumerable method is
-    # called on them. 
+    # Queries are initialized with some SQL and a number of options that 
+    # affect their operation. They are NOT executed at initialization. This 
+    # is important to note as they will not query the database until either
+    # Query#result, Query#execute, Query#generator, or an Enumerable method 
+    # is called on them. 
     #
     # This kind of laziness is supposed to be A Good Thing, and
     # as long as you keep it in mind, it should not cause any problems.
     #
-    # The SQL can be single or multistatement, but the resulting Data::Table will
-    # consist only of the result of the last statement which returns something.
-    #
-    # Options:
-    #
-    # <tt>:source</tt>  
-    #   A source specified in Ruport::Config.sources, defaults to :default
-    # <tt>:origin</tt>  
-    #   query origin, default to :string, but can be
-    #   set to :file, loading the path specified by the sql parameter
-    # <tt>:dsn</tt>
-    #   If specifed, the query object will manually override Ruport::Config
-    # <tt>:user</tt>
-    #   If a DSN is specified, a user can be set by this option
-    # <tt>:password</tt>
-    #   If a DSN is specified, a password can be set by this option
-    # <tt>:raw_data</tt>
-    #   When set to true, DBI::Rows will be returned
-    # <tt>:cache_enabled</tt>
-    #   When set to true, Query will download results only once, and then return
-    #   cached values until cache has been cleared.
+    # The SQL can be single or multistatement, but the resulting Data::Table 
+    # will consist only of the result of the last statement which returns 
+    # something.
+    #
+    # Available options:
+    #
+    # <b><tt>:source</tt></b>::         A source specified in 
+    #                                   Ruport::Config.sources, defaults to 
+    #                                   <tt>:default</tt>.
+    # <b><tt>:origin</tt></b>::         Query origin, defaults to 
+    #                                   <tt>:string</tt>, but it can be set to 
+    #                                   <tt>:file</tt>, loading the path 
+    #                                   specified by the <tt>sql</tt> 
+    #                                   parameter.
+    # <b><tt>:dsn</tt></b>::            If specifed, the Query object will 
+    #                                   manually override Ruport::Config.
+    # <b><tt>:user</tt></b>::           If a DSN is specified, the user can 
+    #                                   be set with this option.
+    # <b><tt>:password</tt></b>::       If a DSN is specified, the password 
+    #                                   can be set with this option.
+    # <b><tt>:raw_data</tt></b>::       When set to true, DBI::Rows will be 
+    #                                   returned instead of a Data::Table.
+    # <b><tt>:cache_enabled</tt></b>::  When set to true, Query will download 
+    #                                   results only once, and then return 
+    #                                   cached values until the cache has been 
+    #                                   cleared.
+    #
     # Examples:
     #   
     #   # uses Ruport::Config's default source
@@ -63,6 +73,7 @@ module Ruport
     #
     #   # explicitly use a file, even if it doesn't end in .sql
     #   Ruport::Query.new("foo",:origin => :file)
+    #
     def initialize(sql, options={})
       options = { :source => :default, :origin => :string }.merge(options)
       options[:binding] ||= binding
@@ -87,103 +98,124 @@ module Ruport
       @cached_data = nil
     end
     
-    # set to true to get DBI:Rows, false to get Ruport constructs
+    #
+    # Set this to <tt>true</tt> to get DBI:Rows, <tt>false</tt> to get Ruport 
+    # constructs.
+    #
     attr_accessor :raw_data
     
-    # modifying this might be useful for testing, this is the data stored by
-    # ruport when caching
+    # The data stored by Ruport when caching.
     attr_accessor :cached_data
     
-    # this is the original SQL for the Query object
+    # The original SQL for the Query object
     attr_reader :sql
     
-    # This will set the dsn, username, and password to one specified by a label
-    # that corresponds to a source in Ruport::Config
+    #
+    # This will set the <tt>dsn</tt>, <tt>username</tt>, and <tt>password</tt> 
+    # to one specified by a source in Ruport::Config.
+    #
     def select_source(label)
       @dsn      = Ruport::Config.sources[label].dsn
       @user     = Ruport::Config.sources[label].user
       @password = Ruport::Config.sources[label].password
     end 
     
-    # Standard each iterator, iterates through result set row by row.
+    #
+    # Standard <tt>each</tt> iterator, iterates through the result set row by 
+    # row.
+    #
     def each(&action) 
       Ruport.log(
         "no block given!", :status => :fatal,
         :level => :log_only, :exception => LocalJumpError 
       ) unless action
       fetch(&action)
+      self
     end
     
-    # Grabs the result set as a Data::Table or if in raw_data mode, an array of
-    # DBI::Row objects
+    #
+    # Grabs the result set as a Data::Table or an Array of DBI::Row objects 
+    # if in <tt>raw_data</tt> mode.
+    #
     def result; fetch; end
     
     # Runs the query without returning its results.
     def execute; fetch; nil; end
     
-    # clears the contents of the cache
+    # Clears the contents of the cache.
     def clear_cache
       @cached_data = nil
     end
 
-    # clears the contents of the cache and then runs the query, filling the
-    # cache with the new result
+    #
+    # Clears the contents of the cache, then runs the query, filling the
+    # cache with the new result.
+    #
     def update_cache
       return unless @cache_enabled
       clear_cache; fetch
     end
     
-    # Turns on caching.  New data will not be loaded until cache is clear or
-    # caching is disabled.
+    #
+    # Turns on caching.  New data will not be loaded until the cache is clear 
+    # or caching is disabled.
+    #
     def enable_caching
       @cache_enabled = true
     end
 
-    # Turns off caching and flushes the cached data
+    # Turns off caching and flushes the cached data.
     def disable_caching
       clear_cache
       @cache_enabled = false
     end
     
-    # Returns a Data::Table, even if in raw_data mode
-    # Does not work with raw data if cache is enabled and filled
+    #
+    # Returns a Data::Table, even if in <tt>raw_data</tt> mode.
+    # This doesn't work with raw data if the cache is enabled and filled.
+    #
     def to_table
       data_flag, @raw_data = @raw_data, false
       data = fetch; @raw_data = data_flag; return data
     end
 
-    # Returns a csv dump of the query
+    # Returns a csv dump of the query.
     def to_csv
       Format.table :plugin => :csv, :data => fetch
     end
 
-    # Returns a Generator object of the result set
+    # Returns a Generator object of the result set.
     def generator
       Generator.new(fetch)
     end
 
     private
     
-    def query_data( query_text, params=@params )
-      
+    def query_data(query_text, params=@params)
       require "dbi"
       
       data = @raw_data ? [] : Data::Table.new
       DBI.connect(@dsn, @user, @password) do |dbh|
-        if params
-          sth = dbh.execute(query_text,*params)
-        else
-          sth = dbh.execute(query_text)
+        dbh.execute(query_text, *(params || [])) do |sth|
+          # Work-around for inconsistent DBD behavior w/ resultless queries
+          names = sth.column_names rescue []
+          if names.empty?
+            # Work-around for SQLite3 DBD bug
+            sth.cancel rescue nil
+            return nil
+          end
+          
+          data.column_names = names unless @raw_data
+          sth.each do |row|
+            row = row.to_a
+            row = Data::Record.new(row, :attributes => names) unless @raw_data
+            yield row if block_given?
+            data << row if !block_given? || @cache_enabled
+          end
         end
-        return unless sth.fetchable?
-        results = sth.fetch_all  
-        data.column_names = sth.column_names unless @raw_data
-        results.each { |row| data << row.to_a }
-        sth.finish
       end
       data
-      rescue NoMethodError; nil
-    end 
+    end
     
     def get_query(type,query)
       type.eql?(:file) ? load_file( query ) : query
@@ -196,17 +228,19 @@ module Ruport
       end
     end
     
-    def fetch
+    def fetch(&block)
       data = nil
       if @cache_enabled and @cached_data
         data = @cached_data
+        data.each { |r| yield(r) } if block_given?
       else
-        @statements.each { |query_text| data = query_data( query_text ) }
+        final = @statements.size - 1
+        @statements.each_with_index do |query_text, index|
+          data = query_data(query_text, &(index == final ? block : nil))
+        end
+        @cached_data = data if @cache_enabled
       end
-      data.each { |r| yield(r) } if block_given? 
-      @cached_data = data if @cache_enabled
       return data
     end
-
   end
 end