ruport 0.4.23 → 0.4.99

data/lib/ruport/format.rb

@@ -9,49 +9,41 @@
 #
 # See LICENSE and COPYING for details
 module Ruport
-  
-  
-# Ruport's Format model is meant to help get your data in a suitable format for
-# output.  Rather than make too many assumptions about how you will want your
-# data to look, a number of tools have been built so that you can quickly define
-# those things yourself.
-#
-# There are three main sets of functionality the Ruport::Format model provides.
-#   * Structured printable document support ( Format::Document and friends)
-#   * Text filter support ( Report#render and the Format class)
-#
-# The support for structured printable documents is currently geared towards PDF
-# support and needs some additional work to be truly useful.  Suggestions would
-# be much appreciated.
-#
-# The filters implemented in the Format class are meant to process strings or
-# entire templates.  The Format class will soon automatically build a
-# Ruport::Parser for any string input.  By default, filters are provided to
-# process erb, pure ruby, and redcloth.  It is trivial to extend this
-# functionality though.
-#
-# This is best shown by a simple example:
-#
-#   a = Ruport::Report.new
-#   Ruport::Format.register_filter :reverser do
-#     content.reverse
-#   end
-#   a.render "somestring", :filters => [:reverser]
-#   
-#   Output: "gnirtsemos"
-#
-# Filters can be combined, and you can run them in different orders to obtain
-# different results.
-#
-# See the source for the built in filters for ideas.
-#
-# Also, see Report#render for how to bind Format objects to your own classes.
-#
-# When combined, filters, data set output templates, and structured printable
-# document facilities create a complete Formatting system.
-#
-# This part of Ruport is under active development.  Please do feel free to
-# submit feature requests or suggestions.
+
+  # Ruport makes heavy use of ruby's advanced meta programming features in 
+  # this Class.
+  #
+  # All subclasses of Ruport::Format::Engine and Ruport::Format::Plugin
+  # (both Ruports' internal ones and any custom ones outside the Ruport 
+  # library) should dynamically register themselves with this class.
+  #
+  # All report generation is then done via Format, not with the engines
+  # and plugins directly.
+  #
+  # For each engine that is registered with Format, 2 methods are created:
+  #  - <enginename>; and
+  #  - <enginename>_object
+  #
+  # Either one of these methods can be used to create your report, depending
+  # on your requirments.
+  #
+  # = Format.enginename
+  #
+  # A brief example of creating a simple report with the table engine
+  #   
+  #   data = [[1,2],[5,3],[3,10]].to_table(%w[a b])
+  #   File.open("myreport.pdf","w") { |f| f.puts Ruport::Format.table(:plugin => :pdf, :data => data)}
+  #
+  # = Format.enginename_object
+  # 
+  # A slightly different way to create a simple report with the table engine. 
+  # This technique gives you a chance to modify some of the engines settings
+  # before calling render manually.
+  #
+  #   data = [[1,2],[5,3],[3,10]].to_table(%w[a b])
+  #   myreport = Ruport::Format.table_object :plugin => :pdf, :data => data
+  #   File.open("myreport.pdf","w") { |f| f.puts myreport.render }
+  # 
   class Format
     
     # Builds a simple interface to a formatting engine.
@@ -83,7 +75,7 @@ module Ruport
           options[:auto_render] = false; simple_interface(engine,options) })
     end
 
-    %w[open_node document engine plugin].each { |lib|
+    %w[engine plugin].each { |lib|
        require "ruport/format/#{lib}" 
     }
 

data/lib/ruport/format/engine.rb

@@ -1,3 +1,5 @@
+class InvalidPluginError < RuntimeError; end
+
 module Ruport
   class Format::Engine
     require "forwardable"
@@ -44,6 +46,11 @@ module Ruport
       end
 
       def plugin=(p)
+        if @format_plugins[p].nil?
+          raise(InvalidPluginError, 
+                'The requested plugin and engine combination is invalid') 
+        end
+
         @plugin = p
         @format_plugins[:current] = @format_plugins[p].dup
         @format_plugins[:current].data = self.data.dup if self.data 
@@ -94,6 +101,18 @@ module Ruport
     private_class_method :new
   end
   
+  class Format::Engine::Graph < Ruport::Format::Engine
+    
+    renderer do
+      super
+      active_plugin.render_graph
+    end
+  
+    alias_engine Graph, :graph_engine
+    Ruport::Format.build_interface_for Graph, :graph
+  
+  end
+ 
  class Format::Engine::Invoice < Ruport::Format::Engine
 
     # order meta data
@@ -150,7 +169,8 @@ module Ruport
       
       def build_field_names
         if active_plugin.respond_to?(:build_field_names)
-          active_plugin.rendered_field_names = active_plugin.build_field_names
+          active_plugin.rendered_field_names = 
+            active_plugin.build_field_names
         end
       end
 

data/lib/ruport/format/plugin.rb

@@ -1,3 +1,5 @@
+require 'bigdecimal'
+
 module Ruport
   class Format::Plugin
 
@@ -64,6 +66,66 @@ module Ruport
       register_on :table_engine
     end
 
+    class SVGPlugin < Format::Plugin
+      
+      helper(:init_plugin) { |eng|
+        # check the supplied data can be used for graphing
+        data.each { |r|
+          if data.column_names.size != r.data.size
+            raise ArgumentError, "Column names and data do not match"           
+          end 
+          r.data.each { |c|
+            begin
+              c = BigDecimal.new(c) unless c.kind_of?(Float) || 
+                c.kind_of?(Fixnum) || c.kind_of?(BigDecimal)
+            rescue
+              raise ArgumentError, "Unable to convert #{c.to_s} into a number" 
+            end
+          }
+        }
+        
+        raise RuntimeError, 'You must provide an options hash before rendering a graph' if self.options.nil?
+
+        # load the appropriate SVG::Graph class based on the graph_style option
+        case options[:graph_style]
+        when :bar
+          require "SVG/Graph/Bar"
+          graphclass = SVG::Graph::Bar
+        when :bar_horizontal
+          require "SVG/Graph/BarHorizontal"
+          graphclass = SVG::Graph::BarHorizontal
+        when :line
+          require "SVG/Graph/Line" 
+          graphclass = SVG::Graph::Line
+        when :pie
+          require "SVG/Graph/Pie" 
+          graphclass = SVG::Graph::Pie
+        else
+          raise "Unsupported graph type requested"
+        end
+
+        # create an instance of the graphing class
+        options[:fields] = data.column_names
+        @graph = graphclass.new(options)
+      }
+
+      renderer :graph do
+        
+        data.each_with_index { |r,i|
+          @graph.add_data({
+            :data => r.data,
+            :title => r.tags[0] || 'series ' + (i+1).to_s
+          })
+        }
+        
+        # return the rendered graph
+        @graph.burn()
+      end
+      
+      plugin_name :svg
+      register_on :graph_engine
+    end
+    
     class TextPlugin < Format::Plugin
       rendering_options :erb_enabled => true, :red_cloth_enabled => false
 
@@ -195,7 +257,8 @@ module Ruport
           pdf.stroke_style! PDF::Writer::StrokeStyle::DEFAULT
           if eng.comments  
             pdf.y -= 20
-            text_box eng.comments, :position => 110, :width => 400
+            text_box eng.comments, :position => 110, :width => 400, 
+                                   :font_size => 14
           end
           pdf.add_text_wrap( 50, 20, 200, "Printed at " + 
                              Time.now.strftime("%H:%M %d/%m/%Y"), 8)

data/lib/ruport/mailer.rb

@@ -7,45 +7,79 @@
 require "net/smtp"
 require "forwardable"
 module Ruport  
-    class Mailer
-      extend Forwardable
-      
-      def initialize( mailer_label=:default )
-        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
-     
-      def_delegators( :@mail, :to, :to=, :from, :from=, 
-                             :subject, :subject=, :attach, 
-                             :text, :text=, :html, :html= )
+
+    # 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"
+  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
+    #
+    def initialize( mailer_label=:default )
+      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
+   
+    def_delegators( :@mail, :to, :to=, :from, :from=, 
+                           :subject, :subject=, :attach, 
+                           :text, :text=, :html, :html= )
+   
+    # sends the message
+    #
+    #   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}=" }
       
-      def deliver(options={})
-        options.each { |k,v| send("#{k}=",v) if respond_to? "#{k}=" }
-        
-        Net::SMTP.start(@host,@port,@host,@user,@password,@auth) do |smtp|
-          smtp.send_message((options[:mail_object] || mail_object).to_s, options[:from], options[:to] )
-        end
+      Net::SMTP.start(@host,@port,@host,@user,@password,@auth) do |smtp|
+        smtp.send_message((options[:mail_object] || mail_object).to_s, options[:from], options[:to] )
       end
+    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
-      end
+    private
 
-      def mail_object
-        return @mail if @mail
-        return @mail ||= @mail_klass.new if @mail_klass
-        require "mailfactory"
-        @mail ||= MailFactory.new
-      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
+    end
+
+    def mail_object
+      return @mail if @mail
+      return @mail ||= @mail_klass.new if @mail_klass
+      require "mailfactory"
+      @mail ||= MailFactory.new
     end
+    
+  end
 end

data/lib/ruport/meta_tools.rb

@@ -1,3 +1,4 @@
+class ActionAlreadyDefinedError < RuntimeError; end
 module Ruport
   # 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
@@ -9,8 +10,7 @@ module Ruport
     # Example:
     # 
     #  class A
-    #     class << self; include MetaTools; end
-    #
+    #     extend Ruport::MetaTools
     #     attribute :foo
     #  end
     #
@@ -21,22 +21,31 @@ module Ruport
       self.send("#{sym}=",value)
     end
 
-    # same as accessor, but takes an array of attributes
+    # same as attribute, but takes an array of attributes
     #
     # e.g. attributes [:foo,:bar,:baz]
     def attributes(syms)
       syms.each { |s| attribute s }
     end
-
+    
+    # allows you to define a method on the singleton_class
+    #
+    # Example:
+    #
+    #   class A
+    #     extend Ruport::MetaTools
+    #     action(:bar) { |x| x + 1 }
+    #   end
+    #
+    #   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
-
 end

data/lib/ruport/query.rb

@@ -107,7 +107,7 @@ module Ruport
     end
     
     # Grabs the result set as a Data::Table or if in raw_data mode, an array of
-    # DBI:Row objects
+    # DBI::Row objects
     def result; fetch; end
     
     # Runs the query without returning its results.

data/lib/ruport/rails/reportable.rb

@@ -1,13 +1,33 @@
 module Ruport
-  
+
+  # This module is designed to be mixed in with an ActiveRecord model
+  # to add easy conversion to ruport data structures.
+  #
+  # In the ActiveRecord Model you wish to integrate with report, add the 
+  # following line just below the class definition:
+  #
+  #   acts_as_reportable
+  #
+  # This will automatically make all the methods in this module available
+  # in the model.
   module Reportable
     
+    # Converts the models' data into a Ruport::Data::Table, then renders
+    # it using the requested plugin. If :find is specified as an option
+    # it is passed directly on to ActiveRecords find method
+    #
+    #   User.formatted_table(:pdf, :find => "age > 18")
     def formatted_table(type,options={})
       to_table(:find => options[:find],:columns => options[:columns]).as(type){ |e|
         yield(e) if block_given?
       }
     end
     
+    # Converts the models' data into a Ruport::Data::Table object
+    # If :find is supplied as an option it is passed directly on to
+    # the models find method.
+    #
+    #   data = User.to_table(:find => "age > 18")
     def to_table(options={})
       options[:columns] ||= column_names
        Ruport::Data::Table.new(
@@ -27,6 +47,8 @@ module Ruport
   end
 end
 
+# Extend rails ActiveRecord::Base class to add the option of mixing in
+# the Ruport::Reportable Module in the standard rails way
 class ActiveRecord::Base
   def self.acts_as_reportable
     extend Ruport::Reportable

data/lib/ruport/report.rb

@@ -95,12 +95,6 @@ module Ruport
     #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
@@ -259,19 +253,25 @@ module Ruport
       self.class.run(self,&block)
     end
 
+
+    # loads a CSV in from file.
+    #
+    # Example
+    #
+    # my_table = load_csv "foo.csv" #=> Data::Table
+    # my_array = load_csv "foo.csv", :as => :array #=> Array
+    #
+    # See also, Ruport::Data::Table.load
     def load_csv(file,options={})
       case options[:as]
       when :array
         a = []
-        Data::Table.load(file) { |s,r| a << r } ; a
+        Data::Table.load(file,options) { |s,r| a << r } ; a
       else
-        Data::Table.load(file)
+        Data::Table.load(file,options)
       end
     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