Skip to content
This repository

Ruby Reports : Making your reporting life suck less, through Ruby

tree: 2051882809

Fetching latest commit…

Cannot retrieve the latest commit at this time

README
# ------------------------------------------------------------------------
# -------------------------------------------------------------------------
#
# WARNING: THIS DOCUMENT IS FREQUENTLY OUT OF DATE.
# 
# The most up to date information can be found at:
# http://reporting.stonecode.org
#
# 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 dependencies:
#     
#    Ruby/DBI and appropriate dbds: Makes Query useable 
#    (must be installed manually)
#
#    FasterCSV: 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)
#
#  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):
#   
#    sudo gem install ruport
#
#  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. 
#
# - 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.
#
#  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
#
#  There also will be some tutorials on stonecode.org
#
#  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/
#
#  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. 
# 
#  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
Something went wrong with that request. Please try again.