ruport 0.10.0 → 0.11.0

data/lib/ruport/formatter/text.rb

@@ -1,11 +1,55 @@
-module Ruport
+# Ruport : Extensible Reporting System                                
+#
+# formatter/text.rb provides text formatting for Ruport.
+#     
+# Created by Gregory Brown, some time around Spring 2006.
+# Copyright (C) 2006-2007, All Rights Reserved.  
+#
+# Mathijs Mohlmann and Marshall T. Vandegrift have provided some patches for
+# this class, see AUTHORS file for details.
+#
+# 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
+  #
+  # It handles things like automatically truncating tables that go off the
+  # edge of the screen in the console, proper column alignment, and pretty
+  # output that looks something like this:
+  #
+  #   +-----------------------------+
+  #   | apple | banana | strawberry |
+  #   +-----------------------------+
+  #   | yes   | no     | yes        |
+  #   | yes   | yes    | god yes    |
+  #   | what  | the    | f?         |
+  #   +-----------------------------+ 
+  #
+  # === Supported Options 
+  #
+  # <tt>:max_col_width:</tt> Ordinal array of column widths.  Set automatically
+  # but can be overridden       
+  #
+  # <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>: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
   class Formatter::Text < Formatter
    
     renders :text, :for => [ Renderer::Row, Renderer::Table,
                              Renderer::Group, Renderer::Grouping ]
 
     opt_reader :max_col_width, :alignment, :table_width, 
-               :show_table_headers, :show_group_headers
+               :show_table_headers, :show_group_headers,
+               :ignore_table_width
     
     # Checks to ensure the table is not empty and then calls
     # calculate_max_col_widths
@@ -47,13 +91,22 @@ module Ruport
         rend.options do |o|
           o.max_col_width = max_col_width
           o.alignment     = alignment
-          o.table_width   = table_width
+          o.table_width   = table_width   
+          o.ignore_table_width = ignore_table_width
         end
       end
 
       output << fit_to_width(hr)
     end
-
+    
+    # Generates a formatted text row. 
+    #
+    # Defaults to numeric values being right justified, and other values being
+    # 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.
+    #
     def build_row
       max_col_widths_for_row(data) unless max_col_width
 
@@ -113,7 +166,8 @@ module Ruport
     end
 
     # Truncates a string so that it does not exceed Text#width
-    def fit_to_width(s)
+    def fit_to_width(s)      
+      return s if options.ignore_table_width
       # workaround for Rails setting terminal_width to 1
       max_width = width < 2 ? 80 : width
       
@@ -137,7 +191,9 @@ module Ruport
           
       data.each { |r| max_col_widths_for_row(r) } 
     end
-
+    
+    # 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 ||= []
       row.each_with_index do |f,i|

data/lib/ruport/query.rb

@@ -1,3 +1,15 @@
+# Ruport : Extensible Reporting System                                
+#
+# query.rb provides a basic wrapper around RubyDBI for SQL interaction
+#
+# Original work began by Gregory Brown based on ideas from James Edward Gray II
+# in August, 2005.
+#
+# Copyright (C) 2005-2007, Gregory Brown
+# All Rights Reserved.   
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.
 require "generator"
 require "ruport/query/sql_split"
 
@@ -5,17 +17,18 @@ module Ruport
   
   # === Overview
   # 
-  # Query offers a way to interact with databases via DBI. It supports
-  # returning result sets in either Ruport's native Data::Table, or in their 
+  # Query offers a way to interact with databases via RubyDBI. It supports
+  # returning result sets in either Ruport's Data::Table, or in their 
   # raw form as DBI::Rows.
   #
-  # It offers basic caching support, the ability to instantiate a generator 
-  # for a result set, and the ability to quickly and easily swap between data
-  # sources.
+  # Query allows you to treat your result sets as an Enumerable data structure
+  # that plays well with the rest of Ruport.
+  #
+  # If you are using ActiveRecord, you might prefer our acts_as_reportable
+  # extension.       
   #
   class Query 
-    
-    
+       
     include Enumerable
     
     # Ruport::Query provides an interface for dealing with raw SQL queries.
@@ -33,12 +46,8 @@ module Ruport
     #                                   be set with this option.
     # <b><tt>:password</tt></b>::       If a DSN is specified, the password 
     #                                   can be set with this option.
-    # <b><tt>:raw_data</tt></b>::       When set to true, DBI::Rows will be 
-    #                                   returned instead of a Data::Table.
-    # <b><tt>:cache_enabled</tt></b>::  When set to true, Query will download 
-    #                                   results only once, and then return 
-    #                                   cached values until the cache has been 
-    #                                   cleared.
+    # <b><tt>:row_type</tt></b>::       When set to :raw, DBI::Rows will be 
+    #                                   returned instead of a Data::Table
     #
     # Examples:
     #   
@@ -56,12 +65,19 @@ module Ruport
     #   Ruport::Query.new("my_query.sql")
     #
     #   # explicitly use a file, even if it doesn't end in .sql
-    #   Ruport::Query.new("foo",:origin => :file)
+    #   Ruport::Query.new(:file => "foo")
     #
-    def initialize(sql, options={})
-      options = { :source => :default, :origin => :string }.merge(options)
-      options[:origin] = :file if sql =~ /.sql$/
-      @statements = SqlSplit.new(get_query(options[:origin],sql))
+    def initialize(sql, options={})   
+      if sql.kind_of?(Hash)  
+        options = { :source => :default }.merge(sql)   
+        sql = options[:file] || options[:string]
+      else 
+        options = { :source => :default, :string => sql }.merge(options)
+        options[:file] = sql if sql =~ /.sql$/    
+      end                                                 
+      origin = options[:file] ? :file : :string      
+      
+      @statements = SqlSplit.new(get_query(origin,sql))
       @sql = @statements.join
       
       if options[:dsn]
@@ -76,28 +92,43 @@ module Ruport
       @raw_data = options[:row_type].eql?(:raw)
       @params = options[:params]
     end
-
+     
+    # Returns an OpenStruct with the configuration options for the default
+    # database source.
+    #
     def self.default_source
       sources[:default]
     end
-
+     
+    # Returns a hash of database sources, keyed by label.
     def self.sources
       @sources ||= {}
     end
-
+    
+    # Allows you to add a labeled DBI source configuration. 
+    #
+    # Query objects will use the source labeled <tt>:default</tt>,
+    # unless another source is specified.
+    #
+    # Examples:
+    #
+    #   # a connection to a MySQL database foo with user root, pass chunkybacon
+    #   Query.add_source :default, :dsn => "dbi:mysql:foo", 
+    #                              :user => "root",
+    #                              :password => "chunkybacon"
+    #
+    #
+    #   # a second connection to a MySQL database bar
+    #   Query.add_source :test, :dsn => "dbi:mysql:bar",
+    #                           :user => "tester",
+    #                           :password => "blinky" 
+    #
+    # 
     def self.add_source(name,options={})
       sources[name] = OpenStruct.new(options)
       check_source(sources[name],name)
     end
 
-    private
-
-    def self.check_source(settings,label) # :nodoc:
-      raise ArgumentError unless settings.dsn
-    end
-
-    public
-
     attr_accessor :raw_data
     
     # The original SQL for the Query object
@@ -112,20 +143,20 @@ module Ruport
       @password = Ruport::Query.sources[label].password
     end 
     
+    # Yields result set by row.
     def each(&action)
       raise(LocalJumpError, "No block given!") unless action
       fetch(&action)
       self
     end
     
+    # Runs the SQL query and returns the result set 
     def result; fetch; end
     
     # Runs the query without returning its results.
     def execute; fetch; nil; end
     
     # Returns a Data::Table, even if in <tt>raw_data</tt> mode.
-    # This doesn't work with raw data if the cache is enabled and filled.
-    #
     def to_table
       data_flag, @raw_data = @raw_data, false
       data = fetch; @raw_data = data_flag; return data
@@ -176,14 +207,6 @@ module Ruport
       type.eql?(:file) ? load_file( query ) : query
     end
     
-    def load_file(query_file)
-      begin
-        File.read( query_file ).strip
-      rescue
-        raise LoadError, "Could not open #{query_file}"
-      end
-    end
-    
     def fetch(&block)
       data = nil
       final = @statements.size - 1
@@ -192,5 +215,18 @@ module Ruport
       end
       return data
     end
+    
+    def load_file(query_file)
+      begin
+        File.read( query_file ).strip
+      rescue
+        raise LoadError, "Could not open #{query_file}"
+      end
+    end
+
+    def self.check_source(settings,label) # :nodoc:
+      raise ArgumentError unless settings.dsn
+    end
+    
   end
 end

data/lib/ruport/renderer.rb

@@ -13,62 +13,156 @@
 # 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
-
-  class RequiredOptionNotSet < RuntimeError; end
-  class UnknownFormatError < RuntimeError; end
-  class StageAlreadyDefinedError < RuntimeError; end
-  class RendererNotSetError < RuntimeError; end
-
-  require "ostruct"
-  class Options < OpenStruct #:nodoc:
+  
+  class RequiredOptionNotSet < RuntimeError #:nodoc:
+  end
+  class UnknownFormatError < RuntimeError #:nodoc:
+  end
+  class StageAlreadyDefinedError < RuntimeError #:nodoc: 
+  end
+  class RendererNotSetError < RuntimeError #:nodoc:
+  end
+                                          
+  require "ostruct"              
+  
+  # Structure for holding renderer options.  
+  # Simplified version of HashWithIndifferentAccess
+  class Options < OpenStruct  
+    # returns a Hash object.  Use this if you need methods other than []
     def to_hash
       @table
-    end   
+    end            
+    # indifferent lookup of an attribute, e.g.
+    #
+    #  options[:foo] == options["foo"]
     def [](key)
       send(key)
-    end
+    end 
+    
+    # Sets an attribute, with indifferent access.
+    #  
+    #  options[:foo] = "bar"  
+    #
+    #  options[:foo] == options["foo"] #=> true
+    #  options["foo"] == options.foo #=> true
+    #  options.foo #=> "bar"
     def []=(key,value)
       send("#{key}=",value)
     end
   end
-
-  module Hooks #:nodoc:
-    module ClassMethods
+   
+  # 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.
+  #
+  # 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> 
+  #
+  # Examples:
+  #
+  #   # Render Arrays with Ruport's Row Renderer
+  #   class Array
+  #     include Ruport::Renderer::Hooks
+  #     renders_as_row
+  #   end
+  #
+  #   # >> [1,2,3].as(:csv) 
+  #   # => "1,2,3\n" 
+  #
+  #   # Render Hashes with Ruport's Row Renderer
+  #   class Hash
+  #      include Ruport::Renderer::Hooks
+  #      renders_as_row
+  #      attr_accessor :column_order
+  #      def renderable_data
+  #         column_order.map { |c| self[c] }
+  #      end
+  #   end       
+  #
+  #   # >> a = { :a => 1, :b => 2, :c => 3 }
+  #   # >> a.column_order = [:b,:a,:c]
+  #   # >> a.as(:csv)
+  #   # => "2,1,3\n"
+  module Hooks 
+    module ClassMethods 
+      
+      # Tells the class which renderer as() will forward to.
+      #
+      # usage:
+      #
+      #   class MyStructure
+      #     include Renderer::Hooks
+      #     renders_with CustomRenderer
+      #   end
+      #   
+      # You can also specify default rendering options, which will be used
+      # if they are not overriden by the options passed to as()
+      #
+      #   class MyStructure
+      #      include Renderer::Hooks
+      #      renders_with CustomRenderer, :font_size => 14
+      #   end
       def renders_with(renderer,opts={})
         @renderer = renderer.name
         @rendering_options=opts
       end  
-
+      
+      # The default rendering options for a class, stored as a hash.
       def rendering_options
         @rendering_options
       end
-      
+       
+      # Shortcut for renders_with(Ruport::Renderer::Table), you
+      # may wish to override this if you build a custom table renderer.
       def renders_as_table(options={})
         renders_with Ruport::Renderer::Table,options
       end
-       
+      
+      # Shortcut for renders_with(Ruport::Renderer::Row), you
+      # may wish to override this if you build a custom row renderer. 
       def renders_as_row(options={})
         renders_with Ruport::Renderer::Row, options
       end
-        
+      
+      # Shortcut for renders_with(Ruport::Renderer::Group), you
+      # may wish to override this if you build a custom group renderer.  
       def renders_as_group(options={})
         renders_with Ruport::Renderer::Group,options
       end 
       
+      # Shortcut for renders_with(Ruport::Renderer::Grouping), you
+      # may wish to override this if you build a custom grouping renderer.
       def renders_as_grouping(options={})
         renders_with Ruport::Renderer::Grouping,options
       end
-
+      
+      # The class of the renderer object for the base class.
+      #
+      # Example
+      # 
+      #   >> Ruport::Data::Table.renderer
+      #   => Ruport::Renderer::Table
       def renderer
         return unless @renderer
         @renderer.split("::").inject(Class) { |c,el| c.const_get(el) }
       end
     end
 
-    def self.included(base)
+    def self.included(base) #:nodoc:
       base.extend(ClassMethods)
     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
+    #
+    # The remaining options are converted to a Renderer::Options object and
+    # accessible in both the renderer and formatter.
+    #
+    #  Example:
+    #
+    #    table.as(:csv, :show_table_headers => false)
     def as(format,options={})
       raise RendererNotSetError unless self.class.renderer
       unless self.class.renderer.formats.include?(format)
@@ -122,28 +216,125 @@ class Ruport::Renderer
   class << self
     
     attr_accessor :first_stage,:final_stage,:required_options,:stages #:nodoc: 
-
+    
+    # Registers a hook to look for in the Formatter object when the render()
+    # method is called.                           
+    #
+    # Usage:
+    #
+    #   class MyRenderer < Ruport::Renderer
+    #      # other details omitted...
+    #      finalize :apple
+    #   end
+    #
+    #   class MyFormatter < Ruport::Formatter
+    #      renders :example, :for => MyRenderer
+    # 
+    #      # other details omitted... 
+    #    
+    #      def finalize_apple
+    #         # this method will be called when MyRenderer tries to render
+    #         # the :example format
+    #      end
+    #   end  
+    #
+    #  If a formatter does not implement this hook, it is simply ignored.
     def finalize(stage)
       if final_stage
         raise StageAlreadyDefinedError, 'final stage already defined'      
       end
       self.final_stage = stage
     end
-
+    
+    # Registers a hook to look for in the Formatter object when the render()
+    # method is called.                           
+    #
+    # Usage:
+    #
+    #   class MyRenderer < Ruport::Renderer
+    #      # other details omitted...
+    #      prepare :apple
+    #   end
+    #
+    #   class MyFormatter < Ruport::Formatter
+    #      renders :example, :for => MyRenderer
+    #
+    #      def prepare_apple
+    #         # this method will be called when MyRenderer tries to render
+    #         # the :example format
+    #      end        
+    #      
+    #      # other details omitted...
+    #   end  
+    #
+    #  If a formatter does not implement this hook, it is simply ignored.
     def prepare(stage)
       if first_stage
         raise StageAlreadyDefinedError, "prepare stage already defined"      
       end 
       self.first_stage = stage
     end
-
+    
+    # Registers hooks to look for in the Formatter object when the render()
+    # method is called.                           
+    #
+    # Usage:
+    #
+    #   class MyRenderer < Ruport::Renderer
+    #      # other details omitted...
+    #      stage :apple,:banana
+    #   end
+    #
+    #   class MyFormatter < Ruport::Formatter
+    #      renders :example, :for => MyRenderer
+    #
+    #      def build_apple
+    #         # this method will be called when MyRenderer tries to render
+    #         # the :example format
+    #      end 
+    #   
+    #      def build_banana
+    #         # this method will be called when MyRenderer tries to render
+    #         # the :example format
+    #      end    
+    #      
+    #      # other details omitted...
+    #   end  
+    #
+    #  If a formatter does not implement these hooks, they are simply ignored.          
+    def stage(*stage_list)
+      self.stages ||= []
+      stage_list.each { |stage|
+        self.stages << stage.to_s 
+      }
+    end
+     
+    # Defines attribute writers for the Renderer::Options object shared
+    # between Renderer and Formatter
+    #
+    # usage:
+    #   
+    #   class MyRenderer < Ruport::Renderer
+    #      option :font_size, :font_style
+    #      # other details omitted
+    #   end
     def option(*opts)
       opts.each do |opt|
         opt = "#{opt}="
         define_method(opt) {|t| options.send(opt, t) } 
       end
     end
-
+    
+    # Defines attribute writers for the Renderer::Options object shared
+    # between Renderer and Formatter. Will throw an error if the user does
+    # not provide values for these options upon rendering.
+    #
+    # usage:
+    #   
+    #   class MyRenderer < Ruport::Renderer
+    #      required_option :employee_name, :address
+    #      # other details omitted
+    #   end
     def required_option(*opts) 
       self.required_options ||= []
       opts.each do |opt|
@@ -151,18 +342,38 @@ class Ruport::Renderer
         option opt
       end
     end
+    
 
-    def stage(*stage_list)
-      self.stages ||= []
-      stage_list.each { |stage|
-        self.stages << stage.to_s 
-      }
-    end
-
+    # Lists the formatters that are currently registered on a renderer,
+    # as a hash keyed by format name.
+    #
+    # Example:
+    # 
+    #   >> Ruport::Renderer::Table.formats
+    #   => {:html=>Ruport::Formatter::HTML, 
+    #   ?>  :csv=>Ruport::Formatter::CSV, 
+    #   ?>  :text=>Ruport::Formatter::Text, 
+    #   ?>  :pdf=>Ruport::Formatter::PDF}
     def formats
       @formats ||= {}
     end
-
+    
+    # Builds up a renderer object, looks up the appropriate formatter,
+    # 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 setup() method is defined on the Renderer, call it
+    #   * If a block is given, yield the Renderer instance
+    #   * 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
+    #
+    # 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()
+    #
+    # Please see the examples/ directory for custom renderer examples, because
+    # this is not nearly as complicated as it sounds in most cases.
     def render(*args)
       rend = build(*args) { |r|
         r.setup if r.respond_to? :setup
@@ -230,10 +441,14 @@ class Ruport::Renderer
     end
     
   end
-
-  attr_accessor :format
+  
+  # The name of format being used
+  attr_accessor :format  
+  
+  # The formatter object being used
   attr_writer :formatter  
-
+  
+  # The +data+ that has been passed to the active formatter.
   def data
     formatter.data
   end