dbi 0.4.0

data/lib/dbi/trace.rb

@@ -0,0 +1,91 @@
+# $Id: trace.rb,v 1.1 2006/01/04 02:03:22 francis Exp $
+# 
+# Tracing for DBI programs
+# 
+# Copyright (c) 2001 Michael Neumann
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+raise LoadError, "the trace module has been removed until it actually works."
+
+# works only correct with the newest version > 0.3.3
+require "aspectr"
+require "dbi"      # to work as "ruby -r dbi/trace myapp.rb"
+
+module DBI
+
+class HandleTracer < AspectR::Aspect
+
+  def initialize(klass)
+    @never_wrap = /^__|^send$|^id$|^class$|^$ /
+    self.wrap(klass, :pre, :post, methods(klass)) 
+  end
+
+  # trace methods -------------------------------------------------------------- 
+
+  def pre(method, object, exitstatus, *args)
+    
+    par = args.collect{|a| a.inspect}.join(", ")
+
+    if object.trace_mode == 2 then
+      object.trace_output << "-> #{method} for #{object} (#{par})\n"
+    elsif object.trace_mode == 3 then
+      object.trace_output << "-> #{method} for #{object.inspect} (#{par})\n"
+    end
+  end
+
+  def post(method, object, exitstatus, *args)
+
+    case object.trace_mode
+    when 1, 2 # return values and errors
+      arrow = object.trace_mode == 1 ? "<=" : "<-"
+      if exitstatus.kind_of? Array
+        object.trace_output << "#{arrow} #{method} for #{object} = #{exitstatus[0] || 'nil'}\n" 
+      else
+        if exitstatus == true
+          object.trace_output << "!! #{$!.message.chomp}\n" 
+        end
+        object.trace_output << "#{arrow} #{method} for #{object}\n"
+      end
+ 
+    when 3
+      if exitstatus.kind_of? Array
+        object.trace_output << "<- #{method} for #{object.inspect} = #{exitstatus[0].inspect}\n" 
+      else
+        if exitstatus == true
+          object.trace_output << "!! #{$!.inspect}\n" 
+        end
+        object.trace_output << "<- #{method} for #{object.inspect}\n"
+      end
+    end
+  
+  end
+
+  private # helper methods -----------------------------------------------------
+
+  def methods(klass)
+    meths = (DBI::Handle.instance_methods | klass.instance_methods) - %w(trace_mode trace_output trace)
+    /(#{meths.collect{|m| Regexp.quote(m)}.join('|')})/
+  end
+
+end
+
+@@tracer_driver    = HandleTracer.new(DBI::DriverHandle)
+@@tracer_database  = HandleTracer.new(DBI::DatabaseHandle)
+@@tracer_statement = HandleTracer.new(DBI::StatementHandle)
+
+ 
+end # module DBI
+  

data/lib/dbi/types.rb

@@ -0,0 +1,158 @@
+require 'time'
+require 'bigdecimal'
+
+module DBI
+    #
+    # Interface to convert SQL result sets to native Ruby types.
+    #
+    # Type is used to convert result sets, which differ from bound variables
+    # (which generally go in the opposite direction). For those, see
+    # DBI::TypeUtil#convert and DBI::TypeUtil#register_conversion.
+    #
+    # Type objects have a simple interface: they implement a +parse+ method
+    # which takes the result from the DBD and attempts to convert it to the
+    # native type. In the event that they do not do this successfully, they are
+    # expected to return the object in its original form.
+    #
+    # As a result, many of the built-in Type classes fallback to simpler forms:
+    # Float falls back to Integer, Integer to Varchar, etc. It's questionable
+    # at this point if it's desirable to do this, but testing has so far proven
+    # it a non-issue.
+    #
+    # To reiterate, it is *never acceptable* to return +nil+ or some other
+    # placeholder when an object will not successfully parse. Return the object
+    # handed to you.
+    #
+    # Types must also handle +nil+ as a result to parse. In this case, the
+    # advisable solution is to just let the +nil+ pass through, as it's usually
+    # indicative of a SQL NULL result.
+    #
+    # DBI::Row handles delegation of these objects as a converter for the
+    # results. Typically, the type object is a class inferred from
+    # DBI::TypeUtil#type_name_to_module ran against the ColumnInfo field
+    # +type_name+. However, the the +dbi_type+ field can be used in its place
+    # to directly associate a Type object with the column in the DBD, and
+    # end-users can leverage StatementHandle#bind_coltype to manually tweak
+    # this transformation.
+    #
+    # As stated before, Type objects are objects. These objects may be Modules
+    # or Classes (and typically are), but there is no reason a traditional
+    # constructed object with a +parse+ method cannot be returned; in fact, it
+    # is used in a few spots to emulate complex types such as PostgreSQL
+    # arrays. Look into the +dbi_type+ ColumnInfo field to pass these types
+    # around.
+    #
+    module Type
+        #
+        # Represents a SQL NULL.
+        #
+        class Null
+            def self.parse(obj)
+                return nil if obj.to_s.match(/^null$/i)
+                return obj
+            end
+        end
+
+        #
+        # Represents a SQL char or varchar. General fallback class.
+        #
+        class Varchar 
+            def self.parse(obj)
+                return obj unless obj
+                return obj.to_s if obj.respond_to? :to_s
+                return obj.to_str if obj.respond_to? :to_str
+                return obj
+            end
+        end
+
+        #
+        # Represents a whole number. Falls back to Varchar.
+        #
+        class Integer < Varchar
+            def self.parse(obj)
+                return nil if Null.parse(obj).nil?
+                return obj.to_i if obj.respond_to? :to_i
+                super 
+            end
+        end
+
+        #
+        # Represents a decimal number with floating-point precision. Falls back
+        # to Integer.
+        #
+        class Float < Integer
+            def self.parse(obj)
+                return nil if Null.parse(obj).nil?
+                return obj.to_f if obj.respond_to? :to_f
+                super
+            end
+        end
+
+        #
+        # Represents a Decimal with real precision (BigDecimal). Falls back to
+        # Float.
+        #
+        class Decimal < Float
+            def self.parse(obj)
+                BigDecimal.new(obj) rescue super
+            end
+        end
+
+        #
+        # Represents a SQL TIMESTAMP and returns DateTime. Falls back to Null.
+        #
+        class Timestamp < Null
+            def self.parse(obj)
+                obj = super
+                return obj unless obj
+                case obj.class
+                when ::DateTime
+                    return obj
+                when ::Date
+                    return ::DateTime.parse(obj.to_s)
+                when ::Time
+                    return ::DateTime.parse(obj.to_s)
+                else
+                    return ::DateTime.parse(obj.to_s)   if obj.respond_to? :to_s
+                    return ::DateTime.parse(obj.to_str) if obj.respond_to? :to_str
+                    return obj
+                end
+            end
+        end
+
+        #
+        # Represents a SQL BOOLEAN. Returns true/false. Falls back to Null.
+        #
+        class Boolean < Null
+            def self.parse(obj)
+                obj = super
+
+                return nil if obj.nil?
+
+                if obj == false or obj.kind_of? FalseClass
+                    return false
+                elsif obj.kind_of? TrueClass
+                    return true
+                else
+                    case obj
+                    when 't'
+                        return true
+                    when 'f'
+                        return false
+                    end
+
+                    if obj.respond_to? :to_i
+                        if obj.to_i == 0
+                            return false
+                        else
+                            return true
+                        end
+                    else
+                        # punt
+                        return nil
+                    end
+                end
+            end
+        end
+    end
+end

data/lib/dbi/typeutil.rb

@@ -0,0 +1,108 @@
+module DBI
+    #
+    # TypeUtil is a series of utility methods for type management.
+    #
+    class TypeUtil
+        @@conversions = { }
+
+        #
+        # Register a conversion for a DBD. This applies to bound parameters for
+        # outgoing statements; please look at DBI::Type for result sets.
+        #
+        # Conversions are given a driver_name, which is then used to look up
+        # the conversion to perform on the object. Please see #convert for more
+        # information. Driver names are typically provided by the DBD, but may
+        # be overridden at any stage temporarily by assigning to the
+        # +driver_name+ attribute for the various handles.
+        #
+        # A conversion block is normally a +case+ statement that identifies
+        # various native ruby types and converts them to string, but ultimately
+        # the result type is dependent on low-level driver. The resulting
+        # object will be fed to the query as the bound value. 
+        #
+        # The result of the block is two arguments, the first being the result
+        # object, and the second being a +cascade+ flag, which if true
+        # instructs #convert to run the result through the +default+ conversion
+        # as well and use its result. This is advantageous when you just need
+        # to convert everything to string, and allow +default+ to properly escape
+        # it.
+        #
+        def self.register_conversion(driver_name, &block)
+            raise "Must provide a block" unless block_given?
+            @@conversions[driver_name] = block
+        end
+
+        #
+        # Convert object for +driver_name+. See #register_conversion for a
+        # complete explanation of how type conversion is performed.
+        #
+        # If the conversion is instructed to cascade, it will go to the special
+        # "default" conversion, which is a pre-defined common case (and
+        # mutable) ruleset for native types. Note that it will use the result
+        # from the first conversion, not what was originally passed. Be sure to
+        # leave the object untouched if that is your intent. E.g., if your DBD
+        # converts an Integer to String and tells it to cascade, the "default"
+        # conversion will get a String and quote it, not an Integer (which has
+        # different rules).
+        #
+        def self.convert(driver_name, obj)
+            if @@conversions[driver_name]
+                newobj, cascade = @@conversions[driver_name].call(obj)
+                if cascade
+                    return @@conversions["default"].call(newobj)
+                end
+                return newobj
+            end
+
+            return @@conversions["default"].call(obj)
+        end
+
+        # 
+        # Convenience method to match many SQL named types to DBI::Type classes. If
+        # none can be matched, returns DBI::Type::Varchar.
+        #
+        def self.type_name_to_module(type_name)
+            case type_name
+            when /^int(?:\d+|eger)?$/i
+                DBI::Type::Integer
+            when /^varchar$/i, /^character varying$/i
+                DBI::Type::Varchar
+            when /^(?:float|real)$/i
+                DBI::Type::Float
+            when /^bool(?:ean)?$/i, /^tinyint$/i
+                DBI::Type::Boolean
+            when /^time(?:stamp(?:tz)?)?$/i
+                DBI::Type::Timestamp
+            when /^(?:decimal|numeric)$/i
+                DBI::Type::Decimal
+            else
+                DBI::Type::Varchar
+            end
+        end
+    end
+end
+
+DBI::TypeUtil.register_conversion("default") do |obj|
+    case obj
+    when DBI::Binary # these need to be handled specially by the driver
+        obj
+    when ::NilClass
+        nil
+    when ::TrueClass
+        "'1'"
+    when ::FalseClass
+        "'0'"
+    when ::Time, ::Date, ::DateTime
+        "'#{::DateTime.parse(obj.to_s).strftime("%m/%d/%Y %H:%M:%S")}'"
+    when ::String
+        obj = obj.gsub(/\\/) { "\\\\" }
+        obj = obj.gsub(/'/) { "''" }
+        "'#{obj}'"
+    when ::BigDecimal
+        obj.to_s("F")
+    when ::Numeric
+        obj.to_s
+    else
+        "'#{obj.to_s}'"
+    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/utils/date.rb

@@ -0,0 +1,59 @@
+module DBI
+    #
+    # Represents a Date.
+    #
+    # DEPRECATED: Please use a regular Date or DateTime object.
+    #
+    class Date
+        attr_accessor :year, :month, :day
+
+        # Aliases
+        alias :mon :month
+        alias :mon= :month=
+        alias :mday :day
+        alias :mday= :day=
+
+        # Returns a new Time object based on the year, month and day or, if a
+        # Time object was passed to the constructor, returns that object.
+        def to_time
+            @original_time || ::Time.local(@year, @month, @day, 0, 0, 0)
+        end
+
+        # Returns a new Date object based on the year, month and day or, if a
+        # Date object was passed to the constructor, returns that object.
+        def to_date
+            @original_date || ::Date.new(@year, @month, @day)
+        end
+
+        # Returns a DBI::Date object as a string in YYYY-MM-DD format.
+        def to_s
+            sprintf("%04d-%02d-%02d", @year, @month, @day)
+        end
+
+        private 
+
+        # DBI::Date.new(year = 0, month = 0, day = 0)
+        # DBI::Date.new(Date)
+        # DBI::Date.new(Time)
+        #
+        # Creates and returns a new DBI::Date object.  It's similar to the
+        # standard Date class' constructor except that it also accepts a
+        # Date or Time object.
+        def initialize(year=0, month=0, day=0)
+            case year
+            when ::Date
+                @year, @month, @day = year.year, year.month, year.day 
+                @original_date = year
+            when ::Time
+                @year, @month, @day = year.year, year.month, year.day 
+                @original_time = year
+            else
+                @year, @month, @day = year, month, day
+            end
+        end
+
+        public
+
+        deprecate :initialize, :public
+    end
+end