where_lower 0.3.0 → 0.3.1

data/.travis.yml

@@ -1,15 +1,26 @@
-before_install: "gem install bundler -v=1.5.2"
+# Send builds to container-based infrastructure
+# http://docs.travis-ci.com/user/workers/container-based-infrastructure/
+sudo: false
+language: ruby
+cache:
+- bundler
 rvm:
-  - 1.9.2
-  - 1.9.3
-  - 2.0.0
-  - 2.1.0
+  - 2.1.10
+  - 2.2.6
+  # Since the Travis Build Env does not recognize `2.3` alias yet
+  # We need to specify the version precisely
+  - 2.3.3
+  - ruby-head
 gemfile:
-  - gemfiles/rails3_1.gemfile
-  - gemfiles/rails3_2.gemfile
-  - gemfiles/rails4_0.gemfile
+  - gemfiles/rails_4_0.gemfile
+  - gemfiles/rails_4_1.gemfile
+  - gemfiles/rails_4_2.gemfile
 matrix:
-  exclude:
-    - rvm: 1.9.2
-      gemfile: gemfiles/rails4_0.gemfile
-
+  fast_finish: true
+  allow_failures:
+    - rvm: ruby-head
+  include:
+  - rvm: 2.3.3
+    gemfile: gemfiles/rails_5_0.gemfile
+  - rvm: ruby-head
+    gemfile: gemfiles/rails_5_0.gemfile

data/Appraisals

@@ -1,15 +1,20 @@
 
-appraise "rails3-1" do
-  version = "3.1.12"
-  gem 'activerecord', version
+appraise "rails_4_0" do
+  version = "~> 4.0.12"
+  gem "activerecord", version
 end
 
-appraise "rails3-2" do
-  version = "3.2.16"
-  gem 'activerecord', version
+appraise "rails_4_1" do
+  version = "~> 4.1.8"
+  gem "activerecord", version
 end
 
-appraise "rails4-0" do
-  version = "4.0.2"
-  gem 'activerecord', version
+appraise "rails_4_2" do
+  version = "~> 4.2.0"
+  gem "activerecord", version
+end
+
+appraise "rails_5_0" do
+  version = "~> 5.0.0"
+  gem "activerecord", version
 end

data/CHANGELOG.md

@@ -1,14 +1,63 @@
-### Changelog
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
 
 
-- **0.3.0**
-  - Add: You can now pass a nested hash for associaiton conditions (see README)
-  - Change: Now it requires at least ruby 1.9.2
+## [Unreleased]
 
-- **0.2.0**
-  - Fix: You can now use this with named scopes
-  - Change: Use dynamic query string instead of Arel Table to generate relation (which cause the bug)
-  - Dev: Add a few test for compatibility with gem `squeel`
+### Added
 
-- **0.1.0**
-  - Initail Release
+- Nothing
+
+### Changed
+
+- Nothing
+
+### Fixed
+
+- Nothing
+
+
+## [0.3.1]
+
+### Changed
+
+- Add support for AR 5.0.x
+- Drop support for AR 3.x
+- Drop support for Ruby < 2.1
+
+
+## [0.3.0]
+
+### Added
+
+- You can now pass a nested hash for associaiton conditions (see README)
+
+### Changed
+
+- Now it requires at least ruby 1.9.2
+
+
+## [0.2.0]
+
+### Changed
+
+- Use dynamic query string instead of Arel Table to generate relation (which cause the bug)
+- Add a few test for compatibility with gem `squeel`
+
+### Fixed
+
+- You can now use this with named scopes
+
+
+## 0.1.0
+
+### Added
+
+- Initial Release
+  
+  
+[Unreleased]: https://github.com/AssetSync/asset_sync/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/AssetSync/asset_sync/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/AssetSync/asset_sync/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/AssetSync/asset_sync/compare/v0.1.0...v0.2.0

data/Gemfile

@@ -1,3 +1,3 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 gemspec

data/README.md

@@ -1,29 +1,26 @@
-where_lower
-===========
+# where_lower
 
 Provide an easy way to use case insensitive `where` in ActiveRecord.
 
-### Support
-===========
-Tested against:
-- Active Record of version `3.1`, `3.2` and `4.0`
-- Ruby `1.9.2`, `1.9.3`, `2.0.0` (except Rails 4 with `1.9.2`)
 
-[![Build Status](https://travis-ci.org/PikachuEXE/where_lower.png?branch=master)](https://travis-ci.org/PikachuEXE/where_lower)
-[![Gem Version](https://badge.fury.io/rb/where_lower.png)](http://badge.fury.io/rb/where_lower)
-[![Dependency Status](https://gemnasium.com/PikachuEXE/where_lower.png)](https://gemnasium.com/PikachuEXE/where_lower)
-[![Coverage Status](https://coveralls.io/repos/PikachuEXE/where_lower/badge.png)](https://coveralls.io/r/PikachuEXE/where_lower)
-[![Code Climate](https://codeclimate.com/github/PikachuEXE/where_lower.png)](https://codeclimate.com/github/PikachuEXE/where_lower)
+## Status
 
-Install
-=======
+[![Build Status](http://img.shields.io/travis/PikachuEXE/where_lower.svg?style=flat-square)](https://travis-ci.org/PikachuEXE/where_lower)
+[![Gem Version](http://img.shields.io/gem/v/where_lower.svg?style=flat-square)](http://badge.fury.io/rb/where_lower)
+[![Dependency Status](http://img.shields.io/gemnasium/PikachuEXE/where_lower.svg?style=flat-square)](https://gemnasium.com/PikachuEXE/where_lower)
+[![Coverage Status](http://img.shields.io/coveralls/PikachuEXE/where_lower.svg?style=flat-square)](https://coveralls.io/r/PikachuEXE/where_lower)
+[![Code Climate](http://img.shields.io/codeclimate/github/PikachuEXE/where_lower.svg?style=flat-square)](https://codeclimate.com/github/PikachuEXE/where_lower)
+[![Inch CI](https://inch-ci.org/github/PikachuEXE/where_lower.svg?branch=master)](https://inch-ci.org/github/PikachuEXE/where_lower)
+
+
+## Installation
 
 ```ruby
 gem 'where_lower'
 ```
 
-Usage
-=====
+
+## Usage
 Supports `String`, `Array`, `Range`  
 Values in `Array` and `Range` will be converted to `String` and then `downcase`  
 Other types will not be touched
@@ -32,7 +29,7 @@ Other types will not be touched
 SomeActiveRecordClass.where_lower(attribute1: 'AbC', attribute2: ['stRing', 123, :symBol], attribute3: ('AA'..'AZ'))
 ```
 
-Since `0.3.0`  
+### Since `0.3.0`
 You can pass a nested hash (1 level deep only) for association condition
 ```ruby
 record.association_records.where_lower(association_table: {association_column: value})
@@ -44,6 +41,6 @@ I don't plan to support any "smart" table guessing though
 record.association_records.where_lower('association_table.association_column' => value)
 ```
 
-Contributors
-============
-[Matthew Rudy Jacobs](https://github.com/matthewrudy) (Who wrote the first version of `where_lower` method)
+
+## Contributors
+- [Matthew Rudy Jacobs](https://github.com/matthewrudy) (Who wrote the first version of `where_lower` method)

data/Rakefile

@@ -1,15 +1,18 @@
 require "appraisal"
 require "bundler"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 Bundler::GemHelper.install_tasks
 
 RSpec::Core::RakeTask.new(:spec)
 
+RuboCop::RakeTask.new(:rubocop)
+
 if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
   task :default do
-    sh "rake appraisal:install && rake appraisal spec"
+    sh "appraisal install && rake appraisal spec"
   end
 else
-  task :default => :spec
+  task default: [:spec]
 end

data/gemfiles/rails_4_0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 4.0.12"
+
+gemspec :path => "../"

data/gemfiles/{rails3_1.gemfile → rails_4_1.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "activerecord", "3.1.12"
+gem "activerecord", "~> 4.1.8"
 
-gemspec :path=>"../"
+gemspec :path => "../"

data/gemfiles/{rails3_2.gemfile → rails_4_2.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "activerecord", "3.2.16"
+gem "activerecord", "~> 4.2.0"
 
-gemspec :path=>"../"
+gemspec :path => "../"

data/gemfiles/{rails4_0.gemfile → rails_5_0.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "activerecord", "4.0.2"
+gem "activerecord", "~> 5.0.0"
 
-gemspec :path=>"../"
+gemspec :path => "../"

data/lib/where_lower.rb

@@ -1,5 +1,5 @@
-require 'active_record'
-require 'where_lower/version'
-require 'where_lower/base'
-require 'where_lower/scope_spawner'
-require 'where_lower/active_record_extension'
+require "where_lower/version"
+
+require "where_lower/base"
+require "where_lower/scope_spawner"
+require "where_lower/active_record_extension"

data/lib/where_lower/active_record_extension.rb

@@ -1,12 +1,32 @@
+require "active_record"
+require "where_lower/base"
+
+# :nodoc:
 module WhereLower
+  # :nodoc:
   module ActiveRecordExtension
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    # :nodoc:
     module ClassMethods
+      # A bit like `where`, but only accept hash, with value of `String`, `Array`, `Range`
+      #
+      # @api
+      #
+      # @param fields [Hash]
+      #   the conditions in hash, values will be downcase
+      #   It could also be a 1 level deep hash so that it can be used in join
+      #
+      # @example Find user by username case insensitively
+      #   User.where_lower(username: param[:name])
+      # @example Find user by alias case insensitively
+      #   User.join(:aliases).where_lower(aliases:{name: param[:name]})
+      #
+      # @raise [ArgumentError] when fields is not a Hash
       def where_lower(fields)
-        fields.is_a?(Hash) or raise AugumentError, 'fields is not a Hash'
+        fail AugumentError, "fields is not a Hash" unless fields.is_a?(Hash)
 
         WhereLower::Base.spawn_lower_scope(self, fields)
       end
@@ -14,6 +34,7 @@ module WhereLower
   end
 end
 
+# Automagically include the module on require
 ActiveRecord::Base.class_eval do
   include ::WhereLower::ActiveRecordExtension
 end

data/lib/where_lower/base.rb

@@ -1,22 +1,44 @@
+require "where_lower/scope_spawner"
+
 module WhereLower
-  SEPERATOR = '.'.freeze
+  # Table name and column name seperator
+  # This should never change
+  SEPERATOR = ".".freeze
 
+  # Raised when some deeply nested hash passed in which cannot be handled by this gem
   class TooDeepNestedConditions < ArgumentError; end
 
+  # Internal API to be called from extension methods
   module Base
     class << self
-      # @params [ActiveRecord::Relation, ActiveRecord::Base] scope
-      # @params [Hash] fields
+      # Spawn a new scope based on existing scope and hash
+      # This is method is for internal use
+      #
+      # @api private
+      #
+      # @params scope [ActiveRecord::Relation, ActiveRecord::Base]
+      #   the existing scope, ActiveRecord::Base also works since `where` will be delegated
+      # @params fields [Hash]
+      #   @see `.where_lower`
+      #
+      # @see `.spawn_lower_scope_by_type`
+      #
+      # @return [ActiveRecord::Relation]
       def spawn_lower_scope(scope, fields)
         fields.inject(scope) do |new_scope, (name, value)|
           spawn_lower_scope_by_type(new_scope, name, value)
         end
       end
 
-      # @params [ActiveRecord::Relation, ActiveRecord::Base] scope
-      # @params [String, Symbol] column_or_table_name When used with nested hash, this is table name
-      # @params [Object] value
-      # @params [String, Symbol] prefix used when doing recursive call
+      # This is method is for internal use
+      #
+      # @api private
+      #
+      # @params scope [ActiveRecord::Relation, ActiveRecord::Base]
+      #   @see spawn_lower_scope
+      # @params column_or_table_name [String, Symbol]
+      #   When used with nested hash, this is table name
+      # @params value [Object]
       #
       # @raise [TooDeepNestedConditions] if the conditions hash has is too deep nested
       #

data/lib/where_lower/scope_spawner.rb

@@ -1,107 +1,143 @@
 module WhereLower
+  # :nodoc:
   class ScopeSpawner
+    # :nodoc:
     attr_reader :scope, :column_or_table_name, :value, :prefix
 
+    # Spawn different scopes based on value
+    # Just delegates to new though
+    #
+    # @param args [Array] arguments that are passed to #initialize
+    #
+    # @see #initialize
     def self.spawn(*args)
       new(*args).spawn
     end
 
+    # Assign ivar only
+    # Actual operation is in #spawn
+    #
+    # @param scope [ActiveRecord::Relation]
+    #   Relation or collection proxy or some AR classes
+    # @param column_or_table_name [Symbol, String]
+    #   when column name, the actual column name (not attribute name)
+    #   when table name, the actual table name (not class name converted to underscore)
+    # @param value [Object]
+    #   value to compare to, also determine what scope spawner to be used
+    # @param prefix [Symbol, String]
+    #   used internally for specifying a scope with prefix (table name)
+    #
+    # @see #spawn
     def initialize(scope, column_or_table_name, value, prefix = nil)
-      @scope, @column_or_table_name, @value, @prefix = scope, column_or_table_name, value, prefix
+      @scope                = scope
+      @column_or_table_name = column_or_table_name
+      @value                = value
+      @prefix               = prefix
     end
 
-    def scope_arguments
-      [scope, column_or_table_name, value, prefix]
-    end
-
-    # acts as factory
+    # Spawn different scopes based on value
+    # Data conversion and query string generation are handled by different spanwer classes
+    #
+    # @return [ActiveRecord::Relation] Relation or collection proxy or some AR classs
     def spawn
-      case value
-      when Hash
-        HashScopeSpawner.spawn(*scope_arguments)
-      when String
-        StringScopeSpawner.spawn(*scope_arguments)
-      when Range
-        RangeScopeSpawner.spawn(*scope_arguments)
-      when Array
-        ArrayScopeSpawner.spawn(*scope_arguments)
-      else
-        BasicScopeSpawner.spawn(*scope_arguments)
-      end
+      CLASS_TO_SPAWNER_CLASS_MAPPINGS[value.class].
+        spawn(*scope_arguments)
     end
 
-
     private
 
+    # :nodoc:
+    def scope_arguments
+      [scope, column_or_table_name, value, prefix]
+    end
+
+    # :nodoc:
     class BasicScopeSpawner < ScopeSpawner
+      # :nodoc:
       def spawn
         scope.where(column_name => value)
       end
 
       private
 
+      # :nodoc:
       def column_name
         [prefix, column_or_table_name].compact.join(SEPERATOR)
       end
     end
 
+    # This class is only for inheritance
+    #
     # @abstract
+    #   Subclass has to implement #query_string & #processed_value
     class EqualScopeSpawner < BasicScopeSpawner
+      # We generate query_string and pass values to it
+      # To avoid some scope chaining problems
       def spawn
         scope.where(query_string, processed_value)
       end
-
-      private
-
-      def query_string
-        "#{column_name} = ?"
-      end
-
-      def processed_value
-        value
-      end
     end
 
+    # :nodoc:
     class StringScopeSpawner < EqualScopeSpawner
+      # :nodoc:
       def query_string
         "lower(#{column_name}) = ?"
       end
 
+      # :nodoc:
       def processed_value
         value.downcase
       end
     end
 
+    # :nodoc:
     class RangeScopeSpawner < EqualScopeSpawner
+      # :nodoc:
       def query_string
         "lower(#{column_name}) IN (?)"
       end
 
+      # :nodoc:
       def processed_value
         Range.new(value.begin.to_s.downcase, value.end.to_s.downcase, value.exclude_end?)
       end
     end
 
+    # :nodoc:
     class ArrayScopeSpawner < EqualScopeSpawner
+      # :nodoc:
       def query_string
         "lower(#{column_name}) IN (?)"
       end
 
+      # :nodoc:
       def processed_value
-        value.to_a.map {|x| x.to_s.downcase}
+        value.to_a.map { |x| x.to_s.downcase }
       end
     end
 
+    # :nodoc:
     class HashScopeSpawner < BasicScopeSpawner
+      # If prefix already exists,
+      # that means we are in association table already,
+      # which cannot accept another hash
+      # This gem has no ability to handle deep nested associaiton reflection yet
       def spawn
-        # If prefix already exists, that means we are in association table already, which cannot accept another hash
-        # This gem has no ability to handle deep nested associaiton reflection yet
-        raise TooDeepNestedConditions unless prefix.nil?
+        fail TooDeepNestedConditions unless prefix.nil?
 
         value.inject(scope) do |new_scope, (column_name, column_value)|
           ScopeSpawner.spawn(new_scope, column_name, column_value, column_or_table_name)
         end
       end
     end
+
+    # This was extracted from `case..when`
+    CLASS_TO_SPAWNER_CLASS_MAPPINGS = {
+      Hash   => HashScopeSpawner,
+      String => StringScopeSpawner,
+      Range  => RangeScopeSpawner,
+      Array  => ArrayScopeSpawner,
+    }.tap { |h| h.default = BasicScopeSpawner }.freeze
   end
 end