rails-dbi 0.1.0

data/lib/dbi/types.rb

@@ -0,0 +1,218 @@
+require 'time'
+require 'bigdecimal'
+require 'rational'
+
+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.create(year, month, day, hour, min, sec, usec=0, of=0)
+                # DateTime will remove leap and leap-leap seconds
+                sec = 59 if sec > 59
+                # store this before we modify it
+                civil = year, month, day
+                time  = hour, min, sec, usec
+                
+                date = ::DateTime.civil(year, month, day, hour, min, sec, of)
+                date += usec
+                #prefill_cache date, civil, time
+                date
+            end
+
+            # FIXME these methods are broken, I don't know why, and I don't really care right now.
+            #       we shouldn't be playing in datetime's garden anyways.
+            if RUBY_VERSION =~ /^1\.8\./
+                def self.prefill_cache date, civil, time
+                    time[3] /= 86400000000.0
+                    date.instance_variable_set :"@__#{:civil.to_i}__", [civil]
+                    date.instance_variable_set :"@__#{:time.to_i}__",  [time]
+                end
+            else
+                def self.prefill_cache date, civil, time
+                    time[3] /= 1000000.0
+                    date.instance_variable_get(:@__ca__)[:civil.object_id] = civil
+                    date.instance_variable_get(:@__ca__)[:time.object_id] = time
+                end
+            end
+
+            def self.parse_string str
+                # special casing the common formats here gives roughly an
+                # 8-fold speed boost over using Date._parse
+                case str
+                when /^(\d{4})-(\d{2})-(\d{2})(?: (\d{2}):(\d{2}):(\d{2})(\.\d+)?)?(?: ([+-]?\d{2}):?(\d{2}))?$/
+                    parts = $~[1..-4].map { |s| s.to_i }
+                    # i feel unclean. if we have fractional seconds, pad the number and then stuff it into a rational.
+                    if $7
+                        frac = $7.to_f * 10000000
+                        parts << Rational(frac.to_i, 864000000000)
+                    else
+                        parts << 0
+                    end
+                    parts << Rational(($8 || 0).to_i * 60 + ($9 || 0).to_i, 1440)
+                else
+                    parts = ::Date._parse(str).values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset)
+                    # some defaults
+                    today = nil
+                    8.times do |i|
+                        next if parts[i]
+                        today ||= ::Time.now.to_a.values_at(5, 4, 3) + [0, 0, 0, 0, 0]
+                        parts[i] = today[i]
+                    end
+                    parts[6] = parts[6].kind_of?(Rational) ? parts[6] : Rational(parts[6], 1)
+                    parts[6] *= Rational(1, 86400)
+                    parts[7] = Rational(parts[7], 86400)
+                end
+                parts
+            end
+
+            def self.parse(obj)
+                case obj
+                when ::DateTime
+                    return obj
+                when ::Date
+                    return create(obj.year, obj.month, obj.day, 0, 0, 0)
+                when ::Time
+                    return create(obj.year, obj.month, obj.day, obj.hour, obj.min, obj.sec, Rational(obj.usec, 86400000000), Rational(obj.utc_offset, 86400))
+                else
+                    obj = super
+                    return obj unless obj
+                    return create(*parse_string(obj.to_s))   if obj.respond_to? :to_s
+                    return create(*parse_string(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,109 @@
+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("%Y-%m-%dT%H:%M:%S")}'"
+    when ::String, ::Symbol
+        obj = obj.to_s
+        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/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

data/lib/dbi/utils/tableformatter.rb

@@ -0,0 +1,112 @@
+module DBI
+    module Utils
+        # Formats a resultset in a textual table, suitable for printing.
+        module TableFormatter
+
+            def self.coerce(obj) # :nodoc:
+                # FIXME this is probably short-sighted.
+                obj = "NULL" if obj.nil?
+                obj = (obj.kind_of?(Array) or obj.kind_of?(Hash)) ? obj.inspect : obj.to_s
+                return obj
+            end
+
+            # Perform the formatting.
+            #
+            # * +header+: table headers, as you'd expect they correspond to each column in the row.
+            # * +rows+: array of array (or DBI::Row) which represent the data.
+            # * +header_orient+: jusification of the header. :left, :right, or :center.
+            # * +rows_orient+: justification of the rows. same as +header_orient+.
+            # * +indent+: number of spaces to indent each line in the output.
+            # * +cellspace+: number of spaces to pad the cell on the left and right.
+            # * +pagebreak_after+: introduce a pagebreak each +n+ rows.
+            # * +output+: object that responds to `<<` which will contain the output. Default is STDOUT.
+            #
+            # If a block is provided, +output+ will be yielded each row if
+            # +pagebreak+ is nil, otherwise it will be yielded when the output
+            # is complete.
+            #--
+            # TODO: add a nr-column where the number of the column is shown
+            #++
+            def self.ascii(header, 
+                           rows, 
+                           header_orient=:left, 
+                           rows_orient=:left, 
+                           indent=2, 
+                           cellspace=1, 
+                           pagebreak_after=nil,
+                           output=STDOUT)
+
+                if rows.size == 0 or rows[0].size == 0
+                    output.puts "No rows selected"
+                    return
+                end
+
+                header_orient ||= :left
+                rows_orient   ||= :left
+                indent        ||= 2
+                cellspace     ||= 1
+
+                # pagebreak_after n-rows (without counting header or split-lines)
+                # yield block with output as param after each pagebreak (not at the end)
+
+                col_lengths = (0...(header.size)).collect do |colnr|
+                    [
+                        (0...rows.size).collect { |rownr|
+                        value = rows[rownr][colnr]
+                        coerce(value).size
+                    }.max,
+                        header[colnr].size
+                    ].max
+                end
+
+                indent = " " * indent
+
+                split_line = indent + "+"
+                col_lengths.each {|col| split_line << "-" * (col+cellspace*2) + "+" }
+
+                cellspace = " " * cellspace
+
+                output_row = proc {|row, orient|
+                    output << indent + "|"
+                    row.each_with_index {|c,i|
+                        output << cellspace
+
+                        str = coerce(c)
+
+                        output << case orient
+                        when :left then   str.ljust(col_lengths[i])
+                        when :right then  str.rjust(col_lengths[i])
+                        when :center then str.center(col_lengths[i])
+                        end 
+                        output << cellspace
+                        output << "|"
+                    }
+                    output << "\n" 
+                } 
+
+                rownr = 0
+
+                loop do 
+                    output << split_line + "\n"
+                    output_row.call(header, header_orient)
+                    output << split_line + "\n"
+                    if pagebreak_after.nil?
+                        rows.each {|ar| output_row.call(ar, rows_orient)}
+                        output << split_line + "\n"
+                        break
+                    end      
+
+                    rows[rownr,pagebreak_after].each {|ar| output_row.call(ar, rows_orient)}
+                    output << split_line + "\n"
+
+                    rownr += pagebreak_after
+
+                    break if rownr >= rows.size
+
+                    yield output if block_given?
+                end
+
+            end
+        end # module TableFormatter
+    end
+end

data/lib/dbi/utils/time.rb

@@ -0,0 +1,52 @@
+module DBI
+    #
+    # Represents a Time
+    #
+    # DEPRECATED: Please use a regular Time or DateTime object.
+   class Time
+      attr_accessor :hour, :minute, :second
+
+      private
+      # DBI::Time.new(hour = 0, minute = 0, second = 0)
+      # DBI::Time.new(Time)
+      #
+      # Creates and returns a new DBI::Time object.  Unlike the Time object
+      # in the standard library, accepts an hour, minute and second, or a
+      # Time object.
+      def initialize(hour=0, minute=0, second=0)
+         case hour
+            when ::Time
+               @hour, @minute, @second = hour.hour, hour.min, hour.sec
+               @original_time = hour
+            else
+               @hour, @minute, @second = hour, minute, second
+         end
+      end
+
+      public
+      
+      deprecate :initialize, :public
+
+      alias :min :minute
+      alias :min= :minute=
+      alias :sec :second
+      alias :sec= :second=
+
+      # Returns a new Time object based on the hour, minute and second, using
+      # the current year, month and day.  If a Time object was passed to the
+      # constructor, returns that object instead.
+      def to_time
+         if @original_time
+            @original_time
+         else
+            t = ::Time.now
+            ::Time.local(t.year, t.month, t.day, @hour, @minute, @second)
+         end
+      end
+
+      # Returns a DBI::Time object as a string in HH:MM:SS format.
+      def to_s
+         sprintf("%02d:%02d:%02d", @hour, @minute, @second)
+      end
+   end
+end

data/lib/dbi/utils/timestamp.rb

@@ -0,0 +1,96 @@
+module DBI
+    #
+    # Represents a Timestamp.
+    #
+    # DEPRECATED: Please use a regular DateTime object.
+    #
+   class Timestamp
+      attr_accessor :year, :month, :day
+      attr_accessor :hour, :minute, :second
+      attr_writer   :fraction
+
+      private
+      # DBI::Timestamp(year=0,month=0,day=0,hour=0,min=0,sec=0,fraction=nil)
+      # DBI::Timestamp(Time)
+      # DBI::Timestamp(Date)
+      #
+      # Creates and returns a new DBI::Timestamp object.  This is similar to
+      # a Time object in the standard library, but it also contains fractional
+      # seconds, expressed in nanoseconds.  In addition, the constructor
+      # accepts either a Date or Time object.
+      def initialize(year=0, month=0, day=0, hour=0, min=0, sec=0, fraction=nil)
+         case year
+            when ::Time
+               @year, @month, @day = year.year, year.month, year.day 
+               @hour, @minute, @second, @fraction = year.hour, year.min, year.sec, nil 
+               @original_time = year
+            when ::Date
+               @year, @month, @day = year.year, year.month, year.day 
+               @hour, @minute, @second, @fraction = 0, 0, 0, nil 
+               @original_date = year
+            else
+               @year, @month, @day = year, month, day
+               @hour, @minute, @second, @fraction = hour, min, sec, fraction
+         end
+      end
+
+      public
+      
+      deprecate :initialize, :public
+
+      # Returns true if +timestamp+ has a year, month, day, hour, minute,
+      # second and fraction equal to the comparing object.
+      #
+      # Returns false if the comparison fails for any reason.
+      def ==(timestamp)
+         @year == timestamp.year and @month == timestamp.month and
+         @day == timestamp.day and @hour == timestamp.hour and
+         @minute == timestamp.minute and @second == timestamp.second and
+         (fraction() == timestamp.fraction)
+      rescue
+         false
+      end
+
+      # Returns fractional seconds, or 0 if not set.
+      def fraction
+         @fraction || 0
+      end
+
+      # Aliases
+      alias :mon :month
+      alias :mon= :month=
+      alias :mday :day
+      alias :mday= :day=
+      alias :min :minute
+      alias :min= :minute=
+      alias :sec :second
+      alias :sec= :second=
+
+      # Returns a DBI::Timestamp object as a string in YYYY-MM-DD HH:MM:SS
+      # format.  If a fraction is present, then it is appended in ".FF" format.
+      def to_s
+         string = sprintf("%04d-%02d-%02d %02d:%02d:%02d",
+             @year, @month, @day, @hour, @minute, @second) 
+
+         if @fraction
+            fraction = ("%.9f" % (@fraction.to_i / 1e9)).
+                        to_s[1..-1].gsub(/0{1,8}$/, "")
+            string += fraction
+         end
+
+         string
+      end
+
+      # 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, @hour, @minute, @second)
+      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
+   end
+end