data_objects 0.9.11 → 0.9.12

data/Manifest.txt

@@ -11,13 +11,31 @@ lib/data_objects/logger.rb
 lib/data_objects/quoting.rb
 lib/data_objects/reader.rb
 lib/data_objects/result.rb
+lib/data_objects/spec/command_spec.rb
+lib/data_objects/spec/connection_spec.rb
+lib/data_objects/spec/encoding_spec.rb
+lib/data_objects/spec/quoting_spec.rb
+lib/data_objects/spec/reader_spec.rb
+lib/data_objects/spec/result_spec.rb
+lib/data_objects/spec/typecast/bigdecimal_spec.rb
+lib/data_objects/spec/typecast/boolean_spec.rb
+lib/data_objects/spec/typecast/byte_array_spec.rb
+lib/data_objects/spec/typecast/class_spec.rb
+lib/data_objects/spec/typecast/date_spec.rb
+lib/data_objects/spec/typecast/datetime_spec.rb
+lib/data_objects/spec/typecast/float_spec.rb
+lib/data_objects/spec/typecast/integer_spec.rb
+lib/data_objects/spec/typecast/ipaddr_spec.rb
+lib/data_objects/spec/typecast/nil_spec.rb
+lib/data_objects/spec/typecast/string_spec.rb
+lib/data_objects/spec/typecast/time_spec.rb
 lib/data_objects/transaction.rb
 lib/data_objects/uri.rb
 lib/data_objects/version.rb
 spec/command_spec.rb
 spec/connection_spec.rb
-spec/dataobjects_spec.rb
 spec/do_mock.rb
+spec/lib/pending_helpers.rb
 spec/reader_spec.rb
 spec/result_spec.rb
 spec/spec.opts

data/Rakefile

@@ -1,6 +1,8 @@
-require 'pathname'
 require 'rubygems'
-require 'spec/rake/spectask'
+require 'rake'
+require 'rake/clean'
+
+require 'pathname'
 require 'lib/data_objects/version'
 
 ROOT    = Pathname(__FILE__).dirname.expand_path
@@ -8,82 +10,6 @@ JRUBY   = RUBY_PLATFORM =~ /java/
 WINDOWS = Gem.win_platform?
 SUDO    = (WINDOWS || JRUBY) ? '' : ('sudo' unless ENV['SUDOLESS'])
 
-AUTHOR = "Dirkjan Bussink"
-EMAIL  = "d.bussink@gmail.com"
-GEM_NAME = "data_objects"
-GEM_VERSION = DataObjects::VERSION
-GEM_DEPENDENCIES = ["addressable", "~>2.0"], ["extlib", "~>0.9.9"]
-GEM_CLEAN = "{coverage,doc,log}/", "profile_results.*", "**/.*.sw?", "*.gem", ".config", "**/.DS_Store"
-GEM_EXTRAS = {}
-
-PROJECT_NAME = "dorb"
-PROJECT_URL  = "http://rubyforge.org/projects/dorb"
-PROJECT_DESCRIPTION = PROJECT_SUMMARY = "The Core DataObjects class"
-
-
-# RCov is run by default, except on the JRuby platform, or if NO_RCOV env is true
-RUN_RCOV = JRUBY ? false : (ENV.has_key?('NO_RCOV') ? ENV['NO_RCOV'] != 'true' : true)
-
-if (tasks_dir = ROOT.parent + 'tasks').directory?
-  require tasks_dir + 'hoe'
-end
-
-def sudo_gem(cmd)
-  sh "#{SUDO} #{RUBY} -S gem #{cmd}", :verbose => false
-end
-
-# Installation
-
-desc "Install #{GEM_NAME} #{GEM_VERSION}"
-task :install => [ :package ] do
-  sudo_gem "install --local pkg/#{GEM_NAME}-#{GEM_VERSION} --no-update-sources"
-end
-
-desc "Uninstall #{GEM_NAME} #{GEM_VERSION}"
-task :uninstall => [ :clobber ] do
-  sudo_gem "uninstall #{GEM_NAME} -v#{GEM_VERSION} -I -x"
-end
-
-# Specs
-
-Spec::Rake::SpecTask.new(:spec) do |t|
-  t.spec_opts << '--format' << 'specdoc' << '--colour'
-  t.spec_opts << '--loadby' << 'random'
-  t.spec_files = Pathname.glob(ENV['FILES'] || 'spec/**/*_spec.rb').map { |f| f.to_s }
-
-  begin
-    t.rcov = RUN_RCOV
-    t.rcov_opts << '--exclude' << 'spec'
-    t.rcov_opts << '--text-summary'
-    t.rcov_opts << '--sort' << 'coverage' << '--sort-reverse'
-  rescue Exception
-    # rcov not installed
-  end
-end
-
-namespace :ci do
-
-  task :prepare do
-    rm_rf ROOT + "ci"
-    mkdir_p ROOT + "ci"
-    mkdir_p ROOT + "ci/doc"
-    mkdir_p ROOT + "ci/cyclomatic"
-    mkdir_p ROOT + "ci/token"
-  end
-
-  task :publish do
-    out = ENV['CC_BUILD_ARTIFACTS'] || "out"
-    mkdir_p out unless File.directory? out
-
-    mv "ci/rspec_report.html", "#{out}/rspec_report.html"
-    mv "ci/coverage", "#{out}/coverage"
-  end
-
-  task :spec => :prepare do
-    Rake::Task[:spec].invoke
-    mv ROOT + "coverage", ROOT + "ci/coverage"
-  end
-
-end
+Dir['tasks/*.rake'].each { |f| import f }
 
-task :ci => ["ci:spec"]
+CLEAN.include(%w[ pkg/ **/*.rbc ])

data/lib/data_objects.rb

@@ -1,6 +1,6 @@
 require 'rubygems'
 
-gem 'extlib', '~>0.9.8'
+gem 'extlib', '~>0.9.11'
 require 'extlib'
 
 require File.expand_path(File.join(File.dirname(__FILE__), 'data_objects', 'version'))
@@ -16,9 +16,4 @@ require File.expand_path(File.join(File.dirname(__FILE__), 'data_objects', 'quot
 
 module DataObjects
   class LengthMismatchError < StandardError; end
-
-  def self.root
-    @root ||= Pathname(__FILE__).dirname.parent.expand_path
-  end
-
 end

data/lib/data_objects/command.rb

@@ -1,30 +1,80 @@
 module DataObjects
+  # Abstract base class for adapter-specific Command subclasses
   class Command
 
+    # The Connection on which the command will be run
     attr_reader :connection
 
-    # initialize creates a new Command object
+    # Create a new Command object on the specified connection
     def initialize(connection, text)
       raise ArgumentError.new("+connection+ must be a DataObjects::Connection") unless DataObjects::Connection === connection
       @connection, @text = connection, text
     end
 
+    # Execute this command and return no dataset
     def execute_non_query(*args)
       raise NotImplementedError.new
     end
 
+    # Execute this command and return a DataObjects::Reader for a dataset
     def execute_reader(*args)
       raise NotImplementedError.new
     end
 
+    # Assign an array of types for the columns to be returned by this command
     def set_types(column_types)
       raise NotImplementedError.new
     end
 
+    # Display the command text
     def to_s
       @text
     end
 
+    private
+
+    # Escape a string of SQL with a set of arguments.
+    # The first argument is assumed to be the SQL to escape,
+    # the remaining arguments (if any) are assumed to be
+    # values to escape and interpolate.
+    #
+    # ==== Examples
+    #   escape_sql("SELECT * FROM zoos")
+    #   # => "SELECT * FROM zoos"
+    #
+    #   escape_sql("SELECT * FROM zoos WHERE name = ?", "Dallas")
+    #   # => "SELECT * FROM zoos WHERE name = `Dallas`"
+    #
+    #   escape_sql("SELECT * FROM zoos WHERE name = ? AND acreage > ?", "Dallas", 40)
+    #   # => "SELECT * FROM zoos WHERE name = `Dallas` AND acreage > 40"
+    #
+    # ==== Warning
+    # This method is meant mostly for adapters that don't support
+    # bind-parameters.
+    def escape_sql(args)
+      sql = @text.dup
+      vars = args.dup
+
+      replacements = 0
+      mismatch     = false
+
+      sql.gsub!(/\?/) do |x|
+        replacements += 1
+        if vars.empty?
+          mismatch = true
+        else
+          var = vars.shift
+          connection.quote_value(var)
+        end
+      end
+
+      if !vars.empty? || mismatch
+        raise ArgumentError, "Binding mismatch: #{args.size} for #{replacements}"
+      else
+        sql
+      end
+    end
+
   end
 
 end

data/lib/data_objects/connection.rb

@@ -6,8 +6,11 @@ rescue LoadError
 end
 
 module DataObjects
+  # An abstract connection to a DataObjects resource. The physical connection may be broken and re-established from time to time.
   class Connection
 
+    # Make a connection to the database using the DataObjects::URI given.
+    # Note that the physical connection may be delayed until the first command is issued, so success here doesn't necessarily mean you can connect.
     def self.new(uri_s)
       uri = DataObjects::URI::parse(uri_s)
 
@@ -40,9 +43,12 @@ module DataObjects
       DataObjects.const_get(driver_name.capitalize)::Connection.new(conn_uri)
     end
 
+    # Ensure that all Connection subclasses handle pooling and logging uniformly.
+    # See also Extlib::Pooling and DataObjects::Logger
     def self.inherited(target)
       target.class_eval do
 
+        # Allocate a Connection object from the pool, creating one if necessary. This method is active in Connection subclasses only.
         def self.new(*args)
           instance = allocate
           instance.send(:initialize, *args)
@@ -50,6 +56,8 @@ module DataObjects
         end
 
         include Extlib::Pooling
+        include Quoting
+
         alias close release
       end
 
@@ -72,18 +80,21 @@ module DataObjects
     #####################################################
     # Standard API Definition
     #####################################################
+
+    # Show the URI for this connection
     def to_s
       @uri.to_s
     end
 
-    def initialize(uri)
+    def initialize(uri) #:nodoc:
       raise NotImplementedError.new
     end
 
-    def dispose
+    def dispose #:nodoc:
       raise NotImplementedError.new
     end
 
+    # Create a Command object of the right subclass using the given text
     def create_command(text)
       concrete_command.new(self, text)
     end

data/lib/data_objects/logger.rb

@@ -1,47 +1,54 @@
 require "time" # httpdate
-# ==== Public DataObjects Logger API
-#
-# Logger taken from Merb :)
-#
-# To replace an existing logger with a new one:
-#  DataObjects::Logger.set_log(log{String, IO},level{Symbol, String})
-#
-# Available logging levels are
-#   DataObjects::Logger::{ Fatal, Error, Warn, Info, Debug }
-#
-# Logging via:
-#   DataObjects.logger.fatal(message<String>)
-#   DataObjects.logger.error(message<String>)
-#   DataObjects.logger.warn(message<String>)
-#   DataObjects.logger.info(message<String>)
-#   DataObjects.logger.debug(message<String>)
-#
-# Flush the buffer to
-#   DataObjects.logger.flush
-#
-# Remove the current log object
-#   DataObjects.logger.close
-#
-# ==== Private DataObjects Logger API
-#
-# To initialize the logger you create a new object, proxies to set_log.
-#   DataObjects::Logger.new(log{String, IO},level{Symbol, String})
-#
-# Logger will not create the file until something is actually logged
-# This avoids file creation on DataObjects init when it creates the
-# default logger.
+
 module DataObjects
 
-  class << self #:nodoc:
+  class << self
+    # The global logger for DataObjects
     attr_accessor :logger
   end
 
+  # ==== Public DataObjects Logger API
+  #
+  # Logger taken from Merb :)
+  #
+  # To replace an existing logger with a new one:
+  #  DataObjects::Logger.set_log(log{String, IO},level{Symbol, String})
+  #
+  # Available logging levels are
+  #   DataObjects::Logger::{ Fatal, Error, Warn, Info, Debug }
+  #
+  # Logging via:
+  #   DataObjects.logger.fatal(message<String>)
+  #   DataObjects.logger.error(message<String>)
+  #   DataObjects.logger.warn(message<String>)
+  #   DataObjects.logger.info(message<String>)
+  #   DataObjects.logger.debug(message<String>)
+  #
+  # Flush the buffer to
+  #   DataObjects.logger.flush
+  #
+  # Remove the current log object
+  #   DataObjects.logger.close
+  #
+  # ==== Private DataObjects Logger API
+  #
+  # To initialize the logger you create a new object, proxies to set_log.
+  #   DataObjects::Logger.new(log{String, IO},level{Symbol, String})
+  #
+  # Logger will not create the file until something is actually logged
+  # This avoids file creation on DataObjects init when it creates the
+  # default logger.
   class Logger
 
+    # Use asynchronous I/O?
     attr_accessor :aio
+    # delimiter to use between message sections
     attr_accessor :delimiter
+    # a symbol representing the log level from {:off, :fatal, :error, :warn, :info, :debug}
     attr_reader   :level
+    # Direct access to the buffer
     attr_reader   :buffer
+    # The name of the log file
     attr_reader   :log
 
     # @note
@@ -64,6 +71,7 @@ module DataObjects
       :debug => 0
     }
 
+    # Set the log level (use the level symbols as documented)
     def level=(new_level)
       @level = LEVELS[new_level.to_sym]
       reset_methods(:close)

data/lib/data_objects/quoting.rb

@@ -1,43 +1,14 @@
 module DataObjects
 
   module Quoting
-    # Escape a string of SQL with a set of arguments.
-    # The first argument is assumed to be the SQL to escape,
-    # the remaining arguments (if any) are assumed to be
-    # values to escape and interpolate.
-    #
-    # ==== Examples
-    #   escape_sql("SELECT * FROM zoos")
-    #   # => "SELECT * FROM zoos"
-    #
-    #   escape_sql("SELECT * FROM zoos WHERE name = ?", "Dallas")
-    #   # => "SELECT * FROM zoos WHERE name = `Dallas`"
-    #
-    #   escape_sql("SELECT * FROM zoos WHERE name = ? AND acreage > ?", "Dallas", 40)
-    #   # => "SELECT * FROM zoos WHERE name = `Dallas` AND acreage > 40"
-    #
-    # ==== Warning
-    # This method is meant mostly for adapters that don't support
-    # bind-parameters.
-    def escape_sql(args)
-      sql = @text.dup
-
-      unless args.empty?
-        sql.gsub!(/\?/) do |x|
-          quote_value(args.shift)
-        end
-      end
-
-      sql
-    end
 
+    # Quote a value of any of the recognised data types
     def quote_value(value)
       return 'NULL' if value.nil?
 
       case value
         when Numeric then quote_numeric(value)
         when String then quote_string(value)
-        when Class then quote_class(value)
         when Time then quote_time(value)
         when DateTime then quote_datetime(value)
         when Date then quote_date(value)
@@ -46,58 +17,83 @@ module DataObjects
         when Range then quote_range(value)
         when Symbol then quote_symbol(value)
         when Regexp then quote_regexp(value)
+        when ::Extlib::ByteArray then quote_byte_array(value)
+        when Class then quote_class(value)
         else
           if value.respond_to?(:to_sql)
             value.to_sql
           else
-            raise "Don't know how to quote #{value.inspect}"
+            raise "Don't know how to quote #{value.class} objects (#{value.inspect})"
           end
       end
     end
 
+    # Convert the Symbol to a String and quote that
     def quote_symbol(value)
       quote_string(value.to_s)
     end
 
+    # Convert the Numeric to a String and quote that
     def quote_numeric(value)
       value.to_s
     end
 
+    # Quote a String for SQL by doubling any embedded single-quote characters
     def quote_string(value)
       "'#{value.gsub("'", "''")}'"
     end
 
+    # Quote a class by quoting its name
     def quote_class(value)
       quote_string(value.name)
     end
 
+    # Convert a Time to standard YMDHMS format (with microseconds if necessary)
     def quote_time(value)
-      "'#{value.strftime('%Y-%m-%d %H:%M:%S')}" + (value.usec > 0 ? ".#{value.usec.to_s.rjust(6, '0')}'" : "'")
+      offset = value.utc_offset
+      if offset >= 0
+        offset_string = "+#{sprintf("%02d", offset / 3600)}:#{sprintf("%02d", (offset % 3600) / 60)}"
+      elsif offset < 0
+        offset_string = "-#{sprintf("%02d", -offset / 3600)}:#{sprintf("%02d", (-offset % 3600) / 60)}"
+      end
+      "'#{value.strftime('%Y-%m-%dT%H:%M:%S')}" << (value.usec > 0 ? ".#{value.usec.to_s.rjust(6, '0')}" : "") << offset_string << "'"
     end
 
+    # Quote a DateTime by relying on it's own to_s conversion
     def quote_datetime(value)
       "'#{value.dup}'"
     end
 
+    # Convert a Date to standard YMD format
     def quote_date(value)
       "'#{value.strftime("%Y-%m-%d")}'"
     end
 
+    # Quote true, false as the strings TRUE, FALSE
     def quote_boolean(value)
       value.to_s.upcase
     end
 
+    # Quote an array as a list of quoted values
     def quote_array(value)
       "(#{value.map { |entry| quote_value(entry) }.join(', ')})"
     end
 
+    # Quote a range by joining the quoted end-point values with AND.
+    # It's not clear whether or when this is a useful or correct thing to do.
     def quote_range(value)
       "#{quote_value(value.first)} AND #{quote_value(value.last)}"
     end
 
+    # Quote a Regex using its string value. Note that there's no attempt to make a valid SQL "LIKE" string.
     def quote_regexp(value)
       quote_string(value.source)
     end
+
+    def quote_byte_array(value)
+      quote_string(value.source)
+    end
+
   end
 
 end