ydbi 0.5.0

data/bin/test_broken_dbi

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+load_path = false
+gems      = false
+redefined = false
+
+# these clauses are for installations which have RUBYOPT=-rubygems, etc.
+if Object.const_defined? "Gem"
+    redefined = true
+    module Kernel
+        alias gem_require require 
+        alias require gem_original_require
+    end
+end
+
+begin
+    require 'dbi'
+    load_path = true
+rescue LoadError => e
+end
+
+if Object.const_defined? "Gem" and redefined
+    module Kernel
+        alias gem_original_require require 
+        alias require gem_require
+    end
+end
+
+begin
+    require 'rubygems'
+    gem 'dbi'
+    gems = true
+rescue LoadError
+rescue Gem::LoadError
+end
+
+puts "Your installation of DBI is broken" if gems and load_path

data/build/Rakefile.dbi.rb

@@ -0,0 +1,60 @@
+require 'rake_task_lib'
+require 'dbi'
+
+DBD_PACKAGES = Dir['lib/dbd/*.rb'].collect { |x| File.basename(x, '.rb') }
+
+# creates a number of tasks like dbi:task_name, dbd_mysql:task_name, so on.
+# Builds these out into an array that can be used as a prereq for other tasks.
+def map_task(task_name)
+    namespaces = (['dbi'] + DBD_PACKAGES.collect { |x| dbd_namespace(x) }).flatten
+    namespaces.collect { |x| [x, task_name].join(":") }
+end
+
+task :package         => (map_task("package") + map_task("gem"))
+task :clobber_package => map_task("clobber_package")
+
+desc 'Run interface tests (no database connectivity required)'
+task :test_dbi do
+    ruby("test/ts_dbi.rb")
+end
+
+desc 'Run database-specific tests'
+task :test_dbd do
+    ruby("test/ts_dbd.rb")
+end
+
+desc 'Run full test suite'
+task :test => [:test_dbi, :test_dbd]
+
+build_dbi_tasks
+
+#
+# There's probably a better way to do this, but here's a boilerplate spec that we dup and modify.
+#
+
+task :dbi => DEFAULT_TASKS.collect { |x| "dbi:#{x.to_s}" }
+
+namespace :dbi do
+    code_files = %w(examples/**/* bin/dbi build/Rakefile.dbi.rb lib/dbi.rb lib/dbi/**/*.rb test/ts_dbi.rb test/dbi/*)
+
+    spec = boilerplate_spec
+    spec.name        = 'dbi'
+    spec.version     = DBI::VERSION
+    spec.test_file   = 'test/ts_dbi.rb'
+    spec.executables = ['dbi', 'test_broken_dbi']
+    spec.files       = gem_files(code_files)
+    spec.summary     = 'A vendor independent interface for accessing databases, similar to Perl\'s DBI'
+    spec.description = 'A vendor independent interface for accessing databases, similar to Perl\'s DBI'
+    spec.add_dependency 'deprecated', '= 2.0.1'
+
+    build_package_tasks(spec, code_files)
+end
+
+DBD_PACKAGES.each do |dbd|
+    my_namespace = dbd_namespace(dbd)
+
+    task my_namespace => DEFAULT_TASKS.collect { |x| "#{my_namespace}:#{x.to_s}" }
+    namespace my_namespace do
+        build_dbd_tasks(dbd)
+    end
+end

data/build/rake_task_lib.rb

@@ -0,0 +1,187 @@
+$:.unshift 'lib'
+require 'rake'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rake/packagetask'
+require 'rdoc/task'
+
+
+DEFAULT_TASKS = [:clobber_package, :package, :gem]
+
+DBD_GEM_DEP_MAP = {
+    'pg'      => 'pg',
+    'mysql'   => 'mysql',
+    'sqlite'  => 'sqlite-ruby',
+    'sqlite3' => 'sqlite3-ruby'
+}
+
+#
+# Packaging
+#
+
+PACKAGE_FILES = %w(Rakefile build/rake_task_lib.rb setup.rb)
+DOC_FILES  = %w(readme.md LICENSE ChangeLog)
+EXCLUSIONS = %w(test/sql.log)
+DBD_FILES  = %w(test/DBD_TESTS)
+
+#
+# some inlines
+#
+
+def gem_files(code_files)
+    (code_files + DOC_FILES).collect { |x| Dir[x] }.reject { |x| EXCLUSIONS.include? x }.flatten
+end
+
+def package_files(code_files)
+    code_files + DOC_FILES + PACKAGE_FILES
+end
+
+def build_package_tasks(spec, code_files)
+    Gem::PackageTask.new(spec) do |s|
+    end
+
+    Rake::PackageTask.new(spec.name, spec.version) do |p|
+        p.need_tar_gz = true
+        p.need_zip = true
+
+        package_files(code_files).each do |x|
+            p.package_files.include(x)
+        end
+
+        EXCLUSIONS.each do |x|
+            p.package_files.exclude(x)
+        end
+    end
+end
+
+def boilerplate_spec
+    gem = Gem::Specification.new 
+    gem.authors     = ['Erik Hollensbe', 'Christopher Maujean']
+    gem.email       = 'ruby-dbi-users@rubyforge.org'
+    gem.homepage    = 'http://www.rubyforge.org/projects/ruby-dbi'
+    gem.platform    = Gem::Platform::RUBY
+    gem.has_rdoc    = true
+    gem.extra_rdoc_files = DOC_FILES
+    gem.required_ruby_version = '>= 1.8.0'
+    gem.rubyforge_project = 'ruby-dbi'
+    return gem
+end
+
+# builds a dbd namespace from the DBD_PACKAGES hash
+def dbd_namespace(dbd)
+    "dbd-" + dbd.to_s.downcase
+end
+
+def dbd_code_files(dbd)
+    code_files = [
+                "test/dbd/general/**", 
+                File.join("test", "dbd", dbd.downcase == "pg" ? "postgresql" : dbd.downcase, "*"), 
+                File.join("lib", "dbd", dbd + ".rb"), 
+                "lib/dbd/#{dbd.downcase}/*.rb",
+    ] + DBD_FILES
+end
+
+def dbd_gem_files(code_files)
+    DBD_FILES + gem_files(code_files)
+end
+
+def dbd_package_files(code_files)
+    DBD_FILES + package_files(code_files)
+end
+
+def dbd_gem_spec(dbd, dbd_const, code_files)
+    spec = boilerplate_spec
+    spec.name        = dbd_namespace(dbd)
+    spec.version     = dbd_version(dbd_const)
+    spec.test_file   = 'test/ts_dbd.rb'
+    spec.files       = gem_files(code_files) 
+    spec.summary     = dbd_description(dbd_const)
+    spec.description = dbd_description(dbd_const) 
+    spec.add_dependency 'dbi', '>= 0.4.0'
+
+    dcdbd = dbd.downcase
+
+    if DBD_GEM_DEP_MAP[dcdbd]
+        spec.add_dependency DBD_GEM_DEP_MAP[dcdbd]
+    end
+
+    return spec
+end
+
+def dbd_version(const)
+    DBI::DBD.const_get(const).const_get("VERSION")
+end
+
+def dbd_description(const)
+    DBI::DBD.const_get(const).const_get("DESCRIPTION")
+end
+
+
+def build_dbd_tasks(dbd)
+    task :default => DEFAULT_TASKS
+
+    begin
+        done = false
+        dbd_const = nil
+        Dir["lib/dbd/*.rb"].each do |dbd_file|
+            if File.basename(dbd_file.downcase, '.rb') == dbd.to_s.downcase
+                dbd_const = File.basename(dbd_file, '.rb')
+                require "dbd/#{dbd_const}"
+                done = true
+            end
+        end
+
+        abort "No DBD found even though we asked to make tasks for it" unless done
+
+        code_files = dbd_code_files(dbd_const) 
+
+        spec = dbd_gem_spec(dbd, dbd_const, code_files)
+
+        build_package_tasks(spec, code_files)
+
+        # FIXME: convert to a rake_test_loader sooner or later
+        task :test do
+            ENV["DBTYPES"] = dbd
+            ruby "test/ts_dbd.rb"
+        end
+    rescue LoadError => e
+        DEFAULT_TASKS.each do |x|
+            task x do
+            end
+        end
+        warn "Skipping #{dbd_namespace(dbd)} because we can't require DBD"
+    end
+end
+
+def build_dbi_tasks
+end
+
+#
+# basic tasks
+#
+
+task :dist      => [:distclean, :package, :rdoc]
+task :distclean => [:clobber_package, :clobber_rdoc]
+task :clean     => [:distclean]
+task :default   => [:test, :dist]
+
+task :to_blog   => [:clobber_rdoc, :rdoc] do
+    sh "rm -r $git/blog/content/docs/ruby-dbi && mv rdoc $git/blog/content/docs/ruby-dbi"
+end
+
+#
+# Documentation
+#
+
+RDoc::Task.new do |rd|
+    rd.rdoc_dir = "rdoc"
+    rd.main = "README"
+    rd.rdoc_files.include("./README")
+    rd.rdoc_files.include("./ChangeLog")
+    rd.rdoc_files.include("./LICENSE")
+    rd.rdoc_files.include("./doc/**/*.rdoc")
+    rd.rdoc_files.include("./lib/**/*.rb")
+    rd.rdoc_files.include("./ext/**/*.c")
+    rd.options = %w(-a)
+end
+

data/doc/DBD_SPEC.rdoc

@@ -0,0 +1,88 @@
+= DBD Specification Version 0.4.0
+By Erik Hollensbe <erik@hollensbe.org>
+
+== FOREWORD
+
+DBI is still in a large state of flux. Previous versions of this
+specification rarely reflected reality, and the 0.4.0 release is an
+attempt to get the code and documentation in touch with each other to
+better reflect said reality.
+
+While this is a goal, nobody's perfect and there is still a lot of
+code to check, sanitize, and otherwise clean up. If you find something
+missing in these specifications while working on a new DBD or a patch
+for DBI, please, do not do what everything else is doing; alert the
+appropriate person to get the spec revised. Doing this will save
+yourself (and the DBI authors) infinite amounts of time.
+
+== WHAT A DBD IS
+
+DBD stands for "DataBase Driver" and is the layer that DBI uses to interface
+with the database. DBDs often employ a low level driver to do the real work
+with the database, leaving the DBD itself to act as a medium between DBI and
+that lower level API.
+
+This allows a great deal of flexibility without having to sacrifice features
+for compatibility. For example, instead of having one PostgreSQL DBD that
+handles all version of PostgreSQL and attempts to limit it's functionality
+based on what version it detects (a error-prone and time/design prohibitive
+process), one can write two PostgreSQL DBD that handle the differences between
+"new" and "old" postgres, all while talking to the same low-level driver (yet
+leveraging different functionality). This method leads to cleaner internals and
+puts the choice of which to use on the end-user, who is probably a lot more
+informed about what features they want than your code.
+
+One traditionally loads a DBD using the DBI.connect method (see DBD LOAD
+PATHS below) which will attempt to load the DBD, connect to the database with
+the arguments supplied and return a DatabaseHandle if successful. However, if
+the DBD is written properly, requiring it directly without DBI's involvement
+(or existence) should not be an issue.
+
+== WHERE DBDs LIVE
+
+DBDs have an expected require path to be loaded by DBI. DBI will attempt to
+load the middle portion of the DBI.connect DSN provided.
+
+Example: DBI.connect("dbi:Mysql:mydb") # requires 'dbd/Mysql'
+
+Since rubygems potentially renders this path virtual, it is not OK to expect
+this path physically exists in one spot on the filesystem. Many assuptions are
+currently made about this and will be pruned in 0.6.0.
+
+If you wish to create submodules for your DBD, create a directory in the 'dbd'
+directory named the same as the DBD. (E.g., "dbd/Mysql" would have a directory
+with files in it relating to the Mysql.rb file that DBI loads).
+
+== HOW DBI INTERFACES WITH YOUR DBD
+
+Your DBD will create classes representing a DBI::BaseDriver, DBI::BaseDatabase,
+and DBI::BaseStatement. DBI will link these to DBI::DriverHandle,
+DBI::DatabaseHandle, and DBI::StatementHandle respectively. Your classes will
+be called by the Handle classes to retreive information to manipulate and send
+to the user. This manipulation can be influenced in a number of ways. 
+
+It is strongly recommended you make the effort to read the RDoc for all six
+of these classes, as they are the meat of this specification, not this
+document.
+
+== BUILDING A DBD FROM SCRATCH
+
+For the purposes of this discussion, we'll call your driver 'Foo'.
+
+Create your module, DBI::DBD::Foo. Store it somewhere in your load path under
+dbd/Foo.rb.
+
+Create classes Driver, Database, and Statement in this new namespace, which
+inherit from DBI::BaseDriver, DBI::BaseDatabase, and DBI::BaseStatement.
+Override (at mininum) the methods that return NotImplementedError in your new
+classes.
+
+Create a method in the root namespace named +driver_name+. This should return a
+string with a short name for your driver, this key will be used in type
+conversion.
+
+Everything else is up to you, up to and including worrying about interacting
+with the database.
+
+At this point, you should be ready to test your driver. See test/DBD_TESTS for
+information on how to configure that.

data/doc/DBI_SPEC.rdoc

@@ -0,0 +1,157 @@
+= DBI Interface Spec, for version 0.4.0
+
+by Erik Hollensbe <erik@hollensbe.org>
+
+== Foreword
+
+DBI is still in a large state of flux. Previous versions of this
+specification rarely reflected reality, and the 0.4.0 release is an
+attempt to get the code and documentation more in sync.
+
+While this is the goal, there is still a lot of
+code to check, sanitize, and otherwise clean up. If you find something
+missing in these specifications while working on a new DBD or a patch
+for DBI, please bring it to our attention (in IRC or on the mailing list)
+to get the spec revised. Doing this will save
+yourself (and the DBI authors) a lot of time.
+
+== Design
+
+With DBI, there are the concepts of driver, database, and statement. The core
+functionality for these concepts is provided by a database driver, or
+DBD.  DBI controls one or more drivers at once, a driver has databases, a
+database may have statements.
+
+DBI uses a delegation model to communicate with its DBDs through a
+series of handles.  When a connection to a database is requested, DBI contacts
+the appropriate DBD and builds a handle in
+its name that it aligns with a DBI base class for that concept. The
+handle provided by the DBD is the first-class method of communication,
+otherwise it resorts to calling the base class methods.  This allows
+DBI to provide a level of consistency unless the DBD author finds it
+otherwise unnecessary.
+
+For example: DBI will provide handy methods like fetch_all and
+fetch_scroll which all leverage the fetch method in the base class,
+and the fetch method must be implemented by the DBD. However, the DBD
+may have an internal representation of fetch_scroll (as is the case
+with the ODBC driver) that may be more suited to direct use, and
+therefore DBI will never see the base class method. This is similar to
+inheritance, but there is a distinct disconnect between the handles
+and the base classes, intentionally so. This way the DBDs have no
+access to the base class and DBI does all the delegation work. Also,
+DBI has no idea what the DBD is doing underneath, nor does it need to
+care as long as valid data is returned.
+
+== Classes
+
+These are the classes that make up the core of DBI and provide
+various functionality:
+
+=== DBI
+Core module, responsible for everything underneath it, kickstarting
+connections and loading drivers.
+
+=== DBI::Row
+
+Responsible for representing the result set and managing the type
+conversion of the result set. 
+
+=== DBI::Utils
+
+Utility methods which propogate through the rest of DBI.
+
+=== DBI::SQL
+
+Utility methods for working with SQL queries. Includes a
+driver-independent SQL bind manager.
+
+=== DBI::ColumnInfo
+
+Responsible for representing the information per column for both
+queries and table descriptions.
+
+=== DBI::Type
+
+Namespace for typecasting classes. These classes are provided with a
+parse method which converts them to a native Ruby type from a string.
+
+=== DBI::TypeUtil
+
+The inverse of DBI::Type, this provides functionality to turn native
+Ruby types into a representation suitable for the DBD's queries.
+
+=== DBI::Binary
+
+The representation of a BLOB/CLOB in a Ruby object. This will
+eventually be rolled into DBI::Type::, but remains here currently for
+compatibility purposes.
+
+=== DBI::Base* and DBI::*Handle
+
+Please see the Design section above for the description of these modules.
+
+== Exceptions
+
+DBI has a slew of custom exceptions it uses to control program flow,
+and alert the user to specific classes of problems.
+
+They currently all live in the DBI namespace, although it's expected
+that there will eventually be an exception namespace.
+
+=== DBI::Warning < RuntimeError
+    For important warnings such as data truncation, etc.
+
+=== DBI::Error < RuntimeError
+    Base class of all other error exceptions.
+    Rescue this to rescue all DBI errors.
+
+=== DBI::InterfaceError < DBI::Error
+    Exception for errors related to the DBI interface rather 
+    than the database itself.
+
+=== DBI::NotImplementedError < DBI::InterfaceError
+    Exception raised if the DBD driver has not specified
+    a mandatory method.
+
+=== DBI::DatabaseError < DBI::Error
+    Exception for errors related to the database.
+ 
+    Has three attributes: ((|err|)), ((|errstr|)) and ((|state|)).
+
+=== DBI::DataError < DBI::DatabaseError
+    Exception for errors due to problems with the processed 
+    data, such as division by zero, numeric value out of range, etc.
+
+=== DBI::OperationalError < DBI::DatabaseError
+    Exception for errors related to the database's operation which
+    are not necessarily under the control of the programmer.  This would include
+    such things as unexpected disconnection, failure to find a datasource name,
+    failure to process a transaction, memory allocation errors, etc.
+
+=== DBI::IntegrityError < DBI::DatabaseError
+    Exception raised when the relational integrity of the database
+    is affected, such as when a foreign key constraint is violated.
+
+=== DBI::InternalError < DBI::DatabaseError
+    Exception raised when the database encounters an internal error, 
+    such as a cursor not being valid anymore, or a transaction going out of
+    sync.
+
+=== DBI::ProgrammingError < DBI::DatabaseError
+    Exception raised for programming errors, e.g., table not found
+    or already exists, syntax error in SQL statement, wrong number
+    of parameters specified, etc.
+
+=== DBI::NotSupportedError < DBI::DatabaseError
+    Raised if, e.g., ((<commit>)) is called for a database that does not
+    support transactions.
+
+== API
+
+To save my sanity, I have joined the specification and the rdoc for
+DBI. Please review the specification there.
+
+If you wish to author your own DBD, please see DBD_SPEC.rdoc,
+which is a more in-depth view of the communication between DBI and
+DBDs.