amalgalite 0.5.1 → 0.6.0

data/lib/amalgalite/column.rb

@@ -34,7 +34,7 @@ module Amalgalite
     # the declared data type of the column in the original sql that created the
     # column
     attr_accessor :declared_data_type
-    
+
     # the collation sequence name of the column
     attr_accessor :collation_sequence_name
 

data/lib/amalgalite/database.rb

@@ -7,6 +7,10 @@ require 'amalgalite/statement'
 require 'amalgalite/trace_tap'
 require 'amalgalite/profile_tap'
 require 'amalgalite/type_maps/default_map'
+require 'amalgalite/function'
+require 'amalgalite/aggregate'
+require 'amalgalite/busy_timeout'
+require 'amalgalite/progress_handler'
 
 module Amalgalite
   #
@@ -31,6 +35,18 @@ module Amalgalite
     # Error thrown if a database is opened with an invalid mode
     class InvalidModeError < ::Amalgalite::Error; end
 
+    # Error thrown if there is a failure in a user defined function
+    class FunctionError < ::Amalgalite::Error; end
+
+    # Error thrown if there is a failure in a user defined aggregate
+    class AggregateError < ::Amalgalite::Error; end
+
+    # Error thrown if there is a failure in defining a busy handler
+    class BusyHandlerError < ::Amalgalite::Error; end
+
+    # Error thrown if there is a failure in defining a progress handler
+    class ProgressHandlerError < ::Amalgalite::Error; end
+
     ##
     # container class for holding transaction behavior constants.  These are the
     # SQLite values passed to a START TRANSACTION SQL statement.
@@ -43,7 +59,7 @@ module Amalgalite
       # a readlock is obtained immediately so that no other process can write to
       # the database
       IMMEDIATE = "IMMEDIATE"
-      
+
       # a read+write lock is obtained, no other proces can read or write to the
       # database
       EXCLUSIVE = "EXCLUSIVE"
@@ -81,6 +97,12 @@ module Amalgalite
     # By default this is an instances of TypeMaps::DefaultMap
     attr_reader :type_map
 
+    # A list of the user defined functions
+    attr_reader :functions
+
+    # A list of the user defined aggregates
+    attr_reader :aggregates
+
     ##
     # Create a new Amalgalite database
     #
@@ -114,6 +136,8 @@ module Amalgalite
       @profile_tap    = nil
       @trace_tap      = nil
       @type_map       = ::Amalgalite::TypeMaps::DefaultMap.new
+      @functions      = Hash.new 
+      @aggregates     = Hash.new
 
       unless VALID_MODES.keys.include?( mode ) 
         raise InvalidModeError, "#{mode} is invalid, must be one of #{VALID_MODES.keys.join(', ')}" 
@@ -509,6 +533,251 @@ module Amalgalite
     def rollback
       execute( "ROLLBACK" ) if in_transaction?
     end
-  end
+
+    ##
+    # call-seq:
+    #   db.function( "name", MyDBFunction.new )
+    #   db.function( "my_func", callable )
+    #   db.function( "my_func" ) do |x,y|
+    #     .... 
+    #     return result
+    #   end
+    #
+    # register a callback to be exposed as an SQL function.  There are multiple
+    # ways to register this function:
+    #
+    # 1. db.function( "name" ) { |a| ... }
+    #    * pass +function+ a _name_ and a block.  
+    #    * The SQL function _name_ taking _arity_ parameters will be registered, 
+    #      where _arity_ is the _arity_ of the block.
+    #    * The return value of the block is the return value of the registred
+    #      SQL function
+    # 2. db.function( "name", callable )
+    #    * pass +function+ a _name_ and something that <tt>responds_to?( :to_proc )</tt>
+    #    * The SQL function _name_ is registered taking _arity_ parameters is
+    #      registered where _arity_ is the _arity_ of +callable.to_proc.call+
+    #    * The return value of the +callable.to_proc.call+ is the return value
+    #      of the SQL function
+    #
+    # See also ::Amalgalite::Function
+    #
+    def define_function( name, callable = nil, &block ) 
+      p = ( callable || block ).to_proc
+      raise FunctionError, "Use only mandatory or arbitrary parameters in an SQL Function, not both" if p.arity < -1
+      db_function = ::Amalgalite::SQLite3::Database::Function.new( name, p )
+      @api.define_function( db_function.name, db_function )
+      @functions[db_function.signature] = db_function
+      nil
+    end
+    alias :function :define_function
+
+    ##
+    # call-seq:
+    #   db.remove_function( 'name', MyScalerFunctor.new )
+    #   db.remove_function( 'name', callable )
+    #   db.remove_function( 'name', arity )
+    #   db.remove_function( 'name' )
+    #
+    # Remove a function from use in the database.  Since the same function may
+    # be registered more than once with different arity, you may specify the
+    # arity, or the function object, or nil.  If nil is used for the arity, then
+    # Amalgalite does its best to remove all functions of given name.
+    #
+    def remove_function( name, callable_or_arity = nil )
+      arity = nil
+      if callable_or_arity.respond_to?( :to_proc ) then
+        arity = callable_or_arity.to_proc.arity
+      elsif callable_or_arity.respond_to?( :to_int ) then
+        arity = callable_or_arity.to_int
+      end
+      to_remove = []
+
+      if arity then
+        signature = ::Amalgalite::SQLite3::Database::Function.signature( name, arity ) 
+        db_function = @functions[ signature ]
+        raise FunctionError, "db function '#{name}' with arity #{arity} does not appear to be defined" unless db_function
+        to_remove << db_function
+      else
+        possibles = @functions.values.select { |f| f.name == name }
+        raise FunctionError, "no db function '#{name}' appears to be defined" if possibles.empty?
+        to_remove = possibles
+      end
+
+      to_remove.each do |db_function|
+        @api.remove_function( db_function.name, db_function) 
+        @functions.delete( db_function.signature )
+      end
+    end
+
+    ##
+    # call-seq:
+    #   db.define_aggregate( 'name', MyAggregateClass )
+    #
+    # Define an SQL aggregate function, these are functions like max(), min(),
+    # avg(), etc.  SQL functions that would be used when a GROUP BY clause is in
+    # effect.  See also ::Amalgalite::Aggregate.
+    #
+    # A new instance of MyAggregateClass is created for each instance that the
+    # SQL aggregate is mentioned in SQL.
+    #
+    def define_aggregate( name, klass )
+      db_aggregate = klass
+      a = klass.new
+      raise AggregateError, "Use only mandatory or arbitrary parameters in an SQL Aggregate, not both" if a.arity < -1
+      raise AggregateError, "Aggregate implementation name '#{a.name}' does not match defined name '#{name}'"if a.name != name
+      @api.define_aggregate( name, a.arity, klass )
+      @aggregates[a.signature] = db_aggregate
+      nil
+    end
+    alias :aggregate :define_aggregate
+
+    ##
+    # call-seq:
+    #   db.remove_aggregate( 'name', MyAggregateClass )
+    #   db.remove_aggregate( 'name' )
+    #
+    # Remove an aggregate from use in the database.  Since the same aggregate
+    # may be refistered more than once with different arity, you may specify the
+    # arity, or the aggregate class, or nil.  If nil is used for the arity then
+    # Amalgalite does its best to remove all aggregates of the given name
+    #
+    def remove_aggregate( name, klass_or_arity = nil )
+      klass = nil
+      case klass_or_arity
+      when Integer
+        arity = klass_or_arity
+      when NilClass
+        arity = nil
+      else
+        klass = klass_or_arity
+        arity = klass.new.arity
+      end
+      to_remove = []
+      if arity then
+        signature = ::Amalgalite::SQLite3::Database::Function.signature( name, arity )
+        db_aggregate = @aggregates[ signature ]
+        raise AggregateError, "db aggregate '#{name}' with arity #{arity} does not appear to be defined" unless db_aggregate
+        to_remove << db_aggregate
+      else
+        possibles = @aggregates.values.select { |a| a.new.name == name }
+        raise AggregateError, "no db aggregate '#{name}' appears to be defined" if possibles.empty?
+        to_remove = possibles
+      end
+
+      to_remove.each do |db_aggregate|
+        i = db_aggregate.new
+        @api.remove_aggregate( i.name, i.arity, db_aggregate )
+        @aggregates.delete( i.signature )
+      end
+    end
+
+    ##
+    # call-seq:
+    #   db.busy_handler( callable )
+    #   db.define_busy_handler do |count|
+    #   end
+    #   db.busy_handler( Amalgalite::BusyTimeout.new( 30 ) )
+    #
+    # Register a busy handler for this database connection, the handler MUST
+    # follow the +to_proc+ protocol indicating that is will 
+    # +respond_to?(:call)+.  This is intrinsic to lambdas and blocks so 
+    # those will work automatically.
+    #
+    # This exposes the sqlite busy handler api to ruby.
+    #
+    # * http://sqlite.org/c3ref/busy_handler.html
+    #
+    # The busy handler's _call(N)_ method may be invoked whenever an attempt is
+    # made to open a database table that another thread or process has locked.
+    # +N+ will be the number of times the _call(N)_ method has been invoked
+    # during this locking event.
+    #
+    # The handler may or maynot be called based upon what SQLite determins.
+    #
+    # If the handler returns _nil_ or _false_ then no more busy handler calls will
+    # be made in this lock event and you are probably going to see an
+    # SQLite::Error in your immediately future in another process or in another
+    # piece of code.
+    #
+    # If the handler returns non-nil or non-false then another attempt will be
+    # made to obtain the lock, lather, rinse, repeat.
+    #
+    # If an Exception happens in a busy handler, it will be the same as if the
+    # busy handler had returned _nil_ or _false_.  The exception itself will not
+    # be propogated further.
+    #
+    def define_busy_handler( callable = nil, &block )
+      handler = ( callable || block ).to_proc
+      a = handler.arity
+      raise BusyHandlerError, "A busy handler expects 1 and only 1 argument, not #{a}" if a != 1
+      @api.busy_handler( handler )
+    end
+    alias :busy_handler :define_busy_handler
+
+    ##
+    # call-seq:
+    #   db.remove_busy_handler
+    #
+    # Remove the busy handler for this database connection.
+    def remove_busy_handler
+      @api.busy_handler( nil )
+    end
+
+    ##
+    # call-seq:
+    #   db.interrupt!
+    #
+    # Cause another thread with a handle on this database to be interrupted and
+    # return at the earliest opportunity as interrupted.  It is not safe to call
+    # this method if the database might be closed before interrupt! returns.
+    #
+    def interrupt!
+      @api.interrupt!
+    end
+
+    ##
+    # call-seq:
+    #   db.progress_handler( 50, MyProgressHandler.new )
+    #   db.progress_handler( 25 , callable )
+    #   db.progress_handler do
+    #     ....
+    #     return result
+    #   end
+    #
+    # Register a progress handler for this database connection, the handler MUST
+    # follow the +to_proc+ protocol indicating that is will 
+    # +respond_to?(:call)+.  This is intrinsic to lambdas and blocks so 
+    # those will work automatically.
+    #
+    # This exposes the sqlite progress handler api to ruby.
+    #
+    # * http://sqlite.org/c3ref/progress_handler.html
+    #
+    # The progress handler's _call()_ method may be invoked ever N SQLite op
+    # codes.  If the progress handler returns anything that can evaluate to
+    # +true+ then current running sqlite statement is terminated at the earliest
+    # oppportunity.
+    #
+    # You can use this to be notified that a thread is still processingn a
+    # request.
+    #
+    def define_progress_handler( op_code_count = 25, callable = nil, &block )
+      handler  = ( callable || block ).to_proc
+      a = handler.arity
+      raise ProgressHandlerError, "A progress handler expects 0 arguments, not #{a}" if a != 0
+      @api.progress_handler( op_code_count, handler )
+    end
+    alias :progress_handler :define_progress_handler
+
+
+    ##
+    # call-seq:
+    #   db.remove_progress_handler
+    #
+    # Remove the progress handler for this database connection.
+    def remove_progress_handler
+      @api.progress_handler( nil, nil )
+    end
+ end
 end
 

data/lib/amalgalite/function.rb

@@ -0,0 +1,61 @@
+require 'amalgalite/sqlite3/database/function'
+module Amalgalite
+  #
+  # A Base class to inherit from for creating your own SQL scalar functions
+  # in ruby.
+  #
+  # These are SQL functions similar to _abs(X)_, _length(X)_, _random()_.  Items
+  # that take parameters and return value.  They have no state between
+  # calls. Built in SQLite scalar functions are :
+  #
+  # * http://www.sqlite.org/lang_corefunc.html
+  # * http://www.sqlite.org/lang_datefunc.html
+  #
+  # Functions defined in Amalgalite databases conform to the Proc interface.
+  # Everything that is defined in an Amalgalite database using +define_function+
+  # has its +to_proc+ method called.  As a result, any Function must also
+  # conform to the +to_proc+ protocol.
+  #
+  # If you choose to use Function as a parent class of your SQL scalar function
+  # implementation you should only have implement +call+ with the appropriate
+  # _arity_.
+  #
+  # For instance to implement a _sha1(X)_ SQL function you could implement it as
+  #
+  #   class SQLSha1 < ::Amalgalite::Function
+  #     def initialize
+  #       super( 'md5', 1 )
+  #     end
+  #     def call( s )
+  #       ::Digest::MD5.hexdigest( s.to_s )
+  #     end
+  #   end
+  #
+  class Function
+    # The name of the SQL function
+    attr_accessor :name
+
+    # The arity of the SQL function
+    attr_accessor :arity
+
+    # Initialize the function with a name and arity
+    def initialize( name, arity )
+      @name = name
+      @arity = arity
+    end
+
+    # All SQL functions defined foloow the +to_proc+ protocol
+    def to_proc
+      self
+    end
+
+    # <b>Do Not Override</b>
+    #
+    # The function signature for use by the Amaglaite datase in tracking
+    # function definition and removal.
+    #
+    def signature
+      @signature ||= ::Amalgalite::SQLite3::Database::Function.signature( self.name, self.arity )
+    end
+  end
+end

data/lib/amalgalite/progress_handler.rb

@@ -0,0 +1,21 @@
+module Amalgalite
+  ##
+  # A base class for use in creating your own progress handler classes
+  #
+  class ProgressHandler
+    def to_proc
+      self
+    end
+
+    # the arity of the call method
+    def arity() 0 ; end
+
+    ##
+    # Override this method, returning +false+ if the SQLite should act as if
+    # +interrupt!+ had been invoked.
+    # 
+    def call
+      raise NotImplementedError, "The progress handler call() method must be implemented"
+    end
+  end
+end

data/lib/amalgalite/sqlite3.rb

@@ -4,3 +4,4 @@ require 'amalgalite/sqlite3/version'
 require 'amalgalite/sqlite3/constants'
 require 'amalgalite/sqlite3/status'
 require 'amalgalite/sqlite3/database/status'
+require 'amalgalite/sqlite3/database/function'

data/lib/amalgalite/sqlite3/database/function.rb

@@ -0,0 +1,48 @@
+module Amalgalite::SQLite3
+  class Database
+    ##
+    # A wrapper around a proc for use as an SQLite Ddatabase fuction
+    #
+    #   f = Function.new( 'md5', lambda { |x| Digest::MD5.hexdigest( x.to_s ) } )
+    #
+    class Function
+
+      # the name of the function, and how it will be called in SQL
+      attr_reader :name
+
+      # The unique signature of this function.  This is used to determin if the
+      # function is already registered or not
+      #
+      def self.signature( name, arity )
+        "#{name}/#{arity}"
+      end
+
+      # Initialize with the name and the Proc
+      #
+      def initialize( name, _proc )
+        @name = name
+        @function = _proc
+      end
+
+      # The unique signature of this function
+      #
+      def signature
+        @signature ||= Function.signature( name, arity )
+      end
+      alias :to_s :signature
+
+      # The arity of SQL function, -1 means it is takes a variable number of
+      # arguments.
+      #
+      def arity
+        @function.arity
+      end
+
+      # Invoke the proc 
+      #
+      def call( *args )
+        @function.call( *args )
+      end
+    end
+  end
+end