ruport 0.4.11 → 0.4.13

data/lib/ruport/format/engine.rb

@@ -72,7 +72,7 @@ module Ruport
       def plugins
         format_plugins.values
       end 
-
+      
     end
   end
   

data/lib/ruport/format/plugin.rb

@@ -42,6 +42,7 @@ module Ruport
       
       attr_accessor :rendered_field_names
       attr_accessor :pre, :post
+      attr_accessor :header, :footer
    end
     
     
@@ -78,7 +79,7 @@ module Ruport
         }
         
         a = data.inject(th){ |s,r| 
-          s << "| #{r.to_a.join(' | ')} |\n"
+          s + "| #{r.to_a.join(' | ')} |\n"
         } << hr
 
         width = self.right_margin || SystemExtensions.terminal_width
@@ -111,7 +112,7 @@ module Ruport
         f = data.fields if data.respond_to? :fields
         d = DataSet.new f, :data => data 
 
-        d[0].fields.inject(0) { |s,e| s+=max_col_width(e) }
+        d[0].fields.inject(0) { |s,e| s + max_col_width(e) }
       end
 
       def self.hr
@@ -158,7 +159,7 @@ module Ruport
       renderer :table do
         rc = data.inject(rendered_field_names) { |s,r| 
           row = r.map { |e| e.to_s.empty? ? "&nbsp;" : e }
-          s << "|#{row.to_a.join('|')}|\n" 
+          s + "|#{row.to_a.join('|')}|\n" 
         }
         Format.document :data => rc, :plugin => :html 
       end

data/lib/ruport/mailer.rb

@@ -11,7 +11,8 @@ module Ruport
       extend Forwardable
       
       def initialize( mailer_label=:default )
-        select_mailer(mailer_label); mail_object
+        select_mailer(mailer_label); 
+        mail_object.from = @mailer.address if mail_object.from.to_s.empty?
         rescue
           raise "you need to specify a mailer to use"
       end
@@ -29,14 +30,14 @@ module Ruport
       end
 
       def select_mailer(label)
-        mailer      = Ruport::Config.mailers[label]
-        @host       = mailer.host
-        @user       = mailer.user
-        @password   = mailer.password
-        @address    = mailer.address
-        @port       = mailer.port       || 25
-        @auth       = mailer.auth_type  || :plain
-        @mail_klass = mailer.mail_klass
+        @mailer      = Ruport::Config.mailers[label]
+        @host       = @mailer.host
+        @user       = @mailer.user
+        @password   = @mailer.password
+        @address    = @mailer.address
+        @port       = @mailer.port       || 25
+        @auth       = @mailer.auth_type  || :plain
+        @mail_klass = @mailer.mail_klass
       end
 
       def mail_object

data/lib/ruport/query.rb

@@ -61,8 +61,7 @@ module Ruport
     #   # uses a SQL file stored on disk
     #   Ruport::Query.new("my_query.sql",:origin => :file)
     def initialize(sql, options={})
-      options[:source] ||= :default
-      options[:origin] ||= :string
+      options = { :source => :default, :origin => :string }.merge(options)
       @sql = sql
       @statements = SqlSplit.new(get_query(options[:origin],sql))
       
@@ -116,15 +115,14 @@ module Ruport
     
     # clears the contents of the cache
     def clear_cache
-      @cached_data = nil
+      @CAched_data = nil
     end
 
     # clears the contents of the cache and then runs the query, filling the
     # cache with the new result
     def update_cache
-      clear_cache
-      caching_flag,@cache_enabled = @cache_enabled, true
-      fetch; @cache_enabled = caching_flag
+      return unless @cache_enabled
+      clear_cache; fetch
     end
     
     # Turns on caching.  New data will not be loaded until cache is clear or
@@ -135,7 +133,7 @@ module Ruport
 
     # Turns off caching and flushes the cached data
     def disable_caching
-      @cached_data   = nil
+      clear_cache
       @cache_enabled = false
     end
     
@@ -148,7 +146,7 @@ module Ruport
 
     # Returns a csv dump of the query
     def to_csv
-      to_dataset.to_csv
+      Format.table :plugin => :csv, :data => fetch
     end
 
     # Returns a Generator object of the result set
@@ -176,12 +174,7 @@ module Ruport
     end 
     
     def get_query(type,query)
-      case (type)
-      when :string
-         query
-      when :file
-        load_file( query )
-      end
+      type.eql?(:file) ? load_file( query ) : query
     end
     
     def load_file( query_file )

data/lib/ruport/report.rb

@@ -1,27 +1,140 @@
-# fixME: Copyright notice here.
+# report.rb : High Level Interface to Ruport
+#
+# Author: Gregory Brown
+# Copyright 2006, All Rights Reserved
+#
+# This is Free Software.  See LICENSE and COPYING files for details.
 
 #load the needed standard libraries.
 %w[erb yaml date logger fileutils].each { |lib| require lib }
 
 require "ruport/mailer"
+require "forwardable"
 
 module Ruport
+  # === Overview
+  #
+  # The Ruport::Report class povides a high level interface to most of Ruport's
+  # functionality.  It is designed to allow you to build and run reports easily.
+  # If your needs are complicated, you will probably need to take a look at the
+  # individual classes of the library, but if they are fairly simple, you may be
+  # able to get away using this class alone.
+  #
+  # === Example
+  #
+  # Here is a simple example of using the Report class to run a simple query and
+  # then email the results as a CSV file, deleting the file from the local
+  # machine after it has been emailed:
+  #
+  #  require "ruport"
+  #  require "fileutils"
+  #  class MyReport < Ruport::Report
+  #    prepare do
+  #      log_file "f.log"
+  #      log "preparing report", :status => :info
+  #      source :default, 
+  #        :dsn => "dbi:mysql:foo", 
+  #        :user => "root"
+  #      mailer :default,
+  #        :host => "mail.adelphia.net", 
+  #        :address => "gregory.t.brown@gmail.com"
+  #    end
+  #      
+  #    generate do
+  #      log "generated csv from query", :status => :info
+  #      query "select * from bar", :as => :csv 
+  #    end
+  #
+  #    cleanup do
+  #      log "removing foo.csv", :status => :info
+  #      FileUtils.rm("foo.csv") 
+  #    end
+  #  end
+  #
+  #  MyReport.run { |res| 
+  #    res.write "foo.csv";
+  #    res.send_to("greg7224@gmail.com") do |mail|
+  #      mail.subject = "Sample report" 
+  #      mail.attach "foo.csv"
+  #      mail.text = <<-EOS
+  #        this is a sample of sending an emailed report from within Ruport.
+  #      EOS
+  #    end
+  #  } 
+  #
+  # 
+  # 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 )
+  #
   class Report   
+    extend Forwardable
+    
+    # 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
+    #
+    # If your report does not need any sort of specialized information, you can
+    # 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 )
-      @source = source_name
-      @report_name = @report = ""
+      use_source source_name
+      use_mailer mailer_name
+      @report_name = @results = ""
       @file        = nil
     end
     
-    attr_accessor :file,:report
-    
-    # High level interface to Ruport::Query
-    # - Can read SQL statements from file or string
-    # - Can use multistatement SQL 
-    # - Can iterate by row or return entire set
-    # - Can return raw DBI:Row objects or Ruport constructs.
+    #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.
+    attr_accessor :results
+
+    # Preserved for backwards compatability, please do not use this.
+    alias_method :report, :results
+
+    # Preserved for backwards compabilitity, please do not use this.
+    alias_method :report=, :results=
+
+
+    # Simplified interface to Ruport::Query
+    #
+    # === Can read SQL statements from file or string
+    #  
+    #  #from string 
+    #  result = query "select * from foo"
+    #
+    #  #from file 
+    #  result = query "my_query.sql", :origin => :file
+    # 
+    # === 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"
+    # 
+    # === Can iterate by row or return entire set
+    #  
+    #  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.
+    # 
+    #  # will return a DataSet
+    #  result = query "select * from foo"
     #
-    # Defaults to returning entire sets of Ruport constructs.
+    #  # will return an Array of DBI::Row objects
+    #  result = query "select * from foo", :raw_data => true
+    #
+    # === 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
     #
     # See source of this function and methods of Ruport::Query for details.
     def query(sql, options={}, &action)
@@ -31,6 +144,8 @@ module Ruport
       q = Query.new(sql, options)
       if options[:yield_type].eql?(:by_row)
         q.each { |r| action.call(r) }
+      elsif options[:as]
+        Format.table :data => q.result, :plugin => options[:as]
       else
         block_given? ? action.call(q.result) : q.result
       end
@@ -38,41 +153,32 @@ module Ruport
     
     # Evaluates _code_ from _filename_ as pure ruby code for files ending in
     # .rb, and as ERb templates for anything else.
-    def eval_template( filename, code )
-      filename =~ /\.rb/ ? eval(code) : ERB.new(code, 0, "%").run(binding)
-    end
-    
-
-    # Generates the report.  If @pre or @post are defined with lambdas,
-    # they will be called before and after the main code.
-    #
-    # If @file != nil, ruport will print to the
-    # file with the specified name.  Otherwise, it will print to STDOUT by
-    # default. 
     #
-    # The source for this function is probably easier to read than this
-    # explanation, so you may want to start there.     
-    def generate_report
-      @pre.call if @pre
-      @file ? File.open(@file,"w") { |f| f.puts @report } : puts(@report)
-      @post.call if @post
+    # 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, "%").run(binding)
     end
-
+   
     # sets the active source to the Ruport::Config source requested by label.
     def use_source(label)
       @source = label
     end
+
+    # sets the active mailer to the Ruport::Config source requested by label.
+    def use_mailer(label)
+      @mailer = label
+    end
     
     # Provides a nice way to execute templates and filters.
     #
     # Example:
     #
-    #   my_report.render( "_<%= @some_internal_var %>_", 
-    #                     :filters => [:erb,:red_cloth] )
+    #  process_text "_<%= @some_internal_var %>_", :filters => [:erb,:red_cloth]
     #
     # This method automatically passes a binding into the filters, so you are
     # free to access data from your Report instance in your templates.
-    def render(string, options)
+    def process_text(string, options)
       options[:filters].each do |f|
         format = Format.new(binding)
         format.content = string
@@ -80,9 +186,104 @@ module Ruport
       end
       string
     end
+    
+    # preserved for backwards compatibility. please do not use.
+    alias_method :render, :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
+    #
+    #  text_processor(:unix_newlines) { results.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
+    # 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)
+      File.open(my_file,"w") { |f| f << results }
+    end
+
+    # 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 }
+    end
+
+    class << self
+
+      # Defines an instance method which will be run before the
+      # <tt>generate</tt> method when Ruport.run is executed
+      #
+      # 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
+      #
+      # The return value of this method is assigned to the <tt>results</tt>
+      # 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 
+      #
+      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>
+      #
+      # 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)
+      # 
+      # Finally, it tries to call cleanup.
+      def run(*reports)
+        reports[0] ||= self.new
+        reports.each { |rep|
+          rep.prepare if rep.respond_to? :prepare;
+          rep.results = rep.generate;
+          yield(rep) if block_given?
+          rep.cleanup if rep.respond_to? :cleanup;
+        }
+      end
+    end
+
+    # this method passes <tt>self</tt> to Report.run 
+    #
+    # Please see the class method for details.
+    def run(&block)
+      self.class.run(self,&block)
+    end
+    
+    # Preserved for backwards compatibility, please do not use this.
+    alias_method :generate_report, :run
 
+    # Allows logging and other fun stuff. See 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.
+    #
+    # By default, this will
+    def send_to(adds)
+      m = Mailer.new
+      m.to = adds
+      yield(m)
+      m.select_mailer @mailer
+      m.deliver :from => m.from, :to => m.to
+    end
+    
+    def_delegators Ruport::Config, :source, :mailer, :log_file, :log_file=
+    
   end
+
 end