japetheape-scoped_search 1.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Willem van Bergen
+ 
+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/README.rdoc

@@ -0,0 +1,78 @@
+= scoped_search
+
+The <b>scoped_search</b> Rails plugin makes it easy to search your ActiveRecord models. Searching is 
+performed using a query string, which should be passed to the named_scope *search_for* that uses SQL 
+<tt>LIKE %keyword%</tt> conditions for searching (ILIKE for Postgres). You can specify what fields 
+should be used for searching.
+
+== Installing
+
+The recommended method to enable scoped_search in your project is adding the scoped_search gem to your environment. Add the following code to your Rails configuration in <tt>config/environment.rb</tt>:
+
+  Rails::Initializer.run do |config|
+    ...
+    config.gem 'wvanbergen-scoped_search', :lib => 'scoped_search', 
+                   source => 'http://gems.github.com/'
+  end
+
+Run <tt>sudo rake gems:install</tt> to install the gem.
+
+Another alternative is to install scoped_search as a Rails plugin:
+
+  script/plugin install git://github.com/wvanbergen/scoped_search.git
+
+== Usage
+
+First, you have to specify in what columns should be searched:
+
+  class User < ActiveRecord::Base
+    searchable_on :first_name, :last_name
+  end
+
+
+Now, the <b>search_for</b> scope is available for queries. You should pass a query string to the scope. 
+This can be empty or nil, in which case all no search conditions are set (and all records will be returned).
+
+  User.search_for(params[:q]).each { |project| ... }
+
+
+You can also search on associate models.  This works with <b>belongs_to</b>, <b>has_one</b>, <b>has_many</b>, 
+<b>has_many :through</b>, and <b>HABTM</b>.  For example if a User <b>has_many</b> Notes (title, content, created_at, updated_at)
+
+  class User < ActiveRecord::Base
+    has_many: notes
+    searchable_on :first_name, :last_name, :notes_title, :notes_content
+  end
+
+The search query language is simple. It supports these constructs:
+* <b>words:</b> <tt>some search keywords</tt>
+* <b>phrases:</b> <tt>"a single search phrase"</tt>
+* <b>negation:</b> <tt>"look for this" -"but do not look for this phrase and this" -word</tt>
+* <b>OR words/phrases:</b> word/phrase OR word/phrase.  Example: <tt>"Hello World" OR "Hello Moon"</tt>
+* <b>dates:</b> mm/dd/yyyy, dd/mm/yyyy, yyyy/mm/dd, yyyy-mm-dd
+* <b>date ranges:</b> > date, >= date, < date, <= date, date TO date.  Examples: <tt>> 30/05/1983</tt>, <tt>< 2009-01-30</tt>
+
+This functionality is build on <tt>named_scope</tt>. The searchable_on statement creates 
+a named_scope *search_for*. Because of this, you can actually chain the call with
+other scopes. For example, this can be very useful if you only want to search in 
+projects that are accessible by a given user.
+
+  class Project < ActiveRecord::Base
+    searchable_on :name, :description
+    named_scope :accessible_by, lambda { |user| ... }
+  end
+
+  # using chained named_scopes and will_paginate
+  Project.accessible_by(current_user).search_for(params[:q]).paginate(:page => params[:page], :include => :tasks)
+
+== Additional resources
+
+* Source code: http://github.com/wvanbergen/scoped_search/tree/master
+* Project wiki: http://wiki.github.com/wvanbergen/scoped_search
+* RDoc documentation: http://wvanbergen.github.com/scoped_search
+* wvanbergen's blog posts: http://techblog.floorplanner.com/tag/scoped_search
+
+== License
+
+This plugin is released under the MIT license. Please contact weshays (http://github.com/weshays) 
+or wvanbergen (http://github.com/wvanbergen) for any questions.

data/Rakefile

@@ -0,0 +1,5 @@
+Dir['tasks/*.rake'].each { |file| load(file) }
+ 
+desc 'Default: run unit tests for only sqlite.' 
+task :default => [:test]
+

data/init.rb

@@ -0,0 +1 @@
+require 'scoped_search'

data/lib/scoped_search.rb

@@ -0,0 +1,108 @@
+module ScopedSearch
+  
+  module ClassMethods
+    
+    def self.extended(base) # :nodoc:
+      require 'scoped_search/reg_tokens'
+      require 'scoped_search/query_language_parser'
+      require 'scoped_search/query_conditions_builder'
+    end
+  
+    # Creates a named scope in the class it was called upon.
+    #
+    # fields:: The fields to search on.
+    def searchable_on(*fields)
+      # Make sure that the table to be searched actually exists
+      if self.table_exists?
+        
+        # Get a collection of fields to be searched on.
+        if fields.first.class.to_s == 'Hash'
+          if fields.first.has_key?(:only)
+            # only search on these fields.
+            fields = fields.first[:only]
+          elsif fields.first.has_key?(:except)
+            # Get all the fields and remove any that are in the -except- list.
+            fields = self.column_names.collect { |column| fields.first[:except].include?(column.to_sym) ? nil : column.to_sym }.compact
+          end
+        end
+        
+        # Get an array of associate modules.
+        assoc_models = self.reflections.collect { |key,value| key }
+        
+        # Subtract out the fields to be searched on that are part of *this* model.
+        # Any thing left will be associate module fields to be searched on.
+        assoc_fields = fields - self.column_names.collect { |column| column.to_sym }
+        
+        # Subtraced out the associated fields from the fields so that you are only left
+        # with fields in *this* model.
+        fields -= assoc_fields
+        
+        # Loop through each of the associate models and group accordingly each
+        # associate model field to search.  Assuming the following relations:
+        # has_many :clients
+        # has_many :notes,
+        # belongs_to :user_type 
+        # assoc_groupings will look like
+        # assoc_groupings = {:clients => [:first_name, :last_name],
+        #                    :notes => [:descr],
+        #                    :user_type => [:identifier]}
+        assoc_groupings = {}
+        assoc_models.each do |assoc_model|
+          assoc_groupings[assoc_model] = []
+        	assoc_fields.each do |assoc_field|
+        	  unless assoc_field.to_s.match(/^#{assoc_model.to_s}_/).nil?
+              assoc_groupings[assoc_model] << assoc_field.to_s.sub(/^#{assoc_model.to_s}_/, '').to_sym 
+            end
+          end
+        end
+    
+        # If a grouping does not contain any fields to be searched on then remove it.
+        assoc_groupings = assoc_groupings.delete_if {|group, field_group| field_group.empty?}
+        
+        # Set the appropriate class attributes. 
+        self.cattr_accessor :scoped_search_fields, :scoped_search_assoc_groupings
+        self.scoped_search_fields = fields
+        self.scoped_search_assoc_groupings = assoc_groupings
+        self.named_scope :search_for, lambda { |keywords| self.build_scoped_search_conditions(keywords) }
+      end
+    end
+  
+    # Build a hash that is used for the named_scope search_for.
+    # This function will split the search_string into keywords, and search for all the keywords
+    # in the fields that were provided to searchable_on.
+    #
+    # search_string:: The search string to parse.
+    def build_scoped_search_conditions(search_string)    
+      if search_string.nil? || search_string.strip.blank?
+        return {:conditions => nil}
+      else        
+        query_fields = {}
+        self.scoped_search_fields.each do |field| 
+          field_name = connection.quote_table_name(table_name) + "." + connection.quote_column_name(field)
+          query_fields[field_name] = self.columns_hash[field.to_s].type
+        end
+        
+        assoc_model_indx = 0
+        assoc_fields_indx = 1
+        assoc_models_to_include = []
+        self.scoped_search_assoc_groupings.each do |group|  
+          assoc_models_to_include << group[assoc_model_indx]
+          group[assoc_fields_indx].each do |group_field|
+            field_name = connection.quote_table_name(group[assoc_model_indx].to_s.pluralize) + "." + connection.quote_column_name(group_field)
+            query_fields[field_name] = self.reflections[group[assoc_model_indx]].klass.columns_hash[group_field.to_s].type
+          end
+        end
+        
+        search_conditions = QueryLanguageParser.parse(search_string) 
+        conditions = QueryConditionsBuilder.build_query(search_conditions, query_fields) 
+ 
+        retVal = {:conditions => conditions}
+        retVal[:include] = assoc_models_to_include unless assoc_models_to_include.empty?
+
+        return retVal
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:extend, ScopedSearch::ClassMethods)

data/lib/scoped_search/query_conditions_builder.rb

@@ -0,0 +1,209 @@
+module ScopedSearch
+  
+  class QueryConditionsBuilder
+
+    # Builds the query string by calling the build method on a new instances of QueryConditionsBuilder.
+    def self.build_query(search_conditions, query_fields)
+      self.new.build(search_conditions, query_fields)
+    end
+
+    # Initializes the default class variables.
+    def initialize
+      @query_fields = nil 
+      @query_params = {}
+      
+      @sql_like = 'LIKE'
+      
+      if ActiveRecord::Base.connected? and ActiveRecord::Base.connection.adapter_name.downcase == 'postgresql'
+        @sql_like = 'ILIKE'
+      end
+    end 
+
+
+    # Build the query based on the search conditions and the fields to query.
+    # 
+    # Hash query_options : A hash of fields and field types.
+    #
+    # Example: 
+    #
+    #   search_conditions = [["Wes", :like], ["Hays", :not], ["Hello World", :like], ["Goodnight Moon", :not], 
+    #                       ["Bob OR Wes", :or], ["Happy cow OR Sad Frog", :or], ["Man made OR Dogs", :or], 
+    #                       ["Cows OR Frog Toys", :or], ['9/28/1980, :datetime]]
+    #   query_fields = {:first_name => :string, :created_at => :datetime}
+    #
+    # Exceptons : 
+    #   1) If search_conditions is not an array
+    #   2) If query_fields is not a Hash    
+    def build(search_conditions, query_fields) 
+      raise 'search_conditions must be a hash' unless search_conditions.class.to_s == 'Array'
+      raise 'query_fields must be a hash' unless query_fields.class.to_s == 'Hash'
+      @query_fields = query_fields
+
+      conditions = []
+ 
+      search_conditions.each_with_index do |search_condition, index|
+        keyword_name = "keyword_#{index}".to_sym
+        conditions << case search_condition.last
+                        # :like also handles integers
+                        when :like then like_condition(keyword_name, search_condition.first)
+                        when :not then not_like_condition(keyword_name, search_condition.first)
+            
+                        when :or then or_condition(keyword_name, search_condition.first)
+      
+                        when :less_than_date  then less_than_date(keyword_name, search_condition.first)      
+                        when :less_than_or_equal_to_date then less_than_or_equal_to_date(keyword_name, search_condition.first)   
+                        when :as_of_date then as_of_date(keyword_name, search_condition.first)      
+                        when :greater_than_date then greater_than_date(keyword_name, search_condition.first) 
+                        when :greater_than_or_equal_to_date then greater_than_or_equal_to_date(keyword_name, search_condition.first)   
+                        
+                        when :between_dates then between_dates(keyword_name, search_condition.first)                                                        
+                      end          
+      end
+
+      [conditions.compact.join(' AND '), @query_params] 
+    end    
+    
+    
+    private 
+    
+    def like_condition(keyword_name, value)      
+      retVal = []
+      @query_fields.each do |field, field_type|  #|key,value| 
+        if field_type == :string or field_type == :text
+          @query_params[keyword_name] = "%#{value}%"
+          retVal << "#{field} #{@sql_like} :#{keyword_name.to_s}"
+        end
+        if value.strip =~ /^[0-9]+$/ and (field_type == :int or field_type == :integer)
+          qkey = "#{keyword_name}_#{value.strip}"
+          @query_params[qkey.to_sym] = value.strip.to_i
+          retVal << "#{field} = :#{qkey}"
+        end
+      end
+      "(#{retVal.join(' OR ')})"
+    end
+    
+    def not_like_condition(keyword_name, value)
+      @query_params[keyword_name] = "%#{value}%"
+      retVal = []
+      @query_fields.each do |field, field_type|  #|key,value| 
+        if field_type == :string or field_type == :text
+          retVal << "(#{field} NOT #{@sql_like} :#{keyword_name.to_s} OR #{field} IS NULL)"
+        end
+      end
+      "(#{retVal.join(' AND ')})"
+    end
+    
+    def or_condition(keyword_name, value)
+      retVal = []
+      word1, word2 = value.split(' OR ')
+      keyword_name_a = "#{keyword_name.to_s}a".to_sym
+      keyword_name_b = "#{keyword_name.to_s}b".to_sym
+      @query_params[keyword_name_a] = "%#{word1}%"
+      @query_params[keyword_name_b] = "%#{word2}%"      
+      @query_fields.each do |field, field_type|  #|key,value|       
+        if field_type == :string or field_type == :text
+          retVal << "(#{field} #{@sql_like} :#{keyword_name_a.to_s} OR #{field} #{@sql_like} :#{keyword_name_b.to_s})"
+        end
+        if (word1.strip =~ /^[0-9]+$/ and word2.strip =~ /^[0-9]+$/) and (field_type == :int or field_type == :integer)
+          qkeya = "#{keyword_name}_a_#{word1.strip}"
+          qkeyb = "#{keyword_name}_b_#{word2.strip}"
+          @query_params[qkeya] = word1.strip.to_i
+          @query_params[qkeyb] = word2.strip.to_i
+          retVal << "(#{field} = :#{qkeya} OR #{field} = :#{qkeyb})"   
+        elsif (word1.strip =~ /^[0-9]+$/ or word2.strip =~ /^[0-9]+$/) and (field_type == :int or field_type == :integer)
+          num_word = word1.strip =~ /^[0-9]+$/ ? word1.strip.to_i : word2.strip.to_i
+          qkey = "#{keyword_name}_#{num_word}"
+          @query_params[qkey.to_sym] = num_word
+          retVal << "(#{field} = :#{qkey})"
+        end             
+      end 
+      "(#{retVal.join(' OR ')})"     
+    end
+    
+    def less_than_date(keyword_name, value)
+      helper_date_operation('<', keyword_name, value)     
+    end
+    
+    def less_than_or_equal_to_date(keyword_name, value)
+      helper_date_operation('<=', keyword_name, value)     
+    end    
+    
+    def as_of_date(keyword_name, value)
+      retVal = []
+      begin
+        dt = Date.parse(value) # This will throw an exception if it is not valid
+        @query_params[keyword_name] = dt.to_s
+        @query_fields.each do |field, field_type|  #|key,value| 
+          if field_type == :date or field_type == :datetime or field_type == :timestamp
+            retVal << "#{field} = :#{keyword_name.to_s}"
+          end
+        end
+      rescue
+        # do not search on any date columns since the date is invalid
+        retVal = [] # Reset just in case
+      end
+      
+      # Search the text fields for the date as well as it could be in text.
+      # Also still search on the text columns for an invalid date as it could
+      # have a different meaning.
+      found_text_fields_to_search = false
+      keyword_name_b = "#{keyword_name}b".to_sym      
+      @query_fields.each do |field, field_type|  #|key,value| 
+        if field_type == :string or field_type == :text
+          found_text_fields_to_search = true
+          retVal << "#{field} #{@sql_like} :#{keyword_name_b.to_s}"
+        end
+      end
+      if found_text_fields_to_search
+        @query_params[keyword_name_b] = "%#{value}%"
+      end
+
+      retVal.empty? ? '' : "(#{retVal.join(' OR ')})"      
+    end
+    
+    def greater_than_date(keyword_name, value)
+      helper_date_operation('>', keyword_name, value)
+    end
+    
+    def greater_than_or_equal_to_date(keyword_name, value)
+      helper_date_operation('>=', keyword_name, value)
+    end    
+    
+    def between_dates(keyword_name, value)
+      date1, date2 = value.split(' TO ')      
+      dt1 = Date.parse(date1) # This will throw an exception if it is not valid
+      dt2 = Date.parse(date2) # This will throw an exception if it is not valid
+      keyword_name_a = "#{keyword_name.to_s}a".to_sym
+      keyword_name_b = "#{keyword_name.to_s}b".to_sym 
+      @query_params[keyword_name_a] = dt1.to_s
+      @query_params[keyword_name_b] = dt2.to_s           
+
+      retVal = []
+      @query_fields.each do |field, field_type|  #|key,value| 
+        if field_type == :date or field_type == :datetime or field_type == :timestamp
+          retVal << "(#{field} BETWEEN :#{keyword_name_a.to_s} AND :#{keyword_name_b.to_s})"
+        end
+      end
+      "(#{retVal.join(' OR ')})"  
+    rescue
+      # The date is not valid so just ignore it
+      return nil      
+    end  
+    
+
+    def helper_date_operation(operator, keyword_name, value)
+      dt = Date.parse(value) # This will throw an exception if it is not valid
+      @query_params[keyword_name] = dt.to_s
+      retVal = []
+      @query_fields.each do |field, field_type|  #|key,value| 
+        if field_type == :date or field_type == :datetime or field_type == :timestamp
+          retVal << "#{field} #{operator} :#{keyword_name.to_s}"
+        end
+      end
+      "(#{retVal.join(' OR ')})"  
+    rescue
+      # The date is not valid so just ignore it
+      return nil      
+    end
+  end
+end

data/lib/scoped_search/query_language_parser.rb

@@ -0,0 +1,117 @@
+module ScopedSearch
+  
+  # Used to parse and build the conditions tree for the search.
+  class QueryLanguageParser
+    
+    # Parses the query string by calling the parse_query method on a new instances of QueryLanguageParser.
+    #
+    # query:: The query string to parse.  If nil the all values will be returned (default is nil)
+    #         If the query string is longer then 300 characters then it will be truncated to a 
+    #         length of 300.
+    def self.parse(query)
+      self.new.parse_query(query)
+    end    
+    
+    # Parse the query string.
+    #
+    # query:: The query string to parse.  If nil the all values will be returned (default is nil)
+    #         If the query string is longer then 300 characters then it will be truncated to a 
+    #         length of 300.
+    def parse_query(query = nil)
+      # truncate query string at 300 characters
+      query = query[0...300] if query.length > 300
+      return build_conditions_tree(tokenize(query))
+    end
+    
+    protected
+  
+    # Build the conditions tree based on the tokens found.
+    #
+    # tokens:: An array of tokens.
+    def build_conditions_tree(tokens)
+      conditions_tree = []
+    
+      negate = false
+      tokens.each do |item|
+        case item
+          when :not
+            negate = true
+          else
+            if /^.+[ ]OR[ ].+$/ =~ item
+              conditions_tree << [item, :or]
+            elsif /^#{RegTokens::BetweenDateFormatMMDDYYYY}$/ =~ item or
+                  /^#{RegTokens::BetweenDateFormatYYYYMMDD}$/ =~ item or
+                  /^#{RegTokens::BetweenDatabaseFormat}$/ =~ item
+              conditions_tree << [item, :between_dates]              
+            elsif /^#{RegTokens::GreaterThanOrEqualToDateFormatMMDDYYYY}$/ =~ item or
+                  /^#{RegTokens::GreaterThanOrEqualToDateFormatYYYYMMDD}$/ =~ item or
+                  /^#{RegTokens::GreaterThanOrEqualToDatabaseFormat}$/ =~ item
+              conditions_tree << [item, :greater_than_or_equal_to_date] 
+            elsif /^#{RegTokens::LessThanOrEqualToDateFormatMMDDYYYY}$/ =~ item or
+                  /^#{RegTokens::LessThanOrEqualToDateFormatYYYYMMDD}$/ =~ item or
+                  /^#{RegTokens::LessThanOrEqualToDatabaseFormat}$/ =~ item
+              conditions_tree << [item, :less_than_or_equal_to_date]              
+            elsif /^#{RegTokens::GreaterThanDateFormatMMDDYYYY}$/ =~ item or
+                  /^#{RegTokens::GreaterThanDateFormatYYYYMMDD}$/ =~ item or
+                  /^#{RegTokens::GreaterThanDatabaseFormat}$/ =~ item
+              conditions_tree << [item, :greater_than_date] 
+            elsif /^#{RegTokens::LessThanDateFormatMMDDYYYY}$/ =~ item or
+                  /^#{RegTokens::LessThanDateFormatYYYYMMDD}$/ =~ item or
+                  /^#{RegTokens::LessThanDatabaseFormat}$/ =~ item
+              conditions_tree << [item, :less_than_date]                           
+            elsif /^#{RegTokens::DateFormatMMDDYYYY}$/ =~ item or
+                  /^#{RegTokens::DateFormatYYYYMMDD}$/ =~ item or
+                  /^#{RegTokens::DatabaseFormat}$/ =~ item
+              conditions_tree << [item, :as_of_date]
+            else
+              conditions_tree << (negate ? [item, :not] : [item, :like])
+              negate = false
+            end
+        end
+      end
+
+      return conditions_tree
+    end
+    
+    # Tokenize the query based on the different RegTokens.
+    def tokenize(query)
+      pattern = [RegTokens::BetweenDateFormatMMDDYYYY,
+                 RegTokens::BetweenDateFormatYYYYMMDD,
+                 RegTokens::BetweenDatabaseFormat,
+                 RegTokens::GreaterThanOrEqualToDateFormatMMDDYYYY,
+                 RegTokens::GreaterThanOrEqualToDateFormatYYYYMMDD,
+                 RegTokens::GreaterThanOrEqualToDatabaseFormat,
+                 RegTokens::LessThanOrEqualToDateFormatMMDDYYYY,
+                 RegTokens::LessThanOrEqualToDateFormatYYYYMMDD,
+                 RegTokens::LessThanOrEqualToDatabaseFormat,
+                 RegTokens::GreaterThanDateFormatMMDDYYYY,
+                 RegTokens::GreaterThanDateFormatYYYYMMDD,
+                 RegTokens::GreaterThanDatabaseFormat,
+                 RegTokens::LessThanDateFormatMMDDYYYY,
+                 RegTokens::LessThanDateFormatYYYYMMDD,
+                 RegTokens::LessThanDatabaseFormat,
+                 RegTokens::DateFormatMMDDYYYY,
+                 RegTokens::DateFormatYYYYMMDD,
+                 RegTokens::DatabaseFormat,           
+                 RegTokens::WordOrWord,
+                 RegTokens::WordOrString,
+                 RegTokens::StringOrWord,
+                 RegTokens::StringOrString,
+                 RegTokens::PossiblyNegatedWord,
+                 RegTokens::PossiblyNegatedString]               
+      pattern = Regexp.new(pattern.join('|'))
+      
+      tokens = []
+      matches = query.scan(pattern).flatten.compact
+      matches.each { |match|
+        tokens << :not if match.index('-') == 0
+        # Remove any escaped quotes
+        # Remove any dashes preceded by a space or at the beginning of a token
+        # Remove any additional spaces - more that one.
+        cleaned_token = match.gsub(/"/,'').gsub(/^-| -/,'').gsub(/[ ]{2,}/, ' ')
+        tokens << cleaned_token if cleaned_token.length > 0
+      }
+      return tokens
+    end
+  end
+end