ruport 0.10.0 → 0.11.0

data/LICENSE

@@ -1,13 +1,59 @@
-= License Terms
+Ruport is copyrighted free software originally produced by Gregory Brown 
+<gregory.t.brown@gmail.com> which now contains a number of community
+contributions and is actively developed by Michael Milner <mikem836@gmail.com>.
 
-Distributed by Gregory Brown under the user's choice* of the 
-{GPL version 2}[http://www.gnu.org/copyleft/gpl.html] (see COPYING for details)
-or the {Ruby software license}[http://www.ruby-lang.org/en/LICENSE.txt].
+See the AUTHORS file for a complete list of contributors.  
 
-Please email Greg[mailto:gregory.t.brown_AT_gmail.com] with any questions.
+Licensing terms follow (License of Ruby 1.8):
 
-*Note:  This license refers specifically to GPLv2.
-Distributing under other versions of the GPL require explicit permission from
-Gregory Brown.  Though we will most likely adopt the GPLv3 when the final draft
-is published, we want to be able to make that decision for ourselves.
+You can redistribute Ruport and/or modify it under either the terms of the GPL
+(see COPYING file), or the conditions below:
 
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+    modifications to Usenet or an equivalent medium, or by allowing
+    the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+    with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+    together with instructions (in the manual page or equivalent)
+    on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+    the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial). 
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/Rakefile

@@ -3,7 +3,7 @@ require "rake/testtask"
 require "rake/gempackagetask"
 
 
-RUPORT_VERSION = "0.10.0"
+RUPORT_VERSION = "0.11.0"
 
 begin
   require "rubygems"
@@ -25,12 +25,10 @@ spec = Gem::Specification.new do |spec|
   spec.platform = Gem::Platform::RUBY
   spec.summary = "A generalized Ruby report generation and templating engine."
   spec.files =  Dir.glob("{examples,lib,test,bin,util/bench}/**/**/*") +
-                      ["Rakefile", "setup.rb"]
+                      ["Rakefile"]
   spec.require_path = "lib"
   
   spec.test_files = Dir[ "test/*_test.rb" ]
-  spec.bindir = "bin"
-  spec.executables = FileList["rope"]
   spec.has_rdoc = true
   spec.extra_rdoc_files = %w{README LICENSE AUTHORS}
   spec.rdoc_options << '--title' << 'Ruport Documentation' <<
@@ -41,7 +39,7 @@ spec = Gem::Specification.new do |spec|
   spec.author = "Gregory Brown"
   spec.email = "  gregory.t.brown@gmail.com"
   spec.rubyforge_project = "ruport"
-  spec.homepage = "http://code.rubyreports.org"
+  spec.homepage = "http://rubyreports.org"
   spec.description = <<END_DESC
   Ruby Reports is a software library that aims to make the task of reporting
   less tedious and painful. It provides tools for data acquisition,

data/examples/line_plotter.rb

@@ -31,6 +31,9 @@ class SVG < Ruport::Formatter
   def initialize
     require "builder"
     @builder = Builder::XmlMarkup.new(:indent => 2)
+  rescue LoadError
+    STDERR.puts "You need Builder to run this example:\ngem install builder"
+    exit
   end
 
   def render_plot

data/examples/pdf_complex_report.rb

@@ -1,4 +1,3 @@
-require 'rubygems'
 require "ruport"
 
 module MyStuff

data/examples/pdf_report_with_common_base.rb

@@ -0,0 +1,72 @@
+########################################################
+# This example shows how to build custom PDF output
+# with Ruport that shares some common elements 
+# between reports.  Basically, CompanyPDFBase implements
+# some default rendering options, and derived classes
+# such as ClientPDF would implement the stuff specific
+# to a given report.
+########################################################
+
+require "active_support"
+require "ruport"
+
+# This looks a little more messy than usual, but it addresses your
+# concern of wanting to have a standard template.
+#
+class ClientRenderer < Ruport::Renderer
+ prepare :standard_report
+ stage :company_header, :client_header, :client_body, :client_footer
+ finalize :standard_report
+ option :example
+
+ def setup
+    # replace this with your header changing code
+    data.rename_columns { |c| c.to_s.titleize }
+    # this just lets us omit the options prefix in the formatter
+    formatter.class.opt_reader(:example)
+ end
+end
+
+# This defines your base PDF output, you'd do similar for other
+# formats if needed It doesn't do much of anything except 
+# implement the common hooks
+class CompanyPDFBase < Ruport::Formatter::PDF
+ def prepare_standard_report
+    options.paper_size = "A4"
+ end
+
+ def build_company_header
+    add_text "This would be my company header",
+             :justification => :center, :font_size => 14
+ end
+
+ def finalize_standard_report
+   render_pdf
+ end
+end
+
+#  This is your report's formatter
+#
+#  It implements the remaining hooks the standard formatter didn't
+#  Notice I left out a footer and it didn't complain. 
+class ClientPDF < CompanyPDFBase
+ renders :pdf, :for => ClientRenderer
+
+ def build_client_header
+   pad(10) do
+    add_text "Specific Report Header with option #{example}",
+             :justification => :center, :font_size => 12
+   end
+ end
+
+ def build_client_body
+    draw_table(data, :width => 300)
+ end
+
+end
+
+
+table = Table([:a,:b,:c]) << [1,2,3] << [4,5,6]
+File.open("example.pdf","w") { |f|
+ f << ClientRenderer.render_pdf(:data => table,:example => "foo")
+}

data/examples/pdf_styles.rb

@@ -0,0 +1,16 @@
+require "ruport"
+require "rubygems"   
+
+class MyReport < Ruport::Report
+  renders_as_grouping
+  
+  def generate
+    table = Table(%w[a b c]) << [1,2,3] << [4,5,6] << [1,7,9]
+    Grouping(table,:by => "a")
+  end
+end
+
+a = MyReport.new(:pdf) 
+[:justified, :separated, :inline, :offset].each do |style|
+  a.run(:style => style) { |r| r.write("#{style}.pdf") } 
+end

data/examples/simple_pdf_lines.rb

@@ -1,4 +1,3 @@
-require 'rubygems'
 require "ruport"
 
 class SimpleLines < Ruport::Renderer

data/lib/ruport.rb

@@ -10,9 +10,12 @@
 # See LICENSE and COPYING for details
 #
 
-module Ruport
+module Ruport #:nodoc:#
   
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"   
+  
+  class FormatterError < RuntimeError #:nodoc:
+  end
   
   # SystemExtensions lovingly ganked from HighLine 1.2.1
   #
@@ -79,69 +82,6 @@ module Ruport
 
   end
 
-  require 'timeout'
-
-  class Attempt # :nodoc:
-    VERSION = '0.1.0'
-
-    # Number of attempts to make before failing.  The default is 3.
-    attr_accessor :tries
-
-    # Number of seconds to wait between attempts.  The default is 60.
-    attr_accessor :interval
-
-    # a level which ruport understands.  
-    attr_accessor :log_level
-
-    # If set, this increments the interval with each failed attempt by that
-    # number of seconds.
-    attr_accessor :increment
-
-    # If set, the code block is further wrapped in a timeout block.
-    attr_accessor :timeout
-
-    # Determines which exception level to check when looking for errors to
-    # retry.  The default is 'Exception' (i.e. all errors).
-    attr_accessor :level
-
-    # :call-seq:
-    #    Attempt.new{ |a| ... }
-    # 
-    # Creates and returns a new +Attempt+ object.  Use a block to set the
-    # accessors.
-    # 
-    def initialize           
-      @tries     = 3         # Reasonable default
-      @interval  = 60        # Reasonable default
-      @increment = nil       # Should be an int, if provided
-      @timeout   = nil       # Wrap the code in a timeout block if provided
-      @level     = Exception # Level of exception to be caught
-      
-      yield self if block_given?
-    end
-
-    def attempt
-      count = 1
-      begin
-         if @timeout
-            Timeout.timeout(@timeout){ yield }
-         else
-            yield
-         end
-      rescue @level => error
-         @tries -= 1
-         if @tries > 0
-            msg = "Error on attempt # #{count}: #{error}; retrying"
-            count += 1
-            @interval += @increment if @increment
-            sleep @interval
-            retry
-         end
-         raise
-      end
-    end
-  end
-
 
 end
 
@@ -161,7 +101,6 @@ end
 require "enumerator"
 require "ruport/renderer" 
 require "ruport/data" 
-require "ruport/report"  
 require "ruport/formatter" 
 require "ruport/query" 
 

data/lib/ruport/acts_as_reportable.rb

@@ -1,16 +1,49 @@
+# Ruport : Extensible Reporting System                                
+#
+# acts_as_reportable.rb provides ActiveRecord integration for Ruport.
+#     
+# Originally created by Dudley Flanders, 2006
+# Revised and updated by Michael Milner, 2007     
+# Copyright (C) 2006-2007 Dudley Flanders / Michael Milner, All Rights Reserved.  
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.   
+#
 require "ruport"
 quiet { require "active_record" }
 
 module Ruport
   
-  # This module is designed to be mixed in with an ActiveRecord model
-  # to add easy conversion to Ruport's data structures.
+  # === Overview
+  # 
+  # This module is designed to allow an ActiveRecord model to be converted to
+  # Ruport's data structures.  If ActiveRecord is available when Ruport is
+  # loaded, this module will be automatically mixed into ActiveRecord::Base.
+  #
+  # Add the acts_as_reportable call to the model class that you want to
+  # integrate with Ruport:
+  #
+  #   class Book < ActiveRecord::Base
+  #     acts_as_reportable
+  #     belongs_to :author
+  #   end
+  #
+  # Then you can use the <tt>report_table</tt> method to get data from the
+  # model using ActiveRecord.
+  #
+  #   Book.report_table(:all, :include => :author)
+  #
   module Reportable
     
-    def self.included(base) # :nodoc:
+    def self.included(base) #:nodoc:
       base.extend ClassMethods  
     end
     
+    # === Overview
+    # 
+    # This module contains class methods that will automatically be available
+    # to ActiveRecord models.
+    #
     module ClassMethods 
       
       # In the ActiveRecord model you wish to integrate with Ruport, add the 
@@ -18,12 +51,24 @@ module Ruport
       #
       #   acts_as_reportable
       #
-      # This will automatically make all the methods in this module available
-      # in the model.
+      # Available options:
       #
-      # You may pass the acts_as_reportable method the :only, :except,
-      # :methods, and :include options.  See report_table for the format
-      # of these options.
+      # <b><tt>:only</tt></b>::     an attribute name or array of attribute
+      #                             names to include in the results, other
+      #                             attributes will be excuded.
+      # <b><tt>:except</tt></b>::   an attribute name or array of attribute
+      #                             names to exclude from the results.
+      # <b><tt>:methods</tt></b>::  a method name or array of method names
+      #                             whose result(s) will be included in the
+      #                             table.
+      # <b><tt>:include</tt></b>::  an associated model or array of associated
+      #                             models to include in the results.
+      #
+      # Example:
+      # 
+      #   class Book < ActiveRecord::Base
+      #     acts_as_reportable, :only => 'title', :include => :author
+      #   end
       #
       def acts_as_reportable(options = {})
         cattr_accessor :aar_options, :aar_columns
@@ -35,51 +80,68 @@ module Ruport
       end
     end
     
+    # === Overview
+    # 
+    # This module contains methods that will be made available as singleton
+    # class methods to any ActiveRecord model that calls
+    # <tt>acts_as_reportable</tt>.
+    #
     module SingletonMethods
       
       # Creates a Ruport::Data::Table from an ActiveRecord find. Takes 
-      # parameters just like a regular find. If you use the :include 
-      # option, it will return a table with all columns from the model and 
-      # the included associations. If you use the :only option, it will
-      # return a table with only the specified columns. If you use the
-      # :except option, it will return a table with all columns except
-      # those specified.
-      # 
-      # Options may be passed to the :include option in order to specify
-      # the output for any associated models. In this case, the :include
-      # option must be a hash, where the keys are the names of the
-      # associations and the values are hashes of options.
+      # parameters just like a regular find.
       #
-      # Use the :methods option to include a column with the same name as
-      # the method and the value resulting from calling the method on the
-      # model object.
+      # Additional options include:
+      #
+      # <b><tt>:only</tt></b>::     an attribute name or array of attribute
+      #                             names to include in the results, other
+      #                             attributes will be excuded.
+      # <b><tt>:except</tt></b>::   an attribute name or array of attribute
+      #                             names to exclude from the results.
+      # <b><tt>:methods</tt></b>::  a method name or array of method names
+      #                             whose result(s) will be included in the
+      #                             table.
+      # <b><tt>:include</tt></b>::  an associated model or array of associated
+      #                             models to include in the results.
+      #
+      # The same set of options may be passed to the :include option in order to
+      # specify the output for any associated models. In this case, the
+      # :include option must be a hash, where the keys are the names of the
+      # associations and the values are hashes of options.
       #
       # Any options passed to report_table will disable the options set by
       # the acts_as_reportable class method.
       #
       # Example:
       # 
-      # class Book < ActiveRecord::Base
-      #   belongs_to :author
-      #   acts_as_reportable
-      # end
+      #   class Book < ActiveRecord::Base
+      #     belongs_to :author
+      #     acts_as_reportable
+      #   end
       #
-      # Book.report_table(:all, :only => ['title'],
-      #   :include => { :author => { :only => 'name' } }).as(:html)
+      #   Book.report_table(:all, :only => ['title'],
+      #     :include => { :author => { :only => 'name' } }).as(:html)
       #
-      # Returns: an html version of a report with two columns, title from 
+      # Returns:
+      #
+      # an html version of the table with two columns, title from 
       # the book, and name from the associated author.
       #
-      # Calling Book.report_table(:all, :include => [:author]).as(:html) will 
-      # return a table with all columns from books and authors.
+      # Example:
+      # 
+      #   Book.report_table(:all, :include => :author).as(:html)
+      #
+      # Returns:
+      #
+      # an html version of the table with all columns from books and authors.
       #
       # Note: column names for attributes of included models will be qualified
-      #       with the model's underscored class name, e.g. 'author.name'
-      #       By default, this will not preserve the entire namespace, but you
-      #       can get the fully qualified namespace by using the
-      #       :preserve_namespace => true option to report_table.  So if the
-      #       Author model was enclosed in a module called MyModule, you'd
-      #       get 'my_module/author.name' as the column name. 
+      # with the model's underscored class name, e.g. 'author.name'
+      # By default, this will not preserve the entire namespace, but you
+      # can get the fully qualified namespace by using the
+      # :preserve_namespace => true option to report_table.  So if the
+      # Author model was enclosed in a module called MyModule, you'd
+      # get 'my_module/author.name' as the column name. 
       #
       def report_table(number = :all, options = {})
         only = options.delete(:only)
@@ -105,12 +167,12 @@ module Ruport
       
       private
       
-      def get_include_for_find(report_option) #:nodoc:
+      def get_include_for_find(report_option)
         includes = report_option.blank? ? aar_options[:include] : report_option
         includes.is_a?(Hash) ? includes.keys : includes
       end
       
-      def normalize_column_names(table) #:nodoc:
+      def normalize_column_names(table)
         renamed = table.column_names.inject({}) do |s,c|
            s.merge(c => c.sub(/.*\//,""))
         end                              
@@ -118,6 +180,11 @@ module Ruport
      end
     end
     
+    # === Overview
+    # 
+    # This module contains methods that will be made available as instance
+    # methods to any ActiveRecord model that calls <tt>acts_as_reportable</tt>.
+    #
     module InstanceMethods
       
       # Grabs all of the object's attributes and the attributes of the
@@ -135,16 +202,18 @@ module Ruport
       #
       # Example:
       # 
-      # class Book < ActiveRecord::Base
-      #   belongs_to :author
-      #   acts_as_reportable
-      # end
+      #   class Book < ActiveRecord::Base
+      #     belongs_to :author
+      #     acts_as_reportable
+      #   end
       # 
-      # abook.reportable_data(:only => ['title'], :include => [:author])
+      #   abook.reportable_data(:only => ['title'], :include => [:author])
       #
-      # Returns:  [{'title' => 'book title',
-      #             'author.id' => 'author id',
-      #             'author.name' => 'author name' }]
+      # Returns:
+      #
+      #   [{'title' => 'book title',
+      #     'author.id' => 'author id',
+      #     'author.name' => 'author name' }]
       #  
       # NOTE: title will only be returned if the value exists in the table.
       # If the books table does not have a title column, it will not be
@@ -152,11 +221,13 @@ module Ruport
       #
       # Example:
       #
-      # abook.reportable_data(:only => ['title'],
-      #   :include => { :author => { :only => ['name'] } })
+      #   abook.reportable_data(:only => ['title'],
+      #     :include => { :author => { :only => ['name'] } })
+      #
+      # Returns:
       #
-      # Returns:  [{'title' => 'book title',
-      #             'author.name' => 'author name' }]
+      #   [{'title' => 'book title',
+      #     'author.name' => 'author name' }]
       #
       def reportable_data(options = {})
         options = options.merge(self.class.aar_options) unless