case_insensitive_arel 0.0.0 → 0.1.0

data/README.rdoc

@@ -1,8 +1,86 @@
 = case_insensitive_arel
 
-Description goes here.
+If you're using Oracle or another DBMS that uses case-sensitive collation sequences, and don't want to litter your
+code with snippets of proprietary case-conversion SQL, this may be the solution you're looking for.
 
-== Contributing to case_insensitive_arel
+== How It Works
+
+This gem is pretty simple in its operation. Working at the Arel level, it takes +String+, +Arel_Attributes_Attribute+,
+and +Arel_Attributes_String+ values, and executes a proc that is responsible for converting them into
+a common format for comparison e.g. uppercase or lowercase. This proc can be overridden to do whatever you want. For
+example, you might prefer to convert the values to lowercase, or use another conversion method. No problem! You can
+also enable and disable the case-insensitive comparison behaviour by setting a flag, see below for details.
+
+It's important to note that any custom SQL you create will _not_ be modified by this gem. Everything that is generated
+by Arel however should be handled as you'd expect. If you find something that doesn't work the way you think it should,
+please let me know.
+
+== Examples
+
+Here are some examples of what +case_insensitive_arel+ will do:
+
+  users.where(users[:name].eq('Steve')).to_sql
+
+  => SELECT  FROM "USERS" WHERE UPPER("USERS"."NAME") = UPPER('Steve')
+
+  users.where(users[:name].matches('Steve%')).to_sql
+
+  => SELECT  FROM "USERS" WHERE UPPER("USERS"."NAME") LIKE UPPER('Steve%')
+
+  users.where(users[:name].in(%w(Steve Barb))).to_sql
+
+  => SELECT  FROM "USERS" WHERE UPPER("USERS"."NAME") IN (UPPER('Steve'), UPPER('Barb')')
+
+  users.group(users[:name]).to_sql
+
+  => SELECT  FROM "USERS" GROUP BY UPPER("USERS"."NAME")
+
+  users.join(photos).on(users[:name].eq(photos[:name])).to_sql
+
+  => SELECT  FROM "USERS" INNER JOIN "PHOTOS" ON UPPER("USERS"."NAME") = UPPER("PHOTOS"."USER_NAME")
+
+  users.project(users[:name]).where(users[:name].eq('Steve'))
+
+  => SELECT "USERS"."NAME" FROM "USERS" WHERE UPPER("USERS"."NAME") = UPPER('Steve')
+
+== Customization
+
+The following default settings can be overridden in your code as required:
+
+  Arel::CaseInsensitive.case_insensitive = false
+  Arel::CaseInsensitive.conversion_proc = Proc.new { |val| "UPPER(#{val})" }
+
+These settings, which were used for the above examples, work for Oracle. You can customize the +convert_attribute+
+setting to specify an alternative conversion function for your DBMS in your application. The +convert_string+ setting is
+used to convert a string literal into a form that can be compared in a case-insensitive fasion to the result of what's
+returned by +convert_attribute+ as the query is processed by the DBMS. Finally, the +case_insensitive+ setting can be
+used to disable case-insensitive behaviour if need be.
+
+As an example, you could add this code to your app if you wanted to use lowercase for conversions:
+
+  Arel::CaseInsensitive.conversion_proc = Proc.new { |val| "LOWER(#{val})" }
+
+== Known Issues
+
+=== Performance/Query Optimization
+
+Due to the wrapping of column names with function calls, certain DBMS' optimizers may ignore indexes on those columns
+that might otherwise be used for a query. If supported by your DBMS, you may be able to create a special index on
+these columns to help out wih your query. As an example, Oracle supports _function-based indexes_.
+
+For more information, please refer to your DBMS's documentation.
+
+=== Single Connection Only
+
+Because this implementation applies across all adapters, there may be issues with applications that use multiple
+database adapters.
+
+=== Custom SQL
+
+Rather than risk madness, I didn't even bother trying to make this work with custom SQL. Stick with Arel and there
+won't be any issues.
+
+== Contributing
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

data/Rakefile

@@ -15,16 +15,14 @@ Jeweler::Tasks.new do |gem|
   gem.name = "case_insensitive_arel"
   gem.homepage = "http://github.com/slamotte/case_insensitive_arel"
   gem.license = "MIT"
-  gem.summary = %Q{Allows Arel queries to be case-insensitive}
-  gem.description = <<EOF
-If you're using Oracle or another DBMS that has case-insensitive collation sequences, this gem is for you.
-EOF
+  gem.summary = %Q{Forces Arel queries to be case-insensitive}
+  gem.description = %Q{If you're using Oracle or another DBMS that has case-insensitive collation sequences, and you don't want to litter your database access code with case conversions, this gem is for you.}
   gem.email = "steve@lexor.ca"
   gem.authors = ["Steve Lamotte"]
   # Include your dependencies below. Runtime dependencies are required when using your gem,
   # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
   gem.add_runtime_dependency 'arel', '>= 2.0.9'
-  gem.add_runtime_dependency 'activesupport'
+  gem.add_runtime_dependency 'activesupport', '>= 2.0.0'
 end
 Jeweler::RubygemsDotOrgTasks.new
 
@@ -52,4 +50,5 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "case_insensitive_arel #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.options += %w(--line-numbers --inline-source --accessor cattr_accessor)
 end

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/case_insensitive_arel.gemspec

@@ -5,13 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{case_insensitive_arel}
-  s.version = "0.0.0"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Steve Lamotte"]
-  s.date = %q{2011-03-18}
-  s.description = %q{If you're using Oracle or another DBMS that has case-insensitive collation sequences, this gem is for you.
-}
+  s.date = %q{2011-03-19}
+  s.description = %q{If you're using Oracle or another DBMS that has case-insensitive collation sequences, and you don't want to litter your database access code with case conversions, this gem is for you.}
   s.email = %q{steve@lexor.ca}
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -38,7 +37,7 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Allows Arel queries to be case-insensitive}
+  s.summary = %q{Forces Arel queries to be case-insensitive}
   s.test_files = [
     "test/helper.rb",
     "test/support/fake_record.rb",
@@ -60,7 +59,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
       s.add_development_dependency(%q<rcov>, [">= 0"])
       s.add_runtime_dependency(%q<arel>, [">= 2.0.9"])
-      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.0.0"])
     else
       s.add_dependency(%q<arel>, [">= 2.0.9"])
       s.add_dependency(%q<activesupport>, [">= 3.0.0"])
@@ -69,7 +68,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
       s.add_dependency(%q<rcov>, [">= 0"])
       s.add_dependency(%q<arel>, [">= 2.0.9"])
-      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<activesupport>, [">= 2.0.0"])
     end
   else
     s.add_dependency(%q<arel>, [">= 2.0.9"])
@@ -79,7 +78,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
     s.add_dependency(%q<rcov>, [">= 0"])
     s.add_dependency(%q<arel>, [">= 2.0.9"])
-    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<activesupport>, [">= 2.0.0"])
   end
 end
 

data/lib/case_insensitive_arel.rb

@@ -1,51 +1,57 @@
 require 'active_support/core_ext/class/attribute_accessors'
 require 'active_support/core_ext/module/aliasing'
 
-module Arel
-  module Visitors
+module Arel #:nodoc:
+  module Visitors #:nodoc: all
     class ToSql
-      # List of Arel types that should be converted to upper or lower case
+      # List of Arel types that should be converted to make them comparable in a case-insensitive fashion
       %w(Arel_Attributes_Attribute Arel_Attributes_String String).each do |arel_type_name|
-        convert_method = case arel_type_name
-                           when /^Arel_Attributes_.+/
-                             :convert_attribute
-                           when 'String'
-                             :convert_string
-                           else
-                             raise "Unexpected Arel type name: #{arel_type_name}"
-                         end
         define_method "visit_#{arel_type_name}_with_case_insensitive" do |o|
           value = send("visit_#{arel_type_name}_without_case_insensitive", o)
-          o.respond_to?(:do_not_make_case_insensitive?) ? value : Arel::CaseInsensitive.convert_value(value, convert_method)
+
+          # If the object has been tagged with
+          o.respond_to?(:do_not_make_case_insensitive?) ? value : Arel::CaseInsensitive.convert_value(value)
         end
         alias_method_chain "visit_#{arel_type_name}", :case_insensitive
       end
     end
   end
 
+  # Controls case-insensitive comparisons. The following attributes can be set to customize behaviour.
   class CaseInsensitive
-    cattr_accessor :case_insensitive, :convert_attribute, :convert_string
+    # Boolean that determines whether case-insensitive processing is enabled or not. Defaults to:
+    #  Arel::CaseInsensitive.case_insensitive = true
+    cattr_accessor :case_insensitive
+
+    # Proc that accepts an Arel object and converts it into something that can be compared in a case-insensitive manner. Defaults to:
+    #  Arel::CaseInsensitive.conversion_proc = Proc.new { |val| "UPPER(#{val})" }
+    cattr_accessor :conversion_proc
 
-    def self.convert_value(val, method)
-      case_insensitive ? send(method).call(val) : val
+    private
+
+    # Return the converted value or the value itself depending on the current state of +case_insensitive+
+    def self.convert_value(val)
+      case_insensitive ? conversion_proc.call(val) : val
     end
   end
 
-  class Table
+  class Table # :nodoc:
+    # We don't want an attribute in the SELECT to be processed by the conversion proc. As such, tag +project+'s' parameters with a special
+    # singleton method to prevent them from being converted.
     def project_with_case_insensitive(*things)
-      things = things.map do |thing|
-        new_thing = thing.clone # Need to clone these because we might want to use an attribute in the SELECT and WHERE clauses, but the former shouldn't be altered
-        def new_thing.do_not_make_case_insensitive?; true; end
+    # If a +thing+ is used elsewhere (e.g. in the WHERE clause), tagging it will cause the WHERE clause to be affected as well. So create a new
+    # list of things and tag them instead.
+    new_things = things.map do |thing|
+        new_thing = thing.clone
+        def new_thing.do_not_make_case_insensitive?; end
         new_thing
       end
-      project_without_case_insensitive *things
+      project_without_case_insensitive *new_things
     end
     alias_method_chain :project, :case_insensitive
   end
 end
 
-# Set the default values (for Oracle)
+# Set the default values (these work for Oracle)
 Arel::CaseInsensitive.case_insensitive = true
-Arel::CaseInsensitive.convert_attribute = Proc.new { |val| "UPPER(#{val})" }
-Arel::CaseInsensitive.convert_string = Proc.new{ |val| val.upcase }
-
+Arel::CaseInsensitive.conversion_proc = Proc.new { |val| "UPPER(#{val})" }

data/test/test_comparisons.rb

@@ -3,15 +3,15 @@ require 'helper'
 class TestComparisons < Test::Unit::TestCase
   should "work correctly in case-insensitive mode" do
     Arel::CaseInsensitive.case_insensitive = true
-    should_be_like @users.where(@users[:name].eq('Steve')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") = 'STEVE'"
-    should_be_like @users.where(@users[:name].not_eq('Steve')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") != 'STEVE'"
-    should_be_like @users.where(@users[:name].matches('Ste%')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") LIKE 'STE%'"
-    should_be_like @users.where(@users[:name].does_not_match('Ste%')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") NOT LIKE 'STE%'"
+    should_be_like @users.where(@users[:name].eq('Steve')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") = UPPER('Steve')"
+    should_be_like @users.where(@users[:name].not_eq('Steve')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") != UPPER('Steve')"
+    should_be_like @users.where(@users[:name].matches('Ste%')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") LIKE UPPER('Ste%')"
+    should_be_like @users.where(@users[:name].does_not_match('Ste%')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") NOT LIKE UPPER('Ste%')"
     should_be_like @users.where(@users[:name].eq(@users[:name])).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") = UPPER(\"users\".\"name\")"
-    should_be_like @users.where(@users[:name].gteq('Steve')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") >= 'STEVE'"
-    should_be_like @users.where(@users[:name].in(['Steve', 'Barb'])).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") IN ('STEVE', 'BARB')"
-    should_be_like @users.where(@users[:name].not_in(['Steve', 'Barb'])).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") NOT IN ('STEVE', 'BARB')"
-    should_be_like @users.where(@users[:name].matches_any(['Steve', 'Barb'])).to_sql, "SELECT FROM \"users\" WHERE (UPPER(\"users\".\"name\") LIKE 'STEVE' OR UPPER(\"users\".\"name\") LIKE 'BARB')"
+    should_be_like @users.where(@users[:name].gteq('Steve')).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") >= UPPER('Steve')"
+    should_be_like @users.where(@users[:name].in(%w(Steve Barb))).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") IN (UPPER('Steve'), UPPER('Barb'))"
+    should_be_like @users.where(@users[:name].not_in(%w(Steve Barb))).to_sql, "SELECT FROM \"users\" WHERE UPPER(\"users\".\"name\") NOT IN (UPPER('Steve'), UPPER('Barb'))"
+    should_be_like @users.where(@users[:name].matches_any(%w(Steve Barb))).to_sql, "SELECT FROM \"users\" WHERE (UPPER(\"users\".\"name\") LIKE UPPER('Steve') OR UPPER(\"users\".\"name\") LIKE UPPER('Barb'))"
   end
 
   should "work correctly in case-sensitive mode" do
@@ -22,8 +22,8 @@ class TestComparisons < Test::Unit::TestCase
     should_be_like @users.where(@users[:name].does_not_match('Ste%')).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" NOT LIKE 'Ste%'"
     should_be_like @users.where(@users[:name].eq(@users[:name])).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" = \"users\".\"name\""
     should_be_like @users.where(@users[:name].gteq('Steve')).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" >= 'Steve'"
-    should_be_like @users.where(@users[:name].in(['Steve', 'Barb'])).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" IN ('Steve', 'Barb')"
-    should_be_like @users.where(@users[:name].not_in(['Steve', 'Barb'])).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" NOT IN ('Steve', 'Barb')"
-    should_be_like @users.where(@users[:name].matches_any(['Steve', 'Barb'])).to_sql, "SELECT FROM \"users\" WHERE (\"users\".\"name\" LIKE 'Steve' OR \"users\".\"name\" LIKE 'Barb')"
+    should_be_like @users.where(@users[:name].in(%w(Steve Barb))).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" IN ('Steve', 'Barb')"
+    should_be_like @users.where(@users[:name].not_in(%w(Steve Barb))).to_sql, "SELECT FROM \"users\" WHERE \"users\".\"name\" NOT IN ('Steve', 'Barb')"
+    should_be_like @users.where(@users[:name].matches_any(%w(Steve Barb))).to_sql, "SELECT FROM \"users\" WHERE (\"users\".\"name\" LIKE 'Steve' OR \"users\".\"name\" LIKE 'Barb')"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: case_insensitive_arel
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 27
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 0
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Steve Lamotte
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-18 00:00:00 -05:00
+date: 2011-03-19 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -134,15 +134,15 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
+        hash: 15
         segments: 
+        - 2
         - 0
-        version: "0"
+        - 0
+        version: 2.0.0
   requirement: *id008
   type: :runtime
-description: |
-  If you're using Oracle or another DBMS that has case-insensitive collation sequences, this gem is for you.
-
+description: If you're using Oracle or another DBMS that has case-insensitive collation sequences, and you don't want to litter your database access code with case conversions, this gem is for you.
 email: steve@lexor.ca
 executables: []
 
@@ -200,7 +200,7 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Allows Arel queries to be case-insensitive
+summary: Forces Arel queries to be case-insensitive
 test_files: 
 - test/helper.rb
 - test/support/fake_record.rb