shoesgem 0.1424.0 → 0.1426.0

data/shoes/ruby/gems/1.9.1/gems/sqlite3-ruby-1.2.5-x86-mswin32/lib/sqlite3/database.rb

@@ -1,721 +1,721 @@
-require 'sqlite3/constants'
-require 'sqlite3/errors'
-require 'sqlite3/pragmas'
-require 'sqlite3/statement'
-require 'sqlite3/translator'
-require 'sqlite3/value'
-
-module SQLite3
-
-  # The Database class encapsulates a single connection to a SQLite3 database.
-  # Its usage is very straightforward:
-  #
-  #   require 'sqlite3'
-  #
-  #   SQLite3::Database.new( "data.db" ) do |db|
-  #     db.execute( "select * from table" ) do |row|
-  #       p row
-  #     end
-  #   end
-  #
-  # It wraps the lower-level methods provides by the selected driver, and
-  # includes the Pragmas module for access to various pragma convenience
-  # methods.
-  #
-  # The Database class provides type translation services as well, by which
-  # the SQLite3 data types (which are all represented as strings) may be
-  # converted into their corresponding types (as defined in the schemas
-  # for their tables). This translation only occurs when querying data from
-  # the database--insertions and updates are all still typeless.
-  #
-  # Furthermore, the Database class has been designed to work well with the
-  # ArrayFields module from Ara Howard. If you require the ArrayFields
-  # module before performing a query, and if you have not enabled results as
-  # hashes, then the results will all be indexible by field name.
-  class Database
-    include Pragmas
-
-    class <<self
-
-      alias :open :new
-
-      # Quotes the given string, making it safe to use in an SQL statement.
-      # It replaces all instances of the single-quote character with two
-      # single-quote characters. The modified string is returned.
-      def quote( string )
-        string.gsub( /'/, "''" )
-      end
-
-    end
-
-    # The low-level opaque database handle that this object wraps.
-    attr_reader :handle
-
-    # A reference to the underlying SQLite3 driver used by this database.
-    attr_reader :driver
-
-    # A boolean that indicates whether rows in result sets should be returned
-    # as hashes or not. By default, rows are returned as arrays.
-    attr_accessor :results_as_hash
-
-    # A boolean indicating whether or not type translation is enabled for this
-    # database.
-    attr_accessor :type_translation
-
-    # Create a new Database object that opens the given file. If utf16
-    # is +true+, the filename is interpreted as a UTF-16 encoded string.
-    #
-    # By default, the new database will return result rows as arrays
-    # (#results_as_hash) and has type translation disabled (#type_translation=).
-    def initialize( file_name, options={} ) # :yields: db
-      utf16 = options.fetch(:utf16, false)
-      load_driver( options[:driver] )
-
-      @statement_factory = options[:statement_factory] || Statement
-
-      result, @handle = @driver.open( file_name, utf16 )
-      Error.check( result, self, "could not open database" )
-
-      @closed = false
-      @results_as_hash = options.fetch(:results_as_hash,false)
-      @type_translation = options.fetch(:type_translation,false)
-      @translator = nil
-      @transaction_active = false
-      
-      if block_given?
-        begin
-          yield self
-        ensure
-          self.close
-        end
-      end
-    end
-
-    # Return +true+ if the string is a valid (ie, parsable) SQL statement, and
-    # +false+ otherwise. If +utf16+ is +true+, then the string is a UTF-16
-    # character string.
-    def complete?( string, utf16=false )
-      @driver.complete?( string, utf16 )
-    end
-
-    # Return a string describing the last error to have occurred with this
-    # database.
-    def errmsg( utf16=false )
-      @driver.errmsg( @handle, utf16 )
-    end
-
-    # Return an integer representing the last error to have occurred with this
-    # database.
-    def errcode
-      @driver.errcode( @handle )
-    end
-
-    # Return the type translator employed by this database instance. Each
-    # database instance has its own type translator; this allows for different
-    # type handlers to be installed in each instance without affecting other
-    # instances. Furthermore, the translators are instantiated lazily, so that
-    # if a database does not use type translation, it will not be burdened by
-    # the overhead of a useless type translator. (See the Translator class.)
-    def translator
-      @translator ||= Translator.new
-    end
-
-    # Closes this database.
-    def close
-      unless @closed
-        result = @driver.close( @handle )
-        Error.check( result, self )
-      end
-      @closed = true
-    end
-
-    # Returns +true+ if this database instance has been closed (see #close).
-    def closed?
-      @closed
-    end
-
-    # Installs (or removes) a block that will be invoked for every SQL
-    # statement executed. The block receives a two parameters: the +data+
-    # argument, and the SQL statement executed. If the block is +nil+,
-    # any existing tracer will be uninstalled.
-    def trace( data=nil, &block )
-      @driver.trace( @handle, data, &block )
-    end
-
-    # Installs (or removes) a block that will be invoked for every access
-    # to the database. If the block returns 0 (or +nil+), the statement
-    # is allowed to proceed. Returning 1 causes an authorization error to
-    # occur, and returning 2 causes the access to be silently denied.
-    def authorizer( data=nil, &block )
-      result = @driver.set_authorizer( @handle, data, &block )
-      Error.check( result, self )
-    end
-
-    # Returns a Statement object representing the given SQL. This does not
-    # execute the statement; it merely prepares the statement for execution.
-    #
-    # The Statement can then be executed using Statement#execute.
-    #
-    def prepare( sql )
-      stmt = @statement_factory.new( self, sql )
-      if block_given?
-        begin
-          yield stmt
-        ensure
-          stmt.close
-        end
-      else
-        return stmt
-      end
-    end
-
-    # Executes the given SQL statement. If additional parameters are given,
-    # they are treated as bind variables, and are bound to the placeholders in
-    # the query.
-    #
-    # Note that if any of the values passed to this are hashes, then the
-    # key/value pairs are each bound separately, with the key being used as
-    # the name of the placeholder to bind the value to.
-    #
-    # The block is optional. If given, it will be invoked for each row returned
-    # by the query. Otherwise, any results are accumulated into an array and
-    # returned wholesale.
-    #
-    # See also #execute2, #query, and #execute_batch for additional ways of
-    # executing statements.
-    def execute( sql, *bind_vars )
-      prepare( sql ) do |stmt|
-        result = stmt.execute( *bind_vars )
-        if block_given?
-          result.each { |row| yield row }
-        else
-          return result.inject( [] ) { |arr,row| arr << row; arr }
-        end
-      end
-    end
-
-    # Executes the given SQL statement, exactly as with #execute. However, the
-    # first row returned (either via the block, or in the returned array) is
-    # always the names of the columns. Subsequent rows correspond to the data
-    # from the result set.
-    #
-    # Thus, even if the query itself returns no rows, this method will always
-    # return at least one row--the names of the columns.
-    #
-    # See also #execute, #query, and #execute_batch for additional ways of
-    # executing statements.
-    def execute2( sql, *bind_vars )
-      prepare( sql ) do |stmt|
-        result = stmt.execute( *bind_vars )
-        if block_given?
-          yield result.columns
-          result.each { |row| yield row }
-        else
-          return result.inject( [ result.columns ] ) { |arr,row|
-            arr << row; arr }
-        end
-      end
-    end
-
-    # Executes all SQL statements in the given string. By contrast, the other
-    # means of executing queries will only execute the first statement in the
-    # string, ignoring all subsequent statements. This will execute each one
-    # in turn. The same bind parameters, if given, will be applied to each
-    # statement.
-    #
-    # This always returns +nil+, making it unsuitable for queries that return
-    # rows.
-    def execute_batch( sql, *bind_vars )
-      sql = sql.strip
-      until sql.empty? do
-        prepare( sql ) do |stmt|
-          stmt.execute( *bind_vars )
-          sql = stmt.remainder.strip
-        end
-      end
-      nil
-    end
-
-    # This is a convenience method for creating a statement, binding
-    # paramters to it, and calling execute:
-    #
-    #   result = db.query( "select * from foo where a=?", 5 )
-    #   # is the same as
-    #   result = db.prepare( "select * from foo where a=?" ).execute( 5 )
-    #
-    # You must be sure to call +close+ on the ResultSet instance that is
-    # returned, or you could have problems with locks on the table. If called
-    # with a block, +close+ will be invoked implicitly when the block 
-    # terminates.
-    def query( sql, *bind_vars )
-      result = prepare( sql ).execute( *bind_vars )
-      if block_given?
-        begin
-          yield result
-        ensure
-          result.close
-        end
-      else
-        return result
-      end
-    end
-
-    # A convenience method for obtaining the first row of a result set, and
-    # discarding all others. It is otherwise identical to #execute.
-    #
-    # See also #get_first_value.
-    def get_first_row( sql, *bind_vars )
-      execute( sql, *bind_vars ) { |row| return row }
-      nil
-    end
-
-    # A convenience method for obtaining the first value of the first row of a
-    # result set, and discarding all other values and rows. It is otherwise
-    # identical to #execute.
-    #
-    # See also #get_first_row.
-    def get_first_value( sql, *bind_vars )
-      execute( sql, *bind_vars ) { |row| return row[0] }
-      nil
-    end
-
-    # Obtains the unique row ID of the last row to be inserted by this Database
-    # instance.
-    def last_insert_row_id
-      @driver.last_insert_rowid( @handle )
-    end
-
-    # Returns the number of changes made to this database instance by the last
-    # operation performed. Note that a "delete from table" without a where
-    # clause will not affect this value.
-    def changes
-      @driver.changes( @handle )
-    end
-
-    # Returns the total number of changes made to this database instance
-    # since it was opened.
-    def total_changes
-      @driver.total_changes( @handle )
-    end
-
-    # Interrupts the currently executing operation, causing it to abort.
-    def interrupt
-      @driver.interrupt( @handle )
-    end
-
-    # Register a busy handler with this database instance. When a requested
-    # resource is busy, this handler will be invoked. If the handler returns
-    # +false+, the operation will be aborted; otherwise, the resource will
-    # be requested again.
-    #
-    # The handler will be invoked with the name of the resource that was
-    # busy, and the number of times it has been retried.
-    #
-    # See also the mutually exclusive #busy_timeout. 
-    def busy_handler( data=nil, &block ) # :yields: data, retries
-      result = @driver.busy_handler( @handle, data, &block )
-      Error.check( result, self )
-    end
-
-    # Indicates that if a request for a resource terminates because that
-    # resource is busy, SQLite should sleep and retry for up to the indicated
-    # number of milliseconds. By default, SQLite does not retry
-    # busy resources. To restore the default behavior, send 0 as the
-    # +ms+ parameter.
-    #
-    # See also the mutually exclusive #busy_handler.
-    def busy_timeout( ms )
-      result = @driver.busy_timeout( @handle, ms )
-      Error.check( result, self )
-    end
-
-    # Creates a new function for use in SQL statements. It will be added as
-    # +name+, with the given +arity+. (For variable arity functions, use
-    # -1 for the arity.)
-    #
-    # The block should accept at least one parameter--the FunctionProxy
-    # instance that wraps this function invocation--and any other
-    # arguments it needs (up to its arity).
-    #
-    # The block does not return a value directly. Instead, it will invoke
-    # the FunctionProxy#set_result method on the +func+ parameter and
-    # indicate the return value that way.
-    #
-    # Example:
-    #
-    #   db.create_function( "maim", 1 ) do |func, value|
-    #     if value.nil?
-    #       func.result = nil
-    #     else
-    #       func.result = value.split(//).sort.join
-    #     end
-    #   end
-    #
-    #   puts db.get_first_value( "select maim(name) from table" )
-    def create_function( name, arity, text_rep=Constants::TextRep::ANY,
-      &block ) # :yields: func, *args
-    # begin
-      callback = proc do |func,*args|
-        begin
-          block.call( FunctionProxy.new( @driver, func ),
-            *args.map{|v| Value.new(self,v)} )
-        rescue StandardError, Exception => e
-          @driver.result_error( func,
-            "#{e.message} (#{e.class})", -1 )
-        end
-      end
-
-      result = @driver.create_function( @handle, name, arity, text_rep, nil,
-        callback, nil, nil )
-      Error.check( result, self )
-
-      self
-    end
-
-    # Creates a new aggregate function for use in SQL statements. Aggregate
-    # functions are functions that apply over every row in the result set,
-    # instead of over just a single row. (A very common aggregate function
-    # is the "count" function, for determining the number of rows that match
-    # a query.)
-    #
-    # The new function will be added as +name+, with the given +arity+. (For
-    # variable arity functions, use -1 for the arity.)
-    #
-    # The +step+ parameter must be a proc object that accepts as its first
-    # parameter a FunctionProxy instance (representing the function
-    # invocation), with any subsequent parameters (up to the function's arity).
-    # The +step+ callback will be invoked once for each row of the result set.
-    #
-    # The +finalize+ parameter must be a +proc+ object that accepts only a
-    # single parameter, the FunctionProxy instance representing the current
-    # function invocation. It should invoke FunctionProxy#set_result to
-    # store the result of the function.
-    #
-    # Example:
-    #
-    #   db.create_aggregate( "lengths", 1 ) do
-    #     step do |func, value|
-    #       func[ :total ] ||= 0
-    #       func[ :total ] += ( value ? value.length : 0 )
-    #     end
-    #
-    #     finalize do |func|
-    #       func.set_result( func[ :total ] || 0 )
-    #     end
-    #   end
-    #
-    #   puts db.get_first_value( "select lengths(name) from table" )
-    #
-    # See also #create_aggregate_handler for a more object-oriented approach to
-    # aggregate functions.
-    def create_aggregate( name, arity, step=nil, finalize=nil,
-      text_rep=Constants::TextRep::ANY, &block )
-    # begin
-      if block
-        proxy = AggregateDefinitionProxy.new
-        proxy.instance_eval(&block)
-        step ||= proxy.step_callback
-        finalize ||= proxy.finalize_callback
-      end
-
-      step_callback = proc do |func,*args|
-        ctx = @driver.aggregate_context( func )
-        unless ctx[:__error]
-          begin
-            step.call( FunctionProxy.new( @driver, func, ctx ),
-              *args.map{|v| Value.new(self,v)} )
-          rescue Exception => e
-            ctx[:__error] = e
-          end
-        end
-      end
-
-      finalize_callback = proc do |func|
-        ctx = @driver.aggregate_context( func )
-        unless ctx[:__error]
-          begin
-            finalize.call( FunctionProxy.new( @driver, func, ctx ) )
-          rescue Exception => e
-            @driver.result_error( func,
-              "#{e.message} (#{e.class})", -1 )
-          end
-        else
-          e = ctx[:__error]
-          @driver.result_error( func,
-            "#{e.message} (#{e.class})", -1 )
-        end
-      end
-
-      result = @driver.create_function( @handle, name, arity, text_rep, nil,
-        nil, step_callback, finalize_callback )
-      Error.check( result, self )
-
-      self
-    end
-
-    # This is another approach to creating an aggregate function (see
-    # #create_aggregate). Instead of explicitly specifying the name,
-    # callbacks, arity, and type, you specify a factory object
-    # (the "handler") that knows how to obtain all of that information. The
-    # handler should respond to the following messages:
-    #
-    # +arity+:: corresponds to the +arity+ parameter of #create_aggregate. This
-    #           message is optional, and if the handler does not respond to it,
-    #           the function will have an arity of -1.
-    # +name+:: this is the name of the function. The handler _must_ implement
-    #          this message.
-    # +new+:: this must be implemented by the handler. It should return a new
-    #         instance of the object that will handle a specific invocation of
-    #         the function.
-    #
-    # The handler instance (the object returned by the +new+ message, described
-    # above), must respond to the following messages:
-    #
-    # +step+:: this is the method that will be called for each step of the
-    #          aggregate function's evaluation. It should implement the same
-    #          signature as the +step+ callback for #create_aggregate.
-    # +finalize+:: this is the method that will be called to finalize the
-    #              aggregate function's evaluation. It should implement the
-    #              same signature as the +finalize+ callback for
-    #              #create_aggregate.
-    #
-    # Example:
-    #
-    #   class LengthsAggregateHandler
-    #     def self.arity; 1; end
-    #
-    #     def initialize
-    #       @total = 0
-    #     end
-    #
-    #     def step( ctx, name )
-    #       @total += ( name ? name.length : 0 )
-    #     end
-    #
-    #     def finalize( ctx )
-    #       ctx.set_result( @total )
-    #     end
-    #   end
-    #
-    #   db.create_aggregate_handler( LengthsAggregateHandler )
-    #   puts db.get_first_value( "select lengths(name) from A" )
-    def create_aggregate_handler( handler )
-      arity = -1
-      text_rep = Constants::TextRep::ANY
-
-      arity = handler.arity if handler.respond_to?(:arity)
-      text_rep = handler.text_rep if handler.respond_to?(:text_rep)
-      name = handler.name
-
-      step = proc do |func,*args|
-        ctx = @driver.aggregate_context( func )
-        unless ctx[ :__error ]
-          ctx[ :handler ] ||= handler.new
-          begin
-            ctx[ :handler ].step( FunctionProxy.new( @driver, func, ctx ),
-              *args.map{|v| Value.new(self,v)} )
-          rescue Exception, StandardError => e
-            ctx[ :__error ] = e
-          end
-        end
-      end
-
-      finalize = proc do |func|
-        ctx = @driver.aggregate_context( func )
-        unless ctx[ :__error ]
-          ctx[ :handler ] ||= handler.new
-          begin
-            ctx[ :handler ].finalize( FunctionProxy.new( @driver, func, ctx ) )
-          rescue Exception => e
-            ctx[ :__error ] = e
-          end
-        end
-
-        if ctx[ :__error ]
-          e = ctx[ :__error ]
-          @driver.sqlite3_result_error( func, "#{e.message} (#{e.class})", -1 )
-        end
-      end
-
-      result = @driver.create_function( @handle, name, arity, text_rep, nil,
-        nil, step, finalize )
-      Error.check( result, self )
-
-      self
-    end
-
-    # Begins a new transaction. Note that nested transactions are not allowed
-    # by SQLite, so attempting to nest a transaction will result in a runtime
-    # exception.
-    #
-    # The +mode+ parameter may be either <tt>:deferred</tt> (the default),
-    # <tt>:immediate</tt>, or <tt>:exclusive</tt>.
-    #
-    # If a block is given, the database instance is yielded to it, and the
-    # transaction is committed when the block terminates. If the block
-    # raises an exception, a rollback will be performed instead. Note that if
-    # a block is given, #commit and #rollback should never be called
-    # explicitly or you'll get an error when the block terminates.
-    #
-    # If a block is not given, it is the caller's responsibility to end the
-    # transaction explicitly, either by calling #commit, or by calling
-    # #rollback.
-    def transaction( mode = :deferred )
-      execute "begin #{mode.to_s} transaction"
-      @transaction_active = true
-
-      if block_given?
-        abort = false
-        begin
-          yield self
-        rescue ::Object
-          abort = true
-          raise
-        ensure
-          abort and rollback or commit
-        end
-      end
-
-      true
-    end
-
-    # Commits the current transaction. If there is no current transaction,
-    # this will cause an error to be raised. This returns +true+, in order
-    # to allow it to be used in idioms like
-    # <tt>abort? and rollback or commit</tt>.
-    def commit
-      execute "commit transaction"
-      @transaction_active = false
-      true
-    end
-
-    # Rolls the current transaction back. If there is no current transaction,
-    # this will cause an error to be raised. This returns +true+, in order
-    # to allow it to be used in idioms like
-    # <tt>abort? and rollback or commit</tt>.
-    def rollback
-      execute "rollback transaction"
-      @transaction_active = false
-      true
-    end
-
-    # Returns +true+ if there is a transaction active, and +false+ otherwise.
-    def transaction_active?
-      @transaction_active
-    end
-
-    # Loads the corresponding driver, or if it is nil, attempts to locate a
-    # suitable driver.
-    def load_driver( driver )
-      case driver
-        when Class
-          # do nothing--use what was given
-        when Symbol, String
-          require "sqlite3/driver/#{driver.to_s.downcase}/driver"
-          driver = SQLite3::Driver.const_get( driver )::Driver
-        else
-          [ "Native", "DL" ].each do |d|
-            begin
-              require "sqlite3/driver/#{d.downcase}/driver"
-              driver = SQLite3::Driver.const_get( d )::Driver
-              break
-            rescue SyntaxError
-              raise
-            rescue ScriptError, Exception, NameError
-            end
-          end
-          raise "no driver for sqlite3 found" unless driver
-      end
-
-      @driver = driver.new
-    end
-    private :load_driver
-
-    # A helper class for dealing with custom functions (see #create_function,
-    # #create_aggregate, and #create_aggregate_handler). It encapsulates the
-    # opaque function object that represents the current invocation. It also
-    # provides more convenient access to the API functions that operate on
-    # the function object.
-    #
-    # This class will almost _always_ be instantiated indirectly, by working
-    # with the create methods mentioned above.
-    class FunctionProxy
-
-      # Create a new FunctionProxy that encapsulates the given +func+ object.
-      # If context is non-nil, the functions context will be set to that. If
-      # it is non-nil, it must quack like a Hash. If it is nil, then none of
-      # the context functions will be available.
-      def initialize( driver, func, context=nil )
-        @driver = driver
-        @func = func
-        @context = context
-      end
-
-      # Calls #set_result to set the result of this function.
-      def result=( result )
-        set_result( result )
-      end
-
-      # Set the result of the function to the given value. The function will
-      # then return this value.
-      def set_result( result, utf16=false )
-        @driver.result_text( @func, result, utf16 )
-      end
-
-      # Set the result of the function to the given error message.
-      # The function will then return that error.
-      def set_error( error )
-        @driver.result_error( @func, error.to_s, -1 )
-      end
-
-      # (Only available to aggregate functions.) Returns the number of rows
-      # that the aggregate has processed so far. This will include the current
-      # row, and so will always return at least 1.
-      def count
-        ensure_aggregate!
-        @driver.aggregate_count( @func )
-      end
-
-      # Returns the value with the given key from the context. This is only
-      # available to aggregate functions.
-      def []( key )
-        ensure_aggregate!
-        @context[ key ]
-      end
-
-      # Sets the value with the given key in the context. This is only
-      # available to aggregate functions.
-      def []=( key, value )
-        ensure_aggregate!
-        @context[ key ] = value
-      end
-
-      # A function for performing a sanity check, to ensure that the function
-      # being invoked is an aggregate function. This is implied by the
-      # existence of the context variable.
-      def ensure_aggregate!
-        unless @context
-          raise MisuseException, "function is not an aggregate"
-        end
-      end
-      private :ensure_aggregate!
-
-    end
-
-    # A proxy used for defining the callbacks to an aggregate function.
-    class AggregateDefinitionProxy # :nodoc:
-      attr_reader :step_callback, :finalize_callback
-
-      def step( &block )
-        @step_callback = block
-      end
-
-      def finalize( &block )
-        @finalize_callback = block
-      end
-    end
-
-  end
-
-end
-
+require 'sqlite3/constants'
+require 'sqlite3/errors'
+require 'sqlite3/pragmas'
+require 'sqlite3/statement'
+require 'sqlite3/translator'
+require 'sqlite3/value'
+
+module SQLite3
+
+  # The Database class encapsulates a single connection to a SQLite3 database.
+  # Its usage is very straightforward:
+  #
+  #   require 'sqlite3'
+  #
+  #   SQLite3::Database.new( "data.db" ) do |db|
+  #     db.execute( "select * from table" ) do |row|
+  #       p row
+  #     end
+  #   end
+  #
+  # It wraps the lower-level methods provides by the selected driver, and
+  # includes the Pragmas module for access to various pragma convenience
+  # methods.
+  #
+  # The Database class provides type translation services as well, by which
+  # the SQLite3 data types (which are all represented as strings) may be
+  # converted into their corresponding types (as defined in the schemas
+  # for their tables). This translation only occurs when querying data from
+  # the database--insertions and updates are all still typeless.
+  #
+  # Furthermore, the Database class has been designed to work well with the
+  # ArrayFields module from Ara Howard. If you require the ArrayFields
+  # module before performing a query, and if you have not enabled results as
+  # hashes, then the results will all be indexible by field name.
+  class Database
+    include Pragmas
+
+    class <<self
+
+      alias :open :new
+
+      # Quotes the given string, making it safe to use in an SQL statement.
+      # It replaces all instances of the single-quote character with two
+      # single-quote characters. The modified string is returned.
+      def quote( string )
+        string.gsub( /'/, "''" )
+      end
+
+    end
+
+    # The low-level opaque database handle that this object wraps.
+    attr_reader :handle
+
+    # A reference to the underlying SQLite3 driver used by this database.
+    attr_reader :driver
+
+    # A boolean that indicates whether rows in result sets should be returned
+    # as hashes or not. By default, rows are returned as arrays.
+    attr_accessor :results_as_hash
+
+    # A boolean indicating whether or not type translation is enabled for this
+    # database.
+    attr_accessor :type_translation
+
+    # Create a new Database object that opens the given file. If utf16
+    # is +true+, the filename is interpreted as a UTF-16 encoded string.
+    #
+    # By default, the new database will return result rows as arrays
+    # (#results_as_hash) and has type translation disabled (#type_translation=).
+    def initialize( file_name, options={} ) # :yields: db
+      utf16 = options.fetch(:utf16, false)
+      load_driver( options[:driver] )
+
+      @statement_factory = options[:statement_factory] || Statement
+
+      result, @handle = @driver.open( file_name, utf16 )
+      Error.check( result, self, "could not open database" )
+
+      @closed = false
+      @results_as_hash = options.fetch(:results_as_hash,false)
+      @type_translation = options.fetch(:type_translation,false)
+      @translator = nil
+      @transaction_active = false
+      
+      if block_given?
+        begin
+          yield self
+        ensure
+          self.close
+        end
+      end
+    end
+
+    # Return +true+ if the string is a valid (ie, parsable) SQL statement, and
+    # +false+ otherwise. If +utf16+ is +true+, then the string is a UTF-16
+    # character string.
+    def complete?( string, utf16=false )
+      @driver.complete?( string, utf16 )
+    end
+
+    # Return a string describing the last error to have occurred with this
+    # database.
+    def errmsg( utf16=false )
+      @driver.errmsg( @handle, utf16 )
+    end
+
+    # Return an integer representing the last error to have occurred with this
+    # database.
+    def errcode
+      @driver.errcode( @handle )
+    end
+
+    # Return the type translator employed by this database instance. Each
+    # database instance has its own type translator; this allows for different
+    # type handlers to be installed in each instance without affecting other
+    # instances. Furthermore, the translators are instantiated lazily, so that
+    # if a database does not use type translation, it will not be burdened by
+    # the overhead of a useless type translator. (See the Translator class.)
+    def translator
+      @translator ||= Translator.new
+    end
+
+    # Closes this database.
+    def close
+      unless @closed
+        result = @driver.close( @handle )
+        Error.check( result, self )
+      end
+      @closed = true
+    end
+
+    # Returns +true+ if this database instance has been closed (see #close).
+    def closed?
+      @closed
+    end
+
+    # Installs (or removes) a block that will be invoked for every SQL
+    # statement executed. The block receives a two parameters: the +data+
+    # argument, and the SQL statement executed. If the block is +nil+,
+    # any existing tracer will be uninstalled.
+    def trace( data=nil, &block )
+      @driver.trace( @handle, data, &block )
+    end
+
+    # Installs (or removes) a block that will be invoked for every access
+    # to the database. If the block returns 0 (or +nil+), the statement
+    # is allowed to proceed. Returning 1 causes an authorization error to
+    # occur, and returning 2 causes the access to be silently denied.
+    def authorizer( data=nil, &block )
+      result = @driver.set_authorizer( @handle, data, &block )
+      Error.check( result, self )
+    end
+
+    # Returns a Statement object representing the given SQL. This does not
+    # execute the statement; it merely prepares the statement for execution.
+    #
+    # The Statement can then be executed using Statement#execute.
+    #
+    def prepare( sql )
+      stmt = @statement_factory.new( self, sql )
+      if block_given?
+        begin
+          yield stmt
+        ensure
+          stmt.close
+        end
+      else
+        return stmt
+      end
+    end
+
+    # Executes the given SQL statement. If additional parameters are given,
+    # they are treated as bind variables, and are bound to the placeholders in
+    # the query.
+    #
+    # Note that if any of the values passed to this are hashes, then the
+    # key/value pairs are each bound separately, with the key being used as
+    # the name of the placeholder to bind the value to.
+    #
+    # The block is optional. If given, it will be invoked for each row returned
+    # by the query. Otherwise, any results are accumulated into an array and
+    # returned wholesale.
+    #
+    # See also #execute2, #query, and #execute_batch for additional ways of
+    # executing statements.
+    def execute( sql, *bind_vars )
+      prepare( sql ) do |stmt|
+        result = stmt.execute( *bind_vars )
+        if block_given?
+          result.each { |row| yield row }
+        else
+          return result.inject( [] ) { |arr,row| arr << row; arr }
+        end
+      end
+    end
+
+    # Executes the given SQL statement, exactly as with #execute. However, the
+    # first row returned (either via the block, or in the returned array) is
+    # always the names of the columns. Subsequent rows correspond to the data
+    # from the result set.
+    #
+    # Thus, even if the query itself returns no rows, this method will always
+    # return at least one row--the names of the columns.
+    #
+    # See also #execute, #query, and #execute_batch for additional ways of
+    # executing statements.
+    def execute2( sql, *bind_vars )
+      prepare( sql ) do |stmt|
+        result = stmt.execute( *bind_vars )
+        if block_given?
+          yield result.columns
+          result.each { |row| yield row }
+        else
+          return result.inject( [ result.columns ] ) { |arr,row|
+            arr << row; arr }
+        end
+      end
+    end
+
+    # Executes all SQL statements in the given string. By contrast, the other
+    # means of executing queries will only execute the first statement in the
+    # string, ignoring all subsequent statements. This will execute each one
+    # in turn. The same bind parameters, if given, will be applied to each
+    # statement.
+    #
+    # This always returns +nil+, making it unsuitable for queries that return
+    # rows.
+    def execute_batch( sql, *bind_vars )
+      sql = sql.strip
+      until sql.empty? do
+        prepare( sql ) do |stmt|
+          stmt.execute( *bind_vars )
+          sql = stmt.remainder.strip
+        end
+      end
+      nil
+    end
+
+    # This is a convenience method for creating a statement, binding
+    # paramters to it, and calling execute:
+    #
+    #   result = db.query( "select * from foo where a=?", 5 )
+    #   # is the same as
+    #   result = db.prepare( "select * from foo where a=?" ).execute( 5 )
+    #
+    # You must be sure to call +close+ on the ResultSet instance that is
+    # returned, or you could have problems with locks on the table. If called
+    # with a block, +close+ will be invoked implicitly when the block 
+    # terminates.
+    def query( sql, *bind_vars )
+      result = prepare( sql ).execute( *bind_vars )
+      if block_given?
+        begin
+          yield result
+        ensure
+          result.close
+        end
+      else
+        return result
+      end
+    end
+
+    # A convenience method for obtaining the first row of a result set, and
+    # discarding all others. It is otherwise identical to #execute.
+    #
+    # See also #get_first_value.
+    def get_first_row( sql, *bind_vars )
+      execute( sql, *bind_vars ) { |row| return row }
+      nil
+    end
+
+    # A convenience method for obtaining the first value of the first row of a
+    # result set, and discarding all other values and rows. It is otherwise
+    # identical to #execute.
+    #
+    # See also #get_first_row.
+    def get_first_value( sql, *bind_vars )
+      execute( sql, *bind_vars ) { |row| return row[0] }
+      nil
+    end
+
+    # Obtains the unique row ID of the last row to be inserted by this Database
+    # instance.
+    def last_insert_row_id
+      @driver.last_insert_rowid( @handle )
+    end
+
+    # Returns the number of changes made to this database instance by the last
+    # operation performed. Note that a "delete from table" without a where
+    # clause will not affect this value.
+    def changes
+      @driver.changes( @handle )
+    end
+
+    # Returns the total number of changes made to this database instance
+    # since it was opened.
+    def total_changes
+      @driver.total_changes( @handle )
+    end
+
+    # Interrupts the currently executing operation, causing it to abort.
+    def interrupt
+      @driver.interrupt( @handle )
+    end
+
+    # Register a busy handler with this database instance. When a requested
+    # resource is busy, this handler will be invoked. If the handler returns
+    # +false+, the operation will be aborted; otherwise, the resource will
+    # be requested again.
+    #
+    # The handler will be invoked with the name of the resource that was
+    # busy, and the number of times it has been retried.
+    #
+    # See also the mutually exclusive #busy_timeout. 
+    def busy_handler( data=nil, &block ) # :yields: data, retries
+      result = @driver.busy_handler( @handle, data, &block )
+      Error.check( result, self )
+    end
+
+    # Indicates that if a request for a resource terminates because that
+    # resource is busy, SQLite should sleep and retry for up to the indicated
+    # number of milliseconds. By default, SQLite does not retry
+    # busy resources. To restore the default behavior, send 0 as the
+    # +ms+ parameter.
+    #
+    # See also the mutually exclusive #busy_handler.
+    def busy_timeout( ms )
+      result = @driver.busy_timeout( @handle, ms )
+      Error.check( result, self )
+    end
+
+    # Creates a new function for use in SQL statements. It will be added as
+    # +name+, with the given +arity+. (For variable arity functions, use
+    # -1 for the arity.)
+    #
+    # The block should accept at least one parameter--the FunctionProxy
+    # instance that wraps this function invocation--and any other
+    # arguments it needs (up to its arity).
+    #
+    # The block does not return a value directly. Instead, it will invoke
+    # the FunctionProxy#set_result method on the +func+ parameter and
+    # indicate the return value that way.
+    #
+    # Example:
+    #
+    #   db.create_function( "maim", 1 ) do |func, value|
+    #     if value.nil?
+    #       func.result = nil
+    #     else
+    #       func.result = value.split(//).sort.join
+    #     end
+    #   end
+    #
+    #   puts db.get_first_value( "select maim(name) from table" )
+    def create_function( name, arity, text_rep=Constants::TextRep::ANY,
+      &block ) # :yields: func, *args
+    # begin
+      callback = proc do |func,*args|
+        begin
+          block.call( FunctionProxy.new( @driver, func ),
+            *args.map{|v| Value.new(self,v)} )
+        rescue StandardError, Exception => e
+          @driver.result_error( func,
+            "#{e.message} (#{e.class})", -1 )
+        end
+      end
+
+      result = @driver.create_function( @handle, name, arity, text_rep, nil,
+        callback, nil, nil )
+      Error.check( result, self )
+
+      self
+    end
+
+    # Creates a new aggregate function for use in SQL statements. Aggregate
+    # functions are functions that apply over every row in the result set,
+    # instead of over just a single row. (A very common aggregate function
+    # is the "count" function, for determining the number of rows that match
+    # a query.)
+    #
+    # The new function will be added as +name+, with the given +arity+. (For
+    # variable arity functions, use -1 for the arity.)
+    #
+    # The +step+ parameter must be a proc object that accepts as its first
+    # parameter a FunctionProxy instance (representing the function
+    # invocation), with any subsequent parameters (up to the function's arity).
+    # The +step+ callback will be invoked once for each row of the result set.
+    #
+    # The +finalize+ parameter must be a +proc+ object that accepts only a
+    # single parameter, the FunctionProxy instance representing the current
+    # function invocation. It should invoke FunctionProxy#set_result to
+    # store the result of the function.
+    #
+    # Example:
+    #
+    #   db.create_aggregate( "lengths", 1 ) do
+    #     step do |func, value|
+    #       func[ :total ] ||= 0
+    #       func[ :total ] += ( value ? value.length : 0 )
+    #     end
+    #
+    #     finalize do |func|
+    #       func.set_result( func[ :total ] || 0 )
+    #     end
+    #   end
+    #
+    #   puts db.get_first_value( "select lengths(name) from table" )
+    #
+    # See also #create_aggregate_handler for a more object-oriented approach to
+    # aggregate functions.
+    def create_aggregate( name, arity, step=nil, finalize=nil,
+      text_rep=Constants::TextRep::ANY, &block )
+    # begin
+      if block
+        proxy = AggregateDefinitionProxy.new
+        proxy.instance_eval(&block)
+        step ||= proxy.step_callback
+        finalize ||= proxy.finalize_callback
+      end
+
+      step_callback = proc do |func,*args|
+        ctx = @driver.aggregate_context( func )
+        unless ctx[:__error]
+          begin
+            step.call( FunctionProxy.new( @driver, func, ctx ),
+              *args.map{|v| Value.new(self,v)} )
+          rescue Exception => e
+            ctx[:__error] = e
+          end
+        end
+      end
+
+      finalize_callback = proc do |func|
+        ctx = @driver.aggregate_context( func )
+        unless ctx[:__error]
+          begin
+            finalize.call( FunctionProxy.new( @driver, func, ctx ) )
+          rescue Exception => e
+            @driver.result_error( func,
+              "#{e.message} (#{e.class})", -1 )
+          end
+        else
+          e = ctx[:__error]
+          @driver.result_error( func,
+            "#{e.message} (#{e.class})", -1 )
+        end
+      end
+
+      result = @driver.create_function( @handle, name, arity, text_rep, nil,
+        nil, step_callback, finalize_callback )
+      Error.check( result, self )
+
+      self
+    end
+
+    # This is another approach to creating an aggregate function (see
+    # #create_aggregate). Instead of explicitly specifying the name,
+    # callbacks, arity, and type, you specify a factory object
+    # (the "handler") that knows how to obtain all of that information. The
+    # handler should respond to the following messages:
+    #
+    # +arity+:: corresponds to the +arity+ parameter of #create_aggregate. This
+    #           message is optional, and if the handler does not respond to it,
+    #           the function will have an arity of -1.
+    # +name+:: this is the name of the function. The handler _must_ implement
+    #          this message.
+    # +new+:: this must be implemented by the handler. It should return a new
+    #         instance of the object that will handle a specific invocation of
+    #         the function.
+    #
+    # The handler instance (the object returned by the +new+ message, described
+    # above), must respond to the following messages:
+    #
+    # +step+:: this is the method that will be called for each step of the
+    #          aggregate function's evaluation. It should implement the same
+    #          signature as the +step+ callback for #create_aggregate.
+    # +finalize+:: this is the method that will be called to finalize the
+    #              aggregate function's evaluation. It should implement the
+    #              same signature as the +finalize+ callback for
+    #              #create_aggregate.
+    #
+    # Example:
+    #
+    #   class LengthsAggregateHandler
+    #     def self.arity; 1; end
+    #
+    #     def initialize
+    #       @total = 0
+    #     end
+    #
+    #     def step( ctx, name )
+    #       @total += ( name ? name.length : 0 )
+    #     end
+    #
+    #     def finalize( ctx )
+    #       ctx.set_result( @total )
+    #     end
+    #   end
+    #
+    #   db.create_aggregate_handler( LengthsAggregateHandler )
+    #   puts db.get_first_value( "select lengths(name) from A" )
+    def create_aggregate_handler( handler )
+      arity = -1
+      text_rep = Constants::TextRep::ANY
+
+      arity = handler.arity if handler.respond_to?(:arity)
+      text_rep = handler.text_rep if handler.respond_to?(:text_rep)
+      name = handler.name
+
+      step = proc do |func,*args|
+        ctx = @driver.aggregate_context( func )
+        unless ctx[ :__error ]
+          ctx[ :handler ] ||= handler.new
+          begin
+            ctx[ :handler ].step( FunctionProxy.new( @driver, func, ctx ),
+              *args.map{|v| Value.new(self,v)} )
+          rescue Exception, StandardError => e
+            ctx[ :__error ] = e
+          end
+        end
+      end
+
+      finalize = proc do |func|
+        ctx = @driver.aggregate_context( func )
+        unless ctx[ :__error ]
+          ctx[ :handler ] ||= handler.new
+          begin
+            ctx[ :handler ].finalize( FunctionProxy.new( @driver, func, ctx ) )
+          rescue Exception => e
+            ctx[ :__error ] = e
+          end
+        end
+
+        if ctx[ :__error ]
+          e = ctx[ :__error ]
+          @driver.sqlite3_result_error( func, "#{e.message} (#{e.class})", -1 )
+        end
+      end
+
+      result = @driver.create_function( @handle, name, arity, text_rep, nil,
+        nil, step, finalize )
+      Error.check( result, self )
+
+      self
+    end
+
+    # Begins a new transaction. Note that nested transactions are not allowed
+    # by SQLite, so attempting to nest a transaction will result in a runtime
+    # exception.
+    #
+    # The +mode+ parameter may be either <tt>:deferred</tt> (the default),
+    # <tt>:immediate</tt>, or <tt>:exclusive</tt>.
+    #
+    # If a block is given, the database instance is yielded to it, and the
+    # transaction is committed when the block terminates. If the block
+    # raises an exception, a rollback will be performed instead. Note that if
+    # a block is given, #commit and #rollback should never be called
+    # explicitly or you'll get an error when the block terminates.
+    #
+    # If a block is not given, it is the caller's responsibility to end the
+    # transaction explicitly, either by calling #commit, or by calling
+    # #rollback.
+    def transaction( mode = :deferred )
+      execute "begin #{mode.to_s} transaction"
+      @transaction_active = true
+
+      if block_given?
+        abort = false
+        begin
+          yield self
+        rescue ::Object
+          abort = true
+          raise
+        ensure
+          abort and rollback or commit
+        end
+      end
+
+      true
+    end
+
+    # Commits the current transaction. If there is no current transaction,
+    # this will cause an error to be raised. This returns +true+, in order
+    # to allow it to be used in idioms like
+    # <tt>abort? and rollback or commit</tt>.
+    def commit
+      execute "commit transaction"
+      @transaction_active = false
+      true
+    end
+
+    # Rolls the current transaction back. If there is no current transaction,
+    # this will cause an error to be raised. This returns +true+, in order
+    # to allow it to be used in idioms like
+    # <tt>abort? and rollback or commit</tt>.
+    def rollback
+      execute "rollback transaction"
+      @transaction_active = false
+      true
+    end
+
+    # Returns +true+ if there is a transaction active, and +false+ otherwise.
+    def transaction_active?
+      @transaction_active
+    end
+
+    # Loads the corresponding driver, or if it is nil, attempts to locate a
+    # suitable driver.
+    def load_driver( driver )
+      case driver
+        when Class
+          # do nothing--use what was given
+        when Symbol, String
+          require "sqlite3/driver/#{driver.to_s.downcase}/driver"
+          driver = SQLite3::Driver.const_get( driver )::Driver
+        else
+          [ "Native", "DL" ].each do |d|
+            begin
+              require "sqlite3/driver/#{d.downcase}/driver"
+              driver = SQLite3::Driver.const_get( d )::Driver
+              break
+            rescue SyntaxError
+              raise
+            rescue ScriptError, Exception, NameError
+            end
+          end
+          raise "no driver for sqlite3 found" unless driver
+      end
+
+      @driver = driver.new
+    end
+    private :load_driver
+
+    # A helper class for dealing with custom functions (see #create_function,
+    # #create_aggregate, and #create_aggregate_handler). It encapsulates the
+    # opaque function object that represents the current invocation. It also
+    # provides more convenient access to the API functions that operate on
+    # the function object.
+    #
+    # This class will almost _always_ be instantiated indirectly, by working
+    # with the create methods mentioned above.
+    class FunctionProxy
+
+      # Create a new FunctionProxy that encapsulates the given +func+ object.
+      # If context is non-nil, the functions context will be set to that. If
+      # it is non-nil, it must quack like a Hash. If it is nil, then none of
+      # the context functions will be available.
+      def initialize( driver, func, context=nil )
+        @driver = driver
+        @func = func
+        @context = context
+      end
+
+      # Calls #set_result to set the result of this function.
+      def result=( result )
+        set_result( result )
+      end
+
+      # Set the result of the function to the given value. The function will
+      # then return this value.
+      def set_result( result, utf16=false )
+        @driver.result_text( @func, result, utf16 )
+      end
+
+      # Set the result of the function to the given error message.
+      # The function will then return that error.
+      def set_error( error )
+        @driver.result_error( @func, error.to_s, -1 )
+      end
+
+      # (Only available to aggregate functions.) Returns the number of rows
+      # that the aggregate has processed so far. This will include the current
+      # row, and so will always return at least 1.
+      def count
+        ensure_aggregate!
+        @driver.aggregate_count( @func )
+      end
+
+      # Returns the value with the given key from the context. This is only
+      # available to aggregate functions.
+      def []( key )
+        ensure_aggregate!
+        @context[ key ]
+      end
+
+      # Sets the value with the given key in the context. This is only
+      # available to aggregate functions.
+      def []=( key, value )
+        ensure_aggregate!
+        @context[ key ] = value
+      end
+
+      # A function for performing a sanity check, to ensure that the function
+      # being invoked is an aggregate function. This is implied by the
+      # existence of the context variable.
+      def ensure_aggregate!
+        unless @context
+          raise MisuseException, "function is not an aggregate"
+        end
+      end
+      private :ensure_aggregate!
+
+    end
+
+    # A proxy used for defining the callbacks to an aggregate function.
+    class AggregateDefinitionProxy # :nodoc:
+      attr_reader :step_callback, :finalize_callback
+
+      def step( &block )
+        @step_callback = block
+      end
+
+      def finalize( &block )
+        @finalize_callback = block
+      end
+    end
+
+  end
+
+end
+