ruport 0.2.9 → 0.3.8

data/ACKNOWLEDGEMENTS

@@ -0,0 +1,33 @@
+Sometimes you just gotta pay some mad propz to the peoples.
+
+- Daniel Berger for releasing gruf to the community
+
+- James Edward Gray II for letting me take query.rb and mash it into something
+  that eventually became Ruport 0.1.0
+
+- Austin Ziegler for suggesting the Ruby License, which hopefully keeps everyone
+  happy.
+
+- All the people at RubyConf 2005, new_haven.rb, and NYC.rb that made
+  suggestions and let me know what kind of problems they were dealing with.
+
+- The people on the Ruport mailing list who will happily run unit tests and
+  check out little things for me when I need it.
+
+- Francis Hwang for overall design suggestions and the contribution of SqlSplit.
+  Additionally, his efforts on DBI to bring it back to life.  (Along with the
+  rest of the new DBI team)
+
+- Mathijs Mohlmann for pointing out that the DataRow constructor sucks and
+  offering some patches for changes to Ruport. 
+
+- JEG2 again for letting me ape Parse::Input from him ;)
+
+- Gregory Gibson for pretending like I'm a worthwhile business investment, and
+  providing funding to let me work on Ruport, instead of like... working in a
+  coffee shop or something.
+
+- 'A Monkey' for catching a bug before I even commited it to SVN.
+
+- RubyTalk, #ruby-lang and the Ruby community in general. 
+  Each and every one of you is my homie.

data/AUTHORS

@@ -1,7 +1,19 @@
+Developers:
+---------------------------------------------------
 {Gregory Brown}[mailto:gregory.t.brown@gmail.com]:
 
 Original Author and Ruport::Report hacker.
 
 {Robert Canieso}[mailto:rcanieso@gmail.com]:
 
-Guy in charge of the Ruport::Format module
+Currently lurking.  Soon to be tester / developer
+
+Contributors / People we've stole from:
+---------------------------------------------------
+
+James Edward Gray II:
+Original inspiration via query.rb
+Parse::Input which is the base for Ruport::Parser
+
+Francis Hwang:
+SQLSplit

data/CHANGELOG

@@ -1,4 +1,79 @@
-The current version of Ruby Reports is 0.2.9
+The current version of Ruby Reports is 0.3.8
+key features of Ruport 0.3.8:
+
+- New configuration system
+
+- New query model
+
+- New formatting system
+
+- Total API redesign
+
+- Lots more API documentation
+
+- A parser adapted from Parse::Input
+
+- ruport executable was deprecated
+
+[ Code was redesigned completely after 0.2.9 ]
+
+changes since Ruport 0.2.9:
+
+- Report::SQL dropped.
+
+- Fixed a bug in query that made ODBC driver not work at ALL!
+  (AFAIK, this bug was ONLY in Ruport 0.2.9)
+
+- removed render() from the engine and implemented DataSet#render_as()
+  example:
+  @report = render(data) do |builder| builder.format = :some_format end
+  is now: @report = data.render_as(:some_format)
+  which takes an optional block that works as before.
+
+- removed method DataSet#select_field() because it was the same as 
+  DataSet#select_fields() and of limited utility.
+
+- added method DataSet#remove_fields and DataSet#remove_fields!
+  to make data manipulation easier.
+
+- added DataSet#empty?
+
+- added DataSet#clone which will actually deep copy a DataSet.
+
+- cleaned up incredibly annoying DataSet constructor so you can now pass
+  field names and data to new()
+
+- Report::DataSet now documented
+
+- added hacks.rb which will include a random collection of potentially
+  useful functions.  (Already cool for making Ruport easy to use with irb).
+
+- added Document class and unit tests.  Needs to be completed.
+
+- added Report::DataSet.clone for making deep copies of DataSets.
+
+- added Element, Section, Page, and Document formatting classes.
+
+- restructured unit tests, adding ts_format and ts_report
+  and moving all non-testcase data into test/samples
+
+- restuctured library, adding ruport/format.rb and ruport/report.rb
+	made format and report into classes, with nested classes within.
+	
+- Moved the Report::Engine class into Report
+	
+- reorginized DataSet#<< to be more efficient. Thanks Francis!
+
+- added OpenNode.  Which is a little scary.
+
+- Francis Hwang has added SqlSplit, which has been tied into query.
+  Now multiple statement SQL dumps can be processed by ruport.
+
+- DataSet can now safely execute commands that return no rows.
+  (This was a bug in RubyDBI which ruport now has a workaround for)
+
+- require "ruportlib" becomes require "ruport"
+
 
 changes since Ruport 0.2.5:
 

data/README

@@ -1,90 +1,209 @@
-Thank you for taking the time to download Ruby Reports. (Ruport)
-
-This software is a powerful report generation engine that allows users to
-generate custom ERb and pure ruby templates that can easily query various forms
-of databases via DBI.  It also provides helper methods and utilities to generate professional reports quickly and cleanly.
-
-It happens to be alpha software, so if it offends your mother, burns out the innards of your computer, or threatens you in any other way, you may want to wait until further releases to play around with it.
-
-Please take the time to run through the examples available on RubyForge!
-This is the best way of learning the system:
-
-http://rubyforge.org/frs/?group_id=856&release_id=3656
-
-Otherwise, here is a brief set of installation and setup instructions which will
-hopefully get you going:
-
-Ruport itself is very easy to install.  However, you will need to install some
-dependencies which the system relies on.  The most important of these
-(and unfortunately the most complex to install) is the Ruby/DBI library.
-Because this library has many possible installation instructions depending on 
-your database and operating system setup, I will not go into the instructions
-in detail here.  However, it essentially boils down to finding your database
-software in the list of drivers on http://ruby-dbi.sourceforge.net/ and 
-downloading and installing the driver.  Once this is complete, you download and install DBI using the instructions at the aformentioned link.  We have
-successfully installed RubyDBI with a MySQL driver on Gentoo Linux, Windows
-2000/XP and Mac OS X.3, X.4.  
-
-There is a tutorial available for installing Ruport and MySQL on Windows
-at: http://stonecode.org:2501/stonecodeproductions/published/Ruport%2C+MySQL+and+Windows
-
-If you're having problems getting mysqld_safe running on Mac OS X,
-you might check out this:
-
-http://stonecode.org:2501/stonecodeproductions/published/Why+OS+X+MySQL+won%27t+start+the+server
-
-We have also successfully installed RubyDBI on Windows 2000 using ODBC. 
-If you are running a similar setup, feel free to email gregory.t.brown@gmail.comwith any questions.  If you successfully install Ruby/DBI on another system /
-database combination, we'd love to hear how you did it so that  we can improve
-this documentation for the next version of Ruport.  Once you've got DBI 
-installed, the Ruport installation  is a piece of cake.
-
-Ruport is a gem.  It relies on FasterCSV but this can easily be installed using the --include-dependencies flag.  Make sure you have adequete permissions and run:
-
-	sudo gem install ruport
-
-on Linux, OS X, and other Unix like systems.  
-
-On Windows, ensure that you have adequete permission to install
-software and run:
-	 
-	gem install ruport
-
-With any luck, Ruport is now installed and you are ready to move on to
-setting up and configuring a sandbox.
-
-To check to see if the ruport executable has been added to you path and is
-working in at least minimal capacity, type:
-
-ruport -v
-
-at the command prompt.
-
-If you see something like this:
-
-	Ruport Version x.y.z  ...
-
-then Ruport is at least installed and running.  
-
-If you get an error instead, feel free to email me,
-but please include the error message.
-
-To generate a new project, type:
+# ------------------------------------------------------------------------
+# The <em>true story</em> behind Ruby Reports...
+#
+#       ------           __________________           -------
+#      /      \       o ( I miss pacman... )         /       \
+#   o |  O  O  | o o o   ------------------     o o  | O   O |
+#  o  |        |  ___________________________  o     |       |
+#  o  \/\/\/\/\/ ( At least we're l33t now.. )o      \/\/\/\/  
+#  o              ---------------------------
+#  o   _________________________________________________
+#   o (vintage video game bad guys... ah... true l33tn355)
+#      --------------------------------------------------
+#
+# Not impressed?  Fine, here's ya damn DOCS!
+# -------------------------------------------------------------------------
+#
+# Contents:
+# 
+#   - What Ruport Is.
+#   - Installation
+#   - Caveats.
+#   - Resources
+#   - Background and Summary 
+#
+# - 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.
+#
+# - Installation 
+#
+#  Optional Dependencies:
+#   
+#    Ruport has a number of optional dependencies:
+#     
+#    Ruby/DBI and appropriate dbds: Makes Query useable 
+#    (must be installed manually)
+#
+#    FasterCSV: Silently enables fast CSV parsing
+#    (available via rubygems)
+#     
+#    RedCloth:  Enables textile/markdown filtering
+#    (available via rubygems)
+#    
+#    PDF::Writer: Enables printable documents via render_pdf (Experimental)
+#    (available via rubygems)
+#
+#    The recommended method of installing ruport is RubyGems.  It has been 
+#    split into two packages, one that installs all of the dependencies
+#    by default, and one which does not install them.  
+#
+#    None of the dependencies are mandatory, so you can still use Ruport
+#    without them, as long as you don't need their functionality.
+#
+#  To install ruport via rubygems with all it's dependencies (except DBI):
+#   
+#    sudo gem install ruport
+#
+#  To install ruport via rubygems with no dependencies:
+#
+#    sudo gem install ruport-lean
+#
+#  Note that by installing any of the dependencies, either via gems or manually,
+#  their functionality will automatically be enabled in ruport-lean.
+#
+#  To install ruport manually:
+# 
+#    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. 
+#
+# - Caveats 
+#
+#  Ruport is alpha 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.
+#
+#  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.
+#
+# - 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.
+#
+#  - 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.
+#
+#  Ruby Reports (Ruport) is a report generation and formatting toolset.
+#
+#  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
+#
+#  - The latest stable API documentation is available at:
+#    http://ruport.rubyforge.org/docs
+#
+#  - If you'd like to get some news on Ruport, you can check out my blog.
+#    (http://stonecode.org/blog)
+#
+#  There also will be some tutorials on stonecode.org
+#
+#  From time to time I will release example packages on RubyForge.  Keep an eye
+#  out for these on ruport's project page and please note that unless otherwise
+#  noted, these examples are meant ONLY for the versions which they correspond
+#  to. (i.e. ruport-example-0.2.9 will NOT work with Ruport 0.3.8)
+#
+#  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 checkout svn://rubyforge.org//var/svn/ruport
+#
+#  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 basecamp
+#  account.  This is primarily intended for people who are working on the
+#  project actively, though.
+#
+# - 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.  Format::Builder can be used to add additional formats which can be
+#  used by DataSet#as, and the Format class can add filters to Report#render
+# 
+#  Query currently provides a high level interface to DBI.  Soon it will support
+#  a mixin wrapper called Fetchable which will enable you to wrap whatever data
+#  source you choose.  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.
+#
+#  There is also a Config class which allows you to set things such as data
+#  sources, mailer information, and logging.  Ruport#complain provides a robust
+#  way to handle error logging and warnings.
+#
+#  Finally, Ruport provides a powerful yet oh-so-scary parsing tool.  It is
+#  essentially James Edward Gray II's Parse::Input library within the Ruport
+#  library.  (And will soon be integrated nicely too)
+#
+#  Read the source of ruport/parser.rb if you have some gnarly data you need to
+#  munge.
+#
+#  Finally, Please consult the API documentation and/or source code for more
+#  information. (http://ruport.rubyforge.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!
+#
+#  Thanks for downloading my software and I hope you enjoy it!
+#  -Greg
   
-  ruport generate ProjectName
-
-This will dump a directory structure for you to start with.
-
-You'll need to edit config/ruport.yaml to get things up and running, and at this
-point, unless you're magic, you'll probably need to either read the
-{API Documentation}[http://ruport.rubyforge.org/docs/] or the source, whichever
-you're most comfortable with.
-
-There is also a set of examples at:
-http://rubyforge.org/frs/?group_id=856&release_id=3481
-
-I hope you enjoy this software and that it is useful to you.
-
--Greg
-
-gregory.t.brown@gmail.com

data/Rakefile

@@ -4,6 +4,8 @@ require "rake/gempackagetask"
 
 require "rubygems"
 
+LEAN=false
+
 task :default => [:test]
 
 Rake::TestTask.new do |test|
@@ -13,8 +15,8 @@ Rake::TestTask.new do |test|
 end
 
 spec = Gem::Specification.new do |spec|
-	spec.name = "ruport"
-	spec.version = "0.2.9"
+	spec.name = LEAN ? "ruport-lean" : "ruport"
+	spec.version = "0.3.8"
 	spec.platform = Gem::Platform::RUBY
 	spec.summary = "A generalized Ruby report generation and templating engine."
 
@@ -22,17 +24,19 @@ spec = Gem::Specification.new do |spec|
    'lib/**/*.rb', 'bin/*', '[A-Z]*','test/**/*'].to_a.delete_if { |item|
    item.include?("CVS") } + ["Rakefile"]
 	spec.require_path = "lib"
-	spec.bindir = "bin"
-	spec.executables << "ruport"
 	
   spec.test_file = "test/ts_all.rb"
   
 	spec.has_rdoc = true
 	spec.extra_rdoc_files = %w{README LICENSE TODO AUTHORS CHANGELOG}
 	spec.rdoc_options << '--title' << 'Ruport Documentation' <<
-	                     '--main'  << 'README'
-  spec.add_dependency('fastercsv', '>= 0.1.0')
-	spec.author = "Gregory Brown"
+	                     '--main'  << 'README' << '-q'
+  unless LEAN
+    spec.add_dependency('fastercsv', '>= 0.1.0')
+    spec.add_dependency('RedCloth',  '>= 3.0.0')
+    spec.add_dependency('pdf-writer', '>= 1.1.3')
+  end
+  spec.author = "Gregory Brown"
 	spec.email = "	gregory.t.brown@gmail.com"
 	spec.rubyforge_project = "ruport"
 	spec.homepage = "http://ruport.rubyforge.org"
@@ -40,7 +44,7 @@ spec = Gem::Specification.new do |spec|
 Ruport is a powerful report generation engine that allows users to generate
 custom ERb templates and easily query various forms of SQL databases via DBI.
 It provides helper methods and utilities to generate professional reports
-quickly and cleanly.
+quickly and cleanly. 
 END_DESC
 end