ydbi 0.5.0

data/lib/dbi/base_classes/driver.rb

@@ -0,0 +1,47 @@
+module DBI
+
+    # Implements the basic functionality that constitutes a Driver
+    #
+    # Drivers do not have a direct interface exposed to the user; these methods
+    # are mostly for DBD authors.
+    #
+    # As with DBI::BaseDatabase, "DBD Required" and "DBD Optional" will be used
+    # to explain the same requirements.
+    #
+    class BaseDriver < Base
+        def initialize(dbi_version)
+            major, minor = dbi_version.split(".").collect { |x| x.to_i }
+            dbi_major, dbi_minor = DBI::VERSION.split(".").collect { |x| x.to_i }
+            unless major == dbi_major and minor == dbi_minor
+                raise InterfaceError, "Wrong DBD API version used"
+            end
+        end
+
+        # Connect to the database. DBD Required.
+        def connect(dbname, user, auth, attr)
+            raise NotImplementedError
+        end
+
+        # Default u/p information in an array.
+        def default_user
+            ['', '']
+        end
+
+        # Default attributes to set on the DatabaseHandle.
+        def default_attributes
+            {}
+        end
+
+        # Return the data sources available to this driver. Returns an empty
+        # array per default.
+        def data_sources
+            []
+        end
+
+        # Disconnect all DatabaseHandles. DBD Required.
+        def disconnect_all
+            raise NotImplementedError
+        end
+
+    end # class BaseDriver
+end

data/lib/dbi/base_classes/statement.rb

@@ -0,0 +1,171 @@
+module DBI
+    #
+    # StatementHandles are used to encapsulate the process of managing a
+    # statement (DDL or DML) and its parameters, sending it to the database,
+    # and gathering any results from the execution of that statement.
+    #
+    # As with the other `Base` classes, the terms "DBD Required" and "DBD
+    # Optional" are defined in DBI::BaseDatabase.
+    #
+    class BaseStatement < Base
+
+        attr_accessor :raise_error
+
+        def initialize(attr=nil)
+            @attr = attr || {}
+        end
+
+        #
+        # Bind a parameter to the statement. DBD Required.
+        #
+        # The parameter number is numeric and indexes starting at 1. This
+        # corresponds to the question marks (?) in the statement from the
+        # left-most part of the statement moving forward.
+        #
+        # The value may be any ruby type. How these are handled is
+        # DBD-dependent, but the vast majority of DBDs will convert these to
+        # string inside the query.
+        #
+        def bind_param(param, value, attribs)
+            raise NotImplementedError
+        end
+
+        #
+        # Execute the statement with the known binds. DBD Required.
+        #
+        def execute
+            raise NotImplementedError
+        end
+
+        #
+        # Close the statement and any result cursors. DBD Required.
+        #
+        # Note:: Most implementations will fail miserably if you forget to
+        #        finish your statement handles.
+        def finish
+            raise NotImplementedError
+        end
+
+        #
+        # Fetch the next row in the result set. DBD Required.
+        #
+        # DBI::Row is responsible for formatting the data the DBD provides it.
+        #
+        def fetch
+            raise NotImplementedError
+        end
+
+        ##
+        # returns result-set column information as array
+        # of hashs, where each hash represents one column. See
+        # BaseDatabase#columns. DBD Required.
+        #
+        def column_info
+            raise NotImplementedError
+        end
+
+        #============================================
+        # OPTIONAL
+        #============================================
+
+        #
+        # Take a list of bind variables and bind them successively using bind_param.
+        #
+        def bind_params(*bindvars)
+            bindvars.each_with_index {|val,i| bind_param(i+1, val, nil) }
+            self
+        end
+
+        #
+        # Cancel any result cursors. DBD Optional, but intentionally does not
+        # raise any exception as it's used internally to maintain consistency.
+        #
+        def cancel
+        end
+
+        #
+        # fetch_scroll is provided with a direction and offset and works
+        # similar to how seek() is used on files.
+        #
+        # The constants available for direction are as follows:
+        # 
+        # * SQL_FETCH_NEXT: fetch the next result.
+        # * SQL_FETCH_LAST: fetch the last result, period.
+        # * SQL_FETCH_RELATIVE: fetch the result at the offset. 
+        #
+        # Other constants can be used, but if this method is not supplied by
+        # the driver, they will result in a raise of DBI::NotSupportedError.
+        #
+
+        def fetch_scroll(direction, offset)
+            case direction
+            when SQL_FETCH_NEXT
+                return fetch
+            when SQL_FETCH_LAST
+                last_row = nil
+                while (row=fetch) != nil
+                    last_row = row
+                end
+                return last_row
+            when SQL_FETCH_RELATIVE
+                raise NotSupportedError if offset <= 0
+                row = nil
+                offset.times { row = fetch; break if row.nil? }
+                return row
+            else
+                raise NotSupportedError
+            end
+        end
+
+        #
+        # fetch x rows. The result is Array of DBI::Row.
+        #
+        def fetch_many(cnt)
+            rows = []
+            cnt.times do
+                row = fetch
+                break if row.nil?
+                rows << row.dup
+            end
+
+            if rows.empty?
+                nil
+            else
+                rows
+            end
+        end
+
+        #
+        # Fetch all available rows. Result is Array of DBI::Row.
+        #
+        def fetch_all
+            rows = []
+            loop do
+                row = fetch
+                break if row.nil?
+                rows << row.dup
+            end
+
+            if rows.empty?
+                nil
+            else
+                rows
+            end
+        end
+
+        #
+        # Get statement attributes.
+        #
+        def [](attr)
+            @attr ||= { }
+            @attr[attr]
+        end
+
+        #
+        # Set statement attributes. DBD Optional.
+        #
+        def []=(attr, value)
+            raise NotSupportedError
+        end
+    end # class BaseStatement
+end

data/lib/dbi/binary.rb

@@ -0,0 +1,25 @@
+module DBI
+    #
+    # Encapsulates the concept of a CLOB/BLOB, which can then be passed as a
+    # bind via BaseStatement#bind_param.
+    #
+    # This is similar to a DBI::Type class and will eventually find its way
+    # there.
+    #
+    # See #new for usage.
+    class Binary
+        attr_accessor :data
+
+        # Construct a new DBI::Binary object with the data supplied as string.
+        # This object can then be used in bound variables to represent a CLOB
+        # or BLOB type.
+        def initialize(data)
+            @data = data
+        end
+
+        # Return the string representation of the DBI::Binary object.
+        def to_s
+            @data
+        end
+    end
+end

data/lib/dbi/columninfo.rb

@@ -0,0 +1,107 @@
+require 'delegate'
+
+begin
+    require 'rubygems'
+    gem 'deprecated', "= 2.0.1"
+rescue LoadError => e
+end
+
+require 'deprecated'
+
+module DBI
+    # This represents metadata for columns within a given table, such as the
+    # data type, whether or not the the column is a primary key, etc.
+    #
+    # ColumnInfo is a delegate of Hash, but represents its keys indifferently,
+    # coercing all strings to symbols. It also has ostruct-like features, f.e.:
+    #
+    #   h = ColumnInfo.new({ "foo" => "bar" })
+    #   h[:foo] => "bar"
+    #   h["foo"] => "bar"
+    #   h.foo => "bar"
+    #
+    # All of these forms have assignment forms as well.
+    #
+    class ColumnInfo < DelegateClass(Hash)
+
+        # Create a new ColumnInfo object.
+        #
+        # If no Hash is provided, one will be created for you. The hash will be
+        # shallow cloned for storage inside the object, and an attempt will be
+        # made to convert all string keys to symbols.
+        #
+        # In the event that both string and symbol keys are provided in the
+        # initial hash, we cannot safely route around collisions and therefore
+        # a TypeError is raised.
+        #
+        def initialize(hash=nil)
+            @hash = hash.dup rescue nil
+            @hash ||= Hash.new
+
+            # coerce all strings to symbols
+            @hash.keys.each do |x|
+                if x.kind_of? String
+                    sym = x.to_sym
+                    if @hash.has_key? sym
+                        raise ::TypeError, 
+                            "#{self.class.name} may construct from a hash keyed with strings or symbols, but not both" 
+                    end
+                    @hash[sym] = @hash[x]
+                    @hash.delete(x)
+                end
+            end
+
+            super(@hash)
+        end
+
+        def [](key)
+            @hash[key.to_sym]
+        end
+
+        def []=(key, value)
+            @hash[key.to_sym] = value
+        end
+
+        def default() # :nodoc; XXX hack to get around Hash#default
+            method_missing(:default)
+        end
+
+        def method_missing(sym, value=nil)
+            if sym.to_s =~ /=$/
+                sym = sym.to_s.sub(/=$/, '').to_sym
+                @hash[sym] = value
+            elsif sym.to_s =~ /\?$/
+                sym = sym.to_s.sub(/\?$/, '').to_sym
+                @hash[sym]
+            else
+                @hash[sym]
+            end
+        end
+
+        # Aliases - XXX soon to be deprecated
+        def self.deprecated_alias(target, source) # :nodoc:
+            define_method(target) { |*args| method_missing(source, *args) }
+            deprecate target 
+        end
+
+        deprecated_alias :is_nullable?, :nullable
+        deprecated_alias :can_be_null?, :nullable
+
+        deprecated_alias :is_indexed?, :indexed
+
+        deprecated_alias :is_primary?, :primary
+
+        deprecated_alias :is_unique, :unique
+
+        deprecated_alias :size, :precision
+        deprecated_alias :size=, :precision=
+        deprecated_alias :length, :precision
+        deprecated_alias :length=, :precision=
+
+        deprecated_alias :decimal_digits, :scale
+        deprecated_alias :decimal_digits=, :scale=
+
+        deprecated_alias :default_value, :default
+        deprecated_alias :default_value=, :default=
+    end
+end

data/lib/dbi/exceptions.rb

@@ -0,0 +1,65 @@
+module DBI
+    #  Exceptions (borrowed by Python API 2.0)
+
+    # Base class of all other error exceptions.  Use this to catch all DBI
+    # errors.
+    class Error < RuntimeError
+    end
+
+    # For important warnings like data truncation, etc.
+    class Warning < RuntimeError
+    end
+
+    # Exception for errors related to the DBI interface rather than the
+    # database itself.
+    class InterfaceError < Error
+    end
+
+    # Exception raised if the DBD driver has not specified a mandatory method.
+    class NotImplementedError < InterfaceError
+    end
+
+    # Exception for errors related to the database.
+    class DatabaseError < Error
+        attr_reader :err, :errstr, :state
+
+        def initialize(errstr="", err=nil, state=nil)
+            super(errstr)
+            @err, @errstr, @state = err, errstr, state
+        end
+    end
+
+    # Exception for errors due to problems with the processed 
+    # data such as division by zero, numeric value out of range, etc.
+    class DataError < DatabaseError
+    end
+
+    # Exception for errors related to the database's operation which are not
+    # necessarily under the control of the programmer.  This includes such
+    # things as unexpected disconnect, datasource name not found, transaction
+    # could not be processed, a memory allocation error occured during
+    # processing, etc.
+    class OperationalError < DatabaseError
+    end
+
+    # Exception raised when the relational integrity of the database
+    # is affected, e.g. a foreign key check fails.
+    class IntegrityError < DatabaseError
+    end
+
+    # Exception raised when the database encounters an internal error, 
+    # e.g. the cursor is not valid anymore, the transaction is out of sync.
+    class InternalError < DatabaseError
+    end
+
+    # Exception raised for programming errors, e.g. table not found
+    # or already exists, syntax error in SQL statement, wrong number
+    # of parameters specified, etc.
+    class ProgrammingError < DatabaseError
+    end
+
+    # Exception raised if e.g. commit() is called for a database which do not
+    # support transactions.
+    class NotSupportedError < DatabaseError
+    end
+end

data/lib/dbi/handles.rb

@@ -0,0 +1,49 @@
+#
+# Dispatch classes (Handle, DriverHandle, DatabaseHandle and StatementHandle)
+#
+
+module DBI
+    #
+    # Base class for all handles.
+    #
+    class Handle
+        attr_reader :trace_mode, :trace_output
+        attr_reader :handle 
+        attr :convert_types, true
+
+        def initialize(handle, convert_types=true)
+            @handle = handle
+            @trace_mode = @trace_output = nil
+            @convert_types = convert_types
+        end
+
+        # Please seee DBI.trace.
+        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
+
+        #
+        # Leverage a driver-specific method. The method name will have "__"
+        # prepended to them before calling, and the DBD must define them as
+        # such for them to work.
+        #
+        def func(function, *values)
+            if @handle.respond_to?("__" + function.to_s) then
+                @handle.send("__" + function.to_s, *values)  
+            else
+                raise InterfaceError, "Driver specific function <#{function}> not available."
+            end
+        rescue ArgumentError
+            raise InterfaceError, "Wrong # of arguments for driver specific function"
+        end
+
+        # error functions?
+    end
+end
+
+require 'dbi/handles/driver'
+require 'dbi/handles/database'
+require 'dbi/handles/statement'