ruport 0.8.14 → 0.10.0

data/README

@@ -1,106 +1,64 @@
 # ------------------------------------------------------------------------
-# -------------------------------------------------------------------------
-# 
-# NOTE:
-#
-# The most up to date information can be found at:
-# http://reporting.stonecode.org
-#
 # Contents:
 # 
-#  - What Ruport Is.
+#  - What Ruport Is
 #  - Installation
-#  - Getting Started
-#  - Caveats.
 #  - Resources
-#  - Background and Summary 
-#
-# = What Ruport Is. 
+#  - Hacking
 #
-# Ruby Reports is a software library that aims to make the task of reporting
-# less tedious and painful.  It provides tools for data acquisition, database
-# interaction, formatting, and parsing/munging.  Designed to be extensible,
-# it is possible to use Ruport for quick specific tasks as well as to build
-# robust reporting applications.
+# = What Ruport Is
 #
-# = Installation 
+# Ruby Reports (Ruport) is an extensible reporting system.
+# 
+# It aims to be as lightweight as possible while still providing core support
+# for data aggregation and manipulation as well as multi-format rendering 
+# of reports.
 #
-# Dependencies:
-#   
-#   Ruport has a number of dependencies.
-#     
-#   Ruby/DBI and appropriate dbds: Makes Query useable 
-#   (must be installed manually)
+# Ruport provides tools for using a number of data sources, including CSV files,
+# ActiveRecord models, and raw SQL connections via RubyDBI.
 #
-#   FasterCSV: Enables fast CSV parsing
-#   (available via rubygems)
-#     
-#   RedCloth:  Enables textile/markdown filtering
-#   (available via rubygems)
-#    
-#   PDF::Writer: Enables printable documents 
-#   (available via rubygems)
+# Data manipulation is easy as there are standard structures that support
+# record, table, and grouping operations.  These all can be extended to
+# implement custom behavior as needed.
 #
-#   MailFactory: For email support. 
-#   (available via rubygems)
+# For common tasks, Ruport provides formatters for CSV, HTML, PDF, and text-
+# based reports.  However, the real power lies in building custom renderers and
+# formatters.  The base formatting libraries provide a number of helper
+# functions that will let you build complex reports while maintaining a DRY and
+# consistent interface.
 #
-#   Scruffy: For Graph Support
-#   (available via rubygems)
+# Since Ruport's core support is intentionally minimalistic, you may be looking
+# for some higher level support for specific needs such as graphing, invoices,
+# report mailing support, etc.  For this, you may wish to take a look at the
+# ruport-util package, which contains some generally useful tools and libraries
+# to extend Ruport's capabilities.
 #
-# Note that by installing any of the dependencies, either via gems or manually,
-# their functionality will automatically be enabled.
+# = Installation 
 #
 # To install ruport via rubygems with all it's dependencies (except DBI):
 #   
 #   sudo gem install ruport -y
 #
-# To install ruport manually via setup.rb:
-# 
-#   sudo ruby setup.rb
-#
-# To not install ruport at all:
-#
-#   ruby -Ipath/to/ruport/lib my_script.rb
-#
 # Check to see if it installed properly:
 #
 #   ruby -rubygems -e "require 'ruport'; puts Ruport::VERSION"
-#   (omit the -rubygems flag if installed manually)
 #
 # If you get an error, please consult the mailing list. 
 #
-# = Getting Started
-#
-# Building a report can be broadly broken up into two phases. 
+# Dependencies Details:
+#   
+#  -- formatting
 #
-# == Data Collection and Manipulation
-# 
-# To begin, your data must be read from its source and stored in Ruport's 
-# standard data structures. Ruport::Data::Table and  Ruport::Data::Record 
-# have further information on how to work with with
-# and store data in ruport.
+# Ruport relies on PDF::Writer and FasterCSV for its formatting support.
+# If you want to make use of textile helpers, you'll also need RedCloth
 #
-# If you wish to retrieve your data using Ruby on Rails and ActiveRecord,
-# please see the acts_as_reportable plugin.
-# 
-# == Report Generation
-#
-# Once the data is ready, it can be rendered using a combination of
-# Ruport::Renderer and Ruport::Format::Plugin. 
-# The renderer defines the report type (tablular, graph, etc), and 
-# the plugin renders the engine into a final format (PDF, CSV, HTML, SVG). 
-# Renderers will often interact with more than one plugin, to allow the same
-# report to be rendered in multiple ways ie. as HTML and a PDF.
-# 
-# To tie these together, a basic DSL is provided by Ruport::Report
+#  -- database interaction
 #
-# For further reading and specific examples, please explore the examples/ 
-# directory in the source tree.
+# If you wish to use Ruport to report against a rails project, 
+# a camping project, or do standalone AAR reports, you'll need ActiveRecord.
 #
-# = Bug Reports / Feature Requests
-#
-#  Our Trac is at: http://code.stonecode.org
-#  You may use the username ruport and password blinky to file tickets
+# If you want to use Ruport::Query for raw SQL support, you'll need to 
+# install RubyDBI and whatever database drivers you might need.
 #
 # = Resources
 #
@@ -108,40 +66,17 @@
 # This software is on the move, so the list is the most reliable way of getting
 # up to date information.
 #
-# - You can sign up and/or view the archives here:
+#  -  You can sign up and/or view the archives here:
 #     http://groups.google.com/group/ruby-reports
 #
-# Please do not hesitate to use this list!  I am happily accepting patches and
-# documentation, as well as encouraging design discussions and also am quite
-# curious about what people use or want to use ruport for.
-#
-# I will announce Ruport releases on RubyTalk, on the Ruport mailing list, on
-# Freshmeat, and RAA.  If you would like to
-# keep an eye out for releases, please monitor one of those places.
-#
-#   - You may download Ruport's source from the project page:
-#     http://rubyforge.org/projects/ruport
-#
-#   - The latest stable API documentation is available at:
+#  -  The latest stable API documentation is available at:
 #     http://api.rubyreports.org
 #
-# There are also some tutorial available:
-# http://stonecode.svnrepository.com/ruport/trac.cgi/wiki/TutorialsAndArticles
-#
-# If you are interested in developing Ruport, please *never* study code in
-# official releases.  As this software is in it's early stages, it's essential
-# to keep an eye on the subversion repository.  If you let me know you are
-# interested in working on something, I will let you know if I'm actively
-# working on that section.
-#
-# - Grabbing the code from the svn trunk is simple:
-#
-#   svn co svn://rubyforge.org//var/svn/ruport/trunk/ ruport
-#
-# - Or if you are interested in the latest updates to the stable branch
-#
-#   svn co svn://rubyforge.org//var/svn/ruport/branches/stable ruport
+#  -  Our Trac is at: http://code.stonecode.org
+#     You may use the username ruport and password blinky to file tickets
 #
-# Thanks for checking out Ruport!
+# = Hacking
 #
-# If you have any questions or concerns, hop on the mailing list and fire away!
+# If you'd like to work on Ruport, please post on the list and let us know what
+# you're interested in doing, or contact Gregory Brown or Michael Milner if you
+# have questions.

data/Rakefile

@@ -2,53 +2,42 @@ require "rake/rdoctask"
 require "rake/testtask"
 require "rake/gempackagetask"
 
+
+RUPORT_VERSION = "0.10.0"
+
 begin
   require "rubygems"
 rescue LoadError
   nil
 end
 
-RUPORT_VERSION = "0.8.14"
-
-#Set to true to disable dependency resolution
-LEAN=false
-dir = File.dirname(__FILE__)
-lib = File.join(dir, "lib", "ruport.rb")
-version = File.read(lib)[/^\s*VERSION\s*=\s*(['"])(\d+\.\d+\.d+)['"]/,1]
 task :default => [:test]
 
 Rake::TestTask.new do |test|
   test.libs << "test"
-  test.test_files = Dir[ "test/test_*.rb" ]
+  test.test_files = Dir[ "test/*_test.rb" ]
   test.verbose = true
 end
 
 spec = Gem::Specification.new do |spec|
-  spec.name = LEAN ? "lean-ruport" : "ruport"
+  spec.name = "ruport"
   spec.version = RUPORT_VERSION
   spec.platform = Gem::Platform::RUBY
   spec.summary = "A generalized Ruby report generation and templating engine."
-  spec.files =  Dir.glob("{examples,lib,test,bin}/**/**/*") +
+  spec.files =  Dir.glob("{examples,lib,test,bin,util/bench}/**/**/*") +
                       ["Rakefile", "setup.rb"]
-  
   spec.require_path = "lib"
   
-  spec.test_files = Dir[ "test/test_*.rb" ]
+  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 TODO AUTHORS}
+  spec.extra_rdoc_files = %w{README LICENSE AUTHORS}
   spec.rdoc_options << '--title' << 'Ruport Documentation' <<
                        '--main'  << 'README' << '-q'
-  unless LEAN
-    spec.add_dependency('fastercsv', '>= 1.1.0')
-    spec.add_dependency('RedCloth',  '>= 3.0.3')
-    spec.add_dependency('pdf-writer', '>= 1.1.3')
-    spec.add_dependency("mailfactory", ">= 1.2.3")
-    spec.add_dependency('scruffy', '>= 0.2.2')
-    spec.add_dependency('gem_plugin', '>=0.2.2')
-  end
-
+  spec.add_dependency('transaction-simple', "=1.4.0")
+  spec.add_dependency('fastercsv', '>= 1.1.0')
+  spec.add_dependency('pdf-writer', '>= 1.1.3')
   spec.author = "Gregory Brown"
   spec.email = "  gregory.t.brown@gmail.com"
   spec.rubyforge_project = "ruport"
@@ -62,7 +51,7 @@ end
 
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include( "README",
-                           "TODO", #"CHANGELOG",
+                           #"CHANGELOG",
                            "AUTHORS", "COPYING",
                            "LICENSE", "lib/" )
   rdoc.main     = "README"
@@ -83,19 +72,27 @@ task :build_archives => [:package,:rcov,:rdoc] do
   sh "tar cjvf ruport-#{RUPORT_VERSION}.tar.bz2 ruport-#{RUPORT_VERSION}"
 end
 
+task :run_benchmarks do
+  files = FileList["util/bench/**/**/*.rb"]
+  files.sort!
+  files.uniq!
+  names = files.map { |r| r.sub("util/bench","").split("/").map { |e| e.capitalize } }
+  names.map! { |e| e[1..-2].join("::") + " <BENCH: #{e[-1].sub('Bench_','').sub('.rb','')}>" }
+  start_time = Time.now
+  files.zip(names).each { |f,n|
+    puts "\n#{n}\n\n"
+    sh "ruby -Ilib #{f}"
+    puts "\n"
+  }
+  end_time = Time.now
+  puts "\n** Total Run Time:  #{end_time-start_time}s **"
+end
+
 begin
   require 'rcov/rcovtask'
   Rcov::RcovTask.new do |t|
-    t.test_files = Dir[ "test/test_*.rb" ]
+    t.test_files = Dir[ "test/*_test.rb" ]
   end
 rescue LoadError
   nil
 end
-
-desc "Generate Ruport Recipes. Assumes you have erb, redcloth, and htmldoc."
-task :cookbook do
-  sh "erb doc/ruport_recipes.textile | redcloth >doc/temp.html" 
-  sh "htmldoc --batch doc/ruport.book" rescue nil
-  rm "doc/temp.html"
-  mv "out.pdf", "doc/out.pdf"
-end

data/examples/centered_pdf_text_box.rb

@@ -2,8 +2,6 @@ require "ruport"
 
 class Document < Ruport::Renderer
   
-  include Ruport::Renderer::Helpers
-  
   required_option :text
   required_option :author
   option :heading
@@ -13,43 +11,39 @@ class Document < Ruport::Renderer
 end
 
 
-class CenteredPDFTextBox < Ruport::Format::PDF
+class CenteredPDFTextBox < Ruport::Formatter::PDF
 
-  Document.add_format self, :pdf
+  renders :pdf, :for => Document
 
   def build_document_body
-
     add_text "-- " << options.author << " --",
-             :justification => :center, :font_size => 20 
-    
+             :justification => :center, :font_size => 20
     
     c = pdf_writer.absolute_x_middle - 239/2
     
-    #img,x,y,width,height
-    center_image_in_box("RWEmerson.jpg",c,325,239,359)
+    center_image_in_box("RWEmerson.jpg", :x => c, :y => 325,
+      :width => 239, :height => 359)
  
     rounded_text_box(options.text) do |o|
        o.radius = 5
-       o.width     = layout.width  || 400
-       o.height    = layout.height || 130
-       o.font_size = layout.font_size || 12
+       o.width     = options.width  || 400
+       o.height    = options.height || 130
+       o.font_size = options.font_size || 12
        o.heading   = options.heading
        
        o.x = pdf_writer.absolute_x_middle - o.width/2
        o.y = 300
-    end         
-
+    end
   end
   
   def finalize_document
-    output << pdf_writer.render
+    render_pdf
   end
 end
 
-a = Document.render_pdf { |r|
-  r.heading = "a good quote"
-  r.author  = "Ralph Waldo Emerson"
-  r.text = <<EOS
+a = Document.render_pdf( :heading => "a good quote", 
+                         :author => "Ralph Waldo Emerson") { |r|
+r.text = <<EOS
 A foolish consistency is the hobgoblin of little minds, adored by little
 statesmen and philosophers and divines. With consistency a great soul has simply
 nothing to do. He may as well concern himself with his shadow on the wall. Speak

data/examples/example.csv

@@ -0,0 +1,3 @@
+1,2,3
+4,5,6
+7,8,9

data/examples/line_plotter.rb

@@ -2,17 +2,17 @@ require "ruport"
 
 class LinePlotter < Ruport::Renderer
 
-  layout do |l|
-    l.line_color   = "green"
-    l.line_width   = 2
-    l.width        = "100%"
-    l.height       = "100%"
+   options do |o|
+    o.line_color   = "green"
+    o.line_width   = 2
+    o.width        = "100%"
+    o.height       = "100%"
   end
 
   def run
-    plugin do |p|
-      p.data = get_lines
-      p.render_plot
+    formatter do |f|
+      f.data = get_lines
+      f.render_plot
     end
   end
 
@@ -24,7 +24,9 @@ class LinePlotter < Ruport::Renderer
 
 end
 
-class SVG < Ruport::Format::Plugin
+class SVG < Ruport::Formatter
+  
+  renders :svg, :for => LinePlotter
 
   def initialize
     require "builder"
@@ -33,12 +35,12 @@ class SVG < Ruport::Format::Plugin
 
   def render_plot
 
-    opts = { :width => layout.width, :height => layout.height,
+    opts = { :width => options.width, :height => options.height,
              :xmlns => "http://www.w3.org/2000/svg" }
 
     output << @builder.svg(opts) do |builder|
-      builder.g( :stroke        => layout.line_color,
-                 "stroke-width" => layout.line_width ) do |g|
+      builder.g( :stroke        => options.line_color,
+                 "stroke-width" => options.line_width ) do |g|
         data.each { |r| render_line(r,g) }
       end
     end
@@ -49,9 +51,7 @@ class SVG < Ruport::Format::Plugin
     opts = { :x1 => line.x1, :x2 => line.x2,
              :y1 => line.y1, :y2 => line.y2 }
     xml_obj.line(opts)
-   end
-
-  LinePlotter.add_format self, :svg
+  end
 
 end
 

data/examples/pdf_complex_report.rb

@@ -1,38 +1,25 @@
+require 'rubygems'
 require "ruport"
 
 module MyStuff
 
   class DocumentRenderer < Ruport::Renderer
-    include Ruport::Renderer::Helpers
-
-    def run
-      build [:header,:body,:footer],:document
-      finalize :document
-    end
-
-    def table=(t)
-      options.table = t
-    end
-
-    def header_text=(t)
-      options.header_text=(t)
-    end
-
-    def footer_text=(t)
-      options.footer_text=(t)
-    end
+    required_option :header_text, :footer_text
 
+    stage :document_header, :document_body, :document_footer
+    
+    finalize :document
   end
 
-  class PDF < Ruport::Format::PDF
-    DocumentRenderer.add_format self, :pdf
+  class PDF < Ruport::Formatter::PDF
+    renders :pdf, :for => DocumentRenderer
 
     def build_document_header
       add_text options.header_text, :justification => :center
     end
 
     def build_document_body
-      pad(10) { draw_table }
+      pad(10) { draw_table(data) }
     end
 
     def build_document_footer
@@ -40,10 +27,10 @@ module MyStuff
     end
 
     def finalize_document
-      output << pdf_writer.render
+      render_pdf
     end
-
   end
+
 end
 
 puts MyStuff::DocumentRenderer.render_pdf { |e|