sql_munger 0.0.7

data/.bnsignore

@@ -0,0 +1,16 @@
+# The list of files that should be ignored by Mr Bones.
+# Lines that start with '#' are comments.
+#
+# A .gitignore file can be used instead by setting it as the ignore
+# file in your Rakefile:
+#
+#   PROJ.ignore_file = '.gitignore'
+#
+# For a project with a C extension, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~
+announcement.txt
+coverage
+doc
+pkg

data/.gitignore

@@ -0,0 +1,3 @@
+doc
+pkg
+

data/History.txt

@@ -0,0 +1,3 @@
+== 0.0.6 / 29-May-2011
+
+* First public release.

data/README.txt

@@ -0,0 +1,57 @@
+by John Anderson http://www.semiosix.com
+
+== DESCRIPTION:
+
+When you're good at SQL, sometimes you want to build SQL statement
+without an ORM or a db api, or a connection to a database.
+SqlMunger will simplify some of the fiddly parts of doing that.
+
+SqlMunger will not give you a SQL equivalent algebra - Sequel and AREL do that very well.
+
+See SqlIzer for an example.
+
+== FEATURES/PROBLEMS:
+
+SqlFieldSet lets you quote, escape, join and generate comparison operators
+for a set of field names and a related set of values. See SqlMunger::FieldSet
+
+SqlMunger::SqlParser knows how to parse a create table statement, giving a relatively
+easy way to create migrations or other representations of a table definition.
+
+
+== SYNOPSIS:
+
+  require 'sql_munger'
+  
+== REQUIREMENTS:
+
+treetop
+
+== INSTALL:
+
+gem install sql_munger
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009,2011 John Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bones'
+rescue LoadError
+  abort '### Please install the "bones" gem ###'
+end
+
+task :default => 'test:run'
+task 'gem:release' => 'test:run'
+
+ensure_in_path 'lib'
+require 'sql_munger'
+
+Bones {
+  name     'sql_munger'
+  authors  'John Anderson'
+  email    'john@semiosix.com'
+  url      'http://www.semiosix.com'
+  
+  version  SqlMunger::VERSION
+  description "SQL manipulation without a db connection"
+  
+  rdoc.include %w{README.txt ^lib/sql_munger/.*\.rb$ examples/sql_izer.rb History.txt}
+  
+  gem.need_tar false
+
+  depend_on 'treetop', '~>1.4.8'
+}

data/examples/sql_izer.rb

@@ -0,0 +1,92 @@
+require 'sql_munger/generation'
+require 'mysql'
+
+=begin rdoc
+Example for how to use SqlMunger
+
+  :include:sql_izer.rb
+=end
+
+class SqlIzer
+  
+  # If the SQL you want to generate uses something
+  # other than " for identifiers, and ' for string values
+  # you need to define quoting.
+  # 
+  # Also, escaping of special characters inside value strings is quite
+  # unpleasant, so for now we depend on external libraries. Feel
+  # free to implement this and send a patch.
+  # 
+  # Set this as the default quoter. Note that default_quoter wants an instance, not a class.
+  SqlMunger::FieldSet.default_quoter = Class.new do
+    include SqlMunger::ValueQuoter
+    include SqlMunger::IdentifierQuoter
+    def escape( st )
+      Mysql.escape_string( st )
+    end
+  end.new
+  
+  # the name of the table. Note that the namespace is optional
+  def table
+    @table ||= SqlMunger::TableName.new( 'namespace.things' )
+  end
+  
+  # this is the set of fields used in the where
+  # clause for update statements
+  def unique_key_fields
+    @unique_key_fields ||= SqlMunger::FieldSet.new( %w{name} )
+  end
+  
+  def field_names
+    values.keys
+  end
+  
+  # sample values for the example
+  def values
+    @values ||= {
+      'name' => 'Mr Mark',
+      'address' => "'The Pub', Dublin",
+      'phone' => '(31)415328',
+      'flavour' => 'bitter',
+      'colour' => 'dark',
+      'spin' => 'widdershins',
+      'manyness' => 16.5
+    }
+  end
+  
+  def field_set
+    @field_set ||= SqlMunger::FieldSet.new( field_names )
+  end
+  
+  # generate an insert statement
+  def insert_sql
+    <<-EOF
+      insert into #{table.quote}
+      ( #{field_set.list} )
+      values
+      (
+      \t#{field_set.quoted_values( values ).join(",\n\t")}
+      );
+    EOF
+  end
+    
+  def update_sql
+    # We want to update the values, but not the field
+    # used in the where clause
+    fields = field_set - unique_key_fields
+    
+    <<-EOF
+      update #{table.quote}
+      set
+      #{fields.update( values ) }
+      where
+      #{unique_key_fields.comparison( values )}
+      ;
+    EOF
+  end
+  
+end
+
+sqlizer = SqlIzer.new
+puts sqlizer.insert_sql
+puts sqlizer.update_sql

data/lib/sql_munger.rb

@@ -0,0 +1,49 @@
+
+module SqlMunger
+
+  # :stopdoc:
+  VERSION = '0.0.7'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module SqlMunger
+
+SqlMunger.require_all_libs_relative_to SqlMunger.libpath( 'sql_munger' )
+
+# EOF

data/lib/sql_munger/field_set.rb

@@ -0,0 +1,355 @@
+require 'sql_munger/quoter.rb'
+
+module SqlMunger
+
+=begin rdoc
+This is a class encapsulating a set of fields
+and providing various methods for producing SQL strings
+from them.
+
+You can also call operators on fieldset (+ - | & ), or 
+with an array as the right-hand parameter.
+
+Fields can be either plain strings, or objects responding
+to name, sql_type, null, default. If they're plain strings, they're
+converted to FieldSet::Field objects, which have a name attribute.
+Mixing different classes in the same FieldSet won't work.
+
+=end
+
+class FieldSet
+  include Quoter
+  
+  class Field
+    def initialize( name )
+      @name = name.to_sym
+    end
+    attr_accessor :name
+    
+    def ==( other )
+      name == other.name
+    end
+  end
+  
+  # collection_or_enum is a collection of field names.
+  #
+  # If block is supplied, collection_or_enum is a collection
+  # of objects that when map( &block ) is applied returns
+  # a collection of field names.
+  #
+  # options is intended to easily pass a :qualifier and a :quoter.
+  def initialize( collection_or_enum, options = {}, &block )
+    @fields = 
+    if collection_or_enum.all?{|x| x.is_a?( String ) || x.is_a?( Symbol ) }
+      collection_or_enum.to_a.map{|x| Field.new(x.to_s)}
+    else
+      first = collection_or_enum.first
+      first.name rescue raise( "Can't use default method :name on #{first}" )
+      collection_or_enum.to_a.dup
+    end
+    
+    @field_name_block = block || lambda {|x| x.name}
+    
+    # set options
+    options.each do |key,value|
+      send( "#{key}=", value )
+    end
+  end
+  
+  # raise an exception with msg appended if any element of ary
+  # is not a String. Otherwise return true
+  def self.check_strings( ary, msg = nil )
+    ary.each do |elt|
+      unless elt.is_a?( String ) || elt.is_a?( Symbol )
+        raise [ "#{elt.inspect} is neither String nor Symbol", msg ].compact.join(' ')
+      end
+    end
+    true
+  end
+  
+  # Create from either a Array of field names (NOTE *not* field objects)
+  # or from another FieldSet
+  def self.[]( fieldset_or_array )
+    case fieldset_or_array
+      when Array
+        check_strings( fieldset_or_array, "Use #{self.class.name}.new" )
+        FieldSet.new( fieldset_or_array )
+      
+      when FieldSet
+        field_set = fieldset_or_array
+        field_set.dup
+      
+      when NilClass
+        nil
+      
+      else
+        raise "dunno what to do with #{fieldset_or_array.inspect}"
+    end
+  end
+  
+  # the field objects, which may be objects or Strings. See field_names
+  # if you definitely always want either Strings or Symbols
+  attr_reader :fields
+  
+  # Set the fields. Assume that they're the same kind of
+  # fields as the previous set of fields
+  def fields=( other_fields )
+    @field_names = nil
+    @fields = other_fields
+  end
+  
+  # Return a new instance of FieldSet. The result
+  # of fields is passed to block, and the result of that
+  # is passed to FieldSet.new. Useful for doing set operations
+  # that aren't covered by + - & |
+  def reconstruct( &block )
+    FieldSet.new( block.call( fields ) )
+  end
+  
+  # the names of the fields
+  def field_names
+    @field_names ||= sanity_check_fields
+  end
+  
+  # enumerate through field_names
+  def each( &block )
+    field_names.each( &block )
+  end
+  include Enumerable
+  
+  # return the field object for name, or nil if it doesn't exist
+  def find_field( name )
+    fields.find{|x| name == @field_name_block.call(x) }
+  end
+  
+  # + - & | (append, difference, intersection union) same as array.
+  # other can be another FieldSet, or an Array
+  # Called from method_missing
+  def operate( operation, other )
+    case other
+      when FieldSet
+        # fetch new fields using the operated set of field_names
+        new_field_objects = field_names.send( operation, other.field_names ).map do |name|
+          # first try self's fields, then try other's fields
+          find_field( name ) || other.find_field( name )
+        end
+        
+        # create the new FieldSet
+        FieldSet.new( new_field_objects, :quoter => quoter, :qualifier => qualifier )
+      
+      when Array
+        case other.first
+          when String
+            operate( operation, FieldSet.new( other ) )
+          
+          when Symbol
+            operate( operation, FieldSet.new( other ) )
+            
+          else
+            # assume it's a field object
+            FieldSet.new( fields.send( operation, other ), :quoter => quoter, :qualifier => qualifier )
+        end
+      
+      else
+        raise "don't know what to do with #{other.inspect}"
+    end
+  end
+  
+  # passes - + & | to operate, otherwise calls method_missing
+  def method_missing( meth, *args, &block )
+    @operations ||= %w{ - + & | }.map{|x| x.to_sym}
+    if @operations.include?( meth )
+      operate( meth, args.first )
+    else
+      super
+    end
+  end
+  
+  # whatever is in front of the fields, usually a table name
+  # It's stored as an array of parts, to be quoted and joined with
+  # '.' when generating SQL
+  attr_reader :qualifier
+  
+  # can take a dotted string, an Array of strings, a TableName instance or nil
+  def qualifier=( other )
+    case other
+      when String
+        @qualifier = other.split( '.' )
+        
+      when Array
+        @qualifier = other
+      
+      when TableName
+        @qualifier = other.parts
+      
+      when NilClass
+        @qualifier = nil
+      
+      else
+        raise "Don't understand  #{other.inspect}"
+    end
+  end
+  
+  # return the set of field names, separated by ', '
+  def list( qualifier = nil )
+    field_names.map do |field|
+      qualify( qualifier, field )
+    end.join(', ')
+  end
+  
+  # prepend the qualifier to each field name
+  def qualified_list
+    list( qualifier )
+  end
+  
+  alias_method :qlist, :qualified_list
+    
+  # one arg is a field, qualified by qualifier
+  # many args is qualifier[s], field
+  def qualify( *args )
+    case args.flatten.size
+      when 1
+        [ qualifier, args.first ]
+      
+      else
+        args
+      
+    end.flatten.compact.map{|x| identifier_quoter.quote_ident(x)}.join('.')
+  end
+  
+  # return a hash of field names to their corresponding transformed values
+  # from hash_values. block will be used to transform each value.
+  def hash_values( hash_values, &block )
+    inject({}) do |hash,field|
+      hash[field] =
+      if block.nil?
+        hash_values[field]
+      else
+        block.call( hash_values[field] )
+      end
+      hash
+    end
+  end
+  
+  # return a comma-separated list of the quoted values for this
+  # fieldset
+  def quoted_values( hash_values )
+    map do |field|
+      value_quoter.quote( hash_values[field] )
+    end
+  end
+  
+  # extract the values for these fields from hash_values
+  # block will be applied to each value
+  def values( hash_values, &block )
+    map do |field|
+      if block.nil?
+        hash_values[field]
+      else
+        block.call( hash_values[field] )
+      end
+    end
+  end
+
+  # return a string of the fields with some operator and value
+  # can be used for where clauses and update statements.
+  # arg is either a String, which is treated passed to TableName.new
+  # or a TableName, which qualifies the rhs
+  # or an Array (actually something with a zip method) which is used as a set of values
+  # or a Hash (or something with to_hash) from which the values corresponding
+  # to the fields in this object are extracted, and used to compare with
+  def express( arg, level = 0, options = { :operator => '=', :joiner => ',' } )
+    expressions = 
+    case
+      when arg.is_a?( String )
+        express( TableName.new( arg ), level+1, options )
+      
+      when arg.is_a?( TableName )
+        other_table = arg
+        field_names.map do |field|
+          "#{qualify( field )} #{options[:operator]} #{qualify( other_table, field )}"
+        end
+      
+      when arg.is_a?( Hash )
+        field_names.map do |field|
+          "#{qualify( field )} #{options[:operator]} #{value_quoter.quote( arg[field] )}"
+        end
+      
+      when arg.respond_to?( :to_hash )
+        express( arg.to_hash, level+1, options )
+      
+      when arg.respond_to?( :zip )
+        raise "#{arg.inspect} doesn't match number of fields in #{field_names}" unless size == arg.size
+        field_names.zip( [ *arg ] ).map do |field,value|
+          "#{qualify( field )} #{options[:operator]} #{value_quoter.quote( value )}"
+        end
+      
+      else
+        raise "Don't know what to do with #{arg.inspect}"
+    end
+    
+    if level == 0
+      if options[:joiner].nil?
+        expressions
+      else
+        expressions.join( options[:joiner] )
+      end
+    else
+      expressions
+    end
+  end
+  
+  # return an SQL set of comparison expressions, joined with 'and' suitable for
+  # a where clause
+  def comparison( arg, operator = '=' )
+    if arg.is_a?( String ) && qualifier.nil?
+      raise "no local qualifier"
+    end
+    
+    st = express( arg, 0, :operator => operator, :joiner => ' and ' )
+    "( #{st} )"
+  end
+  
+  # return something suitable for an update statement
+  def update( arg )
+    save_qualifier = qualifier
+    begin
+      self.qualifier = nil
+      express( arg, 0, :operator => '=', :joiner => ', ' )
+    ensure
+      self.qualifier = save_qualifier
+    end
+  end
+  
+  # probably only works with column definitions from ActiveRecord
+  def definitions( options = {:joiner => ', '} )
+    fields.map do |field|
+      raise "sql_type has no value" if field.sql_type.nil? || field.sql_type == ''
+      "#{field.name} #{field.sql_type}"
+    end.join( options[:joiner] )
+  end
+  
+  def size
+    fields.size
+  end
+  
+  def empty?
+    fields.empty?
+  end
+  
+  def ==( other )
+    return false unless other.is_a?( self.class )
+    qualifier == other.qualifier and
+    fields == other.fields and
+    @field_name_block == other.instance_variable_get( '@field_name_block' )
+  end
+
+protected
+  
+  # generate field names from field objects
+  def sanity_check_fields
+    fields.map( &@field_name_block )
+  end
+end
+
+end # module SqlMunger