ruport 0.1.0

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,69 @@
+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 templates and easily query various forms of SQL databases via DBI.It provides helper methods and utilities to generate professional reports quickly and cleanly.
+
+It is also 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.
+
+There is a user's manual for this application available at http://ruport.rubyforge.org/ruport_manual.pdf which I strongly recommend reading.
+
+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 and Mac OS X.  
+We have also successfully installed RubyDBI on Windows 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 Parse/Input (which will be linked to Ruport
+in future releases) but this can easily be installed using the
+--include-dependencies flag.  Make sure you have adequete permissions and run:
+
+	sudo gem install ruport --include-dependencies
+
+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 --include-dependencies
+
+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 0.1.0  ...
+
+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 sandbox, type ruport generate sandbox_name.
+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
+{manual}[http://ruport.rubyforge.org/ruport_manual.pdf] or the source, whichever
+you're most comfortable with.
+
+I hope you enjoy this software and that it is useful to you.
+
+-Greg
+
+gregory.t.brown@gmail.com

data/Rakefile

@@ -0,0 +1,51 @@
+require "rake/rdoctask"
+require "rake/testtask"
+require "rake/gempackagetask"
+
+require "rubygems"
+
+task :default => [:test]
+
+Rake::TestTask.new do |test|
+	test.libs << "test"
+	test.test_files = [ "tests/tc_ruport.rb" ]
+	test.verbose = true
+end
+
+spec = Gem::Specification.new do |spec|
+	spec.name = "ruport"
+	spec.version = "0.1.0"
+	spec.platform = Gem::Platform::RUBY
+	spec.summary = "A generalized Ruby report generation and templating engine."
+
+	spec.files = Dir.glob("{bin,lib,tests}/**/*.rb").
+	                 delete_if { |item| item.include?("CVS") } +
+	                 ["Rakefile", "setup.rb"]
+	spec.require_path = "lib"
+	spec.bindir = "bin"
+	spec.executables << "ruport" << "ruport.rb" 
+	
+	spec.has_rdoc = true
+	spec.extra_rdoc_files = %w{README LICENSE TODO}
+	spec.rdoc_options << '--title' << 'Ruport Documentation' <<
+	                     '--main'  << 'README'
+
+	spec.add_dependency("parseinput", ">= 0.0.1")
+
+	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,106 @@
+TODO:
+
+Take the following features and stabilize them for Ruport 0.2.0:
+
+- Mail system
+
+	Hook up unit tests and solidify system
+
+- Template Config / Line Editing
+
+	Find a way to accept piped in values
+	Hook up unit tests.
+	
+- Queries Table System
+
+	Write a cross-database table creation script
+	Hook up unit tests.
+
+- SQL builder
+
+	Expand so that it covers most common SQL commands.
+	Form better more complete unit tests.
+
+
+Begin implementing new features:
+
+	Multiple query reports:
+	
+		Allow the user to make arbitrary SQL queries,
+		combining the rows, and then iterating through them row by row in the
+		order specified.
+
+		This could be done with select taking an array of queries and possibly
+		some ordering instructions
+	
+	Cross database import from file:
+
+		Make an import(file,table,delimiter=",") command that will work
+		regardless of database choice and import the data stored in a file into
+		a specified table.
+
+	YAML dump / restore:
+		
+		Make a nice way to dump the results of a query to a yaml file,
+		potentially to be read back in and reconstructed by another ruport
+		template.  This would require splitting the formatting and data feeder
+		functionality, but would allow a user to simply load in a YAML file and
+		apply arbitrary formatting.
+
+	Parse/Input tight integration:
+
+		Write wrapper functions over the Parse/Input library to give Ruport the
+		power to feed in any data source such as a CSV, A website, or a log file
+		and do formatting and use the other features of Ruport.
+
+	PDF::Writer and CSV convenience methods:
+		
+		Create functions that will allow basic and common reports to be built
+		using PDF and CSV format without having to write the functionality over
+		and over again.  This would be especially useful for just dumping a
+		table's values in a certain order with some fields removed.
+
+	Logger / Exception handler:
+
+		Create a system to handle and log errors as well as provide log messages
+		regarding what Ruport does when a template is run.
+
+
+Design considerations:
+
+	Ruport will eventually need to be cleanly seperating between formatting
+	tools and data feeders.  This will likely happen in an early release, if not
+	the next than the one after.
+
+	Ruport trys to use a lot of 'intelligent' defaults but it might try to be
+	too clever in some places making it not clever at all.  The community
+	reaction will determine what places may need opening up more or need more
+	consideration for the defaults.
+
+	"Fix the lame hack that installs two executables" (James Edward Gray II)
+
+
+Other:
+
+	A full set of examples should be made available for download.
+
+	A quick reference page for templates and/or tutorial would be A Good Thing
+
+	The RDOC sucks!
+	
+	The unit tests need to be wired so that they can actually run without a ton
+	of additional steps, they need to be expanded to cover the whole system, and
+	they need to work in the Gem package as well as the source package.
+
+	Ruport needs to be modified to support as many databases as possibly
+	internally.  The system was written with Linux/MySQL and Windows/MS SQL
+	(ODBC) in mind.  This will change when feedback from the community is
+	recieved.
+
+
+This is only the tip of the iceburg.  Please feel free to continue to fill my
+plate by sending any suggestions to gregory.t.brown@gmail.com
+	
+
+		
+

data/bin/ruport

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# ruport.rb : A Ruby Reporting system.
+#
+# Created by Gregory Thomas Brown on 2005-08-02
+# Copyright (c) 2005 Gregory Brown, Stone Code Productions
+# All rights reserved.
+#
+# This product is free software, you may distribute it as such
+# under your choice of the Ruby license or the GNU GPL
+# See LICENSE for details
+#
+# Special thanks and acknowledgement go to James Edward Gray II
+# for providing the original source code for this application
+
+require "rubygems"
+require "query"
+require "mailer"
+require "ftools"
+
+if ARGV[0].eql?("generate")
+	if ARGV[1].nil?
+		puts "You must specify a name for your ruport sandbox"
+		exit
+	end
+	Dir.mkdir(ARGV[1])
+	Dir.mkdir("#{ARGV[1]}/reports")
+	Dir.mkdir("#{ARGV[1]}/templates")
+	Dir.mkdir("#{ARGV[1]}/config")
+	Dir.mkdir("#{ARGV[1]}/queries")
+	conf =  ":driver: 'DBI:mysql'\n"+
+	        ":database: test\n"+
+			":db_user:\n:db_password:\n:mail_host:\n:mail_account:\n"+        
+			":mail_password:\n:mail_address:\n:mail_authentication:\n"+ 
+			":query_table: ruport_queries"
+			    
+	File.open("#{ARGV[1]}/config/ruport.yaml", "w") { |f| f.puts(conf) }
+	File.open("#{ARGV[1]}/templates/test.rb", "w") { |f|
+		f.puts 'select "database()" do |r| puts r end'
+	}
+	exit
+elsif ARGV[0].eql?("-v")
+	puts "Ruport Version 0.1.0 \nA ruby report generation system by Gregory " +
+	"Brown.\nThis application is Free Software under the GPL/Ruby License. " +
+	"\nAll praise and/or criticism can be directed to "+
+	"gregory.t.brown@gmail.com"
+	exit
+end
+config = YAML.load(File.open("config/ruport.yaml"))
+mailer = nil
+
+if config.has_key?(:mail_host)
+	mailer = Mailer.new( config[:mail_host],
+						 config[:mail_address],
+	                     config[:mail_account],
+						 config[:mail_password],
+						 config[:mail_port],
+						 config[:mail_authentication] )
+end
+
+
+query  = Query.new( "#{config[:driver]}:#{config[:database]}",
+                    config[:db_user], config[:db_password], mailer)
+
+query.query_table = config[:query_table]
+
+
+case(ARGV[0])
+when "ins_query", "insq"
+	query_text =  query.load_file(ARGV[2])
+	query.execute("INSERT INTO #{query.query_table} " +
+	              "VALUES ('#{ARGV[1]}','#{query_text}' );")
+when "ls_queries", "lsq"
+	query.select("label FROM #{query.query_table}") do |r| puts r end
+when "show_query", "sq"
+	query.select( "query FROM #{query.query_table} " +
+	              "WHERE label LIKE '%#{ARGV[1]}%'" ) do |r| puts r end
+when "rm_query", "rmq"
+	query.execute("DELETE FROM #{query.query_table} " +
+				   "WHERE label LIKE '#{ARGV[1]}'" )
+else
+	query.eval_report(ARGF.filename, ARGF.read)	
+end
+
+
+
+

data/bin/ruport.rb

@@ -0,0 +1,4 @@
+# THIS IS A NASTY HACK TO GET RUPORT TO WORK IN CMD.EXE
+# BETTER SOLUTION IS A MUST.
+
+eval(File.read("C:/ruby/bin/ruport"))

data/lib/mailer.rb

@@ -0,0 +1,44 @@
+# mailer.rb
+
+#  Created by Gregory Brown on 2005-08-16
+#  Copyright 2005 (Gregory Brown) All Rights Reserved.
+
+#  This product is free software, you may distribute it as such
+#  under your choice of the Ruby license or the GNU GPL
+#  See LICENSE for details
+
+require "net/smtp"
+class Mailer
+	
+	# Creates a new Mailer object.  User must specify their mail host, email
+	# address, and account.  Password, port, and authentication method are all
+	# optional.
+	def initialize(host, address, account, password=nil, port=25, authentication=nil)
+		@host           = host
+		@account        = account
+		@password       = password
+		@address        = address
+		@port           = port
+		@auth 			= authentication
+		@recipients     = []
+		@body           = ""
+	end
+	
+	#A list of email addresses to send the message to.
+	attr_accessor :recipients
+	
+	#The body of the message to be sent
+	attr_accessor :body
+
+	# This takes _report_name_ as argument and sends the contents of @body to
+	# @recipients
+	def send_report(report_name)
+		return if @body.empty?
+		Net::SMTP.start(@host,@port,@host,@account,@password,@auth) do |smtp|
+			smtp.send_message( "Subject: #{report_name}\n\n#{@body}",
+			                   @address, 
+							   @recipients )
+		end
+	end
+
+end

data/lib/query.rb

@@ -0,0 +1,140 @@
+#!/usr/local/bin/ruby
+# query.rb
+# Created by Gregory Thomas Brown on 2005-08-02
+# Copyright 2005 (Gregory Brown) All rights reserved.
+#
+# This product is free software, you may distribute it as such
+# under your choice of the Ruby license or the GNU GPL
+# See LICENSE for details
+#
+# Special thanks and acknowledgement go to James Edward Gray II
+# for providing the original source code for this application
+require "dbi"
+require "parse/input"
+require "erb"
+require "csv"
+require "yaml"
+require "date"
+require "sql"
+class Query
+	def initialize( driver, user, password, mailer=nil )
+		@driver      = driver
+		@user        = user
+		@password    = password
+		@report_name = ""
+		@mailer      = mailer
+		@query_table = nil
+	end
+	
+	attr_accessor :query_table
+	attr_reader   :mailer
+	
+	# Takes a query, an optional sourcetype, and a block which is passed the
+	# results row by row.  When passed a query in string form, it adds the
+	# SELECT clause to the string and executes the query.  When passed a
+	# filename and a source :file, it looks in queries/ for the file specified.
+	# When given a database query label, it looks in config[query_table] for a
+	# query with the label specified.  If no source is specified, it uses
+	# string by default for the source.
+	#
+	# Example:
+	# 
+	# select ( "* FROM test" ) 
+	# Passes "SELECT * FROM test" to the database
+	#
+	# select ( "test.sql", :file )
+	# Passes the contents of queries/test.sql to the database
+	#	
+	# select ( "TEST", :db )
+	# Calls the query TEST stored in the database and query_table specified in
+	# config/ruport.yaml
+	
+	def select( query, source = :string, &action )
+		query = get_query(source, query)
+		source != :string || query = "SELECT " + query
+		DBI.connect(@driver, @user, @password) do |dbh|
+			dbh.prepare(query) do |sth|
+				sth.execute()
+				@column_names = sth.column_names
+				@first_row = true 
+				sth.fetch do |row|
+					action.call(row) if block_given?	
+					@first_row = false 
+				end
+			end
+		end
+	end
+
+	# Takes a query and an optional sourcetype and then runs the query
+	# against the database.  The output is not returned.  This is useful for
+	# doing construction and destruction actions.
+	def execute( query, source = :string )
+		query = get_query(source, query)
+		DBI.connect(@driver, @user, @password) do |dbh|
+			dbh.prepare(query) do |sth|
+				sth.execute()
+			end
+		end
+	end
+
+	# Evaluates _code_ from _filename_ as pure ruby code for files ending in
+	# .rb, and as ERb templates for anything else.
+	def eval_report( filename, code )
+		if filename =~ /\.rb/
+			eval(code)
+		else
+			ERB.new(code, 0, "%").run(binding)
+		end
+		unless @mailer.nil? || @mailer.recipients.empty?
+			@mailer.send_report(@report_name) 
+		end
+	end
+
+	# Loads a yaml file into the @config variable which is accessible in
+	# templates.  If _interactive_ is set to true, the user will be prompted to
+	# enter information for each key.
+	def load_yaml(file, interactive=false)
+		@config = YAML.load(File.open("config/#{file}"))
+		if (interactive)
+			@config.each do |property, value|
+    			$stderr.print "#{property} (#{value}): "
+    			entered = $stdin.gets.strip
+				@config[property] = entered unless entered.eql?("")
+			end
+		end
+	end
+	
+	# Creates an SQL Object.  The block is evaluated within the SQL instance so
+	# you may use any methods available to the SQL class. The generated query is
+	# returned.
+	def fetch( &dsl )
+		SQL.new(:SELECT, &dsl).to_s
+	end
+	
+	# Returns the query string for queries of type string, file, or db
+	def get_query(type,query)
+		case (type)
+		when :string
+			 query
+		when :file
+			load_file( query )
+		when :db
+			select ( "query FROM #{@query_table} WHERE " +
+			         "label LIKE '#{query}';" ) do |row| query = row[0] end
+			return query
+			
+		end
+	end
+			
+	#loads in a file from queries/
+	def load_file( file )
+		query = ""
+		File.open("queries/#{file}", "r").each_line do |line| 
+				query += line.chomp
+		end
+		return query
+	end
+
+
+end
+