rails-dbi 0.1.0

data/lib/dbi/utils/xmlformatter.rb

@@ -0,0 +1,73 @@
+module DBI
+    module Utils
+        # Formats results in XML.
+        module XMLFormatter
+            # Generate XML for a row. The column names will surround the the values as tags.
+            #
+            # * +dbrow+: the array of the result row.
+            # * +rowtag+: the name of the tag that encapsulates a row.
+            # * +output+: Object that responds to `<<`.
+            #
+            def self.row(dbrow, rowtag="row", output=STDOUT)
+                #XMLFormatter.extended_row(dbrow, "row", [],  
+                output << "<#{rowtag}>\n"
+                dbrow.each_with_name do |val, name|
+                    output << "  <#{name}>" + textconv(val) + "</#{name}>\n" 
+                end
+                output << "</#{rowtag}>\n"
+            end
+
+            # good lord, what a mess.
+            #
+            # nil in cols_as_tag, means "all columns expect those listed in cols_in_row_tag"
+            # add_row_tag_attrs are additional attributes which are inserted into the row-tag
+            def self.extended_row(dbrow, rowtag="row", cols_in_row_tag=[], cols_as_tag=nil, add_row_tag_attrs={}, output=STDOUT)
+                if cols_as_tag.nil?
+                    cols_as_tag = dbrow.column_names - cols_in_row_tag
+                end
+
+                output << "<#{rowtag}"
+                add_row_tag_attrs.each do |key, val|  
+                    # TODO: use textconv ? " substitution?
+                    output << %{ #{key}="#{textconv(val)}"}
+                end
+                cols_in_row_tag.each do |key|
+                    # TODO: use textconv ? " substitution?
+                    output << %{ #{key}="#{dbrow[key]}"}
+                end
+                output << ">\n"
+
+                cols_as_tag.each do |key|
+                    output << "  <#{key}>" + textconv(dbrow[key]) + "</#{key}>\n" 
+                end
+                output << "</#{rowtag}>\n"
+            end
+
+            # generate a full XML representation of the table.
+            # 
+            # Arguments and output are similar to #row, with the exception of
+            # +roottag+, which is a container for the individual row tags.
+            #
+            def self.table(rows, roottag = "rows", rowtag = "row", output=STDOUT)
+                output << '<?xml version="1.0" encoding="UTF-8" ?>'
+                output << "\n<#{roottag}>\n"
+                rows.each do |row|
+                    row(row, rowtag, output)
+                end
+                output << "</#{roottag}>\n"
+            end
+
+            class << self
+                private
+                # Your standard XML entity conversions.
+                def textconv(str)
+                    str = str.to_s.gsub('&', "&#38;")
+                    str = str.gsub('\'', "&#39;")
+                    str = str.gsub('"', "&#34;")
+                    str = str.gsub('<', "&#60;")
+                    str.gsub('>', "&#62;")
+                end
+            end # class self
+        end # module XMLFormatter
+    end
+end

data/lib/dbi/utils.rb

@@ -0,0 +1,60 @@
+#
+# $Id: utils.rb,v 1.5 2006/01/29 06:14:19 djberg96 Exp $
+#
+
+module DBI
+    #
+    # Utility classes and methods for use by both DBDs and consumers.
+    #
+    module Utils
+        #
+        # Given a block, returns the execution time for the block.
+        #
+        def self.measure
+            start = ::Time.now
+            yield
+            ::Time.now - start
+        end
+
+        #
+        # parse a string of the form "database=xxx;key=val;..."
+        # or database:host and return hash of key/value pairs
+        #
+        # Used in DBI.connect and offspring.
+        #
+        def self.parse_params(str)
+            # improved by John Gorman <jgorman@webbysoft.com>
+            params = str.split(";")
+            hash = {}
+            params.each do |param| 
+                key, val = param.split("=") 
+                hash[key] = val if key and val
+            end 
+            if hash.empty?
+                database, host = str.split(":")
+                hash['database'] = database if database
+                hash['host']     = host if host   
+            end
+            hash 
+        end
+    end # module Utils
+end # module DBI
+
+#
+# Type converter.
+#
+# FIXME this really needs to go into DBI::TypeUtil or similar
+module DBI::Utils::ConvParam
+    #
+    # Wrapper to convert arrays of bound objects via DBI::TypeUtil#convert.
+    #
+    def self.conv_param(driver_name, *params)
+        params.collect { |param| DBI::TypeUtil.convert(driver_name, param) }
+    end
+end
+
+require 'dbi/utils/date'
+require 'dbi/utils/time'
+require 'dbi/utils/timestamp'
+require 'dbi/utils/xmlformatter'
+require 'dbi/utils/tableformatter'

data/lib/dbi.rb

@@ -0,0 +1,337 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__)) unless $LOAD_PATH.include?(File.dirname(__FILE__))
+#
+# DBI - Database Interface for Ruby. Please see the files README, DBI_SPEC,
+# DBD_SPEC for more information.
+#
+module DBI; end
+#--
+# Ruby/DBI
+#
+# Copyright (c) 2001, 2002, 2003 Michael Neumann <mneumann@ntecs.de>
+# Copyright (c) 2008 Erik Hollensbe <erik@hollensbe.org>
+# 
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions 
+# are met:
+# 1. Redistributions of source code must retain the above copyright 
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright 
+#    notice, this list of conditions and the following disclaimer in the 
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+# THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+# ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+begin
+    require "rubygems"
+    gem "deprecated", "= 2.0.1"
+rescue LoadError
+end
+
+#
+# NOTE see the end of the file for requires that live in the DBI namespace.
+#
+
+require "deprecated"
+require "dbi/row"
+require "dbi/utils"
+require "dbi/sql"
+require "dbi/columninfo"
+require 'dbi/types'
+require 'dbi/typeutil'
+require 'dbi/sql_type_constants'
+require 'dbi/exceptions'
+require 'dbi/binary'
+require 'dbi/handles'
+require 'dbi/base_classes'
+require "date"
+require "thread"
+require 'monitor'
+
+class Class
+    # Given a Class, returns if the object's (another Class) ancestors contain
+    # that class.
+    def inherits_from?(klass)
+        self.ancestors.include?(klass)
+    end
+end
+
+Deprecate.set_action(
+    proc do |call|
+        klass, meth = call.split(/[#.]/)
+        klass = klass.split(/::/).inject(Module) { |a,x| a.const_get(x) }
+
+        case klass
+        when DBI::Date, DBI::Time, DBI::Timestamp
+            warn "DBI::Date/Time/Timestamp are deprecated and will eventually be removed."
+        end
+
+        if klass.inherits_from?(DBI::ColumnInfo)
+            warn "ColumnInfo methods that do not match a component are deprecated and will eventually be removed"
+        end
+
+        warn "You may change the result of calling deprecated code via Deprecate.set_action; Trace follows:"
+        warn caller[2..-1].join("\n")
+    end
+)
+
+#++
+module DBI
+    VERSION = "0.4.5"
+
+    module DBD # :nodoc:
+        API_VERSION = "0.3"
+    end
+
+    #  Module functions (of DBI)
+    DEFAULT_TRACE_MODE = 2
+    DEFAULT_TRACE_OUTPUT = STDERR
+
+    # TODO: Is using class variables within a module such a wise idea? - Dan B.
+    @@driver_map     = Hash.new
+    @@driver_monitor = ::Monitor.new()
+    @@trace_mode     = DEFAULT_TRACE_MODE
+    @@trace_output   = DEFAULT_TRACE_OUTPUT
+    @@caseless_driver_name_map = nil
+    @@convert_types  = true
+    @@last_connection = nil
+
+    # Return the last connection attempted.
+    def self.last_connection
+        @@last_connection
+    end
+
+    # Return the current status of type conversion at this level. This status
+    # will be propogated to any new DatabaseHandles created.
+    def self.convert_types
+        @@convert_types
+    end
+
+    # Set the current status of type conversion at this level. This status
+    # will be propogated to any new DatabaseHandles created.
+    def self.convert_types=(bool)
+        @@convert_types = bool
+    end
+
+    class << self
+
+        # Establish a database connection.  
+        #
+        # Format goes as such: "dbi:Driver:database_conn_args"
+        #
+        # * "dbi" is the literal string "dbi". Case is unimportant.
+        # * "Driver" is the case-dependent name of your database driver class.
+        #   The file "dbd/#{Driver}" will be required. If you are using rubygems to
+        #   control your DBDs and DBI, you must make the gem's file path available
+        #   via the "gem" command before this will work.
+        # * database_conn_args can be:
+        #   * The database name.
+        #   * A more complex key/value association (to indicate host, etc). This
+        #     is driver dependent; you should consult your DBD documentation.
+        def connect(driver_url, user=nil, auth=nil, params=nil, &p)
+            dr, db_args = _get_full_driver(driver_url)
+            dh = dr[0] # driver-handle
+            dh.convert_types = @@convert_types
+            @@last_connection = dh.connect(db_args, user, auth, params, &p)
+        end
+
+        # Load a DBD and returns the DriverHandle object
+        def get_driver(driver_url) #:nodoc:
+            _get_full_driver(driver_url)[0][0]  # return DriverHandle
+        end
+
+        # Extracts the db_args from driver_url and returns the correspondeing
+        # entry of the @@driver_map.
+        def _get_full_driver(driver_url) #:nodoc:
+            db_driver, db_args = parse_url(driver_url)
+            db_driver = load_driver(db_driver)
+            dr = @@driver_map[db_driver]
+            [dr, db_args]
+        end
+
+        #
+        # Enable tracing mode. Requires that 'dbi/trace' be required before it does anything.
+        #
+        # As of 0.4.0, this mode does not do anything either way, so this currently just
+        # throws an InterfaceError. This issue is expected to be resolved in the next release.
+        #
+        def trace(mode=nil, output=nil)
+            # FIXME trace
+            raise InterfaceError, "the trace module has been removed until it actually works."
+            @@trace_mode   = mode   || @@trace_mode   || DBI::DEFAULT_TRACE_MODE
+            @@trace_output = output || @@trace_output || DBI::DEFAULT_TRACE_OUTPUT
+        end
+
+        #
+        # Return a list (of String) of the available drivers.
+        #
+        # NOTE:: This is non-functional for gem installations, due to the
+        #        nature of how it currently works. A better solution for 
+        #        this will be provided in DBI 0.6.0.
+        def collect_drivers
+            drivers = { }
+            # FIXME rewrite this to leverage require and be more intelligent
+            path = File.join(File.dirname(__FILE__), "dbd", "*.rb")
+            Dir[path].each do |f|
+                if File.file?(f)
+                    driver = File.basename(f, ".rb")
+                    drivers[driver] = f
+                end
+            end
+
+            return drivers
+        end
+
+        # Returns a list (of String) of the currently available drivers on your system in
+        # 'dbi:driver:' format.
+        #
+        # This currently does not work for rubygems installations, please see
+        # DBI.collect_drivers for reasons.
+        def available_drivers
+            drivers = []
+            collect_drivers.each do |key, value|
+                drivers.push("dbi:#{key}:")
+            end 
+            return drivers
+        end
+
+        # Attempt to collect the available data sources to the driver,
+        # specified in DBI.connect format.
+        #
+        # The result is heavily dependent on the driver's ability to enumerate
+        # these sources, and results will vary.
+        def data_sources(driver)
+            db_driver, = parse_url(driver)
+            db_driver = load_driver(db_driver)
+            dh = @@driver_map[db_driver][0]
+            dh.data_sources
+        end
+
+        #
+        # Attempt to disconnect all database handles. If a driver is provided,
+        # disconnections will happen under that scope. Otherwise, all loaded
+        # drivers (and their handles) will be attempted.
+        #
+        def disconnect_all( driver = nil )
+            if driver.nil?
+                @@driver_map.each {|k,v| v[0].disconnect_all}
+            else
+                db_driver, = parse_url(driver)
+                @@driver_map[db_driver][0].disconnect_all
+            end
+        end
+
+        private
+
+        # Given a driver name, locate and load the associated DBD package,
+        # generate a DriverHandle and return it.
+        def load_driver(driver_name)
+            @@driver_monitor.synchronize do
+                unless @@driver_map[driver_name]
+                    dc = driver_name.downcase
+
+                    # caseless look for drivers already loaded
+                    found = @@driver_map.keys.find {|key| key.downcase == dc}
+                    return found if found
+
+                    begin
+                        require "dbd/#{driver_name}"
+                    rescue LoadError => e1
+                        # see if you can find it in the path
+                        unless @@caseless_driver_name_map
+                            @@caseless_driver_name_map = { } 
+                            collect_drivers.each do |key, value|
+                                @@caseless_driver_name_map[key.downcase] = value
+                            end
+                        end
+
+                        begin
+                            require @@caseless_driver_name_map[dc] if @@caseless_driver_name_map[dc]
+                        rescue LoadError => e2
+                            raise e1.class, "Could not find driver #{driver_name} or #{driver_name.downcase} (error: #{e1.message})"
+                        end
+                    end
+
+                    # On a filesystem that is not case-sensitive (e.g., HFS+ on Mac OS X),
+                    # the initial require attempt that loads the driver may succeed even
+                    # though the lettercase of driver_name doesn't match the actual
+                    # filename. If that happens, const_get will fail and it become
+                    # necessary to look though the list of constants and look for a
+                    # caseless match.  The result of this match provides the constant
+                    # with the proper lettercase -- which can be used to generate the
+                    # driver handle.
+
+                    dr = nil
+                    dr_error = nil
+                    begin
+                        dr = DBI::DBD.const_get(driver_name.intern)
+                    rescue NameError => dr_error
+                        # caseless look for constants to find actual constant
+                        dc = driver_name.downcase
+                        found = DBI::DBD.constants.find { |e| e.downcase == dc }
+                        dr = DBI::DBD.const_get(found.intern) unless found.nil?
+                    end
+
+                    # If dr is nil at this point, it means the underlying driver
+                    # failed to load.  This usually means it's not installed, but
+                    # can fail for other reasons.
+                    if dr.nil?
+                        err = "Unable to load driver '#{driver_name}'"
+
+                        if dr_error
+                            err += " (underlying error: #{dr_error.message})"
+                        else
+                            err += " (BUG: could not determine underlying error)"
+                        end
+
+                        raise DBI::InterfaceError, err
+                    end
+
+                    dbd_dr = dr::Driver.new
+                    drh = DBI::DriverHandle.new(dbd_dr, @@convert_types)
+                    drh.driver_name = dr.driver_name
+                    # FIXME trace
+                    # drh.trace(@@trace_mode, @@trace_output)
+                    @@driver_map[driver_name] = [drh, dbd_dr]
+                    return driver_name 
+                else
+                    return driver_name
+                end
+            end
+        rescue LoadError, NameError
+            if $SAFE >= 1
+                raise InterfaceError, "Could not load driver (#{$!.message}). Note that in SAFE mode >= 1, driver URLs have to be case sensitive!"
+            else
+                raise InterfaceError, "Could not load driver (#{$!.message})"
+            end
+        end
+
+        # Splits a DBI URL into two components - the database driver name
+        # and the datasource (along with any options, if any) and returns
+        # a two element array, e.g. 'dbi:foo:bar' would return ['foo','bar'].
+        #
+        # A regular expression is used instead of a simple split to validate
+        # the proper format for the URL.  If it isn't correct, an Interface
+        # error is raised.
+        def parse_url(driver_url)
+            if driver_url =~ /^(DBI|dbi):([^:]+)(:(.*))$/ 
+                [$2, $4]
+            else
+                raise InterfaceError, "Invalid Data Source Name"
+            end
+        end
+    end # self
+end # module DBI

data/test/dbi/tc_columninfo.rb

@@ -0,0 +1,94 @@
+############################################################
+# tc_columninfo.rb
+#
+# Test case for the DBI::ColumnInfo class.
+############################################################
+$LOAD_PATH.unshift(Dir.pwd)
+$LOAD_PATH.unshift(File.dirname(Dir.pwd))
+$LOAD_PATH.unshift("../../lib")
+$LOAD_PATH.unshift("../../lib/dbi")
+$LOAD_PATH.unshift("lib")
+
+require "dbi/columninfo"
+require "test/unit"
+
+class TC_DBI_ColumnInfo < Test::Unit::TestCase
+   def setup
+      @colinfo = DBI::ColumnInfo.new(
+         "name"      => "test",
+         "sql_type"  => "numeric",
+         "type_name" => "test_type_name",
+         "precision" => 2,
+         "scale"     => 2,
+         "default"   => 100.00,
+         "nullable"  => false,
+         "indexed"   => true,
+         "primary"   => true,
+         "unique"    => false
+      )
+      @keys = %w/name sql_type type_name precision scale default nullable
+         indexed primary unique
+      /
+   end
+   
+   def test_constructor
+      assert_nothing_raised{ DBI::ColumnInfo.new }
+
+      assert_nothing_raised do
+          DBI::ColumnInfo.new({"foo" => "bar", "baz" => "quux"})
+          DBI::ColumnInfo.new({:foo => "bar", :baz => "quux"})
+      end
+
+      assert_raises(TypeError) do
+          DBI::ColumnInfo.new({"foo" => "bar", :foo => "quux"})
+      end
+   end
+
+   def test_accessors
+       assert_nothing_raised do
+           @keys.each do |x|
+               assert_equal(@colinfo[x], @colinfo[x.to_sym])
+               assert_equal(@colinfo.send(x.to_sym), @colinfo[x.to_sym])
+               @colinfo[x] = "poop"
+               assert_equal("poop", @colinfo[x])
+               assert_equal("poop", @colinfo[x.to_sym])
+           end
+       end
+   end
+
+   def test_precision_basic
+      assert_respond_to(@colinfo, :size)
+      assert_respond_to(@colinfo, :size=)
+      assert_respond_to(@colinfo, :length)
+      assert_respond_to(@colinfo, :length=)
+   end
+
+   def test_scale_basic
+      assert_respond_to(@colinfo, :decimal_digits)
+      assert_respond_to(@colinfo, :decimal_digits=)
+   end
+
+   def test_default_value_basic
+      assert_respond_to(@colinfo, :default_value)
+      assert_respond_to(@colinfo, :default_value=)
+   end
+
+   def test_unique_basic
+      assert_respond_to(@colinfo, :is_unique)
+   end
+
+   def test_keys
+      assert_respond_to(@colinfo, :keys)
+      assert_equal(@keys.sort, @colinfo.keys.collect { |x| x.to_s }.sort)
+   end
+   
+   def test_respond_to_hash_methods
+      assert_respond_to(@colinfo, :each)
+      assert_respond_to(@colinfo, :empty?)
+      assert_respond_to(@colinfo, :has_key?)
+   end
+
+   def teardown
+      @colinfo = nil
+   end
+end

data/test/dbi/tc_date.rb

@@ -0,0 +1,88 @@
+##############################################################################
+# tc_date.rb
+#
+# Test case for the DBI::Date class (currently) located in the utils.rb file.
+##############################################################################
+$LOAD_PATH.unshift(Dir.pwd)
+$LOAD_PATH.unshift(File.dirname(Dir.pwd))
+$LOAD_PATH.unshift("../../lib")
+$LOAD_PATH.unshift("../../lib/dbi")
+$LOAD_PATH.unshift("lib")
+
+require 'date'
+require 'dbi'
+require 'test/unit'
+
+Deprecate.set_action(proc { })
+
+class TC_DBI_Date < Test::Unit::TestCase
+   def setup
+      @date     = Date.new
+      @time     = Time.now
+      @dbi_date = DBI::Date.new
+   end
+
+   def test_constructor
+      assert_nothing_raised{ DBI::Date.new(2006) }
+      assert_nothing_raised{ DBI::Date.new(2006, 1) }
+      assert_nothing_raised{ DBI::Date.new(2006, 1, 20) }
+      assert_nothing_raised{ DBI::Date.new(Date.new) }
+      assert_nothing_raised{ DBI::Date.new(Time.now) }
+   end
+
+   def test_year
+      assert_respond_to(@dbi_date, :year)
+      assert_respond_to(@dbi_date, :year=)
+      assert_equal(0, @dbi_date.year)
+   end
+
+   def test_month
+      assert_respond_to(@dbi_date, :month)
+      assert_respond_to(@dbi_date, :month=)
+   end
+
+   # An alias for :month, :month=
+   def test_mon
+      assert_respond_to(@dbi_date, :mon)
+      assert_respond_to(@dbi_date, :mon=)
+      assert_equal(0, @dbi_date.mon)
+   end
+
+   def test_day
+      assert_respond_to(@dbi_date, :day)
+      assert_respond_to(@dbi_date, :day=)
+      assert_equal(0, @dbi_date.day)
+   end
+
+   # An alias for :day, :day=
+   def test_mday
+      assert_respond_to(@dbi_date, :mday)
+      assert_respond_to(@dbi_date, :mday=)
+   end
+
+   def test_to_time
+      assert_respond_to(@dbi_date, :to_time)
+      assert_equal(@time, DBI::Date.new(@time).to_time)
+      assert_equal(@time.object_id, DBI::Date.new(@time).to_time.object_id)
+   end
+
+   def test_to_date
+      assert_respond_to(@dbi_date, :to_date)
+      assert_equal(@date, DBI::Date.new(@date).to_date)
+      assert_equal(@date.object_id, DBI::Date.new(@date).to_date.object_id)
+   end
+
+   # We test .to_s because it has an explicit implementation
+   def test_to_s
+      assert_respond_to(@dbi_date, :to_s)
+      assert_nothing_raised{ @dbi_date.to_s }
+      assert_kind_of(String, @dbi_date.to_s)
+      assert_equal("0000-00-00", @dbi_date.to_s)
+   end
+
+   def teardown
+      @date = nil
+      @time = nil
+      @dbi_date = nil
+   end
+end