sqlyzer 0.1

data/lib/sqlyzer/db.rb

@@ -0,0 +1,141 @@
+# SQLYZER Ruby Object serializer to SQL.
+# For more information visit http://sqlyzer.rubyforge.org
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#
+
+require 'dbi'
+
+require 'sqlyzer/errors'
+
+module Sqlyzer
+
+  #
+  #Static class assuming connectivity and traffic to remote database server.
+  #It's a pure ruby interface to Ruby DBI Api, offering some usage improvements.
+  #
+  class   Db
+    
+    private
+    
+    #
+    #Class variable storing current DBI connexion to the database.
+    #
+    @@handle = nil
+    
+    #
+    #This method is called by do, query_hash and query_array to manage
+    #error handling.
+    #
+    #Throws Sqlyzer::NotConnectedError and Sqlyzer::RequestError.
+    #
+    def   Db._safe_request(request)
+      raise Sqlyzer::NotConnectedError unless @@handle
+      begin
+        yield request
+      rescue DBI::Error
+        raise Sqlyzer::RequestError, request
+      end
+    end
+
+    public
+    
+    #
+    #This method will try to establish the connexion to remote database server from
+    #given _api_, _hostname_, _database_, _username_ and _password_.
+    #Method call will assign _handle_ class attribute.    
+    #
+    #Throws Sqlyzer::ConnexionError.
+    #
+    def   Db.connect(api, hostname, database, username, password)
+      begin
+        @@handle = DBI.connect("DBI:#{api}:#{database}:#{hostname}", username, password)
+      rescue DBI::Error
+        raise Sqlyzer::ConnexionError, "#{username}@DBI:#{api}:#{database}:#{hostname}"
+      else  
+        true
+      end
+    end    
+    
+    public
+    
+    #
+    #Retreive the Array containing the table list in current database.
+    #
+    #Throws Sqlyzer::NotConnectedError.
+    #
+    def   Db.tables
+      raise Sqlyzer::NotConnectedError unless @@handle
+      @@handle.tables
+    end
+    
+    #
+    #Send given _request_ to the database, doesn't expect any return value.
+    #Mostly used with CREATE, ALTER, INSERT, UPDATE or DELETE Sql commands.
+    #
+    def   Db.do(request)
+      Db::_safe_request(request) { |r|
+        @@handle.do r
+      }
+    end
+    
+    #
+    #Send given _request_ to the database and expect a return value as an array
+    #from the remote server. Each tupple will be passed through a yield call, enabling
+    #user to process a request result just like Array#each.
+    #Mostly used with SELECT Sql command.
+    #
+    #If no block is given, return do call value.    
+    #
+    def   Db.query_array(request)
+      return Db::do(request) unless block_given?
+      Db::_safe_request(request) { |r|
+        sth = @@handle.execute r
+        while row = sth.fetch
+          yield row
+        end
+        sth.finish
+      }
+    end
+    
+    #
+    #Send given _request_ to the database and expect a return value as a Hash
+    #from the remote server. Each tupple will be passed through a yield call, enabling
+    #user to process a request result just like Hash#each.
+    #Mostly used with SELECT Sql command.
+    #
+    #If no block is given, return do call value.
+    #
+    def   Db.query_hash(request)
+      return Db::do(request) unless block_given?
+      Db::_safe_request(request) { |r|
+        sth = @@handle.execute r
+        while row = sth.fetch_hash
+          yield row
+        end
+        sth.finish
+      }
+    end
+    
+    #
+    #Alias to query_hash.
+    #
+    def   Db.query(request, &block)
+      query_hash(request, &block)
+    end
+    
+  end #~  Db
+  
+end #~ Sqlyzer

data/lib/sqlyzer/errors.rb

@@ -0,0 +1,75 @@
+# SQLYZER Ruby Object serializer to SQL.
+# For more information visit http://sqlyzer.rubyforge.org
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#
+
+module Sqlyzer
+
+  #
+  #Sqlyzer main Error class.
+  #
+  #All other errors from this module are inherited from Sqlyzer::Error :
+  #* Sqlyzer::DatabaseError
+  #* Sqlyzer::NotConnectedError
+  #* Sqlyzer::ConnexionError
+  #* Sqlyzer::RequestError  
+  #
+  class   Error < ::RuntimeError
+  end #~  Error
+
+  #
+  #Database main Error class.
+  #
+  #All other errors relating Database are inherited from Sqlyzer::DatabaseError :
+  #* Sqlyzer::NotConnectedError
+  #* Sqlyzer::ConnexionError  
+  #* Sqlyzer::RequestError
+  #
+  class   DatabaseError < Error
+  end #~  DatabaseError
+
+  #
+  #Raised when calling an instruction which need a database connectivity before 
+  #calling Sqlyzer::Db::connect to establish connexion.
+  #
+  class   NotConnectedError < DatabaseError
+    def   initialize
+      super "You have to call Sqlyzer::Db::connect at the top of your code before running this command.\nSee RDoc for more instructions."
+    end
+  end #~  NotConnectedError
+
+  #
+  #Raised when an error is caught during connexion to the database.
+  #
+  class   ConnexionError < DatabaseError
+    def   initialize(connexion_string)
+      super "Received error : #{$!.to_s.chomp}\nfor DBI connexion string : '#{connexion_string}'"
+    end
+  end #~  ConnexionError
+
+  #
+  #Raised when an invalid Sql request is sent to the database.
+  #
+  #Development will aim at never raise such error (as the user doesn't have to
+  #deal with Sql).
+  #
+  class   RequestError < DatabaseError
+    def   initialize(request)
+      super "Received error : #{$!.to_s.chomp}\nfor DBI sql request : '#{request}'"
+    end
+  end #~  RequestError
+
+end #~ Sqlyzer

data/lib/sqlyzer/handler.rb

@@ -0,0 +1,88 @@
+# SQLYZER Ruby Object serializer to SQL.
+# For more information visit http://sqlyzer.rubyforge.org
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#
+
+require 'singleton'
+
+require 'sqlyzer/errors'
+require 'sqlyzer/db'
+require 'sqlyzer/request'
+
+module  Sqlyzer
+
+  #
+  #Singleton class handling generation and  execution of all Sql commands.
+  #This is the only place where Sql requests are executed.
+  #
+  class     Handler
+    include Singleton
+
+    public
+
+    #
+    #Register an instance of class extended with Sqlyzer::Serializer.
+    #This method will create the Sql table associated with _sender_ class if there
+    #is no table named like _sender_#sql_container_table().
+    #
+    def     register_sender(sender)
+      Db::do sender.sql_serialize(:sql_table) unless
+        Db::tables.include?(sender.sql_container_table)
+    end
+
+    public
+
+    #
+    #Static method called by Sqlyzer::Serializer to request execution and generation of
+    #every Sql command.
+    #The command to generate and execute is determined by _action_ Symbol value :
+    #* :sql_select,
+    #* :sql_insert,
+    #* :sql_update,
+    #* :sql_delete.
+    #
+    #When _action_ value is :sql_select, this method restore all _sender_ attributes from data
+    #returned by generated Sql SELECT command execution.
+    #
+    #When _sender_ call this method for the first time, it is automatically registered
+    #through register_sender.
+    #
+    #TODO: This method is very trivial for now, but further optimizations of Sql
+    #commands execution timelime have to go there.
+    #
+    def     Handler.request(sender, action)
+      Handler.instance.register_sender sender
+      case action
+      when :sql_select then
+        Db::query(sender.sql_serialize(:sql_select)) { |data|
+          data.each { |key, value|
+            attrib = sender.sql_container_values[key]
+            if attrib.nil?
+              sender.sql_container_keys[key].to_owner(sender, value)
+            else
+              attrib.to_owner(sender, value)
+            end
+          }
+        }
+      else
+        Db::do(sender.sql_serialize(action))
+      end
+      nil
+    end
+
+  end #~    Handler
+
+end #~  Sqlyzer

data/lib/sqlyzer/parameters.rb

@@ -0,0 +1,448 @@
+# SQLYZER Ruby Object serializer to SQL.
+# For more information visit http://sqlyzer.rubyforge.org
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#
+
+require 'sqlyzer/errors'
+
+module  Sqlyzer
+
+  #
+  #Handling of class attributes to serialize
+  #
+  module  Parameter
+
+    #
+    #Every Sql type Mixin with serialize/unserialize procedures
+    #
+    module    Types
+      
+      public
+      
+      #Sql Integer type Mixin
+      module    Int
+        def     to_sql_type; 'INT'; end
+      end #~    Int
+  
+      #Sql Integer2 type Mixin
+      module    Int2
+        def     to_sql_type; 'INT2'; end
+      end #~    Int2
+  
+      #Sql Integer4 type Mixin
+      module    Int4
+        def     to_sql_type; 'INT4'; end
+      end #~    Int4
+  
+      #Sql Integer8 type Mixin
+      module    Int8
+        def     to_sql_type; 'INT8'; end
+      end #~    Int8
+  
+      #Sql Float type Mixin
+      module    Float
+        def     to_sql_type; 'FLOAT'; end
+      end #~    Float
+  
+      #Sql Float4 type Mixin
+      module    Float4
+        def     to_sql_type; 'FLOAT4'; end
+      end #~    Float4
+  
+      #Sql Float8 type Mixin
+      module    Float8
+        def     to_sql_type; 'FLOAT8'; end
+      end #~    Float8
+  
+      #Sql Boolean type Mixin
+      module    Bool
+        def     to_sql_type; 'BOOL'; end
+      end #~    Bool
+  
+      #Sql Text type Mixin
+      module    Text
+        def     to_sql_type; 'TEXT'; end
+        #Ruby String to Sql Text serialization with Sql escaping notation.
+        def     to_sql(owner)
+          "E'#{super(owner).to_s.gsub "'", "\\'"}'"
+        end
+      end #~    Text
+  
+      #Sql Varchar type Mixin
+      module    VarChar
+        #Return _VARCHAR_ if no capacity was specified by the user.
+        def     to_sql_type
+          return 'VARCHAR' if @capacity.nil?
+          "VARCHAR(#{@capacity})"
+        end        #
+        #Overload default parameter assigment for setting VarChar capacity with a Ruby Range object.
+        def     /(default)
+          @capacity = default.max
+          super ''
+        end
+        #Ruby String to Sql Varchar serialization like Text, but truncate the String if too long.
+        def     to_sql(owner)
+          if @capacity.nil?
+            "E'#{super(owner).to_s.gsub "'", "\\'"}'"
+          else
+            "E'#{super(owner).to_s[0..@capacity - 1].gsub "'", "\\'"}'"
+          end
+        end
+      end #~    VarChar
+  
+      #Sql Date type Mixin
+      module    Date
+        def     to_sql_type; 'DATE'; end
+        #Ruby Time object to Sql Date String representation
+        def     to_sql(owner)
+          sql_parameter_eval(owner).strftime "'%Y-%m-%d'"
+        end
+        #DBI::Date object to Ruby Time
+        def     to_owner(owner, data)
+          sql_parameter_set owner, data.to_time
+        end
+      end #~    Date
+  
+      #Sql Time type Mixin
+      module    Time
+        def     to_sql_type; 'TIME'; end
+        #Ruby Time object to Sql Time String representation
+        def     to_sql(owner)
+          sql_parameter_eval(owner).strftime "'%H:%M:%S'"
+        end
+        #Sql Time type to Ruby Time object
+        def     to_owner(owner, data)
+          sql_parameter_set owner, ::Time.parse(data)
+        end
+      end #~    Time
+  
+      #Sql DateTime type Mixin
+      module    DateTime
+        def     to_sql_type; 'DATETIME'; end
+        #Ruby Time object to Sql DateTime String representation
+        def     to_sql(owner)
+          sql_parameter_eval(owner).strftime "'%Y-%m-%d %H:%M:%S'"
+        end
+        #DBI::DateTime object to Ruby Time object
+        def     to_owner(owner, data)
+          sql_parameter_set owner, data.to_time
+        end
+      end #~    DateTime      
+            
+      public
+
+      module    Alias
+      
+        #Constant alias for Sqlyzer::Parameter::Types::Int
+        SQL_INT       = Sqlyzer::Parameter::Types::Int
+        #Constant alias for Sqlyzer::Parameter::Types::Int2      
+        SQL_INT2      = Sqlyzer::Parameter::Types::Int2
+        #Constant alias for Sqlyzer::Parameter::Types::Int4
+        SQL_INT4      = Sqlyzer::Parameter::Types::Int4
+        #Constant alias for Sqlyzer::Parameter::Types::Int8      
+        SQL_INT8      = Sqlyzer::Parameter::Types::Int8
+        #Constant alias for Sqlyzer::Parameter::Types::Float      
+        SQL_FLOAT     = Sqlyzer::Parameter::Types::Float
+        #Constant alias for Sqlyzer::Parameter::Types::Float4
+        SQL_FLOAT4    = Sqlyzer::Parameter::Types::Float4
+        #Constant alias for Sqlyzer::Parameter::Types::Float8
+        SQL_FLOAT8    = Sqlyzer::Parameter::Types::Float8
+        #Constant alias for Sqlyzer::Parameter::Types::Bool
+        SQL_BOOL      = Sqlyzer::Parameter::Types::Bool
+        #Constant alias for Sqlyzer::Parameter::Types::Text
+        SQL_TEXT      = Sqlyzer::Parameter::Types::Text
+        #Constant alias for Sqlyzer::Parameter::Types::VarChar
+        SQL_VARCHAR   = Sqlyzer::Parameter::Types::VarChar
+        #Constant alias for Sqlyzer::Parameter::Types::Date
+        SQL_DATE      = Sqlyzer::Parameter::Types::Date
+        #Constant alias for Sqlyzer::Parameter::Types::Time
+        SQL_TIME      = Sqlyzer::Parameter::Types::Time
+        #Constant alias for Sqlyzer::Parameter::Types::DateTime
+        SQL_DATETIME  = Sqlyzer::Parameter::Types::DateTime
+       
+      end #~    Alias
+      
+    end #~    Types
+
+    #
+    #Proxy class for Symbol. Permit to extend a Symbol class with coresponding
+    #Sql type handling Mixin.
+    #
+    #This class mainly exists to enable extending a Symbol, which is not possible
+    #with Ruby regular Symbol class. This is nearly an abstract class (as Ruby doesn't
+    #really implement this concept) and must be extended with coresponding Sql type Mixin.
+    #If no type specification is given, the class will be considered as a 
+    #Sqlyzer::Parameter::Types::Text attribute.
+    #
+    class     Default
+      include Comparable
+
+      attr_reader :symbol
+
+      public
+      
+      #
+      #Constructor method. The fresh Default object will possess _symbol_ as @symbol attribute.
+      #
+      def     initialize(symbol)
+        @symbol = symbol
+      end
+
+      private
+      
+      #
+      #Evaluate the Symbol value in the given _owner_ object.
+      #If Symbol does not exists in _owner_, try to reach default value else raise
+      #an error.
+      #
+      def     sql_parameter_eval(owner)
+        begin
+          res = owner.send(@symbol)
+          return res unless res.nil?
+          @default
+        rescue => err
+          raise err unless @default
+          @default
+        end
+      end
+
+      #
+      #Assign the Symbol _value_ in to _owner_ object.
+      #
+      def     sql_parameter_set(owner, value)
+        owner.method("#{@symbol}=").call value
+      end
+
+      #
+      #Set parameter default in case of non existent Symbol.
+      #
+      #See sql_parameter_eval.
+      #
+      def     sql_parameter_default(val)
+        @default = val
+      end
+
+      public
+      
+      #
+      #Implement the Ruby Comparable Mixin, enabling to compare Default 
+      #with Default, Symbol or String (in this order).
+      #
+      def     <=>(other)
+        if other.kind_of?(Default)
+          @symbol.to_i <=> other.symbol.to_i
+        elsif other.kind_of?(Symbol)
+          @symbol.to_i <=> other.to_i
+        else
+          @symbol.to_s <=> other.to_s
+        end
+      end
+
+      #
+      #Call sql_parameter_default and return _self_.
+      #
+      def     /(default)
+        sql_parameter_default default
+        self
+      end
+
+      #
+      #Call contained Symbol to_s method.
+      #
+      def     to_s
+        @symbol.to_s
+      end
+    
+      #
+      #Return the Sql type name of the current instance.
+      #
+      #This method will raise an error unless current instance was extend with
+      #coresponding Sql type Mixin.
+      #
+      def     to_sql_type
+        raise 'unreached'
+      end
+
+      #
+      #Serialize the Symbol value contained in _owner_ to Sql representation.
+      #
+      def     to_sql(owner)
+        sql_parameter_eval(owner).to_s
+      end
+
+      #
+      #Unserialize Sql representation of _data_ to assign it to _owner_.
+      #
+      def     to_owner(owner, data)
+        sql_parameter_set(owner, data)
+      end
+
+      public
+      
+      #
+      #Create an instance of Default by giving a Symbol and a default value.
+      #Coresponding Sql type Mixin will be determined from default value type.
+      #
+      #Here is the list of coresponding Sql type for each Ruby class handled :
+      #* Integer, Fixnum <=> Sqlyzer::Parameter::Types::Int (SQL_INT),
+      #* Float <=> Sqlyzer::Parameter::Types::Float (SQL_FLOAT),
+      #* Time <=> Sqlyzer::Parameter::Types::Date (SQL_DATE),
+      #* TrueClass, FalseClass <=> Sqlyzer::Parameter::Types::Bool (SQL_BOOL),
+      #* Range <=> Sqlyzer::Parameter::Types::VarChar (SQL_VARCHAR).
+      #
+      #Any other Ruby class will be considered as a Sqlyzer::Parameter::Types::Text (SQL_TEXT).
+      #
+      def     Default.get_from_default(symbol, val)
+        res = Default.new(symbol)
+        case  val
+        when  Object::Integer, Object::Fixnum       then
+          res.extend Types::Alias::SQL_INT
+        when  Object::Float                         then
+          res.extend Types::Alias::SQL_FLOAT
+        when  Object::Time                          then
+          res.extend Types::Alias::SQL_DATE
+        when  Object::TrueClass, Object::FalseClass then
+          res.extend Types::Alias::SQL_BOOL
+        when  Object::Range                         then
+          res.extend Types::Alias::SQL_VARCHAR
+        else
+          res.extend Types::Alias::SQL_TEXT
+        end
+        res/val
+      end
+
+      #
+      #Create a new instance of Default by giving a Symbol and the coresponding
+      #Sql type Mixin.
+      #
+      def     Default.get_from_type(symbol, type)
+        res = Default.new(symbol)
+        res.extend type
+        res
+      end
+
+    end #~    Default
+
+    #
+    #Overloaded Array class to store Default class list.
+    #
+    class     List < Array
+
+      public
+      
+      #
+      #Create a new instance of List with given _elements_ considered as an Array
+      #of Symbol or a List.
+      #If no parameter is given, create an empty List.
+      #
+      def     initialize(elements = nil)
+        push_parameters elements if elements
+      end
+
+      public
+      
+      #
+      #Return a new Array class containing each contained Default class Sql representation
+      #from values retreived in _owner_.
+      #
+      def     to_sql(owner)
+        collect { |symbol|
+          symbol.to_sql owner
+        }
+      end
+
+      public
+
+      #
+      #Search trough contained Default classes for _key_.
+      #_key_ should be a Default class, a Symbol or a String.
+      #
+      #See Default#<=> for more informations.
+      #
+      def     fetch_parameter(key)
+        each { |parameter|
+          if parameter == key
+            yield parameter if block_given?
+            return parameter
+          end
+        }
+        nil
+      end
+      alias   [] fetch_parameter
+
+      public
+
+      #
+      #Push a _symbol_ on the top of the Array.
+      #_symbol_ should be Default class or a Symbol. If _symbol_ is a Symbol, it
+      #will be automatically converted to a Default class extended with Text Sql 
+      #type handling.
+      #
+      def     push(symbol)
+        return if include?(symbol)
+        if symbol.kind_of?(Default)
+          super symbol
+        else
+          super(symbol/Sqlyzer::Parameter::Types::Text)
+        end
+      end
+      alias   push_parameter push
+      alias   << push
+
+      #
+      #Push each item of _data_ Array by calling previous push_paramether method.
+      #
+      def     push_parameters(data)
+        data.each { |symbol|
+          push symbol
+        }
+        self
+      end
+      alias   + push_parameters
+
+      #
+      #Overloaded version on Array#join to handle suffix on each element.
+      #
+      def     join(separator = ', ', suffix = '')
+        "#{super("#{suffix}#{separator}")}#{suffix}"
+      end
+      alias   join_parameters join
+
+    end #~    List
+
+  end #~  Parameter
+end #~  Sqlyzer
+
+#
+#Extend regular Symbol class of Ruby to enable sexy explicit Sql type cast 
+#through divide (/) operator.
+#
+class   Symbol
+  #
+  #Create a new instance of Sqlyzer::Parameter::Default containing current Symbol 
+  #instance.
+  #If _param_ is a Ruby Module, the new Sqlyzer::Parameter::Default class will be 
+  #generated by calling Sqlyzer::Parameter::Default::get_from_type(), else from 
+  #Sqlyzer::Parameter::Default::get_from_default().
+  #
+  def   /(param)
+    if param.kind_of?(Module)
+      Sqlyzer::Parameter::Default.get_from_type self, param
+    else
+      Sqlyzer::Parameter::Default.get_from_default self, param
+    end
+  end
+end #~  Symbol