libsql 0.1.0

data/lib/libsql/table.rb

@@ -0,0 +1,91 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+require 'set'
+module ::Libsql
+  #
+  # a class representing the meta information about an SQLite table
+  #
+  class Table
+    # the schema object the table is associated with
+    attr_accessor :schema
+
+    # the table name
+    attr_reader   :name
+
+    # the original sql that was used to create this table
+    attr_reader   :sql
+
+    # hash of Index objects holding the meta informationa about the indexes
+    # on this table.  The keys of the indexes variable is the index name
+    attr_accessor :indexes
+
+    # a hash of Column objects holding the meta information about the columns
+    # in this table.  keys are the column names
+    attr_accessor :columns
+
+    def initialize( name, sql = nil )
+      @name        = name
+      @sql         = sql
+      @indexes     = {}
+      @columns     = {}
+      @schema      = nil
+      @primary_key = nil
+    end
+
+    # Is the table a temporary table or not
+    def temporary?
+      schema.temporary?
+    end
+
+    # the Columns in original definition order
+    def columns_in_order
+      @columns.values.sort_by { |c| c.order }
+    end
+
+    # the column names in original definition order
+    def column_names
+      columns_in_order.map { |c| c.name }
+    end
+
+    # the columns that make up the primary key
+    def primary_key_columns
+      @columns.values.find_all { |c| c.primary_key? }
+    end
+
+    # the array of colmuns that make up the primary key of the table
+    # since a primary key has an index, we loop over all the indexes for the
+    # table and pick the first one that is unique, and all the columns in the
+    # index have primary_key? as true.
+    #
+    # we do this instead of just looking for the columns where primary key is
+    # true because we want the columns in primary key order
+    def primary_key
+      unless @primary_key
+        pk_column_names = Set.new( primary_key_columns.collect { |c| c.name } )
+        unique_indexes  = indexes.values.find_all { |i| i.unique? }
+
+        pk_result = []
+
+        unique_indexes.each do |idx|
+          idx_column_names = Set.new( idx.columns.collect { |c| c.name } )
+          r = idx_column_names ^ pk_column_names
+          if r.size == 0 then
+            pk_result = idx.columns
+            break
+          end
+        end
+
+        # no joy, see about just using all the columns that say the are primary
+        # keys
+        if pk_result.empty? then
+          pk_result = self.primary_key_columns
+        end
+        @primary_key = pk_result
+      end
+      return @primary_key
+    end
+  end
+end
+

data/lib/libsql/taps/console.rb

@@ -0,0 +1,27 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'libsql/taps/io'
+
+module ::Libsql::Taps
+  #
+  # Class provide an IO tap that can write to $stdout
+  #
+  class Stdout < ::Libsql::Taps::IO
+    def initialize
+      super( $stdout )
+    end
+  end
+
+  #
+  # This class provide an IO tap that can write to $stderr
+  #
+  class Stderr < ::Libsql::Taps::IO
+    def initialize
+      super( $stderr )
+    end
+  end
+
+end

data/lib/libsql/taps/io.rb

@@ -0,0 +1,74 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'libsql/profile_tap'
+require 'stringio'
+
+module ::Libsql
+  module Taps
+    #
+    # An IOTap is an easy way to send all top information to any IO based
+    # object.  Both profile and trace tap information can be captured
+    # This means you can send the events to STDOUT with:
+    #
+    #   db.profile_tap = db.trace_tap  = ::Libsql::Taps::Stdout.new
+    #
+    #
+    class IO
+
+      attr_reader :profile_tap
+      attr_reader :io
+      attr_reader :trace_count
+
+      def initialize( io )
+        @io = io
+        @profile_tap = ProfileTap.new( self, 'output_profile_event' )
+        @trace_count = 0
+      end
+
+      def trace( msg )
+        @trace_count += 1
+        io.puts msg
+      end
+
+      # need a profile method, it routes through the profile tap which calls back
+      # to output_profile_event
+      def profile( msg, time )
+        @profile_tap.profile(msg, time)
+      end
+
+      def output_profile_event( msg, time )
+        io.puts "#{time} : #{msg}"
+      end
+
+      def dump_profile
+        samplers.each_pair do |k,v|
+          io.puts v.to_s
+        end
+      end
+
+      def samplers
+        profile_tap.samplers
+      end
+    end
+
+    #
+    # This class provides an IO tap that writes to a StringIO.  The result is
+    # available via .to_s or .string.
+    #
+    class StringIO < ::Libsql::Taps::IO
+      def initialize
+        @stringio = ::StringIO.new
+        super( @stringio )
+      end
+
+      def to_s
+        @stringio.string
+      end
+      alias :string :to_s
+    end
+  end
+end
+

data/lib/libsql/taps.rb

@@ -0,0 +1,2 @@
+require 'libsql/taps/console'
+require 'libsql/taps/io'

data/lib/libsql/trace_tap.rb

@@ -0,0 +1,35 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module ::Libsql
+  #
+  # A TraceTap receives tracing information from SQLite3. It receives the SQL
+  # statement being executed as a +msg+ just before the statement first begins
+  # executing.
+  #
+  # A TraceTap is a wrapper around another object and a method.  The Tap object
+  # will receive the call to +trace+ and redirect that call to another object
+  # and method.
+  #
+  class TraceTap
+
+    attr_reader :delegate_obj
+    attr_reader :delegate_method
+
+    def initialize( wrapped_obj, send_to = 'trace' )
+      unless wrapped_obj.respond_to?( send_to )
+        raise ::Libsql::Error, "#{wrapped_obj.class.name} does not respond to #{send_to.to_s} "
+      end
+
+      @delegate_obj = wrapped_obj
+      @delegate_method = send_to
+    end
+
+    def trace( msg )
+      delegate_obj.send( delegate_method, msg )
+    end
+  end
+end
+

data/lib/libsql/type_map.rb

@@ -0,0 +1,63 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module Libsql
+  ##
+  # TypeMap defines the protocol used between Ruby and SQLite for mapping
+  # binding types, used in prepared statements; and result types, used in
+  # returning objects from a query.
+  #
+  #
+  class TypeMap
+    ##
+    # :call-seq:
+    #   map.bind_type_of( obj ) -> DataType constant
+    #
+    # bind_type_of is called during the Statement#bind process to convert the
+    # bind parameter to the appropriate SQLite types.  This method MUST return
+    # one of the valid constants in the namespace 
+    # Libsql::SQLite::Constants::DataType
+    #
+    def bind_type_of( obj )
+      raise NotImplementedError, "bind_type_of has not been implemented"
+    end
+
+    ##
+    # :call-seq:
+    #   map.result_value_of( declared_type, value ) -> String
+    #
+    # result_value_of is called during the result processing of column values 
+    # to convert an SQLite database value into the appropriate Ruby class.  
+    #
+    # +declared_type+ is the string from the original CREATE TABLE statment 
+    # from which the column value originates.  It may also be nil if the origin
+    # column cannot be determined.
+    #
+    # +value+ is the SQLite value from the column as either a Ruby String,
+    # Integer, Float or Libsql::Blob. 
+    #
+    # result_value should return the value that is to be put into the result set
+    # for the query.  It may do nothing, or it may do massive amounts of
+    # conversion. 
+    def result_value_of( delcared_type, value )
+      raise NotImplementedError, "result_value_of has not been implemented"
+    end
+  end 
+
+  ##
+  # The TypeMaps module holds all typemaps that ship with libsql.  They
+  # currently are:
+  #
+  # DefaultMap:: does a 'best-guess' mapping to convert as many types as
+  #              possible to known ruby classes from known SQL types.
+  # StorageMap:: converts to a limited set of classes directly based 
+  #              upon the SQLite storage types
+  # TextMap::    Everything is Text ... everything everything everything
+  #
+  module TypeMaps
+  end
+end
+require 'libsql/type_maps/default_map'
+require 'libsql/type_maps/storage_map'
+require 'libsql/type_maps/text_map'

data/lib/libsql/type_maps/default_map.rb

@@ -0,0 +1,166 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'time'
+require 'date'
+
+module ::Libsql::TypeMaps
+  ##
+  # An ::Libsql::TypeMap that does its best to convert between Ruby classes
+  # and known SQL data types.  
+  #
+  # Upon instantiation, DefaultMap generates a conversion map to try to figure
+  # out the best way to convert between populate SQL 'types' and ruby classes
+  #
+  class DefaultMap
+    class << self
+      def methods_handling_sql_types # :nodoc:
+        @methods_handling_sql_types ||= {
+          'date'      => %w[ date ],
+          'datetime'  => %w[ datetime ],
+          'time'      => %w[ timestamp time ],
+          'float'     => %w[ double float real numeric decimal ],
+          'integer'   => %w[ integer tinyint smallint int int2 int4 int8 bigint serial bigserial ],
+          'string'    => %w[ text char string varchar character json ],
+          'boolean'   => %w[ bool boolean ],
+          'blob'      => %w[ binary blob ],
+        }
+      end
+
+      # say what method to call to convert an sql type to a ruby type
+      #
+      def sql_to_method( sql_type  ) # :nodoc:
+        unless defined? @sql_to_method
+          @sql_to_method = {}
+          methods_handling_sql_types.each_pair do |method, sql_types|
+            sql_types.each { |t| @sql_to_method[t] = method }
+          end
+        end
+        return_method = @sql_to_method[sql_type]
+
+        # the straight lookup didn't work, try iterating through the types and
+        # see what is found
+        unless return_method
+          @sql_to_method.each_pair do |sql, method|
+            if sql_type.index(sql) then
+              return_method = method
+              break
+            end
+          end
+        end
+        return return_method
+      end
+    end
+
+    def initialize
+    end
+
+    ##
+    # A straight logical mapping (for me at least) of basic Ruby classes to SQLite types, if
+    # nothing can be found then default to TEXT.
+    #
+    def bind_type_of( obj )
+      case obj
+      when Float
+        ::Libsql::SQLite3::Constants::DataType::FLOAT
+      when Integer
+        ::Libsql::SQLite3::Constants::DataType::INTEGER
+      when NilClass
+        ::Libsql::SQLite3::Constants::DataType::NULL
+      when ::Libsql::Blob
+        ::Libsql::SQLite3::Constants::DataType::BLOB
+      else
+        ::Libsql::SQLite3::Constants::DataType::TEXT
+      end
+    end
+
+    ##
+    # Map the incoming value to an outgoing value.  For some incoming values,
+    # there will be no change, but for some (i.e. Dates and Times) there is some
+    # conversion
+    #
+    def result_value_of( declared_type, value )
+      case value
+      when Numeric
+        return value
+      when NilClass
+        return value
+      when ::Libsql::Blob
+        return value
+      when String
+        if declared_type then
+          conversion_method = DefaultMap.sql_to_method( declared_type.downcase )
+          if conversion_method then
+            return send(conversion_method, value)  
+          else
+            raise ::Libsql::Error, "Unable to convert SQL type of #{declared_type} to a Ruby class"
+          end
+        else
+          # unable to do any other conversion, just return what we have.
+          return value
+        end
+      else 
+        raise ::Libsql::Error, "Unable to convert a class #{value.class.name} with value #{value.inspect}"
+      end
+    end
+
+    ##
+    # convert a string to a date
+    #
+    def date( str )
+      Date.parse( str )
+    end
+
+    ##
+    # convert a string to a datetime, if no timzone is found in the parsed
+    # string, set it to the local offset.  
+    #
+    def datetime( str )
+      DateTime.parse( str )
+    end
+
+    ##
+    # convert a string to a Time
+    #
+    def time( str )
+      Time.parse( str )
+    end
+
+    ##
+    # convert a string to a Float
+    #
+    def float( str )
+      Float( str )
+    end
+
+    ##
+    # convert an string to an Integer
+    #
+    def integer( str )
+      Float( str ).to_i
+    end
+
+    ##
+    # convert a string to a String, yes redundant I know.
+    # 
+    def string( str )
+      str
+    end
+
+    ##
+    # convert a string to true of false
+    #
+    def boolean( str )
+      ::Libsql::Boolean.to_bool( str )
+    end
+
+    ##
+    # convert a string to a blob
+    #
+    def blob( str )
+      ::Libsql::Blob.new( :string => str )
+    end
+  end
+end

data/lib/libsql/type_maps/storage_map.rb

@@ -0,0 +1,38 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module ::Libsql::TypeMaps
+  ##
+  # An Amalagliate TypeMap that has a one-to-one conversion between SQLite types
+  # and Ruby classes
+  #
+  class StorageMap < ::Libsql::TypeMap
+    ##
+    # A straight logical mapping (for me at least) of basic Ruby classes to SQLite types, if
+    # nothing can be found then default to TEXT.
+    #
+    def bind_type_of( obj )
+      case obj
+      when Float
+        ::Libsql::SQLite3::Constants::DataType::FLOAT
+      when Integer
+        ::Libsql::SQLite3::Constants::DataType::INTEGER
+      when NilClass
+        ::Libsql::SQLite3::Constants::DataType::NULL
+      when ::Libsql::Blob
+        ::Libsql::SQLite3::Constants::DataType::BLOB
+      else
+        ::Libsql::SQLite3::Constants::DataType::TEXT
+      end
+    end
+
+    ##
+    # Do no mapping, just return the value as it was retrieved from SQLite.
+    #
+    def result_value_of( delcared_type, value )
+      return value
+    end
+  end
+end

data/lib/libsql/type_maps/text_map.rb

@@ -0,0 +1,21 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+#
+
+module ::Libsql::TypeMaps
+  ##
+  # An Amalagliate TypeMap that converts both bind parameters and result
+  # parameters to a String, no matter what.
+  #
+  class TextMap < ::Libsql::TypeMap
+    def bind_type_of( obj )
+      return ::Libsql::SQLite3::Constants::DataType::TEXT
+    end
+
+    def result_value_of( delcared_type, value )
+      return value.to_s
+    end
+  end
+end

data/lib/libsql/version.rb

@@ -0,0 +1,8 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for licensing details
+#++
+
+module Libsql
+  VERSION = "0.1.0"
+end

data/lib/libsql/view.rb

@@ -0,0 +1,26 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module ::Libsql
+  #
+  # a class representing the meta information about an SQLite view
+  #
+  class View
+    # the schame this view is assciated with
+    attr_accessor :schema
+
+    # the table name
+    attr_reader   :name
+
+    # the original sql that was used to create this table
+    attr_reader   :sql
+
+    def initialize( name, sql ) 
+      @name    = name
+      @sql     = sql
+    end
+  end
+end
+

data/lib/libsql-ruby.rb

@@ -0,0 +1 @@
+require_relative './libsql'

data/lib/libsql.rb

@@ -0,0 +1,51 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+# check if sqlite3 has already been required.  ::Libsql conflicts with system
+# level sqlite3 libraries.
+unless $LOADED_FEATURES.grep( /\Asqlite3/ ).empty? then
+  raise LoadError, "libsql conflicts with sqlite3, please choose one or the other."
+end
+
+module ::Libsql
+  # 
+  # Base class of all errors in ::Libsql
+  #
+  class Error < ::StandardError; end
+end
+
+# Load the binary extension, try loading one for the specific version of ruby
+# and if that fails, then fall back to one in the top of the library.
+# this is the method recommended by rake-compiler
+begin
+  # this will be for windows
+  require "libsql/#{RUBY_VERSION.sub(/\.\d+$/,'')}/libsql_ext"
+rescue LoadError
+  # everyone else.
+  require 'libsql/libsql_ext'
+end
+
+
+require 'libsql/aggregate'
+require 'libsql/blob'
+require 'libsql/boolean'
+require 'libsql/busy_timeout'
+require 'libsql/column'
+require 'libsql/database'
+require 'libsql/function'
+require 'libsql/index'
+require 'libsql/memory_database'
+require 'libsql/paths'
+require 'libsql/profile_tap'
+require 'libsql/progress_handler'
+require 'libsql/schema'
+require 'libsql/sqlite3'
+require 'libsql/statement'
+require 'libsql/table'
+require 'libsql/taps'
+require 'libsql/trace_tap'
+require 'libsql/type_map'
+require 'libsql/version'
+require 'libsql/view'