ruport 0.4.23 → 0.4.99

data/AUTHORS

@@ -1,15 +1,13 @@
-Developers:
----------------------------------------------------
+= Developers
 
-{Gregory Brown}[mailto:gregory.t.brown@gmail.com]
-{Dudley Flanders}[mailto:dudley@misnomer.us]
+- {Gregory Brown}[mailto:gregory.t.brown@gmail.com]
+- {Dudley Flanders}[mailto:dudley@misnomer.us]
 
-Contributors / People we've (legally) stolen from:
----------------------------------------------------
+= Contributors / People we've (legally) stolen from:
 
 James Edward Gray II:
-- Original inspiration via query.rb
-- system_extensions.rb
+  - Original inspiration via query.rb
+  - system_extensions.rb
 
 Francis Hwang:
 - SQLSplit
@@ -19,3 +17,13 @@ Simon Claret:
 
 Dinko Mehinovic:
 - util/release/raa.rb
+- util/release/freshmeat.rb
+
+James Healy:
+- original inspiration for Invoice engine
+- SVG::Graph integration
+
+The SVG Graph support is made possible by SVG::Graph, which we have vendored
+because a gem is not available.  
+See: http://www.germane-software.com/software/SVG/SVG::Graph/
+

data/CHANGELOG

@@ -1,4 +1,33 @@
-The current version of Ruby Reports is 0.4.23
+The current version of Ruby Reports is 0.4.99
+
+changes since 0.4.23
+
+- Removed the legacy Format::Document|Element|Page|OpenNode classes
+
+- Added lots of API documentation
+
+- actions now will throw an error if they are already defined.
+  (Temporary collision remedy)
+
+- You can now dup Sets
+
+- Unit tests should no longer explode when PDF::Writer is not installed
+
+- Added a simplistic Rake task for building the recipe book
+
+- Added intuitive error message for invalid plugins
+
+- Fixed an error in Tag duplication for Data::Record
+
+- Ruport now has charting support via SVG::Graph
+
+- reordering now has intuitive error messages
+
+- Trimmed down system_extensions.rb to only include the relevant terminal
+  geometry code
+
+- Record/Table reordering can now be expressed either as a splatted list or an
+  array.  Eg %w[a b c] and "a","b","c" are both acceptable as arguments.
 
 changes since 0.4.21
 

data/README

@@ -8,161 +8,191 @@
 #
 # Contents:
 # 
-#   - What Ruport Is.
-#   - Installation
-#   - Caveats.
-#   - Resources
-#   - Background and Summary 
+#  - What Ruport Is.
+#  - Installation
+#  - Getting Started
+#  - Caveats.
+#  - Resources
+#  - Background and Summary 
 #
-# - What Ruport Is. 
+# = What Ruport Is. 
 #
-#  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.
+# 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.
 #
-# - Installation 
+# = Installation 
 #
-#  Dependencies:
+# Dependencies:
 #   
-#    Ruport has a number of dependencies.
+#   Ruport has a number of dependencies.
 #     
-#    Ruby/DBI and appropriate dbds: Makes Query useable 
-#    (must be installed manually)
+#   Ruby/DBI and appropriate dbds: Makes Query useable 
+#   (must be installed manually)
 #
-#    FasterCSV: Enables fast CSV parsing
-#    (available via rubygems)
+#   FasterCSV: Enables fast CSV parsing
+#   (available via rubygems)
 #     
-#    RedCloth:  Enables textile/markdown filtering
-#    (available via rubygems)
+#   RedCloth:  Enables textile/markdown filtering
+#   (available via rubygems)
 #    
-#    PDF::Writer: Enables printable documents 
-#    (available via rubygems)
+#   PDF::Writer: Enables printable documents 
+#   (available via rubygems)
 #
-#    MailFactory: For email support. 
+#   MailFactory: For email support. 
 #
-#  Note that by installing any of the dependencies, either via gems or manually,
-#  their functionality will automatically be enabled.
+# Note that by installing any of the dependencies, either via gems or manually,
+# their functionality will automatically be enabled.
 #
-#  To install ruport via rubygems with all it's dependencies (except DBI):
+# To install ruport via rubygems with all it's dependencies (except DBI):
 #   
-#    sudo gem install ruport
+#   sudo gem install ruport
 #
-#  To install ruport manually via setup.rb:
+# To install ruport manually via setup.rb:
 # 
-#    sudo ruby setup.rb
+#   sudo ruby setup.rb
 #
-#  To not install ruport at all:
+# To not install ruport at all:
 #
-#    ruby -Ipath/to/ruport/lib my_script.rb
+#   ruby -Ipath/to/ruport/lib my_script.rb
 #
-#  Check to see if it installed properly:
+# Check to see if it installed properly:
 #
-#    ruby -rubygems -e "require 'ruport'; puts Ruport::VERSION"
-#    (omit the -rubygems flag if installed manually)
+#   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. 
+# If you get an error, please consult the mailing list. 
 #
-# - Caveats 
+# = Getting Started
 #
-#  Ruport is experimental software.  It's not completely tested and the API is
-#  changing rapidly from version to version.  Test suites are becoming
-#  increasingly robust, but have not identified all possible edge cases.  If
-#  Ruport goes wild on you, it's because it hasn't been tamed yet.
+# Building a report can be broadly broken up into two phases. 
 #
-#  The functionality is also not complete yet.  There is a lot left to be added
-#  and there is a lot to think about.  If you find yourself wondering why
-#  feature foo is in Ruport, chances are it just hasn't been written yet.
+# == Data Collection and Manipulation
+# 
+# To begin, your data must be read from its source and stored in Ruports 
+# standard data structures. Ruport::Data::Set, Ruport::Data::Table and 
+# Ruport::Data::Record have further information on how to work with with
+# and store data in ruport.
+#
+# If you wish to retrieve your data using Ruby on Rails and ActiveRecord,
+# Ruport::Reportable has some useful information; To pull your data directly
+# from a database, Ruport::Query will be useful, and to build it manually
+# Array has been extended with a convenience function or two.
+# 
+# == Report Generation
+#
+# Once the data is ready, it can be rendered using a combination of
+# Ruport::Format, Ruport::Format::Engine and Ruport::Format::Plugin. 
+# The engine defines the report type (tablular, invoice, graph, etc), and 
+# the plugin renders the engine into a final format (PDF, CSV, HTML, SVG). 
+# Engines 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
+#
+# For further reading and specific examples, please explore the examples/ 
+# directory in the source tree and read the Ruport Cookbook.
+#
+# = Caveats 
+#
+# Ruport is experimental software.  It's not completely tested and the API is
+# changing rapidly from version to version.  Test suites are becoming
+# increasingly robust, but have not identified all possible edge cases.  If
+# Ruport goes wild on you, it's because it hasn't been tamed yet.
+#
+# The functionality is also not complete yet.  There is a lot left to be added
+# and there is a lot to think about.  If you find yourself wondering why
+# feature foo is in Ruport, chances are it just hasn't been written yet.
 #
-#  Documentation so far is something that is a struggle to keep up with.  As of
-#  this release, there is at least partial documentation for the API.  This
-#  will continue to get better as time goes on.
+# Documentation so far is something that is a struggle to keep up with.  As of
+# this release, there is at least partial documentation for the API.  This
+# will continue to get better as time goes on.
 #
-#  Platform independence is a priority, but I don't absolutely always have
-#  access to every OS / DBMS combination, so if something breaks on your
-#  system, please feel free to yell loud at the mailing list.
+# Platform independence is a priority, but I don't absolutely always have
+# access to every OS / DBMS combination, so if something breaks on your
+# system, please feel free to yell loud at the mailing list.
 #
-#  That having been said, I do use ruport in my daily work.  That means that it
-#  will probably have at least something you will find useful.  Or so I hope.
+# That having been said, I do use ruport in my daily work.  That means that it
+# will probably have at least something you will find useful.  Or so I hope.
 #
-# - Resources
+# = Resources
 #
-#  The best way to get help and make suggestions is the Ruport mailing list.
-#  This software is on the move, so the list is the most reliable way of getting
-#  up to date information.
+# The best way to get help and make suggestions is the Ruport mailing list.
+# 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:
-#    http://lists.stonecode.org/listinfo.cgi/ruport-stonecode.org
+# - You can sign up and/or view the archives here:
+#   http://lists.stonecode.org/listinfo.cgi/ruport-stonecode.org
 #
-#  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.
+# 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, RAA, and the new_haven.rb mailing list.  If you would like to
-#  keep an eye out for releases, please monitor one of those places.
+# I will announce Ruport releases on RubyTalk, on the Ruport mailing list, on
+# Freshmeat, RAA, and the new_haven.rb mailing list.  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
+#   - You may download Ruport's source from the project page:
+#     http://rubyforge.org/projects/ruport
 #
-#  - The latest stable API documentation is available at:
-#    http://reporting.stonecode.org/docs
+#   - The latest stable API documentation is available at:
+#     http://reporting.stonecode.org/docs
 #
-#  There also will be some tutorials on ruport.infogami.com
+# There also will be some tutorials on ruport.infogami.com
 #
-#  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.
+# 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:
+# - Grabbing the code from the svn trunk is simple:
 #
-#    svn co svn://rubyforge.org//var/svn/ruport/trunk/
+#   svn co svn://rubyforge.org//var/svn/ruport/trunk/
 #
-#  Those who would like to become regular contributors will be given write
-#  access.  Also, anyone interested in the internal design and project
-#  management aspects of Ruport can request to be added to our Trac
-#  account.  This is primarily intended for people who are working on the
-#  project actively, though.
+# Those who would like to become regular contributors will be given write
+# access.  Also, anyone interested in the internal design and project
+# management aspects of Ruport can request to be added to our Trac
+# account.  This is primarily intended for people who are working on the
+# project actively, though.
 #
-# - Background / Summary 
+# = Background / Summary 
 #  
-#  Ruport aims to help you fetch data from various sources, perform 
-#  manipulations on them as needed, and then output them in a variety
-#  of formats easily.  The powerful ERb templating engine is integrated
-#  to let you embed Ruport code into your formatted data. Also, Ruport
-#  provides a high level interface to databases, to make getting
-#  your data easy.
-#
-#  The standard datastructure for Ruport is the DataSet.  It is an enumerable
-#  ordered list which consists of DataRow objects that can be accessed
-#  by field names or ordinal position. DataRows can be arbitrarily tagged,
-#  allowing for easy retrieval of the same rows for many different purposes.
-#
-#  The rest of the code is organized into three main models, Report, Query,
-#  and Format.  Each is meant to be a high level interface to Ruport.
-#  The inner classes can be used where a decent level of customization
-#  is needed.
-#
-#  Report is in some sense the 'controller' of your application, and provides
-#  methods to help you write a Reporting application
-#
-#  Format provides support for building filters and specialized formatting
-#  systems. 
+# Ruport aims to help you fetch data from various sources, perform 
+# manipulations on them as needed, and then output them in a variety
+# of formats easily.  The powerful ERb templating engine is integrated
+# to let you embed Ruport code into your formatted data. Also, Ruport
+# provides a high level interface to databases, to make getting
+# your data easy.
+#
+# The core of Ruport is it's datastructures.  Data::Record, Data::Table, and
+# Data::Set provide tools that help with manipulation and preperation of data
+# for reporting.
+#
+# The rest of the code is organized into three main models, Report, Query,
+# and Format.  Each is meant to be a high level interface to Ruport.
+# The inner classes can be used where a decent level of customization
+# is needed.
+#
+# Report is in some sense the 'controller' of your application, and provides
+# methods to help you write a Reporting application
+#
+# Format provides support for building filters and specialized formatting
+# systems. 
 # 
-#  Query currently provides a high level interface to DBI.
-#  If you would like to query a database or load a sql dump, 
-#  this class can help you do that.  It can generate DataSets on the fly, 
-#  or feed you DBI:Rows, depending on what you need.
+# Query currently provides a high level interface to DBI.
+# If you would like to query a database or load a sql dump, 
+# this class can help you do that.  It can generate Data::Table objects on 
+# the fly, or feed you DBI:Rows, depending on what you need.
 #
-#  Finally, Please consult the API documentation and/or source code for more
-#  information. (http://reporting.stonecode.org/docs).  Not all classes have been
-#  documented but the ones that have may be easier to understand when their docs
-#  have been read.  Also, feel free to contribute documentation.
+# Finally, Please consult the API documentation and/or source code for more
+# information. (http://reporting.stonecode.org/docs).  Not all classes have been
+# documented but the ones that have may be easier to understand when their docs
+# have been read.  Also, feel free to contribute documentation.
 #
-#  If you have any questions or concerns, hop on the mailing list and fire away!
+# If you have any questions or concerns, hop on the mailing list and fire away!
 #
-#  Thanks for downloading my software and I hope you enjoy it!
-#  -Greg
+# Thanks for downloading my software and I hope you enjoy it!
+# -Greg

data/Rakefile

@@ -17,13 +17,13 @@ task :default => [:test]
 
 Rake::TestTask.new do |test|
 	test.libs << "test"
-	test.test_files = [ "test/ts_all.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.version = "0.4.23"
+	spec.version = "0.4.99"
 	spec.platform = Gem::Platform::RUBY
 	spec.summary = "A generalized Ruby report generation and templating engine."
 	spec.files =  Dir.glob("{examples,lib,test,bin}/**/**/*") +
@@ -31,7 +31,7 @@ spec = Gem::Specification.new do |spec|
   
   spec.require_path = "lib"
 	
-  spec.test_file = "test/ts_all.rb"
+  spec.test_files = Dir[ "test/test_*.rb" ]
   spec.bindir = "bin"
   spec.executables = FileList["rope"]
 	spec.has_rdoc = true
@@ -74,8 +74,16 @@ end
 begin
   require 'rcov/rcovtask'
   Rcov::RcovTask.new do |t|
-    t.test_files = [ "test/ts_all.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/TODO

@@ -1,8 +1,5 @@
-TODO:
+= TODO
 
-This file needs updating badly.
-
-In the interim, check the Roadmap at 
-http://stonecode.svnrepository.com/ruport
-
-- Check out the way Ruport.log prints
+Any future plans are available on Ruports Trac website
+  
+  http://stonecode.svnrepository.com/ruport/trac.cgi

data/bin/rope

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require "fileutils"
 include FileUtils
 
@@ -7,21 +9,20 @@ if ARGV.empty?
 end
 project = ARGV[0]
 
-RAKEFILE = <<-EOS
-require "rubygems" rescue LoadError nil  
+RAKEFILE = <<END_RAKEFILE
+begin; require "rubygems"; rescue LoadError; end
 require "rake/testtask"
 
 task :default => [:test]
 
 Rake::TestTask.new do |test|
-  test.libs       << "test"
-  test.pattern = 'test/**/tc_*.rb'
-  test.verbose    =  true
+  test.libs    << "test"
+  test.pattern =  'test/**/test_*.rb'
+  test.verbose =  true
 end
+END_RAKEFILE
 
-EOS
-
-CONFIG = <<-EOS
+CONFIG = <<END_CONFIG
 require "ruport"
 
 # For details, see Ruport::Config documentation
@@ -30,11 +31,9 @@ Ruport.configure { |c|
                      :dsn      =>  "dbi:mysql:mydb"
   c.log_file "log/ruport.log"
 }
+END_CONFIG
 
-EOS
-
-BUILD = '
-
+BUILD = <<'END_BUILD'
 def format_class_name(string)
   string.downcase.split("_").map { |s| s.capitalize }.join
 end
@@ -51,8 +50,8 @@ if ARGV[0].eql? "report"
   File.open("app/reports.rb", "a") { |f| 
     f << "require \"app/reports/#{ARGV[1]}\""
   }
-REP = <<-EOR
-require "rubygems" rescue LoadError nil  
+REP = <<EOR
+begin; require "rubygems"; rescue LoadError; end
 require "ruport"
 require "config/ruport_config"
 
@@ -72,8 +71,8 @@ end
 ##{class_name}.run { |res| puts res.results }
 EOR
 
-TEST = <<-EOR
-require "rubygems" rescue LoadError nil  
+TEST = <<EOR
+begin; require "rubygems"; rescue LoadError; end
 require "ruport"
 require "test/unit"
 require "app/reports/#{ARGV[1]}"
@@ -81,36 +80,30 @@ require "config/ruport_config"
 
 class Test#{class_name} < Test::Unit::TestCase
   def test_flunk
-    flunk "Write your real tests here or in any test/tc_* file"
+    flunk "Write your real tests here or in any test/test_* file"
   end
 end
 EOR
   File.open("app/reports/#{ARGV[1]}.rb", "w") { |f| f << REP }
-  File.open("test/tc_#{ARGV[1]}.rb","w") { |f| f << TEST } 
+  File.open("test/test_#{ARGV[1]}.rb","w") { |f| f << TEST } 
 end
-'
+END_BUILD
 
-SQL_EXEC = '
-require "rubygems" rescue LoadError nil  
+SQL_EXEC = <<'END_SQL'
+begin; require "rubygems"; rescue LoadError; end
 require "ruport"
 require "config/ruport_config"
 
 puts Ruport::Query.new(ARGF.read).result
-'
+END_SQL
 
 mkdir project
-
 %w[test config output data app app/reports templates sql log util].each do |d|
   mkdir "#{project}/#{d}"
 end
 
-
 touch("#{project}/app/reports.rb")
 File.open("#{project}/config/ruport_config.rb","w") { |f| f << CONFIG }
 File.open("#{project}/Rakefile","w") { |f| f << RAKEFILE }
 File.open("#{project}/util/build.rb","w") { |f| f << BUILD }
 File.open("#{project}/util/sql_exec.rb","w") { |f| f << SQL_EXEC }
-
-
-
-