lean-ruport 0.3.8

data/LICENSE

@@ -0,0 +1,7 @@
+= License Terms
+
+Distributed under the user's choice of the GPL[http://www.gnu.org/copyleft/gpl.html] (see COPYING for details) or the
+{Ruby software license}[http://www.ruby-lang.org/en/LICENSE.txt] by Gregory Brown.
+
+Please email Greg[mailto:gregory.t.brown_AT_gmail.com] with any questions.
+

data/README

@@ -0,0 +1,209 @@
+# ------------------------------------------------------------------------
+# 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
+  

data/Rakefile

@@ -0,0 +1,54 @@
+require "rake/rdoctask"
+require "rake/testtask"
+require "rake/gempackagetask"
+
+require "rubygems"
+
+LEAN=true
+
+task :default => [:test]
+
+Rake::TestTask.new do |test|
+	test.libs << "test"
+	test.test_files = [ "test/ts_all.rb" ]
+	test.verbose = true
+end
+
+spec = Gem::Specification.new do |spec|
+	spec.name = LEAN ? "lean-ruport" : "ruport"
+	spec.version = "0.3.8"
+	spec.platform = Gem::Platform::RUBY
+	spec.summary = "A generalized Ruby report generation and templating engine."
+
+	spec.files =  spec.files = FileList[
+   'lib/**/*.rb', 'bin/*', '[A-Z]*','test/**/*'].to_a.delete_if { |item|
+   item.include?("CVS") } + ["Rakefile"]
+	spec.require_path = "lib"
+	
+  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' << '-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"
+	spec.description = <<END_DESC
+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. 
+END_DESC
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_zip = true
+	pkg.need_tar = true
+end

data/TODO

@@ -0,0 +1,27 @@
+TODO: (Wiped clean for a fresh start as of 2006.02.20)
+
+For Ruport 0.4.0
+
+- Integrate Ruport::Parser into Report#parse and Format#parser
+
+- Document the inner classes of Format
+
+- Get unit tests up to 100% coverage
+
+- make the Fetchable module to abstract data acquisition
+
+High Priority Goals:
+
+- Implement some aspects of XST into DataSet
+
+- Offer charting support in Format
+
+Community Requests:
+
+- Integration with Rails (ActiveRecord)
+
+Other (Unordered) Goals:
+
+- Make mailer more robust via MailFactory
+
+- Support KirbyBase

data/lib/ruport.rb

@@ -0,0 +1,58 @@
+require "rubygems"
+# ruport.rb : Ruby Reports toplevel module
+#
+# Author: Gregory T. Brown (gregory.t.brown at gmail dot com)
+#
+# Copyright (c) 2006, All Rights Reserved.
+#
+# This is free software.  You may modify and redistribute this freely under
+# your choice of the GNU General Public License or the Ruby License. 
+#
+# See LICENSE and COPYING for details
+#
+
+module Ruport
+  VERSION = "Ruport Version 0.3.8 (Developmental)"
+  
+  # Ruports logging and error interface.
+  # Can generate warnings or raise fatal errors
+  # 
+  # Takes a message to display and a set of options.
+  # Will log to the file defined by Config::log_file
+  #
+  # Options:
+  # <tt>:status</tt>::    sets the severity level. defaults to <tt>:warn</tt>
+  # <tt>:output</tt>::    optional secondary output, defaults to <tt>$stderr</tt>
+  # <tt>:level</tt>::     set to <tt>:log_only</tt> to disable secondary output
+  # <tt>:exception</tt>:: exception to throw on fail.  Defaults to RunTimeError
+  # 
+  # The status <tt>:warn</tt> will invoke Logger#warn.  A status of
+  # <tt>:fatal</tt> will invoke Logger#fatal and raise an exception
+  # 
+  # By default, complain will also print warnings to $stderr
+  # You can redirect this to any I/O object via <tt>:output</tt>
+  #
+  # You can prevent messages from appearing on the secondary output by setting
+  # <tt>:level</tt> to <tt>:log_only</tt>
+  # 
+  # If you want to recover these messages to secondary output for debugging, you
+  # can use Config::enable_paranoia 
+  def Ruport.complain(message,options={})
+    options[:status] ||= :warn
+    options[:output] ||= $stderr
+    case(options[:status])
+    when :warn
+      Ruport::Config::logger.warn(message) if Ruport::Config::logger
+    when :fatal
+      Ruport::Config::logger.fatal(message) if Ruport::Config::logger
+      raise options[:exception] || RuntimeError, message
+    end
+    options[:output].puts "[!!] #{message}" unless 
+      options[:level].eql?(:log_only) and not Ruport::Config.paranoid?
+  end
+
+end
+
+%w[ config report format query data_row data_set].each { |lib|
+  require "ruport/#{lib}" 
+}

data/lib/ruport/config.rb

@@ -0,0 +1,114 @@
+# ruport/config.rb : Ruby Reports configuration system
+#
+# Author: Gregory T. Brown (gregory.t.brown at gmail dot com)
+#
+# Copyright (c) 2006, All Rights Reserved.
+#
+# This is free software.  You may modify and redistribute this freely under
+# your choice of the GNU General Public License or the Ruby License. 
+#
+# See LICENSE and COPYING for details
+#
+require "singleton"
+require "ostruct"
+module Ruport
+  # This class serves as the configuration system for Ruport.
+  # It's functionality is implemented through Config::method_missing
+  #  
+  # source :default and mailer :default will become the fallback values if one
+  # is not specified in Report::Mailer or Query, but you may define as many
+  # sources as you like and switch between them later.
+  #
+  # An example config file is shown below:
+  #   
+  #   # password is optional, dsn may omit hostname for localhost
+  #   Ruport::Config.source :default,
+  #   :dsn => "dbi:mysql:somedb:db.blixy.org", :user => "root", :password => "chunky_bacon"
+  #   
+  #   # :password, :port, and :auth_type are optional. :port defaults to 25 and
+  #   # :auth_type defaults to :plain.  For more information, see the source
+  #   # of Report::Mailer#select_mailer
+  #   Ruport::Config.mailer :default,
+  #   :host => "mail.chunkybacon.org", :address => "chunky@bacon.net",
+  #   :user => "cartoon", :password => "fox", :port => 25, :auth_type => :login
+  #   
+  #   # optional, if specifed, Ruport#complain will report to it
+  #   Ruport::Config.log_file 'foo.log'
+  #
+  #   # optional, if enabled, will force :log_only complaint calls to
+  #   # print to secondary output ($sterr by default).
+  #   # call Ruport::Config.disable_paranoia to disable
+  #   Ruport::Config.enable_paranoia
+  #
+  # Alternatively, this configuration could be done by opening the class:
+  #   class Ruport::Config
+  #
+  #     source :default, :dsn => "dbi:mysql:some_db", :user => "root"
+  #     
+  #     mailer :default, :host => "mail.iheartwhy.com", 
+  #     :address => "sandal@ruby-harmonix.net", :user => "sandal",
+  #     :password => "abc123"
+  #     
+  #     logfile 'foo.log'
+  #
+  #   end
+  #
+  # Saving this config information into a file and then requiring it can allow
+  # you share configurations between Ruport applications.
+  #
+  class Config
+    include Singleton
+    
+    def Config.method_missing(method_id,*args)
+      case(method_id)
+      when :source
+        return @@sources[args.first] if args.length == 1
+        @@sources[args.first] = OpenStruct.new(*args[1..-1])
+        unless @@sources[args.first].send(:dsn)
+          Ruport.complain("Bad or missing DSN for source #{args.first}!")
+        end
+      when :mailer
+        @@mailers[args.first] = OpenStruct.new(*args[1..-1])
+      when :log_file
+        @@logger = Logger.new(args.first)
+      when :default_source
+        @@sources[:default]
+      when :default_mailer
+        @@mailers[:default]
+      when :sources
+        @@sources
+      when :mailers
+        @@mailers
+      when :logger
+        @@logger
+      when :enable_paranoia
+        @@paranoid = true
+      when :disable_paranoia
+        @@paranoid = false
+      when :paranoid?
+        @@paranoid
+      else
+        super
+      end 
+    end
+    
+    private
+    
+    def Config.init!
+      @@sources  = { :default => 
+                       OpenStruct.new( :dsn      => "ruport",
+                                       :user     => "",
+                                       :password => ""
+                                     )
+                   }
+      @@mailers  = { :default => nil }
+      @@logger ||= nil
+      @@paranoid ||= false
+    end
+
+
+   
+    init!
+    
+  end
+end