ruport 0.6.1 → 0.7.0

data/lib/ruport/renderer/graph.rb

@@ -0,0 +1,48 @@
+# renderer/graph.rb
+# Generalized graphing support for Ruby Reports
+#
+# Written by Gregory Brown, Copright December 2006, All Rights Reserved.
+#
+# This is free software.  See LICENSE and COPYING for details.
+
+module Ruport
+  
+  # This class implements the basic graphing engine for Ruport.
+  #
+  # == Supported Format Plugins
+  # 
+  # * Format::XML
+  # * Format::SVG
+  #
+  # == Default layout options
+  #
+  # * height #=> 350
+  # * width  #=> 500
+  # * style  #=> :line
+  #
+  # ==  Plugin hooks called (in order)
+  # 
+  # * prepare_graph
+  # * build_graph
+  # * finalize_graph
+  class Renderer::Graph < Renderer
+
+    include Renderer::Helpers
+
+    add_formats :svg,:xml
+
+    layout do |l|
+      l.height = 350
+      l.width  = 500
+      l.style  = :line
+    end
+
+    def run
+      prepare :graph
+      build :graph
+      finalize :graph
+    end
+
+  end
+
+end

data/lib/ruport/renderer/table.rb

@@ -0,0 +1,132 @@
+# renderer/table.rb : Tabular data renderer for Ruby Reports
+#
+# Written by Gregory Brown, December 2006.  Copyright 2006, All Rights Reserved
+# This is Free Software, please see LICENSE and COPYING for details.
+
+module Ruport
+  #
+  # This module provides some additional methods for Renderer::Table that may be
+  # helpful when rendering tabular data.
+  #
+  # These methods assume you are working with Data::Table objects
+  module Renderer::TableHelpers
+
+    # Allows you to modify a column at rendering time based on a block.
+    # This will not effect the original data object you provided to the table
+    # renderer
+    #
+    # Example:
+    #
+    #   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] }
+    end
+
+    # Gets the number of columns in a table.  Useful in formatting plugins.
+    def num_cols
+      data[0].to_a.length
+    end
+
+    # Allows you to remove duplicates from data tables.
+    #
+    # By default, it will try to prune the entire table, but you may provide a
+    # limit of how many columns in it should work.
+    #
+    # Examples:
+    #
+    #   irb(main):014:0> puts a
+    #    +-----------+
+    #    | a | b | c |
+    #    +-----------+
+    #    | 1 | 2 | 3 |
+    #    | 1 | 2 | 2 |
+    #    | 1 | 3 | 5 |
+    #    | 2 | 7 | 9 |
+    #    | 2 | 8 | 3 |
+    #    | 2 | 7 | 1 |
+    #    | 1 | 7 | 9 |
+    #    +-----------+
+    #    => nil
+    #    irb(main):015:0> puts a.as(:text) { |e| e.prune(2) }
+    #    +-----------+
+    #    | a | b | c |
+    #    +-----------+
+    #    | 1 | 2 | 3 |
+    #    |   |   | 2 |
+    #    |   | 3 | 5 |
+    #    | 2 | 7 | 9 |
+    #    |   | 8 | 3 |
+    #    |   | 7 | 1 |
+    #    | 1 | 7 | 9 |
+    #    +-----------+
+    #    => nil
+    #    irb(main):016:0> puts a.as(:text) { |e| e.prune(1) }
+    #    +-----------+
+    #    | a | b | c |
+    #    +-----------+
+    #    | 1 | 2 | 3 |
+    #    |   | 2 | 2 |
+    #    |   | 3 | 5 |
+    #    | 2 | 7 | 9 |
+    #    |   | 8 | 3 |
+    #    |   | 7 | 1 |
+    #    | 1 | 7 | 9 |
+    #    +-----------+
+    def prune(limit=data[0].length)
+      require "enumerator"
+      limit.times do |field|
+        last = ""
+        data.each_cons(2) { |l,e|
+          next if field.nonzero? && e[field-1] 
+          last = l[field] if l[field]
+          e[field] = nil if e[field] == last
+        }
+      end
+    end
+
+  end
+  
+  # This class implements the basic tabular data renderer for Ruport.
+  #
+  # For a set of methods that might be helpful while working with this class,
+  # see the included TableHelpers module
+  #
+  # == Supported Format Plugins 
+  #  
+  # * Format::CSV
+  # * Format::Text
+  # * Format::HTML
+  # * Format::Latex
+  # * Format::PDF
+  #
+  # == Default layout options 
+  #  
+  # * <tt>show_table_headers</tt> #=> true
+  #
+  # == Plugin hooks called (in order)
+  #  
+  # * prepare_table
+  # * build_table_header
+  # * build_table_body
+  # * build_table_footer
+  # * finalize_table
+  #
+  class Renderer::Table < Renderer
+    include TableHelpers
+    include Renderer::Helpers
+     
+    add_formats :csv, :text, :html, :latex, :pdf
+
+    layout do |lay|
+      lay.show_table_headers = true
+    end
+    
+    def run
+      prepare :table
+      build [:header,:body,:footer], :table
+      finalize :table
+    end
+
+  end
+end

data/lib/ruport/renderer.rb

@@ -0,0 +1,193 @@
+# renderer.rb : General purpose formatted data renderer for Ruby Reports
+#
+# Copyright December 2006, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+
+# This class implements the core engine for Ruport's formatting system.  It is
+# designed to implement the low level tools necessary to build report renderers
+# for different kinds of tasks.  See Renderer::Table for a tabular data renderer
+# and Renderer::Graph for graphing support.  
+#
+# This class can easily be extended to build custom formatting engines, but if
+# you do not need that, may not be relevant to study for your use of Ruport.
+class Ruport::Renderer
+  module Helpers #:nodoc:
+    def prepare(name)
+      maybe "prepare_#{name}"
+    end
+
+    def build(names,prefix=nil)
+      return maybe("build_#{names}") if prefix.nil?
+      names.each { |n| maybe "build_#{prefix}_#{n}" }
+    end
+
+    def finalize(name)
+      maybe "finalize_#{name}"
+    end
+
+    private 
+
+    def maybe(something)
+      plugin.send something if plugin.respond_to? something
+    end
+  end
+  # allows you to register a format with the renderer.
+  #
+  # example:
+  #
+  #   class MyPlugin < Ruport::Format::Plugin
+  #
+  #     # plugin code ...
+  #
+  #     SomeRenderer.add_format self, :my_plugin
+  #
+  #   end
+  def self.add_format(format,name=nil)
+    return formats[name] = format if name
+
+    add_core_format(format)   
+ end
+
+
+  # reader for formats.  Defaults to a hash
+  def self.formats
+    @formats ||= {}
+  end
+
+  # 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?
+
+    return @layout
+  end
+
+  # creates a new instance of the renderer
+  # then looks up the formatting plugin and creates a new instance of that as
+  # well.  If a block is given, the renderer instance is yielded.
+  #
+  # 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
+    return rend.plugin.output
+  end
+
+
+  # creates a new instance of the renderer and sets it to use the specified
+  # formatting plugin (by name).  If a block is given, the renderer instance is
+  # yielded.  
+  #
+  # Returns the renderer instance.
+  def self.build(format)
+    rend = self.new
+
+    rend.send(:use_plugin,format)
+    rend.send(:layout=, layout.dup)
+    yield(rend) if block_given?
+    return rend
+  end
+
+  attr_accessor :format
+  attr_reader   :data
+
+  # Generates a layout object and passes it along to the current formatting
+  # plugin.  If the block form is used, the layout object will be yielded for
+  # modification.
+  #
+  def layout
+    @layout ||= Ruport::Layout::Component.new
+    yield(@layout) if block_given?
+
+    plugin.layout = @layout
+  end
+
+  # sets +data+ attribute on both the renderer and any active plugin
+  def data=(val)
+    @data = val.dup
+    plugin.data = @data if plugin
+  end
+
+  # General purpose openstruct which is shared with the current formatting
+  # plugin.
+  def options
+    yield(plugin.options) if block_given?
+    plugin.options
+  end
+
+  # when no block is given, returns active plugin
+  #
+  # when a block is given with a block variable, sets the block variable to the
+  # plugin.  
+  #
+  # 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 
+    elsif block.arity > 0
+      yield(@plugin)
+    else
+      @plugin.instance_eval(&block)
+    end
+    return @plugin
+  end
+
+  private
+  
+  attr_writer :plugin
+
+  #internal layout accessor.
+  def layout=(lay)
+    @layout = lay
+    plugin.layout = lay
+  end
+
+  # 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)
+    
+    klass = Ruport::Format.const_get(
+      Ruport::Format.constants.find { |c| c =~ /#{format}/i })
+    
+    formats[format] = klass
+  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}"  
+    rescue LoadError
+      nil
+    end
+  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"
+require "ruport/renderer/graph"

data/lib/ruport/report/graph.rb

@@ -2,12 +2,12 @@ module Ruport
   class Report
     module Graph #:nodoc:
       def build_graph
-        a = Ruport::Format.graph_object :plugin => :svg
+        a = Ruport::Renderer::Graph.build(:svg)
         yield(a); return a
       end
 
       def render_graph(&block)
-        build_graph(&block).render
+        build_graph(&block).run
       end
     end
   end

data/lib/ruport/report.rb

@@ -7,14 +7,14 @@
 
 #load the needed standard libraries.
 %w[erb yaml date logger fileutils].each { |lib| require lib }
-%w[invoice graph].each { |lib| require "ruport/report/"+lib }
+%w[graph].each { |lib| require "ruport/report/"+lib }
 require "forwardable"
 
 module Ruport
 
   # === Overview
   #
-  # The Ruport::Report class povides a high level interface to most of Ruport's
+  # The Ruport::Report class provides 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
@@ -72,7 +72,6 @@ module Ruport
   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
@@ -139,26 +138,15 @@ module Ruport
       options[:source] ||= @source
       options[:binding] ||= binding
       q = options[:query_obj] || Query.new(sql, options)
-      if options[:yield_type].eql?(:by_row)
+      if block_given?
         q.each { |r| yield(r) }
       elsif options[:as]
-        Format.table :data => q.result, :plugin => options[:as]
+        q.result.as(options[:as])
       else
-        block_given? ? yield(q.result) : q.result
+        q.result
       end
     end
     
-    #
-    # 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 <tt>label</tt>.
     def use_source(label)
       @source = label
@@ -169,55 +157,103 @@ module Ruport
       @mailer = label
     end
     
+    # 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.
+    #
+    def append(my_file=file)
+      File.open(my_file,"a") { |f| f << results }
+    end
+    
+    # This method passes <tt>self</tt> to Report.run.
     #
-    # Provides a nice way to execute templates and filters.
+    # 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  a file.
     #
     # Example:
     #
-    #  process_text "_<%= @some_internal_var %>_", :filters => [:erb,:red_cloth]
+    #   my_table = load_csv "foo.csv"                 #=> Data::Table
+    #   my_array = load_csv "foo.csv", :as => :array  #=> Array
     #
-    # This method automatically passes a binding into the filters, so you are
-    # free to access data from your Report instance in your templates.
+    # See also Ruport::Data::Table.load
     #
-    def process_text(string, options)
-      options[:filters].each do |f|
-        format = Format.new(binding)
-        format.content = string
-        string = format.send("filter_#{f}")
+    def load_csv(file,options={})
+      case options[:as]
+      when :array
+        a = []
+        Data::Table.load(file,options) { |s,r| a << r } ; a
+      else
+        Data::Table.load(file,options)
       end
-      string
     end
-    
+
     #
-    # This allows you to create filters to be used by process_text.
+    # Executes an erb template.  If a filename is given which matches the
+    # pattern /\.r\w+$/ (eg foo.rhtml, bar.rtxt, etc), 
+    # it will be loaded and evaluated.  Otherwise, the string will be processed
+    # directly.
     #
-    # The block is evaluated in the context of the instance.
+    # Examples:
     #
-    # Example:
+    #  @foo = 'greg'
+    #  erb "My name is <%= @foo %>" #=> "My name is greg"
     #
-    #  text_processor(:unix_newlines) { |r| r.gsub(/\r\n/,"\n") }
+    #  erb "foo.rhtml" #=> contents of evaluated text in foo.rhtml
     #
-    def text_processor(label,&block)
-      Format.register_filter(label, &block)
+    def erb(s)
+      if s =~ /\.r\w+$/
+        ERB.new(File.read(s)).result(binding)
+      else
+        ERB.new(s).result(binding)
+      end
     end
 
+    # uses RedCloth to turn a string containing textile markup into HTML.
     #
-    # 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.
+    # Example:
     #
-    def write(my_file=file,my_results=results)
-      File.open(my_file,"w") { |f| f << my_results }
+    #   textile "*bar*" #=> "<p><strong>foo</strong></p>"
+    #
+    def textile(s)
+      require "redcloth"
+      RedCloth.new(s).to_html
     end
-
+    
     #
-    # Like Report#write, but will append to a file rather than overwrite it if
-    # the file already exists.
+    # Allows logging and other fun stuff. 
+    # See also Ruport.log
     #
-    def append(my_file=file)
-      File.open(my_file,"a") { |f| f << results }
+    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.
+    #
+    def send_to(adds)
+      m = Mailer.new
+      m.to = adds
+      yield(m)
+      m.send(:select_mailer,@mailer)
+      m.deliver :from => m.from, :to => m.to
     end
-
+    
+    def_delegators Ruport::Config, :source, :mailer, :log_file, :log_file=
+    
     class << self
 
       #
@@ -252,6 +288,11 @@ module Ruport
       # 
       # Finally, it tries to call cleanup.
       #
+      # This method will return the contents of Report#results, as a single
+      # value for single reports, and an array of outputs for multiple reports.
+
+      private :prepare, :generate, :cleanup
+
       def run(options={})
         options[:reports] ||= [self.new]
 
@@ -275,62 +316,19 @@ module Ruport
         else
           process.call
         end
+
+        outs = options[:reports].map { |r| r.results }
+        if outs.length == 1
+          outs.last
+        else
+          outs
+        end
+        
       end
 
     end
 
-    #
-    # 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  a 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,options) { |s,r| a << r } ; a
-      else
-        Data::Table.load(file,options)
-      end
-    end
-    
-    #
-    # 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.
-    #
-    def send_to(adds)
-      m = Mailer.new
-      m.to = adds
-      yield(m)
-      m.send(:select_mailer,@mailer)
-      m.deliver :from => m.from, :to => m.to
-    end
-    
-    def_delegators Ruport::Config, :source, :mailer, :log_file, :log_file=
-    
   end
-
 end
 
 

data/lib/ruport/system_extensions.rb

@@ -24,7 +24,7 @@
 #  This is Free Software.  See LICENSE and COPYING for details.
 
 module Ruport
-  module SystemExtensions
+  module SystemExtensions #:nodoc:
     module_function
     
     #
@@ -57,7 +57,8 @@ module Ruport
     rescue LoadError             # If we're not on Windows try...
       # A Unix savvy method to fetch the console columns, and rows.
       def terminal_size
-       `stty size`.split.map { |x| x.to_i }.reverse
+        size = `stty size 2>/dev/null`.split.map { |x| x.to_i }.reverse
+        return $? == 0 ? size : [80,24]
       end
 
    end
@@ -66,9 +67,5 @@ module Ruport
      terminal_size.first
    end
 
-   def terminal_height
-    terminal_size.last
-   end
-
   end
 end