ruport 0.6.0 → 0.6.1

data/lib/ruport/query/sql_split.rb

@@ -12,7 +12,7 @@ module Ruport
   class Query
     # This class properly splits up multi-statement SQL input for use with
     # Ruby/DBI
-    class SqlSplit < Array
+    class SqlSplit < Array  #:nodoc:
 			def initialize( sql )
 				super()
 				next_sql = ''

data/lib/ruport/report.rb

@@ -29,7 +29,7 @@ module Ruport
   #  require "ruport"
   #  require "fileutils"
   #  class MyReport < Ruport::Report
-  #    prepare do
+  #    def prepare
   #      log_file "f.log"
   #      log "preparing report", :status => :info
   #      source :default, 
@@ -40,12 +40,12 @@ module Ruport
   #        :address => "gregory.t.brown@gmail.com"
   #    end
   #      
-  #    generate do
+  #    def generate
   #      log "generated csv from query", :status => :info
   #      query "select * from bar", :as => :csv 
   #    end
   #
-  #    cleanup do
+  #    def cleanup
   #      log "removing foo.csv", :status => :info
   #      FileUtils.rm("foo.csv") 
   #    end
@@ -63,24 +63,26 @@ module Ruport
   #  } 
   #
   # 
-  # This class can also be used to run templates and process text filters
+  # This class can also be used to run templates and process text filters.
   #
   # See the examples in the documentation below to see how to use these
-  # features. (Namely Report#process_text , Report#text_processor, and
-  # Report#eval_template )
+  # features (namely Report#process_text , Report#text_processor, and
+  # Report#eval_template).
   #
   class Report   
     extend Forwardable
     
     include Ruport::Data::TableHelper
+    # 
     # When initializing a report, you can provide a default mailer and source by
     # giving a name of a valid source or mailer you've defined via
-    # Ruport::Config
+    # Ruport::Config.
     #
     # If your report does not need any sort of specialized information, you can
-    # simply use Report.run (Or MyReportName.run if you've inherited)
+    # simply use Report.run (Or MyReportName.run if you've inherited).
     #
     # This will auto-initialize a report.
+    #
     def initialize( source_name=:default, mailer_name=:default )
       use_source source_name
       use_mailer mailer_name
@@ -89,46 +91,49 @@ module Ruport
       @file        = nil
     end
     
-    #by default, this file will be used by Report#write
+    # By default, this file will be used by Report#write.
     attr_accessor :file
 
-    #this attribute will get the results of Report#generate when the report is
-    #run.
+    #
+    # This attribute will get the results of Report#generate when the report is
+    # run.
+    #
     attr_accessor :results
 
-    # Simplified interface to Ruport::Query
+    # This is a simplified interface to Ruport::Query.
     #
-    # === Can read SQL statements from file or string
+    # You can use it to read SQL statements from file or string:
     #  
-    #  #from string 
-    #  result = query "select * from foo"
+    #   #from string 
+    #   result = query "select * from foo"
     #
-    #  #from file 
-    #  result = query "my_query.sql", :origin => :file
+    #   #from file 
+    #   result = query "my_query.sql", :origin => :file
     # 
-    # === Can use multistatement SQL
+    # You can use multistatement SQL:
     #
-    #  # will return the value of the last statement, "select * from foo"
-    #  result = query "insert into foo values(1,2); select * from foo"
+    #   # will return the value of the last statement, "select * from foo"
+    #   result = query "insert into foo values(1,2); select * from foo"
     # 
-    # === Can iterate by row or return entire set
+    # You can iterate by row or return the entire set:
     #  
-    #  query("select * from foo", :yield_type => :by_row) { |r|
+    #   query("select * from foo", :yield_type => :by_row) { |r|
     #     #do something with the rows here
-    #  }
+    #   }
     # 
-    # === Can return raw DBI:Row objects or Ruport's data structures.
+    # query() can return raw DBI:Row objects or Ruport's data structures:
     # 
-    #  # will return an Array of DBI::Row objects
-    #  result = query "select * from foo", :raw_data => true
+    #   # will return an Array of DBI::Row objects
+    #   result = query "select * from foo", :raw_data => true
     #
-    # === Can quickly output in a number of formats
+    # You can quickly output in a number of formats:
     # 
-    #  result = query "select * from foo", :as => :csv
-    #  result = query "select * from foo", :as => :html
-    #  result = query "select * from foo", :as => :pdf
+    #   result = query "select * from foo", :as => :csv
+    #   result = query "select * from foo", :as => :html
+    #   result = query "select * from foo", :as => :pdf
+    #
+    # See Ruport::Query for details.
     #
-    # See source of this function and methods of Ruport::Query for details.
     def query(sql, options={})
       options[:origin] ||= :string
       options[:source] ||= @source
@@ -143,25 +148,28 @@ module Ruport
       end
     end
     
-    # Evaluates _code_ from _filename_ as pure ruby code for files ending in
-    # .rb, and as ERb templates for anything else.
     #
-    # This code will be evaluated in the context of the instance on which it is
-    # called.
+    # Evaluates <tt>code</tt> from <tt>filename</tt> as pure ruby code for 
+    # files ending in .rb, and as ERb templates for anything else.
+    #
+    # This code will be evaluated in the context of the instance on which it 
+    # is called.
+    #
     def eval_template( code, filename=nil )
       filename =~ /\.rb/ ? eval(code) : ERB.new(code, 0, "%").result(binding)
     end
    
-    # sets the active source to the Ruport::Config source requested by label.
+    # Sets the active source to the Ruport::Config source requested by <tt>label</tt>.
     def use_source(label)
       @source = label
     end
 
-    # sets the active mailer to the Ruport::Config source requested by label.
+    # Sets the active mailer to the Ruport::Config source requested by <tt>label</tt>.
     def use_mailer(label)
       @mailer = label
     end
     
+    #
     # Provides a nice way to execute templates and filters.
     #
     # Example:
@@ -170,6 +178,7 @@ module Ruport
     #
     # This method automatically passes a binding into the filters, so you are
     # free to access data from your Report instance in your templates.
+    #
     def process_text(string, options)
       options[:filters].each do |f|
         format = Format.new(binding)
@@ -179,60 +188,70 @@ module Ruport
       string
     end
     
-    # This allows you to create filters to be used by process_text
+    #
+    # This allows you to create filters to be used by process_text.
     #
     # The block is evaluated in the context of the instance.
     #
-    # E.g
+    # Example:
     #
     #  text_processor(:unix_newlines) { |r| r.gsub(/\r\n/,"\n") }
+    #
     def text_processor(label,&block)
       Format.register_filter(label, &block)
     end
 
-
-    # Writes the contents of <tt>results</tt> to file.  If a filename is
+    #
+    # Writes the contents of <tt>results</tt> to a file.  If a filename is
     # specified, it will use it.  Otherwise, it will try to write to the file
     # specified by the <tt>file</tt> attribute.
+    #
     def write(my_file=file,my_results=results)
       File.open(my_file,"w") { |f| f << my_results }
     end
 
+    #
     # Like Report#write, but will append to a file rather than overwrite it if
-    # the file already exists
+    # the file already exists.
+    #
     def append(my_file=file)
       File.open(my_file,"a") { |f| f << results }
     end
 
     class << self
 
+      #
       # Defines an instance method which will be run before the
-      # <tt>generate</tt> method when Ruport.run is executed
+      # <tt>generate</tt> method when Ruport.run is executed.
       #
-      # Good for setting config info and perhaps files and/or loggers
+      # Good for setting config info and perhaps files and/or loggers.
       #
       def prepare(&block); define_method(:prepare,&block) end
       
-      # Defines an instance method which will be executed by Report.run
+      #
+      # Defines an instance method which will be executed by Report.run.
       #
       # The return value of this method is assigned to the <tt>results</tt>
-      # attribute
+      # attribute.
       #
       def generate(&block); define_method(:generate,&block) end
       
+      #
       # Defines an instance method which will be executed after the object is
-      # yielded in Report.run 
+      # yielded in Report.run.
       #
       def cleanup(&block); define_method(:cleanup,&block) end
       
+      #
       # Runs the reports specified.  If no reports are specified, then it
-      # creates a new instance via <tt>self.new</tt>
+      # creates a new instance via <tt>self.new</tt>.
       #
       # Tries to execute the prepare instance method, then runs generate.
       # It then yields the object so that you may do something with it
-      # (print something out, write to file, email, etc)
+      # (print something out, write to file, email, etc.).
       # 
       # Finally, it tries to call cleanup.
+      #
       def run(options={})
         options[:reports] ||= [self.new]
 
@@ -260,23 +279,26 @@ module Ruport
 
     end
 
-    # this method passes <tt>self</tt> to Report.run 
+    #
+    # This method passes <tt>self</tt> to Report.run.
     #
     # Please see the class method for details.
+    #
     def run(options={},&block)
       options[:reports] ||= [self]
       self.class.run(options,&block)
     end
 
-
-    # loads a CSV in from file.
     #
-    # Example
+    # Loads a CSV in from  a file.
+    #
+    # Example:
+    #
+    #   my_table = load_csv "foo.csv"                 #=> Data::Table
+    #   my_array = load_csv "foo.csv", :as => :array  #=> Array
     #
-    # my_table = load_csv "foo.csv" #=> Data::Table
-    # my_array = load_csv "foo.csv", :as => :array #=> Array
+    # See also Ruport::Data::Table.load
     #
-    # See also, Ruport::Data::Table.load
     def load_csv(file,options={})
       case options[:as]
       when :array
@@ -287,11 +309,15 @@ module Ruport
       end
     end
     
-    # Allows logging and other fun stuff. See Ruport.log
+    #
+    # Allows logging and other fun stuff. 
+    # See also Ruport.log
+    #
     def log(*args); Ruport.log(*args) end
    
+    #
     # Creates a new Mailer and sets the <tt>to</tt> attribute to the addresses
-    # specified.  Yields a Mailer object, which can be modified before delivery.
+    # specified. Yields a Mailer object, which can be modified before delivery.
     #
     def send_to(adds)
       m = Mailer.new

data/lib/ruport/report/graph.rb

@@ -1,6 +1,6 @@
 module Ruport
   class Report
-    module Graph
+    module Graph #:nodoc:
       def build_graph
         a = Ruport::Format.graph_object :plugin => :svg
         yield(a); return a

data/lib/ruport/report/invoice.rb

@@ -1,6 +1,6 @@
 module Ruport
   class Report
-    module Invoice
+    module Invoice #:nodoc:
       
       # Returns a Format::Engine::Invoice object
       #

data/test/test_query.rb

@@ -1,80 +1,337 @@
 require "test/unit"
 require "ruport"
-class TestQuery < Test::Unit::TestCase
-  
+
+begin
+  require 'mocha'
+  require 'stubba'
+  require 'dbi'
+rescue LoadError
+  $stderr.puts "Warning: Mocha not found -- skipping some Query tests"
+end
   
+class TestQuery < Test::Unit::TestCase
   def setup
-    Ruport::Config.source :default,
-      :dsn => "ruport:test", :user => "greg", :password => "apple"
+    @sources = {
+      :default => {
+        :dsn => 'ruport:test',  :user => 'greg',   :password => 'apple' },
+      :alternative => {
+        :dsn => "ruport:test2", :user => "sandal", :password => "harmonix" },
+    }
+    Ruport::Config.source :default,     @sources[:default]
+    Ruport::Config.source :alternative, @sources[:alternative]
+
+    @columns = %w(a b c)
+    @data = [ [[1,2,3],[4,5,6],[7,8,9]],
+              [[9,8,7],[6,5,4],[3,2,1]],
+              [[7,8,9],[4,5,6],[1,2,3]], ]
+    @datasets = @data.dup
+
+    @sql = [ "select * from foo", "create table foo ..." ]
+    @sql << @sql.values_at(0, 0).join(";\n")
+    @sql << @sql.values_at(1, 0).join(";\n")
+    @query = {
+      :plain      => Ruport::Query.new(@sql[0]),
+      :sourced    => Ruport::Query.new(@sql[0], :source        => :alternative),
+      :paramed    => Ruport::Query.new(@sql[0], :params        => [ 42 ]),
+      :cached     => Ruport::Query.new(@sql[0], :cache_enabled => true),
+      :uncached   => Ruport::Query.new(@sql[0], :cache_enabled => false),
+      :precached  => Ruport::Query.new(@sql[0], :cache_enabled => true),
+      :raw        => Ruport::Query.new(@sql[0], :raw_data      => true),
+      :unraw      => Ruport::Query.new(@sql[0], :raw_data      => false),
+      :resultless => Ruport::Query.new(@sql[1]),
+      :multi      => Ruport::Query.new(@sql[2]),
+      :mixed      => Ruport::Query.new(@sql[3]),
+    }
+    @query[:precached].cached_data = @data[0]
+  end
+
+  def test_execute
+    return unless Object.const_defined? :Mocha
+    query = @query[:uncached]
+    setup_mock_dbi(1)
 
-    Ruport::Config.source :alternate,
-      :dsn => "ruport:test2", :user => "sandal", :password => "harmonix"
+    assert_equal nil, query.execute
+  end
+
+  def test_execute_sourced
+    return unless Object.const_defined? :Mocha
+    query = @query[:sourced]
+    setup_mock_dbi(1, :source => :alternative)
+
+    assert_equal nil, query.execute
+  end
+
+  def test_execute_paramed
+    return unless Object.const_defined? :Mocha
+    query = @query[:paramed]
+    setup_mock_dbi(1, :params => [ 42 ])
+
+    assert_equal nil, query.execute
+  end
+
+  def test_result_cache_disabled
+    return unless Object.const_defined? :Mocha
+    query = @query[:uncached]
+    setup_mock_dbi(3)
     
-    @query1 = Ruport::Query.new "select * from foo", :cache_enabled => true 
-    @query1.cached_data = [[1,2,3],[4,5,6],[7,8,9]] 
+    assert_nothing_raised { query.result }
+    assert_equal @data[1], get_raw(query.result)
+    assert_equal @data[2], get_raw(query.result)
   end
   
+  def test_result_cache_enabled
+    return unless Object.const_defined? :Mocha
+    query = @query[:cached]
+    setup_mock_dbi(1)
+    
+    assert_nothing_raised { query.result }
+    assert_equal @data[0], get_raw(query.result)
+    assert_equal @data[0], get_raw(query.result)
+  end
+
+  def test_result_resultless
+    return unless Object.const_defined? :Mocha
+    query = @query[:resultless]
+    setup_mock_dbi(1, :resultless => true, :sql => @sql[1])
+
+    assert_equal nil, query.result
+  end
+
+  def test_result_multi
+    return unless Object.const_defined? :Mocha
+    query = @query[:multi]
+    setup_mock_dbi(2)
+
+    assert_equal @data[1], get_raw(query.result)
+  end
+
+  def test_result_raw_disabled
+    return unless Object.const_defined? :Mocha
+    query = @query[:unraw]
+    setup_mock_dbi(1)
+    
+    assert_equal @data[0].to_table(@columns), query.result
+  end  
+
+  def test_result_raw_enabled
+    return unless Object.const_defined? :Mocha
+    query = @query[:raw]
+    setup_mock_dbi(1)
+    
+    assert_equal @data[0], query.result
+  end  
+
+  def test_update_cache
+    return unless Object.const_defined? :Mocha
+    query = @query[:cached]
+    setup_mock_dbi(2)
+    
+    assert_equal @data[0], get_raw(query.result)
+    query.update_cache
+    assert_equal @data[1], get_raw(query.cached_data)
+    assert_equal @data[1], get_raw(query.result)
+  end
+
+  def test_clear_cache
+    return unless Object.const_defined? :Mocha
+    query = @query[:cached]
+    setup_mock_dbi(2)
+
+    assert_equal @data[0], get_raw(query.result)
+    query.clear_cache
+    assert_equal nil,      query.cached_data
+    assert_equal @data[1], get_raw(query.result)
+  end
   
-  def test_result
-    assert_nothing_raised { @query1.result }
-    assert_equal([[1,2,3],[4,5,6],[7,8,9]],@query1.result)
+  def test_disable_caching
+    return unless Object.const_defined? :Mocha
+    query = @query[:cached]
+    setup_mock_dbi(3)
+
+    assert_equal @data[0], get_raw(query.result)
+    assert_equal @data[0], get_raw(query.result)
+    query.disable_caching
+    assert_equal @data[1], get_raw(query.result)
+    assert_equal @data[2], get_raw(query.result)    
   end
 
-  def test_auto_resolve_file
-    q = Ruport::Query.new "test/samples/query_test.sql"
-    assert_equal "select * from foo", q.sql
+  def test_enable_caching
+    return unless Object.const_defined? :Mocha
+    query = @query[:uncached]
+    setup_mock_dbi(3)
+
+    assert_equal @data[0], get_raw(query.result)
+    assert_equal @data[1], get_raw(query.result)
+    query.enable_caching
+    assert_equal @data[2], get_raw(query.result)
+    assert_equal @data[2], get_raw(query.result)    
+  end
+
+  def test_load_file
+    return unless Object.const_defined? :Mocha
+    File.expects(:read).
+      with("query_test.sql").
+      returns("select * from foo\n")
+    
+    query = Ruport::Query.new "query_test.sql"
+    assert_equal "select * from foo", query.sql
   end
 
-  def test_erb_replacement
+  def test_load_file_erb
+    return unless Object.const_defined? :Mocha
     @table = 'bar'
-    q = Ruport::Query.new "test/samples/erb_test.sql", :binding => binding
-    assert_equal "select * from bar", q.sql
+    File.expects(:read).
+      with("query_test.sql").
+      returns("select * from <%= @table %>\n")
+    
+    query = Ruport::Query.new "query_test.sql", :binding => binding
+    assert_equal "select * from bar", query.sql
   end
 
-  def test_each
-    data = [[1,2,3],[4,5,6],[7,8,9]]
-    @query1.each do |r|
-      assert_equal(data.shift,r)
-    end
-    data = [1,4,7]
-    @query1.each do |r|
-      assert_equal(data.shift,r.first)
+  def test_load_file_not_found
+    return unless Object.const_defined? :Mocha
+    File.expects(:read).
+      with("query_test.sql").
+      raises(Errno::ENOENT)
+    Ruport.expects(:log).
+      with("Could not open query_test.sql",
+           :status => :fatal, :exception => LoadError).
+      raises(LoadError)
+
+    assert_raises LoadError do
+      query = Ruport::Query.new "query_test.sql"
     end
-    assert_raise (LocalJumpError) { @query1.each }
   end
 
-  def test_select_source
-    
-    assert_equal( "ruport:test", @query1.instance_eval("@dsn")  )
-    assert_equal( "greg",        @query1.instance_eval("@user") )
-    assert_equal( "apple",       @query1.instance_eval("@password") )
+  def test_each_cache_disabled
+    return unless Object.const_defined? :Mocha
+    query = @query[:uncached]
+    setup_mock_dbi(2)
 
-    @query1.select_source :alternate
+    result = []; query.each { |r| result << r.to_a }
+    assert_equal @data[0], result
+                 
+    result = []; query.each { |r| result << r.to_a }
+    assert_equal @data[1], result
+  end  
   
-    assert_equal( "ruport:test2", @query1.instance_eval("@dsn")  )
-    assert_equal( "sandal",        @query1.instance_eval("@user") )
-    assert_equal( "harmonix",       @query1.instance_eval("@password") ) 
+  def test_each_cache_enabled
+    return unless Object.const_defined? :Mocha
+    query = @query[:cached]
+    setup_mock_dbi(1)
     
-    @query1.select_source :default
+    result = []; query.each { |r| result << r.to_a }
+    assert_equal @data[0], result
+                 
+    result = []; query.each { |r| result << r.to_a }
+    assert_equal @data[0], result
+  end  
+
+  def test_each_multi
+    return unless Object.const_defined? :Mocha
+    query = @query[:multi]
+    setup_mock_dbi(2)
 
-    assert_equal( "ruport:test", @query1.instance_eval("@dsn")  )
-    assert_equal( "greg",        @query1.instance_eval("@user") )
-    assert_equal( "apple",       @query1.instance_eval("@password") )
-     
+    result = []; query.each { |r| result << r.to_a }
+    assert_equal @data[1], result
+  end
+  
+  def test_each_without_block
+    assert_raise (LocalJumpError) { @query[:precached].each }
+  end
+  
+  def test_select_source
+    query = @query[:precached]
+    assert_equal @sources[:default], get_query_source(query)
+
+    query.select_source :alternative
+    assert_equal @sources[:alternative], get_query_source(query)
+  
+    query.select_source :default
+    assert_equal @sources[:default], get_query_source(query)
+  end
+
+  def test_initialize_source_temporary
+    query = Ruport::Query.new "<unused>", @sources[:alternative]
+    assert_equal @sources[:alternative], get_query_source(query)
+  end
+
+  def test_initialize_source_temporary_multiple
+    query1 = Ruport::Query.new "<unused>", @sources[:default]
+    query2 = Ruport::Query.new "<unused>", @sources[:alternative]
+    
+    assert_equal @sources[:default], get_query_source(query1)
+    assert_equal @sources[:alternative], get_query_source(query2)
   end
 
   def test_generator
-    assert @query1.generator.kind_of?(Generator)
-    gen = @query1.generator
-    assert_equal [1,2,3], gen.next 
-    assert_equal [4,5,6], gen.next 
-    assert_equal [7,8,9], gen.next 
+    query = @query[:precached]
+    gen = query.generator
+    assert_equal @data[0][0], gen.next 
+    assert_equal @data[0][1], gen.next 
+    assert_equal @data[0][2], gen.next 
     assert_raise(EOFError) { gen.next }
   end
 
-  def test_caching_triggers
-    assert_nothing_raised { @query1.enable_caching }
-    assert_nothing_raised { @query1.disable_caching }
+  def test_to_table
+    return unless Object.const_defined? :Mocha
+    query = @query[:raw]
+    setup_mock_dbi(3, :returns => @data[0])
+
+    assert_equal @data[0], query.result
+    assert_equal @data[0].to_table(@columns), query.to_table
+    assert_equal @data[0], query.result
   end
 
+  def test_to_csv
+    return unless Object.const_defined? :Mocha
+    query = @query[:plain]
+    setup_mock_dbi(1)
+    
+    csv = @data[0].to_table(@columns).as(:csv)
+    assert_equal csv, query.to_csv
+  end
+  
+  private
+  def setup_mock_dbi(count, options={})
+    sql = options[:sql] || @sql[0]
+    source = options[:source] || :default
+    returns = options[:returns] || Proc.new { @datasets.shift }
+    resultless = options[:resultless]
+    params = options[:params] || []
+    
+    @dbh = mock("database_handle")
+    @sth = mock("statement_handle")
+    def @dbh.execute(*a, &b); execute__(*a, &b); ensure; sth__.finish if b; end
+    def @sth.each; data__.each { |x| yield(x) }; end
+    def @sth.fetch_all; data__; end
+    
+    DBI.expects(:connect).
+      with(*@sources[source].values_at(:dsn, :user, :password)).
+      yields(@dbh).times(count)
+    @dbh.expects(:execute__).with(sql, *params).
+      yields(@sth).returns(@sth).times(count)
+    @dbh.stubs(:sth__).returns(@sth)
+    @sth.expects(:finish).with().times(count)
+    unless resultless
+      @sth.stubs(:fetchable?).returns(true)
+      @sth.stubs(:column_names).returns(@columns)
+      @sth.expects(:data__).returns(returns).times(count)
+    else
+      @sth.stubs(:fetchable?).returns(false)
+      @sth.stubs(:column_names).returns([])
+      @sth.stubs(:cancel)
+      @sth.expects(:data__).times(0)
+    end  
+  end
+  
+  def get_query_source(query)
+    [ :dsn, :user, :password ].inject({}) do |memo, var|
+      memo.update var => query.instance_variable_get("@#{var}")
+    end
+  end
+
+  def get_raw(table)
+    table.collect { |row| row.to_a }
+  end
 end