# ———————————————————————— # The true story 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: # 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: # rubyforge.org/projects/ruport # # - The latest stable API documentation is available at: # ruport.rubyforge.org/docs # # - If you’d like to get some news on Ruport, you can check out my blog. # (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. (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