ruport 1.0.2 → 1.2.0

data/lib/ruport/formatter/template.rb

@@ -0,0 +1,167 @@
+# Ruport : Extensible Reporting System                                
+#
+# template.rb provides templating support for Ruby Reports.
+#
+# Copyright August 2007, Gregory Brown / Michael Milner.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+
+# This class provides templating functionality for Ruport.
+# New templates are created using the Template.create method.
+#
+# Example:
+#
+#   Ruport::Formatter::Template.create(:simple) do |t|
+#     t.page_layout = :landscape
+#     t.grouping_style = :offset
+#   end
+#
+# You can then determine how the template should be used by defining
+# an <tt>apply_template</tt> method in your formatter.
+#
+# Example:
+#
+#   class Ruport::Formatter::PDF 
+#     def apply_template
+#       options.paper_orientation = template.page_layout
+#       options.style = template.grouping_style
+#     end
+#   end
+#
+# When you're ready to render the output, you can set the :template as an
+# option for the formatter. Using the template remains optional and you can
+# still render the report without it.
+#
+# Example:
+#
+#   puts g.to_pdf(:template => :simple) #=> uses the template
+#   puts g.to_pdf                       #=> doesn't use the template
+#
+# The built-in formatters all have <tt>apply_template</tt> methods defined that
+# accept a standard set of options. Each option can be set by supplying a hash
+# with the keys/values listed in the tables below.
+#
+# Example:
+#
+#   Ruport::Formatter::Template.create(:simple) do |t|
+#     t.page_format = {
+#       :size   => "LETTER",
+#       :layout => :landscape
+#     }
+#   end
+#
+# ==== PDF Formatter Options
+#
+#   Option          Key                 Value
+# 
+#   page_format     :size               Any size supported by the :paper
+#                                       option to PDF::Writer.new
+# 
+#                   :layout             :portrait, :landscape
+# 
+#   text_format     Any available to    Corresponding values
+#                   PDF::Writer#text
+# 
+#   table_format    All attributes of   Corresponding values
+#                   PDF::SimpleTable
+# 
+#                   :column_options     - All attributes of
+#                                         PDF::SimpleTable::Column
+#                                         except :heading
+#                                       - Hash keyed by a column name, whose
+#                                         value is a hash containing any of
+#                                         the other:column_options (sets values
+#                                         for specific columns)
+#                                       - :heading => { All attributes of
+#                                         PDF::SimpleTable::Column::Heading }
+# 
+#   column_format   :alignment          :left, :right, :center, :full
+# 
+#                   :width              column width
+# 
+#   heading_format  :alignment          :left, :right, :center, :full
+# 
+#                   :bold               true or false
+# 
+#                   :title              heading title (if not set,
+#                                       defaults to column name)
+# 
+#   grouping_format :style              :inline, :justified, :separated, :offset
+#
+#
+# ==== Text Formatter Options
+# 
+#   Option          Key                 Value
+# 
+#   table_format    :show_headings      true or false
+#                   :width              Table width
+#                   :ignore_width       true or false
+# 
+#   column_format   :alignment          :center
+#                   :maximum_width      Max column width
+# 
+#   grouping_format :show_headings      true or false
+#
+#
+# ==== HTML Formatter Options
+# 
+#   Option          Key                 Value
+# 
+#   table_format    :show_headings      true or false
+# 
+#   grouping_format :style              :inline, :justified
+#                   :show_headings      true or false
+#
+#
+# ==== CSV Formatter Options
+# 
+#   Option          Key                 Value
+# 
+#   table_format    :show_headings      true or false
+# 
+#   grouping_format :style              :inline, :justified, :raw
+#                   :show_headings      true or false
+# 
+#   format_options  All options         Corresponding values
+#                   available to
+#                   FasterCSV.new
+#
+class Ruport::Formatter::Template < Ruport::Renderer::Options
+  
+  # Returns all existing templates in a hash keyed by the template names.
+  def self.templates
+    @templates ||= Hash.new 
+  end
+  
+  # Creates a new template with a name given by <tt>label</tt>.
+  #
+  # Example:
+  #
+  #   Ruport::Formatter::Template.create(:simple) do |t|
+  #     t.page_layout = :landscape
+  #     t.grouping_style = :offset
+  #   end
+  #
+  # You can inherit all the options set in a template by using the :base option
+  # and providing an existing template name to use as the base.
+  #
+  # Example:
+  #
+  #   Ruport::Formatter::Template.create(:derived, :base => :simple)
+  #
+  def self.create(label,opts={})
+    if opts[:base]
+      obj = Marshal.load(Marshal.dump(self[opts[:base]]))
+    else
+      obj = new
+    end
+    yield(obj) if block_given?
+    templates[label] = obj
+  end
+  
+  # Returns an existing template with the provided name (label).
+  def self.[](label) 
+    templates[label]
+  end
+end

data/lib/ruport/formatter/text.rb

@@ -10,9 +10,10 @@
 #
 # This is free software distributed under the same terms as Ruby 1.8
 # See LICENSE and COPYING for details.
-module Ruport           
-  # This class provides text output for Ruport's Row,Table,Group, and Grouping
-  # renderers
+module Ruport
+  
+  # This class provides text output for Ruport's Row, Table, Group, and
+  # Grouping renderers
   #
   # It handles things like automatically truncating tables that go off the
   # edge of the screen in the console, proper column alignment, and pretty
@@ -24,24 +25,24 @@ module Ruport
   #   | yes   | no     | yes         |
   #   | yes   | yes    | red snapper |
   #   | what  | the    | red snapper |
-  #   +------------------------------+
+  #   +------------------------------+ 
   #
   # === Supported Options 
   #
   # <tt>:max_col_width:</tt> Ordinal array of column widths.  Set automatically
-  # but can be overridden       
+  # but can be overridden.
   #
-  # <tt>:alignment:</tt> Defaults to left justify text and right justify numbers.
-  # centers all fields when set to :center
+  # <tt>:alignment:</tt> Defaults to left justify text and right justify
+  # numbers. Centers all fields when set to :center.
   #
-  # <tt>:table_width:</tt> Will truncate rows at this limit. 
+  # <tt>:table_width:</tt> Will truncate rows at this limit.
   #
   # <tt>:show_table_headers:</tt> Defaults to true
   #
   # <tt>:show_group_headers:</tt> Defaults to true  
   #
   # <tt>:ignore_table_width:</tt> When set to true, outputs full table without
-  # truncating it.  Useful for file output
+  # truncating it.  Useful for file output.
   class Formatter::Text < Formatter
    
     renders :text, :for => [ Renderer::Row, Renderer::Table,
@@ -51,8 +52,16 @@ module Ruport
                :show_table_headers, :show_group_headers,
                :ignore_table_width
     
+    # Hook for setting available options using a template. See the template 
+    # documentation for the available options and their format.
+    def apply_template
+      apply_table_format_template(template.table_format)
+      apply_column_format_template(template.column_format)
+      apply_grouping_format_template(template.grouping_format)
+    end
+
     # Checks to ensure the table is not empty and then calls
-    # calculate_max_col_widths
+    # calculate_max_col_widths.
     #
     def prepare_table
       raise Ruport::FormatterError, "Can't output table without " +
@@ -63,7 +72,7 @@ module Ruport
     # Uses the column names from the given Data::Table to generate a table
     # header.
     #
-    # Calls fit_to_width to truncate table heading if necessary.
+    # Calls fit_to_width to truncate the table heading if necessary.
     #
     def build_table_header
       return unless should_render_column_names?
@@ -81,7 +90,7 @@ module Ruport
     # left justified.  Can be changed to support centering of output by
     # setting options.alignment to :center
     #
-    # Uses fit_to_width to truncate table if necessary.
+    # Uses fit_to_width to truncate the table if necessary.
     #
     def build_table_body
       output << fit_to_width(hr)
@@ -107,7 +116,7 @@ module Ruport
     # left justified.  Can be changed to support centering of output by
     # setting options.alignment to :center
     #
-    # Uses fit_to_width to truncate table if necessary.
+    # Uses fit_to_width to truncate the row if necessary.
     #
     def build_row
       max_col_widths_for_row(data) unless max_col_width
@@ -179,7 +188,7 @@ module Ruport
       }.join("\n") + "\n"
     end
 
-    # determines the text widths for each column.
+    # Determines the text widths for each column.
     def calculate_max_col_widths
       # allow override
       return if max_col_width
@@ -195,7 +204,7 @@ module Ruport
       data.each { |r| max_col_widths_for_row(r) } 
     end
     
-    # used to calculate the <tt>max_col_widths</tt> array.
+    # Used to calculate the <tt>max_col_widths</tt> array.
     # Override this to tweak the automatic column size adjustments.
     def max_col_widths_for_row(row)
       options.max_col_width ||= []
@@ -205,6 +214,29 @@ module Ruport
         end
       end
     end
+    
+    private
+    
+    def apply_table_format_template(t)
+      t = t || {}
+      options.show_table_headers = t[:show_headings] unless
+        t[:show_headings].nil?
+      options.table_width = t[:width] if t[:width]
+      options.ignore_table_width = t[:ignore_width] unless
+        t[:ignore_width].nil?
+    end
+    
+    def apply_column_format_template(t)
+      t = t || {}
+      options.max_col_width = t[:maximum_width] if t[:maximum_width]
+      options.alignment = t[:alignment] if t[:alignment]
+    end
+    
+    def apply_grouping_format_template(t)
+      t = t || {}
+      options.show_group_headers = t[:show_headings] unless
+        t[:show_headings].nil?
+    end
 
   end
 end

data/lib/ruport/query.rb

@@ -196,7 +196,7 @@ module Ruport
             row = row.to_a
             row = Data::Record.new(row, :attributes => names) unless @raw_data
             yield row if block_given?
-            data << row if !block_given? || @cache_enabled
+            data << row if !block_given?
           end
         end
       end

data/lib/ruport/renderer.rb

@@ -26,11 +26,11 @@ class Ruport::Renderer
   # Structure for holding renderer options.  
   # Simplified version of HashWithIndifferentAccess
   class Options < OpenStruct  
-    # returns a Hash object.  Use this if you need methods other than []
+    # Returns a Hash object.  Use this if you need methods other than []
     def to_hash
       @table
     end            
-    # indifferent lookup of an attribute, e.g.
+    # Indifferent lookup of an attribute, e.g.
     #
     #  options[:foo] == options["foo"]
     def [](key)
@@ -50,12 +50,12 @@ class Ruport::Renderer
   end
    
   # This module provides hooks into Ruport's formatting system.
-  # It is used to implement the as() method for all of Ruport's datastructures,
-  # as well as the renders_with and renders_as_* helpers.
+  # It is used to implement the as() method for all of Ruport's data
+  # structures, as well as the renders_with and renders_as_* helpers.
   #
   # You can actually use this with any data structure, it will look for a
-  # renderable_data method to pass to the <tt>renderer</tt> you specify, 
-  # but if that is not defined, it will pass <tt>self</tt> 
+  # renderable_data(format) method to pass to the <tt>renderer</tt> you 
+  # specify, but if that is not defined, it will pass <tt>self</tt>.
   #
   # Examples:
   #
@@ -73,10 +73,10 @@ class Ruport::Renderer
   #      include Ruport::Renderer::Hooks
   #      renders_as_row
   #      attr_accessor :column_order
-  #      def renderable_data
-  #         column_order.map { |c| self[c] }
+  #      def renderable_data(format)
+  #        column_order.map { |c| self[c] }
   #      end
-  #   end       
+  #   end
   #
   #   # >> a = { :a => 1, :b => 2, :c => 3 }
   #   # >> a.column_order = [:b,:a,:c]
@@ -87,7 +87,7 @@ class Ruport::Renderer
       
       # Tells the class which renderer as() will forward to.
       #
-      # usage:
+      # Usage:
       #
       #   class MyStructure
       #     include Renderer::Hooks
@@ -95,11 +95,11 @@ class Ruport::Renderer
       #   end
       #   
       # You can also specify default rendering options, which will be used
-      # if they are not overriden by the options passed to as()
+      # if they are not overriden by the options passed to as().
       #
       #   class MyStructure
-      #      include Renderer::Hooks
-      #      renders_with CustomRenderer, :font_size => 14
+      #     include Renderer::Hooks
+      #     renders_with CustomRenderer, :font_size => 14
       #   end
       def renders_with(renderer,opts={})
         @renderer = renderer.name
@@ -137,7 +137,7 @@ class Ruport::Renderer
       
       # The class of the renderer object for the base class.
       #
-      # Example
+      # Example:
       # 
       #   >> Ruport::Data::Table.renderer
       #   => Ruport::Renderer::Table
@@ -152,11 +152,11 @@ class Ruport::Renderer
     end      
     
     # Uses the Renderer specified by renders_with to generate formatted
-    # output.  Passes the return value of the <tt>renderable_data</tt> method if
-    # the method is defined, otherwise passes <tt>self</tt> as :data
+    # output.  Passes the return value of the <tt>renderable_data(format)</tt>
+    # method if the method is defined, otherwise passes <tt>self</tt> as :data
     #
     # The remaining options are converted to a Renderer::Options object and
-    # accessible in both the renderer and formatter.
+    # are accessible in both the renderer and formatter.
     #
     #  Example:
     #
@@ -167,16 +167,17 @@ class Ruport::Renderer
         raise UnknownFormatError
       end
       self.class.renderer.render(format,
-       self.class.rendering_options.merge(options)) do |rend|
-         rend.data = respond_to?(:renderable_data) ? renderable_data : self
-         yield(rend) if block_given?  
+        self.class.rendering_options.merge(options)) do |rend|
+          rend.data =
+            respond_to?(:renderable_data) ? renderable_data(format) : self
+          yield(rend) if block_given?  
       end
     end  
   end
-
-                          
+  
+  
   module AutoRunner  #:nodoc:
-    # called automagically when the report is rendered. Uses the
+    # Called automatically when the report is rendered. Uses the
     # data collected from the earlier methods.
     def _run_
 
@@ -189,6 +190,10 @@ class Ruport::Renderer
         end
       end
 
+      if formatter.respond_to?(:apply_template) && options.template
+        formatter.apply_template  
+      end       
+
       prepare self.class.first_stage if self.class.first_stage
                 
       if formatter.respond_to?(:layout)  && options.layout != false
@@ -198,14 +203,13 @@ class Ruport::Renderer
       end
 
       finalize self.class.final_stage if self.class.final_stage
-
     end  
     
     def execute_stages
       # call each stage to build the report
       unless self.class.stages.nil?
         self.class.stages.each do |stage|
-          self.send(:build,stage)
+          maybe("build_#{stage}")
         end
       end
     end
@@ -308,7 +312,7 @@ class Ruport::Renderer
     end
      
     # Defines attribute writers for the Renderer::Options object shared
-    # between Renderer and Formatter
+    # between Renderer and Formatter.
     #
     # usage:
     #   
@@ -366,12 +370,13 @@ class Ruport::Renderer
     # sets the data and options, and then does the following process:
     #
     #   * If the renderer contains a module Helpers, mix it in to the instance.
-    #   * If a block is given, yield the Renderer instance  
-    #   * If a setup() method is defined on the Renderer, call it
-    #   * If the renderer has defined a run() method, call it, otherwise,
-    #     include Renderer::AutoRunner. (you usually won't need a run() method )
-    #   * call _run_ if it exists (This is provided by default, by AutoRunner)
-    #   * return the results of formatter.output
+    #   * If a block is given, yield the Renderer instance.
+    #   * If a setup() method is defined on the Renderer, call it.
+    #   * If the renderer has defined a run() method, call it. Otherwise,
+    #     include Renderer::AutoRunner (you usually won't need a run() method).
+    #   * Call _run_ if it exists (this is provided by default, by AutoRunner).
+    #   * If the :file option is set to a file name, appends output to the file.
+    #   * Return the results of formatter.output
     #
     # Note that the only time you will need a run() method is if you can't
     # do what you need to via a helpers module or via setup()
@@ -389,10 +394,11 @@ class Ruport::Renderer
         include AutoRunner
       end
       rend._run_ if rend.respond_to? :_run_
+      rend.formatter.save_output(rend.options.file) if rend.options.file
       return rend.formatter.output
     end
 
-    # Allows you to set class_wide default options
+    # Allows you to set class-wide default options.
     # 
     # Example:
     #  
@@ -433,7 +439,7 @@ class Ruport::Renderer
     
     # Allows you to register a format with the renderer.
     #
-    # example:
+    # Example:
     #
     #   class MyFormatter < Ruport::Formatter
     #     # formatter code ...
@@ -446,10 +452,10 @@ class Ruport::Renderer
     
   end
   
-  # The name of format being used
+  # The name of format being used.
   attr_accessor :format  
   
-  # The formatter object being used
+  # The formatter object being used.
   attr_writer :formatter  
   
   # The +data+ that has been passed to the active formatter.
@@ -477,22 +483,11 @@ class Ruport::Renderer
     options.io=obj    
   end
 
-  # When no block is given, returns active formatter.
-  #
-  # When a block is given with a block variable, sets the block variable to the
-  # formatter.  
-  #
-  # When a block is given without block variables, instance_evals the block
-  # within the context of the formatter.
+  # Returns the active formatter.
   #
+  # If a block is given, it is evaluated in the context of the formatter.
   def formatter(&block)
-    if block.nil?
-      return @formatter
-    elsif block.arity > 0
-      yield(@formatter)
-    else
-      @formatter.instance_eval(&block)
-    end
+    @formatter.instance_eval(&block) if block   
     return @formatter
   end
 
@@ -513,11 +508,6 @@ class Ruport::Renderer
     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      
@@ -530,7 +520,7 @@ class Ruport::Renderer
     formatter.options = o
   end
   
-  # selects a formatter for use by format name
+  # Selects a formatter for use by format name
   def use_formatter(format)
     self.formatter = self.class.formats[format].new
     self.formatter.format = format