ruport 0.7.2 → 0.8.0

data/lib/ruport/query.rb

@@ -3,6 +3,7 @@ require "ruport/query/sql_split"
 
 module Ruport
   
+  #
   # === Overview
   # 
   # Query offers a way to interact with databases via DBI. It supports
@@ -18,6 +19,7 @@ module Ruport
     
     include Enumerable
     
+    #
     # 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
@@ -96,6 +98,7 @@ module Ruport
       @cached_data = nil
     end
     
+    #
     # Set this to <tt>true</tt> to get DBI:Rows, <tt>false</tt> to get Ruport 
     # constructs.
     #
@@ -107,6 +110,7 @@ module Ruport
     # The original SQL for the Query object
     attr_reader :sql
     
+    #
     # This will set the <tt>dsn</tt>, <tt>username</tt>, and <tt>password</tt> 
     # to one specified by a source in Ruport::Config.
     #
@@ -116,18 +120,20 @@ module Ruport
       @password = Ruport::Config.sources[label].password
     end 
     
+    #
     # 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 
+        :level => :log_only, :raises => LocalJumpError 
       ) unless action
       fetch(&action)
       self
     end
     
+    #
     # Grabs the result set as a Data::Table or an Array of DBI::Row objects 
     # if in <tt>raw_data</tt> mode.
     #
@@ -141,6 +147,7 @@ module Ruport
       @cached_data = nil
     end
 
+    #
     # Clears the contents of the cache, then runs the query, filling the
     # cache with the new result.
     #
@@ -149,6 +156,7 @@ module Ruport
       clear_cache; fetch
     end
     
+    #
     # Turns on caching.  New data will not be loaded until the cache is clear 
     # or caching is disabled.
     #
@@ -162,6 +170,7 @@ module Ruport
       @cache_enabled = false
     end
     
+    #
     # 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.
     #
@@ -183,9 +192,11 @@ module Ruport
     private
     
     def query_data(query_text, params=@params)
+
       require "dbi"
       
       data = @raw_data ? [] : Data::Table.new
+
       DBI.connect(@dsn, @user, @password) do |dbh|
         dbh.execute(query_text, *(params || [])) do |sth|
           # Work-around for inconsistent DBD behavior w/ resultless queries
@@ -197,6 +208,7 @@ module Ruport
           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

data/lib/ruport/renderer.rb

@@ -14,6 +14,93 @@
 # you do not need that, may not be relevant to study for your use of Ruport.
 class Ruport::Renderer
   module Helpers #:nodoc:
+    module ClassMethods
+
+      # establish some class instance variables for storing require data
+      attr_accessor :first_stage,:final_stage,:required_options,:stages
+
+      # allow the report designer to specify what method will 
+      # render the report  e.g.
+      #   finalize :document
+      #
+      def finalize(stage)
+        raise 'final stage already defined' if final_stage
+        self.final_stage = stage
+      end
+
+      # allow the report designer to specify a preparation stage for their
+      # report, e.g.
+      #
+      #   prepare :document
+      #
+      def prepare(stage)
+        raise "prepare stage already defined" if first_stage
+        self.first_stage = stage
+      end
+
+      # allow the report designer to specify options that can be used to build
+      # the report. These are generally used for defining rendering options or
+      # data
+      # e.g.
+      #   option :report_title
+      #   option :table_width
+      def option(opt)
+        opt = "#{opt.to_s}="
+        define_method(opt) {|t| options.send(opt, t) }
+      end
+
+      # allow the report designer to specify a compulsory option
+      # e.g.
+      #   required_option :freight
+      #   required_option :tax
+      def required_option(opt)
+        self.required_options ||= []
+        self.required_options << opt
+        option opt
+      end
+ 
+      # allow the report designer to specify the stages that will be used to
+      # build the report
+      # e.g.
+      #   stage :document_header
+      #   stage :document_body
+      #   stage :document_footer
+      def stage(stage)
+        self.stages ||= []
+        self.stages << stage.to_s
+      end
+    end
+ 
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # called automagically when the report is rendered. Uses the
+    # data collected from the earlier methods.
+    def run
+      # ensure all the required options have been set
+      unless self.class.required_options.nil?
+        self.class.required_options.each do |opt|
+          if options.__send__(opt).nil?
+            raise "Required option #{opt} not set"
+          end
+        end
+      end
+
+      prepare self.class.first_stage if self.class.first_stage
+
+      # call each stage to build the report
+      unless self.class.stages.nil?
+        self.class.stages.each do |stage|
+          self.build stage
+        end
+      end
+
+      finalize self.class.final_stage if self.class.final_stage
+
+    end
+
+ 
     def prepare(name)
       maybe "prepare_#{name}"
     end
@@ -33,8 +120,7 @@ class Ruport::Renderer
       plugin.send something if plugin.respond_to? something
     end
   end
-
-  # Allows you to register a format with the renderer.
+  # allows you to register a format with the renderer.
   #
   # example:
   #
@@ -45,13 +131,11 @@ class Ruport::Renderer
   #     SomeRenderer.add_format self, :my_plugin
   #
   #   end
-  #
   def self.add_format(format,name=nil)
     return formats[name] = format if name
 
-    # NOTE: MEANT FOR INTERNAL USE
     add_core_format(format)   
- end
+  end
 
 
   # reader for formats.  Defaults to a hash
@@ -61,7 +145,6 @@ class Ruport::Renderer
 
   # same as Renderer#layout, but can be used to specify a default layout object
   # for the entire class.  
-  #
   def self.layout
     @layout ||= Ruport::Layout::Component.new
     yield(@layout) if block_given?
@@ -76,7 +159,6 @@ class Ruport::Renderer
   # The run() method is then called on the renderer method.
   #
   # Finally, the value of the plugin's output accessor is returned
-  #
   def self.render(format,&block)
     rend = build format, &block
     rend.run
@@ -89,7 +171,6 @@ class Ruport::Renderer
   # yielded.  
   #
   # Returns the renderer instance.
-  #
   def self.build(format)
     rend = self.new
 
@@ -114,7 +195,6 @@ class Ruport::Renderer
   end
 
   # sets +data+ attribute on both the renderer and any active plugin
-  #
   def data=(val)
     @data = val.dup
     plugin.data = @data if plugin
@@ -122,7 +202,6 @@ class Ruport::Renderer
 
   # General purpose openstruct which is shared with the current formatting
   # plugin.
-  #
   def options
     yield(plugin.options) if block_given?
     plugin.options
@@ -135,7 +214,6 @@ class Ruport::Renderer
   #
   # when a block is given without block variables, instance_evals the block
   # within the context of the plugin
-  #
   def plugin(&block)
     if block.nil?
       return @plugin 
@@ -159,7 +237,6 @@ class Ruport::Renderer
 
   # tries to autoload and register a format which is part of the Ruport::Format
   # module.  For internal use only.
-  #
   def self.add_core_format(format)
     try_require(format)
     
@@ -170,14 +247,12 @@ class Ruport::Renderer
   end
 
   # internal shortcut for format registering
-  #
   def self.add_formats(*formats)
     formats.each { |f| add_format f }
   end
 
   # Trys to autoload a given format,
   # silently fails
-  #
   def self.try_require(format)
     begin
       require "ruport/format/#{format}"  
@@ -187,20 +262,17 @@ class Ruport::Renderer
   end
 
   # selects a plugin for use by format name
-  #
   def use_plugin(format)
     self.plugin = self.class.formats[format].new
   end
 
   # provides a shortcut to render() to allow
   # render(:csv) to become render_csv
-  #
   def self.method_missing(id,*args,&block)
     id.to_s =~ /^render_(.*)/
     $1 ? render($1.to_sym,&block) : super
   end
 
-
 end
 
 require "ruport/renderer/table"

data/lib/ruport/renderer/graph.rb

@@ -37,11 +37,11 @@ module Ruport
       l.style  = :line
     end
 
-    def run
-      prepare :graph
-      build :graph
-      finalize :graph
-    end
+    prepare :graph
+
+    stage :graph
+
+    finalize :graph
 
   end
 

data/lib/ruport/renderer/table.rb

@@ -20,7 +20,7 @@ module Ruport
     #   table.as(:text){ |r| r.rewrite_column("col1") { |a| a[0] + 5 }
     #   table.as(:csv) { |r| r.rewrite_column(2) { |a| a.capitalize }
     def rewrite_column(key,&block)
-      data.each { |r| r[key] = block[r] }
+      data.to_a.each { |r| r[key] = block[r] }
     end
 
     # Gets the number of columns in a table.  Useful in formatting plugins.
@@ -118,15 +118,14 @@ module Ruport
      
     add_formats :csv, :text, :html, :latex, :pdf
 
-    layout do |lay|
-      lay.show_table_headers = true
-    end
+    layout { |lay| lay.show_table_headers = true }
+
+    prepare :table
     
-    def run
-      prepare :table
-      build [:header,:body,:footer], :table
-      finalize :table
-    end
+    stage :table_header
+    stage :table_body
+    stage :table_footer
 
+    finalize :table
   end
 end

data/lib/ruport/report.rb

@@ -160,8 +160,8 @@ module Ruport
     # Like Report#write, but will append to a file rather than overwrite it if
     # the file already exists.
     #
-    def append(my_file=file)
-      File.open(my_file,"a") { |f| f << results }
+    def append(my_file=file,my_results=results)
+      File.open(my_file,"a") { |f| f << my_results }
     end
     
     # This method passes <tt>self</tt> to Report.run.
@@ -308,10 +308,6 @@ module Ruport
         end
         
       end
-
     end
-
   end
 end
-
-

data/test/test_config.rb

@@ -1,76 +1,88 @@
-require "test/unit"
-require "ruport"
-
-class TestConfiguration < Test::Unit::TestCase
-
-  def setup
-    Ruport::Config.log_file = "test/unit.log"
-  end
-  
-  def test_dsn_defaults
-    assert_equal(nil, Ruport::Config.default_source)
-  end
-
-  def test_mail_defaults
-    assert_equal(nil, Ruport::Config.default_mailer)
-  end
-
-  def test_missing_dsn
-   assert_raise(ArgumentError) {
-     Ruport::Config.source :foo, :user => "root", :password => "fff"
-   }
-   assert_nothing_raised { Ruport::Config.source :bar, :dsn => "..." }
-  end
-
-  def test_mailer_errors
-    assert_raise(ArgumentError) {
-      Ruport::Config.mailer :bar, :user => :foo, :address => "foo@bar.com"
-    }
-    assert_nothing_raised { Ruport::Config.mailer :bar, :host => "localhost" }
-  end
-
-  def test_new_defaults
-   Ruport::Config.source :default, :dsn      => "dbi:mysql:test",
-                                   :user     => "root",
-                                   :password => ""
-   assert_equal("dbi:mysql:test", Ruport::Config.default_source.dsn)
-   assert_equal("root", Ruport::Config.default_source.user)
-   assert_equal("", Ruport::Config.default_source.password)
-  end
-
-  def test_multiple_sources
-    Ruport::Config.source :foo, :dsn => "dbi:mysql:test"
-    Ruport::Config.source :bar, :dsn => "dbi:mysql:test2"
-    assert_equal("dbi:mysql:test",  Ruport::Config.sources[:foo].dsn)
-    assert_equal("dbi:mysql:test2", Ruport::Config.sources[:bar].dsn)
-  end
-
-  def test_simple_interface
-    Ruport.configure do |c|
-      c.source :foo, :dsn => "dbi:odbc:test"
-      c.source :bar, :dsn => "dbi:odbc:test2"
-    end
-    assert_equal("dbi:odbc:test",Ruport::Config.sources[:foo].dsn)
-    assert_equal("dbi:odbc:test2",Ruport::Config.sources[:bar].dsn)
-  end
-    
-
-  def test_logger
-    # We have a logger running now, dont we?
-    assert(Ruport::Config.logger.kind_of?(Logger)) 
-      
-    # And then we change are mind again.  Back logging?
-    Ruport::Config.log_file = "test/unit.log"  
-    assert(Ruport::Config.logger.kind_of?(Logger))
-    
-  end
-
-  def test_debug
-    assert_equal(false, Ruport::Config.debug_mode?)
-    Ruport::Config.debug_mode = true 
-    assert_equal(true, Ruport::Config.debug_mode?)
-    Ruport::Config.debug_mode = false
-    assert_equal(false, Ruport::Config.debug_mode?)
-  end
-   
-end
+require "test/unit"
+require "ruport"
+
+class TestConfiguration < Test::Unit::TestCase
+
+  def setup
+    Ruport::Config.log_file = "test/unit.log"
+  end
+  
+  def test_dsn_defaults
+    assert_equal(nil, Ruport::Config.default_source)
+  end
+
+  def test_mail_defaults
+    assert_equal(nil, Ruport::Config.default_mailer)
+  end
+
+  def test_missing_dsn
+   assert_raise(ArgumentError) {
+     Ruport::Config.source :foo, :user => "root", :password => "fff"
+   }
+   assert_nothing_raised { Ruport::Config.source :bar, :dsn => "..." }
+  end
+
+  def test_mailer_errors
+    assert_raise(ArgumentError) {
+      Ruport::Config.mailer :bar, :user => :foo, :address => "foo@bar.com"
+    }
+    assert_nothing_raised { Ruport::Config.mailer :bar, :host => "localhost" }
+  end
+
+  def test_new_defaults
+   Ruport::Config.source :default, :dsn      => "dbi:mysql:test",
+                                   :user     => "root",
+                                   :password => ""
+   assert_equal("dbi:mysql:test", Ruport::Config.default_source.dsn)
+   assert_equal("root", Ruport::Config.default_source.user)
+   assert_equal("", Ruport::Config.default_source.password)
+  end
+
+  def test_multiple_sources
+    Ruport::Config.source :foo, :dsn => "dbi:mysql:test"
+    Ruport::Config.source :bar, :dsn => "dbi:mysql:test2"
+    assert_equal("dbi:mysql:test",  Ruport::Config.sources[:foo].dsn)
+    assert_equal("dbi:mysql:test2", Ruport::Config.sources[:bar].dsn)
+  end
+
+  def test_simple_interface
+    Ruport.configure do |c|
+      c.source :foo, :dsn => "dbi:odbc:test"
+      c.source :bar, :dsn => "dbi:odbc:test2"
+    end
+    assert_equal("dbi:odbc:test",Ruport::Config.sources[:foo].dsn)
+    assert_equal("dbi:odbc:test2",Ruport::Config.sources[:bar].dsn)
+  end
+    
+
+  def test_logger
+    # We have a logger running now, dont we?
+    assert(Ruport::Config.logger.kind_of?(Logger)) 
+      
+    # And then we change are mind again.  Back logging?
+    Ruport::Config.log_file = "test/unit.log"  
+    assert(Ruport::Config.logger.kind_of?(Logger))
+    
+  end
+
+  def test_debug
+    assert_equal(false, Ruport::Config.debug_mode?)
+    Ruport::Config.debug_mode = true 
+    assert_equal(true, Ruport::Config.debug_mode?)
+    Ruport::Config.debug_mode = false
+    assert_equal(false, Ruport::Config.debug_mode?)
+  end
+  
+  def test_adding_custom_accessors
+    Ruport::Config.my_new_setting = 'blinky'
+    assert_equal('blinky', Ruport::Config.my_new_setting)
+    Ruport::Config.my_new_setting = 'clyde'
+    assert_equal('clyde', Ruport::Config.my_new_setting)
+    
+    Ruport::Config.my_other_new_setting 'inky'
+    assert_equal('inky', Ruport::Config.my_other_new_setting)
+    Ruport::Config.my_other_new_setting 'sue'
+    assert_equal('sue', Ruport::Config.my_other_new_setting)
+  end
+  
+end