SqlStatement 1.0.0 → 1.0.1

data/doc/ChangeLog

@@ -0,0 +1,14 @@
+=Change Log
+==1.0.1
+* +add_fields+ and +add_tables+ now support hashes too, so no more of 
+  this silly <tt>stmt.fields.merge!</tt> stuff is requred anymore
+* now there's a DBI adaptor that lets DBI accept +SQLStatements+ and 
+  process them automatically, so no more of this silly 
+  <tt>dbh.do(stmt.to_s,*stmt.placeheld)</tt> you can just say 
+  <tt>dbh.do(stmt)</tt> (likewise for +execute+)
+* fix a bug in string_func which broke it completely.
+* Documentation fixes
+* Make <tt>== nil</tt> comparisons turn into <tt>is null</tt> in SQL.
+
+==1.0.0
+Initial Release

data/doc/EXAMPLE

@@ -0,0 +1,124 @@
+#=Example
+#  # We subclass the standard classes so that we can construct
+#  # a query with a complex computed field. The newlists method
+#  # makes this easy, giving us a constructor and combination
+#  # operators for free.
+#
+#  class ProbabilityParts < SQLStatement::SelectParts
+#     newlists :multiply
+#  end
+#  class ProbabilityStatement < SQLStatement::SelectCreate
+#     newlists :multiply
+#
+#     # Add our own special fields here, computed
+#     # from the list we added to this class.
+#     def allfields
+#       retval=super
+#       retval.merge! :probability =>
+#          SQLFunc(@multiply.collect{|x| x.to_sqlpart}.join('*'))
+#       retval
+#     end
+#  end
+#
+#
+#  #In real life, I use a special library for detecting what attributes
+#  #are available based on the columns in my tables.
+#  #We'll mimic that functionality here.
+#  #
+#  #The first definition of this module mocks the stuff that's in my more
+#  #complicated library
+#  module AttributeDetection
+#     class Attribute
+#       def initialize(domain,name)
+#          @domain=domain
+#          @name=name
+#       end
+#       attr_reader :name, :domain
+#     end
+#     class Hierarchy < Attribute
+#       def initialize(leftcolumn)
+#          ignored1,m_domain,m_name,ignored2=leftcolumn.split(/_/)
+#          super(m_domain,m_name)
+#       end
+#     end
+#     class DomainlessPerGroup < Attribute
+#       def initialize (colname)
+#          name=@colname=colname
+#          domain="!"
+#          super(domain,name)
+#       end
+#     end
+#
+#     #I have a few other attribute types, none of which
+#     #are used in this code yet.
+#
+#  end
+#
+#  include SQLHelpers
+#
+#  #The second definition of this module is the code that I actually define
+#  #in this particular program.
+#  module AttributeDetection
+#     class Attribute
+#       def condname
+#          :"cond_#{name}"
+#       end
+#       def priorname
+#          :"prior_#{name}"
+#       end
+#       #parts that go in to the CREATE TABLE `probabilities` statement
+#       #which relate to the attribute we are disambiguating
+#       def probability_disambig 
+#          parts=ProbabilityParts.new
+#          parts.add_fields [priorname[probkey]]
+#          parts.add_tables [priorname]
+#          parts.multiply << priorname[:pt]
+#          parts
+#       end
+#       #parts that go in to the CREATE TABLE `probabilities` statement
+#       #which relate to the attributes we are using as features
+#       def probability_features(conditionalon)
+#          parts=ProbabilityParts.new
+#          parts.tables={priorname=>priorname,condname=>condname}
+#          parts.add_fields [priorname[probkey]]
+#          parts.conditions << sql_func{ condname[probkey]==priorname[probkey]}
+#          parts.conditions << sql_func{
+#             condname[conditionalon.probkey]==
+#             conditionalon.priorname[conditionalon.probkey]
+#             }
+#          parts.multiply << sql_func{condname[:pt]/priorname[:pt]}
+#          parts
+#       end
+#     end
+#     class Hierarchy
+#       def probkey
+#          "att_#{domain}_#{name}_left".to_sym
+#       end
+#     end
+#     class DomainlessPerGroup
+#       def probkey
+#          @colname.to_sym
+#       end
+#     end
+#  end
+#
+#  include AttributeDetection
+#  include SQLHelpers
+#
+#  #And this code calls methods to actually build the query.
+#
+#  #First we define the names of the attributes
+#  att_disambig=Hierarchy.new("att_appraisal_attitude_left")
+#  att_features=[Hierarchy.new("att_products_appraisedtype_left"),
+#     DomainlessPerGroup.new("priority")]
+#
+#
+#  #Then we construct the statement
+#  stmt=ProbabilityStatement.new :probabilities,true
+#
+#  stmt << att_disambig.probability_disambig 
+#  att_features.each { |x| stmt<< x.probability_features(att_disambig) }
+#
+#  #Finally, we execute it against the database. Assume dbh is a
+#  #dbi connection handle.
+#  dbh.execute(stmt.to_s,*stmt.placeheld)

data/lib/sql/dbi-support.rb

@@ -0,0 +1,25 @@
+#Redefine DBI's query methods to accept SQL statement objects from
+#this library. This is automatically loaded if DBI was loaded before 
+#+sqlstatement+. If not, <tt>require 'sql/dbi-support'</tt> after DBI 
+#is included and you'll be on your way.
+class DBI::DatabaseHandle
+   alias_method :kenbloom_sqlstatement_old_do, :"do"
+   alias_method :kenbloom_sqlstatement_old_execute, :execute
+
+   def do(stmt,*args)
+      if stmt.respond_to?(:placeheld)
+	 kenbloom_sqlstatement_old_do(stmt.to_s,*stmt.placeheld)
+      else
+	 kenbloom_sqlstatement_old_do(stmt,*args)
+      end
+   end
+   def execute(stmt,*args)
+      if stmt.respond_to?(:placeheld)
+	 kenbloom_sqlstatement_old_execute(stmt.to_s,*stmt.placeheld)
+      else
+	 kenbloom_sqlstatement_old_execute(stmt,*args)
+      end
+   end
+
+end
+

data/lib/sql/expression.rb

@@ -12,6 +12,10 @@ class Array
 	 "count(distinct "+rest_sqlpart+")"
       elsif first.to_s =~ /[a-zA-Z]/
 	 first.to_s+"("+rest_sqlpart+")"
+      elsif first == :== and self[2]==nil
+	 self[1].to_sqlpart+" is null"
+      elsif first == :== and self[1]==nil
+	 self[2].to_sqlpart+" is null"
       elsif x={:& => " and ", :| => " or ", :== => "="}[first]
 	 "("+self[1].to_sqlpart+x+self[2].to_sqlpart+")"
       else

data/lib/sql/statement.rb

@@ -1,70 +1,3 @@
-=begin rdoc
-= sqlstatement - Generate complex SQL statements programmatically
-
-The main goal of this library is to be able to construct an SQL statement
-from "slices" that concern different aspects of the final query (perhaps
-in different places in your code) and then combine them all together into
-one statement easily.
-
-Another important goal of this library is to give some consistent Ruby
-syntax to three statements (INSERT, SELECT, and UPDATE) that seem to have
-different enough syntax that one has two write different code to generate
-each kind of statement.
-
-I use my SQL database (specifically MySQL) largely as a bulk data
-processing engine, by doing INSERT...SELECT or CREATE TABLE...SELECT
-statements. This library is intended to make that kind of coding easier. I
-expect that Object Relational mappers (such as ActiveRecord) are more
-useful for most people, who are performing queries and
-inserting/updating/querying for individual records. I have nevertheless 
-added INSERT...VALUES statements, and will add other statements soon, for 
-consistency.
-
-This library is inspired by CLSQL[http://clsql.b9.com/] for Common LISP,
-or SchemeQL[http://schematics.sourceforge.net/schemeql.html] for Scheme,
-although it is very different from these two libraries. Scheme and
-LISP's use of s-expressions make it very easy to construct an entire
-sublanguage for the WHERE clause, simply by list parsing.  The
-Criteria[http://mephle.org/Criteria/] library for Ruby has attempted
-this, but in a more limited manner than SchemeQL or CLSQL.  My library
-aims to cover much of the functionality in these libraries.
-
-This library doesn't try to abstract out the limitations of your DBMS, and
-I think that the SQL it uses should be fairly portable, in large measure
-because it hasn't attempted to deal with serious CREATE TABLE statements,
-where a lot of syntax concerning types, keys and sequences is much more
-variable.
-
-==License
-
-Copyright (c) 2006 Ken Bloom
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-1. Redistributions of source code must retain the above copyright
-   notice, this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-3. Neither Ken Bloom's name, nor the name of any of his contributors may
-   may be used to endorse or promote products derived from this software
-   without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE KEN BLOOM AND CONTRIBUTORS ``AS IS'' AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGE.
-=end
-
 # Everything in Ruby is a descendant of the Object class. Practically
 # speaking, this means that any object that hasn't otherwise defined
 # the +placeheld+ and <tt>to_sqlpart</tt> methods will be treated as a piece
@@ -107,6 +40,15 @@ class Symbol
    end
 end
 
+class NilClass
+   def to_sqlpart
+      "null"
+   end
+   def placeheld
+      []
+   end
+end
+
 module SQLStatement
 
 # This class is used to represent complex SQL expressions, so that
@@ -118,7 +60,7 @@ module SQLStatement
 class Function < String
 
    def initialize(val="",placeheld=[])
-      super
+      super val
       @placeheld=placeheld
    end
 
@@ -220,19 +162,24 @@ class SelectParts
    #See the documentation for SelectStatement which describes these.
    attr_accessor :conditions, :groupby, :orderby, :fields, :tables
 
-   #Adds an array of unaliased fields to this SQL statement. See 
-   #documentation at SelectStatement
+   #Adds an array of unaliased fields, or a hash of aliased fields to 
+   #this SQL statement. See documentation at SelectStatement
    def add_fields (newfields)
-      newfields.each do |x|
-	 @fields[x]=x
+      if newfields.is_a?(Hash)
+	 @fields.merge! newfields
+      else
+	 newfields.each { |x| @fields[x]=x }
       end
+      nil
    end
 
-   #Adds an array of unaliased tables to this SQL statement. See 
-   #documentation for SelectStatement
+   #Adds an array of unaliased tables or a hash of aliased tables to 
+   #this SQL statement. See documentation for SelectStatement
    def add_tables (newtables)
-      newtables.each do |x|
-	 @tables[x]=x
+      if newtables.is_a?(Hash)
+	 @tables.merge! newtables
+      else
+	 newtables.each { |x| @tables[x]=x }
       end
    end
 
@@ -297,11 +244,15 @@ class Select
    #aliasing a field name, use the form <tt>fieldname => fieldname</tt>.
    attr_accessor :fields
 
-   #Adds an array of unaliased fields to this SQL statement.
+   #Adds an array of unaliased fields, or a hash of aliased fields to 
+   #this SQL statement.
    def add_fields (newfields)
-      newfields.each do |x|
-	 @fields[x]=x
+      if newfields.is_a?(Hash)
+	 @fields.merge! newfields
+      else
+	 newfields.each { |x| @fields[x]=x }
       end
+      nil
    end
 
    #This is the tables to include in the query (i.e. the +FROM+ clause). 
@@ -311,10 +262,13 @@ class Select
    #aliasing a table name, use the form <tt>tablename => tablename</tt>.
    attr_accessor :tables
 
-   #Adds an array of unaliased tables to this SQL statement.
+   #Adds an array of unaliased tables or a hash of aliased tables to 
+   #this SQL statement.
    def add_tables (newtables)
-      newtables.each do |x|
-	 @tables[x]=x
+      if newtables.is_a?(Hash)
+	 @tables.merge! newtables
+      else
+	 newtables.each { |x| @tables[x]=x }
       end
    end
 

data/lib/sqlstatement.rb

@@ -1,2 +1,81 @@
+=begin rdoc
+= sqlstatement - Generate complex SQL statements programmatically
+
+The main goal of this library is to be able to construct an SQL statement
+from "slices" that concern different aspects of the final query (perhaps
+in different places in your code) and then combine them all together into
+one statement easily.
+
+Another important goal of this library is to give some consistent Ruby
+syntax to three statements (INSERT, SELECT, and UPDATE) that seem to have
+different enough syntax that one has two write different code to generate
+each kind of statement.
+
+I use my SQL database (specifically MySQL) largely as a bulk data
+processing engine, by doing INSERT...SELECT or CREATE TABLE...SELECT
+statements. This library is intended to make that kind of coding easier. I
+expect that Object Relational mappers (such as ActiveRecord) are more
+useful for most people, who are performing queries and
+inserting/updating/querying for individual records. I have nevertheless 
+added INSERT...VALUES statements, and will add other statements soon, for 
+consistency.
+
+This library is inspired by CLSQL[http://clsql.b9.com/] for Common LISP,
+or SchemeQL[http://schematics.sourceforge.net/schemeql.html] for Scheme,
+although it is very different from these two libraries. Scheme and
+LISP's use of s-expressions make it very easy to construct an entire
+sublanguage for the WHERE clause, simply by list parsing.  The
+Criteria[http://mephle.org/Criteria/] library for Ruby has attempted
+this, but in a more limited manner than SchemeQL or CLSQL.  My library
+aims to cover much of the functionality in these libraries.
+
+This library doesn't try to abstract out the limitations of your DBMS, and
+I think that the SQL it uses should be fairly portable, in large measure
+because it hasn't attempted to deal with serious CREATE TABLE statements,
+where a lot of syntax concerning types, keys and sequences is much more
+variable.
+
+This library can be downloaded from 
+http://rubyforge.org/projects/sqlstatement/
+
+==Author
+Ken Bloom <mailto:kbloom@gmail.com> 
+
+http://www.iit.edu/~kbloom1/
+
+==License
+
+Copyright (c) 2006 Ken Bloom
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither Ken Bloom's name, nor the name of any of his contributors may
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE KEN BLOOM AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+=end
+
+
 require 'sql/statement'
 require 'sql/expression'
+if defined?(DBI)
+   require 'sql/dbi-support'
+end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: SqlStatement
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
-date: 2006-10-09 00:00:00 -05:00
+  version: 1.0.1
+date: 2006-11-20 00:00:00 -06:00
 summary: A library for generating arbitrary SQL statements using convenient Ruby objects.
 require_paths: 
 - lib
@@ -29,18 +29,22 @@ post_install_message:
 authors: 
 - Ken Bloom
 files: 
-- bin/example.rb
 - lib/sql
 - lib/sqlstatement.rb
 - lib/sql/expression.rb
 - lib/sql/bathon-sxp.rb
 - lib/sql/statement.rb
+- lib/sql/dbi-support.rb
+- doc/EXAMPLE
+- doc/ChangeLog
 test_files: []
 
-rdoc_options: []
-
-extra_rdoc_files: []
-
+rdoc_options: 
+- --main
+- lib/sqlstatement.rb
+extra_rdoc_files: 
+- doc/EXAMPLE
+- doc/ChangeLog
 executables: []
 
 extensions: []

data/bin/example.rb

@@ -1,129 +0,0 @@
-#!/usr/bin/env ruby
-require_gem 'SqlStatement'
-require 'sql/statement'
-require 'sql/expression'
-
-# We subclass the standard classes so that we can construct
-# a query with a complex computed field. The newlists method
-# makes this easy, giving us a constructor and combination
-# operators for free.
-
-class ProbabilityParts < SQLStatement::SelectParts
-   newlists :multiply
-end
-class ProbabilityStatement < SQLStatement::SelectCreate
-   newlists :multiply
-
-   # Add our own special fields here, computed
-   # from the list we added to this class.
-   def allfields
-      retval=super
-      retval.merge! :probability =>
-	 SQLFunc(@multiply.collect{|x| x.to_sqlpart}.join('*'))
-      retval
-   end
-end
-
-
-#In real life, I use a special library for detecting what attributes
-#are available based on the columns in my tables.
-#We'll mimic that functionality here.
-#
-#The first definition of this module mocks the stuff that's in my more
-#complicated library
-module AttributeDetection
-   class Attribute
-      def initialize(domain,name)
-	 @domain=domain
-	 @name=name
-      end
-      attr_reader :name, :domain
-   end
-   class Hierarchy < Attribute
-      def initialize(leftcolumn)
-	 ignored1,m_domain,m_name,ignored2=leftcolumn.split(/_/)
-	 super(m_domain,m_name)
-      end
-   end
-   class DomainlessPerGroup < Attribute
-      def initialize (colname)
-	 name=@colname=colname
-	 domain="!"
-	 super(domain,name)
-      end
-   end
-
-   #I have a few other attribute types, none of which
-   #are used in this code yet.
-
-end
-
-include SQLHelpers
-
-#The second definition of this module is the code that I actually define
-#in this particular program.
-module AttributeDetection
-   class Attribute
-      def condname
-	 :"cond_#{name}"
-      end
-      def priorname
-	 :"prior_#{name}"
-      end
-      #parts that go in to the CREATE TABLE `probabilities` statement
-      #which relate to the attribute we are disambiguating
-      def probability_disambig 
-	 parts=ProbabilityParts.new
-	 parts.add_fields [priorname[probkey]]
-	 parts.add_tables [priorname]
-	 parts.multiply << priorname[:pt]
-	 parts
-      end
-      #parts that go in to the CREATE TABLE `probabilities` statement
-      #which relate to the attributes we are using as features
-      def probability_features(conditionalon)
-	 parts=ProbabilityParts.new
-	 parts.tables={priorname=>priorname,condname=>condname}
-	 parts.add_fields [priorname[probkey]]
-	 parts.conditions << sql_func{ condname[probkey]==priorname[probkey]}
-	 parts.conditions << sql_func{
-	    condname[conditionalon.probkey]==
-	    conditionalon.priorname[conditionalon.probkey]
-	    }
-	 parts.multiply << sql_func{condname[:pt]/priorname[:pt]}
-	 parts
-      end
-   end
-   class Hierarchy
-      def probkey
-	 "att_#{domain}_#{name}_left".to_sym
-      end
-   end
-   class DomainlessPerGroup
-      def probkey
-	 @colname.to_sym
-      end
-   end
-end
-
-include AttributeDetection
-include SQLHelpers
-
-#And this code calls methods to actually build the query.
-
-#First we define the names of the attributes
-att_disambig=Hierarchy.new("att_appraisal_attitude_left")
-att_features=[Hierarchy.new("att_products_appraisedtype_left"),
-   DomainlessPerGroup.new("priority")]
-
-
-#Then we construct the statement
-stmt=ProbabilityStatement.new :probabilities,true
-
-stmt << att_disambig.probability_disambig 
-att_features.each { |x| stmt<< x.probability_features(att_disambig) }
-
-#Finally, we print it (or execute it against the database)
-puts stmt.to_s
-   
-