ruport 0.8.14 → 0.10.0

data/lib/ruport/renderer.rb

@@ -5,275 +5,319 @@
 # 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
+# This class implements the core renderer 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.  
+# for different kinds of tasks.  See Renderer::Table for a tabular data
+# renderer.  
 #
-# 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.
+# This class can easily be extended to build custom formatting systems, but if
+# you do not need that, it 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
+  class RequiredOptionNotSet < RuntimeError; end
+  class UnknownFormatError < RuntimeError; end
+  class StageAlreadyDefinedError < RuntimeError; end
+  class RendererNotSetError < RuntimeError; end
+
+  require "ostruct"
+  class Options < OpenStruct #:nodoc:
+    def to_hash
+      @table
+    end   
+    def [](key)
+      send(key)
+    end
+    def []=(key,value)
+      send("#{key}=",value)
+    end
+  end
 
-      # 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
+  module Hooks #:nodoc:
+    module ClassMethods
+      def renders_with(renderer,opts={})
+        @renderer = renderer.name
+        @rendering_options=opts
+      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
+      def rendering_options
+        @rendering_options
       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) }
+      
+      def renders_as_table(options={})
+        renders_with Ruport::Renderer::Table,options
       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
+       
+      def renders_as_row(options={})
+        renders_with Ruport::Renderer::Row, options
       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
+        
+      def renders_as_group(options={})
+        renders_with Ruport::Renderer::Group,options
+      end 
+      
+      def renders_as_grouping(options={})
+        renders_with Ruport::Renderer::Grouping,options
+      end
+
+      def renderer
+        return unless @renderer
+        @renderer.split("::").inject(Class) { |c,el| c.const_get(el) }
       end
     end
- 
+
     def self.included(base)
-      base.extend ClassMethods
-    end
+      base.extend(ClassMethods)
+    end      
+
+    def as(format,options={})
+      raise RendererNotSetError unless self.class.renderer
+      unless self.class.renderer.formats.include?(format)
+        raise UnknownFormatError
+      end
+      self.class.renderer.render(format,
+       self.class.rendering_options.merge(options)) do |rend|
+        rend.data = send(:renderable_data) rescue self
+        yield(rend) if block_given?  
+      end
+    end  
+  end
 
+                          
+  module AutoRunner  #:nodoc:
     # called automagically when the report is rendered. Uses the
     # data collected from the earlier methods.
-    def run
+    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"
+            raise RequiredOptionNotSet, "Required option #{opt} not set"
           end
         end
       end
 
       prepare self.class.first_stage if self.class.first_stage
+                
+      if formatter.respond_to?(:layout)
+        formatter.layout do execute_stages end
+      else
+        execute_stages
+      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.build stage
+          self.send(:build,stage)
         end
       end
-
-      finalize self.class.final_stage if self.class.final_stage
-
     end
+  end
+  
+  class << self
+    
+    attr_accessor :first_stage,:final_stage,:required_options,:stages #:nodoc: 
 
- 
-    def prepare(name)
-      maybe "prepare_#{name}"
+    def finalize(stage)
+      if final_stage
+        raise StageAlreadyDefinedError, 'final stage already defined'      
+      end
+      self.final_stage = stage
     end
 
-    def build(names,prefix=nil)
-      return maybe("build_#{names}") if prefix.nil?
-      names.each { |n| maybe "build_#{prefix}_#{n}" }
+    def prepare(stage)
+      if first_stage
+        raise StageAlreadyDefinedError, "prepare stage already defined"      
+      end 
+      self.first_stage = stage
     end
 
-    def finalize(name)
-      maybe "finalize_#{name}"
+    def option(*opts)
+      opts.each do |opt|
+        opt = "#{opt}="
+        define_method(opt) {|t| options.send(opt, t) } 
+      end
     end
 
-    private 
-
-    def maybe(something)
-      plugin.send something if plugin.respond_to? something
+    def required_option(*opts) 
+      self.required_options ||= []
+      opts.each do |opt|
+        self.required_options << opt 
+        option opt
+      end
     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
+    def stage(*stage_list)
+      self.stages ||= []
+      stage_list.each { |stage|
+        self.stages << stage.to_s 
+      }
+    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?
+    def formats
+      @formats ||= {}
+    end
 
-    return @layout
-  end
+    def render(*args)
+      rend = build(*args) { |r|
+        r.setup if r.respond_to? :setup
+        yield(r) if block_given?
+      }
+      if rend.respond_to? :run
+        rend.run
+      else
+        include AutoRunner
+      end
+      rend._run_ if rend.respond_to? :_run_
+      return rend.formatter.output
+    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
+    # Allows you to set class_wide default options
+    # 
+    # Example:
+    #  
+    #  options { |o| o.style = :justified }
+    #
+    def options
+      @options ||= Ruport::Renderer::Options.new
+      yield(@options) if block_given?
+
+      return @options
+    end
 
+    # Creates a new instance of the renderer and sets it to use the specified
+    # formatter (by name).  If a block is given, the renderer instance is
+    # yielded.  
+    #
+    # Returns the renderer instance.
+    #
+    def build(*args)
+      rend = self.new
+
+      rend.send(:use_formatter,args[0])
+      rend.send(:options=, options.dup)
+      if rend.class.const_defined? :Helpers
+        rend.formatter.extend(rend.class.const_get(:Helpers))
+      end
+      if args[1].kind_of?(Hash)
+        d = args[1].delete(:data)
+        rend.data = d if d
+        args[1].each {|k,v| rend.options.send("#{k}=",v) }
+      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
+      yield(rend) if block_given?
+      return rend
+    end
+    
+    private
+    
+    # Allows you to register a format with the renderer.
+    #
+    # example:
+    #
+    #   class MyFormatter < Ruport::Formatter
+    #     # formatter code ...
+    #     SomeRenderer.add_format self, :my_formatter
+    #   end
+    #
+    def add_format(format,name=nil)
+      formats[name] = format
+    end
+    
   end
 
   attr_accessor :format
-  attr_reader   :data
+  attr_writer :formatter  
 
-  # 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
+  def data
+    formatter.data
   end
 
-  # sets +data+ attribute on both the renderer and any active plugin
+  # Sets +data+ attribute on the active formatter.
   def data=(val)
-    @data = val.dup
-    plugin.data = @data if plugin
+    formatter.data = val.dup 
   end
 
-  # General purpose openstruct which is shared with the current formatting
-  # plugin.
+  # Renderer::Options object which is shared with the current formatter.
   def options
-    yield(plugin.options) if block_given?
-    plugin.options
+    yield(formatter.options) if block_given?
+    formatter.options
+  end
+  
+  # If an IO object is given, Formatter#output will use it instead of 
+  # the default String.  For Ruport's core renderers, we technically
+  # can use any object that supports the << method, but it's meant
+  # for IO objects such as File or STDOUT
+  #
+  def io=(obj)
+    options.io=obj    
   end
 
-  # when no block is given, returns active plugin
+  # 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 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 formatter.
   #
-  # when a block is given without block variables, instance_evals the block
-  # within the context of the plugin
-  def plugin(&block)
+  def formatter(&block)
     if block.nil?
-      return @plugin 
+      return @formatter
     elsif block.arity > 0
-      yield(@plugin)
+      yield(@formatter)
     else
-      @plugin.instance_eval(&block)
+      @formatter.instance_eval(&block)
     end
-    return @plugin
+    return @formatter
   end
 
-  private
+  # Provides a shortcut to render() to allow
+  # render(:csv) to become render_csv
+  #
+  def self.method_missing(id,*args,&block)
+    id.to_s =~ /^render_(.*)/
+    unless args[0].kind_of? Hash
+      args = [ (args[1] || {}).merge(:data => args[0]) ]
+    end
+    $1 ? render($1.to_sym,*args,&block) : super
+  end
   
-  attr_writer :plugin
+  private  
 
-  #internal layout accessor.
-  def layout=(lay)
-    @layout = lay
-    plugin.layout = lay
+  def prepare(name)
+    maybe "prepare_#{name}"
   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
+  def build(names,prefix=nil)
+    return maybe("build_#{names}") if prefix.nil?
+    names.each { |n| maybe "build_#{prefix}_#{n}" }
   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
+  def finalize(name)
+    maybe "finalize_#{name}"
+  end      
+  
+  def maybe(something)
+    formatter.send something if formatter.respond_to? something
+  end    
 
-  # selects a plugin for use by format name
-  def use_plugin(format)
-    self.plugin = self.class.formats[format].new
+  def options=(o)
+    formatter.options = o
   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
+  
+  # selects a formatter for use by format name
+  def use_formatter(format)
+    self.formatter = self.class.formats[format].new
+    self.formatter.format = format
   end
 
 end
 
 require "ruport/renderer/table"
-require "ruport/renderer/graph"
+require "ruport/renderer/grouping"