@@ -1,13 +1,59 @@ -= License Terms +Ruport is copyrighted free software originally produced by Gregory Brown +<gregory.t.brown@gmail.com> which now contains a number of community +contributions and is actively developed by Michael Milner <mikem836@gmail.com>. -Distributed by Gregory Brown under the user's choice* of the -{GPL version 2}[http://www.gnu.org/copyleft/gpl.html] (see COPYING for details) -or the {Ruby software license}[http://www.ruby-lang.org/en/LICENSE.txt]. +See the AUTHORS file for a complete list of contributors. -Please email Greg[mailto:gregory.t.brown_AT_gmail.com] with any questions. +Licensing terms follow (License of Ruby 1.8): -*Note: This license refers specifically to GPLv2. -Distributing under other versions of the GPL require explicit permission from -Gregory Brown. Though we will most likely adopt the GPLv3 when the final draft -is published, we want to be able to make that decision for ourselves. +You can redistribute Ruport and/or modify it under either the terms of the GPL +(see COPYING file), or the conditions below: + 1. You may make and give away verbatim copies of the source form of the + software without restriction, provided that you duplicate all of the + original copyright notices and associated disclaimers. + + 2. You may modify your copy of the software in any way, provided that + you do at least ONE of the following: + + a) place your modifications in the Public Domain or otherwise + make them Freely Available, such as by posting said + modifications to Usenet or an equivalent medium, or by allowing + the author to include your modifications in the software. + + b) use the modified software only within your corporation or + organization. + + c) rename any non-standard executables so the names do not conflict + with standard executables, which must also be provided. + + d) make other distribution arrangements with the author. + + 3. You may distribute the software in object code or executable + form, provided that you do at least ONE of the following: + + a) distribute the executables and library files of the software, + together with instructions (in the manual page or equivalent) + on where to get the original distribution. + + b) accompany the distribution with the machine-readable source of + the software. + + c) give non-standard executables non-standard names, with + instructions on where to get the original software distribution. + + d) make other distribution arrangements with the author. + + 4. You may modify and include the part of the software into any other + software (possibly commercial). + + 5. The scripts and library files supplied as input to or produced as + output from the software do not automatically fall under the + copyright of the software, but belong to whomever generated them, + and may be sold commercially, and may be aggregated with this + software. + + 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. LICENSE @@ -1,3 +1,15 @@ +# Ruport : Extensible Reporting System +# +# query.rb provides a basic wrapper around RubyDBI for SQL interaction +# +# Original work began by Gregory Brown based on ideas from James Edward Gray II +# in August, 2005. +# +# Copyright (C) 2005-2007, Gregory Brown +# All Rights Reserved. +# +# This is free software distributed under the same terms as Ruby 1.8 +# See LICENSE and COPYING for details. require "generator" require "ruport/query/sql_split" @@ -5,17 +17,18 @@ module Ruport # === Overview # - # Query offers a way to interact with databases via DBI. It supports - # returning result sets in either Ruport's native Data::Table, or in their + # Query offers a way to interact with databases via RubyDBI. It supports + # returning result sets in either Ruport's Data::Table, or in their # raw form as DBI::Rows. # - # It offers basic caching support, the ability to instantiate a generator - # for a result set, and the ability to quickly and easily swap between data - # sources. + # Query allows you to treat your result sets as an Enumerable data structure + # that plays well with the rest of Ruport. + # + # If you are using ActiveRecord, you might prefer our acts_as_reportable + # extension. # class Query - - + include Enumerable # Ruport::Query provides an interface for dealing with raw SQL queries. @@ -34,11 +47,7 @@ module Ruport # <tt>:password</tt>:: If a DSN is specified, the password # can be set with this option. # <tt>:raw_data</tt>:: When set to true, DBI::Rows will be - # returned instead of a Data::Table. - # <tt>:cache_enabled</tt>:: When set to true, Query will download - # results only once, and then return - # cached values until the cache has been - # cleared. + # returned instead of a Data::Table # # Examples: # @@ -76,28 +85,43 @@ module Ruport @raw_data = options[:row_type].eql?(:raw) @params = options[:params] end - + + # Returns an OpenStruct with the configuration options for the default + # database source. + # def self.default_source sources[:default] end - + + # Returns a hash of database sources, keyed by label. def self.sources @sources ||= {} end - + + # Allows you to add a labeled DBI source configuration. + # + # Query objects will use the source labeled <tt>:default</tt>, + # unless another source is specified. + # + # Examples: + # + # # a connection to a MySQL database foo with user root, pass chunkybacon + # Query.add_source :default, :dsn => "dbi:mysql:foo", + # :user => "root", + # :password => "chunkybacon" + # + # + # # a second connection to a MySQL database bar + # Query.add_source :test, :dsn => "dbi:mysql:bar", + # :user => "tester", + # :password => "blinky" + # + # def self.add_source(name,options={}) sources[name] = OpenStruct.new(options) check_source(sources[name],name) end - private - - def self.check_source(settings,label) # :nodoc: - raise ArgumentError unless settings.dsn - end - - public - attr_accessor :raw_data # The original SQL for the Query object @@ -112,20 +136,20 @@ module Ruport @password = Ruport::Query.sources[label].password end + # Yields result set by row. def each(&action) raise(LocalJumpError, "No block given!") unless action fetch(&action) self end + # Runs the SQL query and returns the result set def result; fetch; end # Runs the query without returning its results. def execute; fetch; nil; end # Returns a Data::Table, even if in <tt>raw_data</tt> mode. - # This doesn't work with raw data if the cache is enabled and filled. - # def to_table data_flag, @raw_data = @raw_data, false data = fetch; @raw_data = data_flag; return data @@ -176,14 +200,6 @@ module Ruport type.eql?(:file) ? load_file( query ) : query end - def load_file(query_file) - begin - File.read( query_file ).strip - rescue - raise LoadError, "Could not open #{query_file}" - end - end - def fetch(&block) data = nil final = @statements.size - 1 @@ -192,5 +208,18 @@ module Ruport end return data end + + def load_file(query_file) + begin + File.read( query_file ).strip + rescue + raise LoadError, "Could not open #{query_file}" + end + end + + def self.check_source(settings,label) # :nodoc: + raise ArgumentError unless settings.dsn + end + end end lib/ruport/query.rb @@ -40,8 +40,8 @@ module Ruport # # == Default layout options # - # * <tt>show_group_headers</tt> #=> true - # * <tt>style</tt> #=> :inline + # * <tt>show_group_headers</tt> #=> true + # * <tt>style</tt> #=> :inline # # == Formatter hooks called (in order) # lib/ruport/renderer/grouping.rb setup.rb dfd7bbff64af28d1c2dd9a9d15f91fc821b4b4f0 sandal sandal@bb2e8eb0-7117-0410-aac4-c024b40ed5f7 http://github.com/ruport/ruport/commit/690784a924b9503eef3ecbcef506c5bd44c60ea6 690784a924b9503eef3ecbcef506c5bd44c60ea6

2007-05-01T09:13:45-07:00

Query doc update and license update git-svn-id: http://stonecode.svnrepository.com/svn/ruport/ruport/trunk@865 bb2e8eb0-7117-0410-aac4-c024b40ed5f7 673b6c692af08b8a80b052042073e274a64aabc2 sandal sandal@bb2e8eb0-7117-0410-aac4-c024b40ed5f7