dbi 0.4.0

data/lib/dbi/row.rb

@@ -0,0 +1,249 @@
+require "delegate"
+
+module DBI
+    # DBI::Row is the representation of a row in a result set returned by the
+    # database.
+    #
+    # It is responsible for containing and representing the result set, converting
+    # it to native Ruby types, and providing methods to sanely move through itself. 
+    #
+    # The DBI::Row class is a delegate of Array, rather than a subclass, because
+    # there are times when it should act like an Array, and others when it should
+    # act like a Hash (and still others where it should act like String, Regexp,
+    # etc).  It also needs to store metadata about the row, such as
+    # column data type and index information, that users can then access.
+    #
+    class Row < DelegateClass(Array)
+        attr_reader :column_names
+
+        # DBI::Row.new(columns, column_types, size_or_array=nil)
+        #
+        # Returns a new DBI::Row object using +columns+.  The +size_or_array+
+        # argument may either be an Integer or an Array.  If it is not provided,
+        # it defaults to the length of +columns+.
+        #
+        # Column types is a corresponding Array of Class/Module objects that
+        # conform to the DBI::Type interface. These will be used to convert types
+        # as they are returned.
+        #
+        # DBI::Row is a delegate of the Array class, so all of the Array
+        # instance methods are available to your DBI::Row object (keeping in
+        # mind that initialize, [], and []= have been explicitly overridden).
+        #
+        def initialize(columns, column_types, size_or_array=nil, convert_types=true)
+            @column_types = column_types
+            @convert_types = convert_types
+            size_or_array ||= columns.size 
+            
+            # The '@column_map' is used to map column names to integer values so
+            # that users can reference row values by name or number.
+
+            @column_map   = {}
+            @column_names = columns
+            columns.each_with_index { |c,i| @column_map[c] = i }
+
+            case size_or_array
+            when Integer
+                super(@arr = Array.new(size_or_array))
+            when Array
+                super(@arr = size_or_array.dup)
+                set_values(size_or_array.dup)
+            else
+                raise TypeError, "parameter must be either Integer or Array"
+            end
+        end
+
+        # converts the types in the array to their specified representation
+        # from column types provided at construction time.
+        def convert_types(arr)
+            return arr.dup unless @convert_types
+
+            if arr.size != @column_types.size
+                raise TypeError, "Type mapping is not consistent with result"
+            end
+            new_arr = []
+            arr.each_with_index do |item, i|
+                new_arr.push((@column_types[i] || DBI::Type::Varchar).parse(item))
+            end
+
+            return new_arr
+        end
+
+        # Replaces the contents of the internal array with +new_values+.
+        # elements are type converted at this time.
+        def set_values(new_values)
+            @arr.replace(convert_types(new_values))
+        end
+
+        # Yields a column value by name (rather than index), along with the
+        # column name itself.
+        def each_with_name
+            @arr.each_with_index do |v, i|
+                yield v, @column_names[i]
+            end 
+        end
+
+        # returns the underlying array (duplicated)
+        def to_a
+            @arr.dup
+        end
+
+        # Returns the Row object as a hash, created by #each_with_name.
+        def to_h
+            hash = {}
+            each_with_name{ |v, n| hash[n] = v}
+            hash
+        end
+
+        # Create a new row with 'new_values', reusing the field name hash.
+        # Initial cloning is done deeply, via Marshal.
+        def clone_with(new_values)
+            obj = Marshal.load(Marshal.dump(self))
+            obj.set_values(new_values)
+
+            return obj
+        end
+
+        alias field_names column_names
+
+        # Retrieve a value by index (rather than name).
+        #
+        # Deprecated.  Since Row delegates to Array, just use Row#at.
+        def by_index(index)
+            @arr[index]
+        end
+
+        # Value of the field named +field_name+ or nil if not found.
+        def by_field(field_name)
+            begin
+                @arr[@column_map[field_name.to_s]]
+            rescue TypeError
+                nil
+            end
+        end
+
+        # Row#[]
+        #
+        # row[int]
+        # row[array]
+        # row[regexp]
+        # row[arg, arg]
+        # row[arg, arg, ...]
+        #
+        # Sample: Row.new(["first","last","age"], ["Daniel", "Berger", "36"])
+        #
+        # Retrieves row elements.  Exactly what it retrieves depends on the
+        # kind and number of arguments used.
+        #
+        # Zero arguments will raise an ArgumentError.
+        #
+        # One argument will return a single result.  This can be a String,
+        # Symbol, Integer, Range or Regexp and the appropriate result will
+        # be returned.  Strings, Symbols and Regexps act like hash lookups,
+        # while Integers and Ranges act like Array index lookups.
+        #
+        # Two arguments will act like the second form of Array#[], i.e it takes
+        # two integers, with the first number the starting point and the second
+        # number the length, and returns an array of values.
+        #
+        # If three or more arguments are provided, an array of results is
+        # returned.  The behavior for each argument is that of a single argument,
+        # i.e. Strings, Symbols, and Regexps act like hash lookups, while
+        # Integers and Ranges act like Array index lookups.
+        # 
+        # If no results are found, or an unhandled type is passed, then nil
+        # (or a nil element) is returned.
+        #
+        def [](*args)
+            begin
+                case args.length
+                when 0
+                    err = "wrong # of arguments(#{args.size} for at least 1)"
+                    raise ArgumentError, err
+                when 1
+                    case args[0]
+                    when Array
+                        args[0].collect { |e| self[e] }
+                    when Regexp
+                        self[@column_names.grep(args[0])] 
+                    else
+                        @arr[conv_param(args[0])]
+                    end
+                    # We explicitly check for a length of 2 in order to properly
+                    # simulate the second form of Array#[].
+                when 2
+                    @arr[conv_param(args[0]), conv_param(args[1])]
+                else
+                    results = []
+                    args.flatten.each{ |arg|
+                        case arg
+                        when Integer
+                            results.push(@arr[arg])
+                        when Regexp
+                            results.push(self[@column_names.grep(arg)])
+                        else
+                            results.push(self[conv_param(arg)])
+                        end
+                    }
+                    results.flatten
+                end
+            rescue TypeError
+                nil
+            end
+        end
+
+        # Assign a value to a Row object by element.  You can assign using
+        # a single element reference, or by using a start and length similar
+        # to the second form of Array#[]=.
+        #
+        # row[0]     = "kirk"
+        # row[:last] = "haines"
+        # row[0, 2]  = "test" 
+        #
+        def []=(key, value_or_length, obj=nil)
+            if obj
+                @arr[conv_param(key), conv_param(value_or_length)] = obj
+            else
+                @arr[conv_param(key)] = value_or_length
+            end
+        end
+
+        #
+        # See Object#clone.
+        #
+        # #clone and #dup here, however, are both deep copies via Marshal.
+        #
+        def clone
+            Marshal.load(Marshal.dump(self))
+        end
+
+        alias dup clone
+
+        private
+
+        # Simple helper method to grab the proper value from @column_map
+        # NOTE this does something completely different than DBI::Utils::ConvParam
+        def conv_param(arg) # :nodoc:
+            case arg
+            when String, Symbol
+                @column_map[arg.to_s]
+            when Range
+                if arg.first.kind_of?(Symbol) || arg.first.kind_of?(String)
+                    first = @column_map[arg.first.to_s]
+                    last  = @column_map[arg.last.to_s]
+                else
+                    first = arg.first
+                    last  = arg.last
+                end
+
+                if arg.exclude_end?
+                    (first...last) 
+                else
+                    (first..last)
+                end
+            else
+                arg
+            end
+        end
+    end # class Row
+end # module DBI

data/lib/dbi/sql.rb

@@ -0,0 +1,23 @@
+#
+# $Id: sql.rb,v 1.3 2006/03/27 20:25:02 francis Exp $
+#
+# parts extracted from Jim Weirichs DBD::Pg
+#
+
+require "dbi/utils"
+require "parsedate"
+require "time"
+
+module DBI
+    # the SQL package contains assistance for DBDs and generally will not be
+    # needed outside of them.
+    module SQL
+        # Helper to determine if the statement is a query. Very crude and
+        # should not be relied on for accuracy.
+        def self.query?(sql)
+            sql =~ /^\s*select\b/i
+        end
+    end # module SQL
+end # module DBI
+
+require 'dbi/sql/preparedstatement'

data/lib/dbi/sql/preparedstatement.rb

@@ -0,0 +1,115 @@
+module DBI
+    module SQL
+        #
+        # The PreparedStatement class attempts to provide binding functionality
+        # for database systems that do not have this built-in. This package
+        # emulates the whole concept of a statement.
+        #
+        class PreparedStatement
+            attr_accessor :unbound
+
+            # Convenience method for consumers that just need the tokens
+            # method.
+            def self.tokens(sql)
+                self.new(nil, sql).tokens
+            end
+
+            #
+            # "prepare" a statement.
+            #
+            # +quoter+ is deprecated and will eventually disappear, it is kept
+            # currently for compatibility. It is safe to pass nil to this parameter.
+            #
+            # +sql+ is the statement itself.
+            #
+            def initialize(quoter, sql)
+                @quoter, @sql = quoter, sql
+                prepare
+            end
+
+            # Break the sql string into parts.
+            #
+            # This is NOT a full lexer for SQL.  It just breaks up the SQL
+            # string enough so that question marks, double question marks and
+            # quoted strings are separated.  This is used when binding
+            # arguments to "?" in the SQL string.  
+            #
+            # C-style (/* */) and Ada-style (--) comments are handled.
+            # Note:: Nested C-style comments are NOT handled!
+            #
+            def tokens
+                @sql.scan(%r{
+                    (
+                        -- .*                               (?# matches "--" style comments to the end of line or string )
+                        |   -                                   (?# matches single "-" )
+                        |
+                        /[*] .*? [*]/                       (?# matches C-style comments )
+                        |   /                                   (?# matches single slash )    
+                        |
+                        ' ( [^'\\]  |  ''  |  \\. )* '  (?# match strings surrounded by apostophes )
+                        |
+                        " ( [^"\\]  |  ""  |  \\. )* "      (?# match strings surrounded by " )
+                        |
+                        \?\??                               (?# match one or two question marks )
+                        |
+                        [^-/'"?]+                           (?# match all characters except ' " ? - and / )
+
+                )}x).collect {|t| t.first}
+            end
+
+            # attempts to bind the arguments in +args+ to this statement.
+            # Will raise StandardError if there are any extents issues.
+            def bind(args)
+                if @arg_index < args.size
+                    raise "Too many SQL parameters"
+                elsif @arg_index > args.size
+                    raise "Not enough SQL parameters"
+                end
+
+                @unbound.each do |res_pos, arg_pos|
+                    @result[res_pos] = args[arg_pos]
+                end
+
+                @result.join("")
+            end
+
+            private
+
+            # prepares the statement for binding. This is done by scanning the
+            # statement and itemizing what needs to be bound and what does not.
+            # 
+            # This information will then be used by #bind to appropriately map
+            # parameters to the intended destinations.
+            def prepare
+                @result = [] 
+                @unbound = {}
+                pos = 0
+                @arg_index = 0
+
+                tokens.each { |part|
+                    case part
+                    when '?'
+                        @result[pos] = nil
+                        @unbound[pos] = @arg_index
+                        pos += 1
+                        @arg_index += 1
+                    when '??'
+                        if @result[pos-1] != nil
+                            @result[pos-1] << "?"
+                        else
+                            @result[pos] = "?"
+                            pos += 1
+                        end
+                    else
+                        if @result[pos-1] != nil
+                            @result[pos-1] << part
+                        else
+                            @result[pos] = part
+                            pos += 1
+                        end
+                    end
+                }
+            end
+        end # PreparedStatement
+    end
+end

data/lib/dbi/sql_type_constants.rb

@@ -0,0 +1,75 @@
+module DBI
+    #  Constants
+
+    # Constants for fetch_scroll
+    #
+    SQL_FETCH_NEXT     = 1
+    SQL_FETCH_PRIOR    = 2
+    SQL_FETCH_FIRST    = 3
+    SQL_FETCH_LAST     = 4
+    SQL_FETCH_ABSOLUTE = 5
+    SQL_FETCH_RELATIVE = 6
+
+    # SQL type constants
+    # 
+    SQL_CHAR       = 1
+    SQL_NUMERIC    = 2
+    SQL_DECIMAL    = 3
+    SQL_INTEGER    = 4
+    SQL_SMALLINT   = 5
+    SQL_FLOAT      = 6
+    SQL_REAL       = 7
+    SQL_DOUBLE     = 8
+    SQL_DATE       = 9  # 91
+    SQL_TIME       = 10 # 92 
+    SQL_TIMESTAMP  = 11 # 93 
+    SQL_VARCHAR    = 12
+    SQL_BOOLEAN    = 13
+
+    SQL_LONGVARCHAR   = -1
+    SQL_BINARY        = -2
+    SQL_VARBINARY     = -3
+    SQL_LONGVARBINARY = -4
+    SQL_BIGINT        = -5
+    SQL_TINYINT       = -6
+    SQL_BIT           = -7
+
+    # TODO
+    # Find types for these (XOPEN?)
+    #SQL_ARRAY = 
+    SQL_BLOB = -10   # TODO
+    SQL_CLOB = -11   # TODO
+    #SQL_DISTINCT = 
+    #SQL_OBJECT = 
+    #SQL_NULL = 
+    SQL_OTHER = 100
+    #SQL_REF = 
+    #SQL_STRUCT = 
+
+    SQL_TYPE_NAMES = {
+        SQL_BIT               => 'BIT',
+        SQL_TINYINT           => 'TINYINT',
+        SQL_SMALLINT          => 'SMALLINT',
+        SQL_INTEGER           => 'INTEGER',
+        SQL_BIGINT            => 'BIGINT',
+        SQL_FLOAT             => 'FLOAT',
+        SQL_REAL              => 'REAL',
+        SQL_DOUBLE            => 'DOUBLE',
+        SQL_NUMERIC           => 'NUMERIC',
+        SQL_DECIMAL           => 'DECIMAL',
+        SQL_CHAR              => 'CHAR',
+        SQL_VARCHAR           => 'VARCHAR',
+        SQL_LONGVARCHAR       => 'LONG VARCHAR',
+        SQL_DATE              => 'DATE',
+        SQL_TIME              => 'TIME',
+        SQL_TIMESTAMP         => 'TIMESTAMP',
+        SQL_BINARY            => 'BINARY',
+        SQL_VARBINARY         => 'VARBINARY',
+        SQL_LONGVARBINARY     => 'LONG VARBINARY',
+        SQL_BLOB              => 'BLOB',
+        SQL_CLOB              => 'CLOB',
+        SQL_OTHER             => nil,
+        SQL_BOOLEAN           => 'BOOLEAN',
+
+    }
+end