amalgalite 0.10.1-x86-mingw32

data/lib/amalgalite/aggregate.rb

@@ -0,0 +1,67 @@
+require 'amalgalite/sqlite3/database/function'
+module Amalgalite
+  #
+  # A Base class to inherit from for creating your own SQL aggregate functions
+  # in ruby.
+  #
+  # These are SQL functions similar to _max(X)_, _count(X)_, _avg(X)_. The built
+  # in SQLite aggregate functions are:
+  #
+  # * http://www.sqlite.org/lang_aggfunc.html
+  #
+  # If you choose to use Aggregate as a parent class of your SQL scalar function
+  # implementation you must:
+  #
+  # * implement _initalize_ with 0 arguments
+  # * set the @arity data member
+  # * set the @name data member 
+  # * implement _step_ with arity of +@arity+
+  # * implement _finalize_ with arity of 0
+  #
+  # For instance to implement a <i>unique_word_count(X)</i> aggregate function you could
+  # implement it as:
+  #
+  #   class UniqueWordCount < ::Amalgalite::Aggregate
+  #     attr_accessor :words
+  #
+  #     def initialize
+  #       @name = 'unique_word_count'
+  #       @arity = 1
+  #       @words = Hash.new { |h,k| h[k] = 0 }
+  #     end
+  #
+  #     def step( str )
+  #       str.split(/\W+/).each do |word|
+  #         words[ word.downcase ] += 1
+  #       end
+  #       return nil
+  #     end
+  #
+  #     def finalize
+  #       return words.size
+  #     end
+  #   end
+  #
+  #
+  class Aggregate
+    # The name of the SQL function
+    attr_accessor :name
+
+    # The arity of the SQL function
+    attr_accessor :arity
+
+    # finalize should return the final value of the aggregate function
+    def finalize
+      raise NotImplementedError, "Aggregate#finalize must be implemented"
+    end
+
+    # <b>Do Not Override</b>
+    #
+    # The function signature for use by the Amaglaite datase in tracking
+    # function creation.
+    #
+    def signature
+      @signature ||= ::Amalgalite::SQLite3::Database::Function.signature( self.name, self.arity )
+    end
+  end
+end

data/lib/amalgalite/blob.rb

@@ -0,0 +1,186 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module Amalgalite
+  ##
+  # This is the interface to allow Blob objects to be written to and read from
+  # the SQLite database.  When using statements, use a Blob object as
+  # the wrapper around the source to be written to the row, and a Blob object is
+  # returned if the the type mapping warrents during select queries.
+  #
+  # For instance during an insert:
+  #
+  #   blob_column = db.schema.tables['blobs'].columns['data']
+  #   db.execute("INSERT INTO blobs(name, data) VALUES ( $name, $blob )",
+  #             { "$name" => "/path/to/file",
+  #               "$blob" => Amalgalite::Blob.new( :file => '/path/to/file',
+  #                                                :column => blob_column) } )
+  #
+  #   db.execute("INSERT INTO blobs(id, data) VALUES ($id, $blob )",
+  #             { "$name" => 'blobname',
+  #               "$blob" => Amalgalite::Blob.new( :io => "something with .read and .length methods",
+  #                                                :column => blob_column) } )
+  #
+  # On select the blob data needs to be read into an IO object
+  #
+  #   all_rows = db.execute("SELECT name, blob FROM blobs WHERE name = '/path/to/file' ")
+  #   blob_row = all_rows.first
+  #   blob_row['blob'].write_to_file( blob_row['name'] )
+  #   
+  # Or write to an IO object
+  #   
+  #   blob_results = {}
+  #   db.execute("SELECT name, blob FROM blobs") do |row|
+  #     io = StringIO.new
+  #     row['blob'].write_to_io( io )
+  #     blob_results[row['name']] = io
+  #     # or use a shortcut
+  #     # blob_results[row['name']] = row['blob'].to_string_io
+  #   end
+  #
+  # If using a Blob as a conditional, for instance in a WHERE clause then the
+  # Blob must resolvable to a String.
+  #
+  #   db.execute("SELECT FROM blobs(name, data) WHERE data = $blob",
+  #             { "$blob' => Amalgalite::Blob.new( :string => "A string of data" ) })
+  #
+  class Blob 
+    class Error < ::Amalgalite::Error; end
+    class << self
+      def valid_source_params
+        @valid_source_params ||= [ :file, :io, :string, :db_blob ]
+      end
+
+      def default_block_size
+        @default_block_size ||= 8192
+      end
+    end
+
+    # the object representing the source of the blob
+    attr_reader :source 
+
+    # the size in bytes of the of the blob
+    attr_reader :length
+
+    # the size in bytes of the blocks of data to move from the source
+    attr_reader :block_size
+
+    # the column the blob is associated with
+    attr_reader :column
+
+    ##
+    # Initialize a new blob, it takes a single parameter, a hash which describes
+    # the source of the blob.  The keys of the hash are one of:
+    #
+    #   :file    : the value is the path to a file on the file system
+    #   :io      : the value is an object that responds to the the methods +read+
+    #              and +length+.  +read+ should have the behavior of IO#read
+    #   :db_blob : not normally used by an end user, used to initialize a blob
+    #              object that is returned from an SQL query.
+    #   :string  : used when a Blob is part of a WHERE clause or result
+    #
+    # And additional key of :block_size may be used to indicate the maximum size
+    # of a single block of data to move from the source to the destination, this
+    # defaults ot 8192.
+    #
+    def initialize( params )
+      if (Blob.valid_source_params & params.keys).size > 1 then
+        raise Blob::Error, "Only a one of #{Blob.valid_source_params.join(', ')} is allowed to initialize a Blob.  #{params.keys.join(', ')} were sent"
+      end
+
+      @source                  = nil
+      @source_length           = 0
+      @close_source_after_read = false
+      @incremental             = true
+      @block_size              = params[:block_size] || Blob.default_block_size
+      @column                  = params[:column]     
+
+      raise Blob::Error, "A :column parameter is required for a Blob" unless @column or params.has_key?( :string )
+
+      if params.has_key?( :file ) then
+        @source = File.open( params[:file], "r" )
+        @length = File.size( params[:file] )
+        @close_source_after_read = true
+      elsif params.has_key?( :io ) then
+        @source = params[:io]
+        @length = @source.length
+      elsif params.has_key?( :db_blob ) then
+        @source = params[:db_blob]
+        @length = @source.length
+        @close_source_after_read = true
+      elsif params.has_key?( :string ) then
+        @source = params[:string]
+        @length = @source.length
+        @incremental = false
+      end
+    end
+
+    ##
+    # close the source when done reading from it
+    #
+    def close_source_after_read?
+      @close_source_after_read
+    end
+
+    ##
+    # is this an incremental Blob or not
+    #
+    def incremental?
+      @incremental
+    end
+
+    ##
+    # Write the Blob to an IO object
+    #
+    def write_to_io( io )
+      if source.respond_to?( :read ) then
+        while buf = source.read( block_size ) do
+          io.write( buf )
+        end
+      else
+        io.write( source.to_s )
+      end
+
+      if close_source_after_read? then
+        source.close
+      end
+    end
+
+    ##
+    # conver the blob to a string
+    #
+    def to_s
+      to_string_io.string
+    end
+
+    ##
+    # write the Blob contents to a StringIO
+    #
+    def to_string_io
+      sio = StringIO.new
+      write_to_io( sio )
+      return sio
+    end
+
+    ##
+    # Write the Blob contents to a File.  
+    #
+    def write_to_file( filename, modestring="w" )
+      File.open(filename, modestring) do |f|
+        write_to_io( f )
+      end
+    end
+
+    ##
+    # Write the Blob contents to the column.  This assumes that the row_id to
+    # insert into is the last row that was inserted into the db
+    #
+    def write_to_column!
+      last_rowid = column.schema.db.last_insert_rowid
+      SQLite3::Blob.new( column.schema.db.api, column.db, column.table, column.name, last_rowid, "w" ) do |sqlite_blob|
+        write_to_io( sqlite_blob )
+      end
+    end
+  end
+end

data/lib/amalgalite/boolean.rb

@@ -0,0 +1,42 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module Amalgalite
+  ##
+  # Do type conversion on values that could be boolen values into 
+  # real 'true' or 'false'
+  #
+  # This is pulled from the possible boolean values from PostgreSQL
+  #
+  class Boolean
+    class << self
+      #
+      # list of downcased strings are potential true values
+      # 
+      def true_values
+        @true_values ||= %w[ true t yes y 1 ]
+      end
+
+      #
+      # list of downcased strings are potential false values
+      #
+      def false_values
+        @false_values ||= %w[ false f no n 0 ]
+      end
+
+      # 
+      # Convert +val+ to a string and attempt to convert it to +true+ or +false+
+      #
+      def to_bool( val )
+        return false if val.nil?
+        unless defined? @to_bool
+          @to_bool = {}
+          true_values.each  { |t| @to_bool[t] = true  }
+          false_values.each { |f| @to_bool[f] = false }
+        end
+        return @to_bool[val.to_s.downcase]
+      end
+    end
+  end
+end

data/lib/amalgalite/busy_timeout.rb

@@ -0,0 +1,47 @@
+module Amalgalite
+  ##
+  # A base class for use in creating your own busy handler classes
+  #
+  class BusyHandler
+    def to_proc
+      self
+    end
+
+    # the arity of the call method
+    def arity() 1 ; end
+
+    ##
+    # Override this method, returning +false+ if the SQLite should return
+    # SQLITE_BUSY for all parties involved in the lock, and anything else if the
+    # lock attempt should be tried again.
+    def call( count )
+      raise NotImplementedError, "The busy handler call(N) method must be implemented"
+    end
+  end
+
+  ##
+  # A busy time out class for use in Database#define_busy_handler
+  #
+  class BusyTimeout < BusyHandler
+    attr_reader :call_count
+    ##
+    # intialize by setting _count_ and _duration_ ( in milliseconds ).
+    #
+    def initialize( count = 20 , duration = 50 )
+      @count = count
+      @duration = duration.to_f / 1_000
+      @call_count = 0
+    end
+
+    ##
+    # return +false+ if _callcount_ is >  _count_ otherwise sleep for _duration_
+    # milliseconds and then return +true+
+    #
+    def call( call_count )
+      @call_count = call_count
+      return false if ( call_count > @count )
+      sleep @duration
+      return true
+    end
+  end
+end

data/lib/amalgalite/column.rb

@@ -0,0 +1,97 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'amalgalite/boolean'
+require 'amalgalite/blob'
+
+module Amalgalite
+  ##
+  # a class representing the meta information about an SQLite column, this class
+  # serves both for general Schema level information, and for result set
+  # information from a SELECT query.
+  #
+  class Column
+    # the schema object this column is associated with
+    attr_accessor :schema
+
+    # the database name this column belongs to
+    attr_accessor :db
+
+    # the column name
+    attr_accessor :name
+
+    # the table to which this column belongs
+    attr_accessor :table
+
+    # the default value of the column.   This may not have a value and that
+    # either means that there is no default value, or one could not be
+    # determined.
+    #
+    attr_accessor :default_value
+
+    # 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
+
+    # The index (starting with 0) of this column in the table definition
+    # or result set
+    attr_accessor :order
+
+    ##
+    # Create a column with its name and associated table
+    #
+    def initialize( db, table, name, order)
+      @db                 = db
+      @name               = name
+      @table              = table
+      @order              = Float(order).to_i
+      @declared_data_type = nil
+      @default_value      = nil
+    end
+
+    # true if the column has a default value
+    def has_default_value?
+      not default_value.nil?
+    end
+
+    # true if the column may have a NULL value
+    def nullable?
+      @not_null_constraint == false
+    end
+
+    # set whether or not the column has a not null constraint
+    def not_null_constraint=( other )
+      @not_null_constraint = Boolean.to_bool( other )
+    end
+
+    # true if the column as a NOT NULL constraint
+    def not_null_constraint?
+      @not_null_constraint
+    end
+
+    # set whether or not the column is a primary key column
+    def primary_key=( other )
+      @primary_key = Boolean.to_bool( other )
+    end
+
+    # true if the column is a primary key column
+    def primary_key?
+      @primary_key
+    end
+
+    # set whether or not the column is auto increment
+    def auto_increment=( other )
+      @auto_increment = Boolean.to_bool( other )
+    end
+
+    # true if the column is auto increment
+    def auto_increment?
+      @auto_increment
+    end
+  end
+end