easy_search 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2766cdc5f1074ec9e13036fb2c2fede256a7a23f
+  data.tar.gz: 1d00907cd274a6edf63fc6eac697bcc6b9b6d701
+SHA512:
+  metadata.gz: 1ce0fa34e0dcd8377e7c9b91cfab9ff444cc33b42b6b66f7d5ced39be59933141bcecc6743acc90873aa5e145e15e793a85d24ab4f2623521ffd271ac7a0d7d5
+  data.tar.gz: c40f743b06954e8e84bd41cde5ea1ef25fea83a3e65e4a7dec541969d0bd8f2ecfabdf330de42909fab1885fce07529de81a151aa56af9436326eb70effcd89c

data/.gitignore

@@ -0,0 +1,5 @@
+coverage
+rdoc*
+rdoc/*
+.DS_Store
+pkg

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in easy_search.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Ryan Heath
+
+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.textile

@@ -0,0 +1,124 @@
+h1. EasySearch
+
+Easy search provides a convenient DSL for quickly searching your @ActiveRecord@ models.
+
+h2. What It's NOT
+
+Firstly, let's just get this out of the way. EasySearch is _not_ intended for search-intensive or high-performance applications. There are plenty of other (awesome) full-text plugins for that (e.g. acts_as_ferret, sphinx/ultrasphinx, etc). It's just an easy, quick-n-dirty search for your @ActiveRecord@ models. So if you're looking for a search solution to hunt through your 10 million record database, please, leave now while you still can.
+
+h2. So, Why Build it?
+
+Honestly? Because building a DSL interface to a simple thing is fun. It's actually a lot of fun. Also, I think it's a reasonable place to start for creating something bigger. Overall, this plugin is more-or-less the result of me toying around with the dynamism of Ruby :-)
+
+h2. Installation
+
+You can install this as a Rails plugin. Navigate to your project root and type:
+
+<pre><code>git clone git://github.com/rpheath/easy_search.git vendor/plugins/easy_search</code></pre>
+
+Use it at your own risk. You've been warned.
+
+h2. General Use Case
+
+Again, please don't attempt to use this if you'll be searching giant databases, as I'd imagine you would need something performance aware, which this is _not_. But. It should work fine for hundreds, thousands, maybe even tens-of-thousands of records. You know, like blogs, small forums, etc.
+
+h3. Configuration
+
+In config/initializers/easy_search_setup.rb (or config/environment.rb if you aren't running Rails 2.0+), you'd do something like this:
+
+<pre><code>
+EasySearch::Setup.config do
+  setup_tables do
+    users    :first_name, :last_name, :email, :login
+    projects :title, :description
+    comments :name, :body
+    groups   :name, :description
+  end
+end
+</code></pre>
+
+The @setup_tables@ method allows you to specify which columns should be searched for each one of your tables. It's required if you want to use @EasySearch@ with one of your models. Otherwise, @EasySearch@ wouldn't have a clue what to do with your keywords.
+
+And of course, should you try to search a model that has not been configured, @EasySearch@ will let you know :-)
+
+h2. Examples
+
+We'll go straight into it. First thing, you install the plugin. Then you add a generic class and give it the @EasySearch@ functionality. Like so:
+
+<pre><code>
+# app/models/search.rb
+class Search
+  include EasySearch
+end
+</pre></code>
+
+Now we have a @Search@ class that can easily handle search your @ActiveRecord@ models! Notice how this class _does not_ descend from @ActiveRecord@.
+
+h3. Usage
+
+In words, let's say we want to "search the users table with 'ryan heath'". To represent that in code, it's basically the same thing:
+
+<pre><code>
+$> Search.users.with('ryan heath')
+$> => [<#User ...>]
+
+$> Search.projects.with('webdesign')
+$> => [<#Project ...>, <#Project ...>, ...]
+</code></pre>
+
+Note: the above will not compare 'ryan heath' with each of the configured columns, but it will compare 'ryan' and 'heath' separately against each of those columns for better results. Another thing worthy of mention about keyword splitting: it's slightly more sophisticated, in that it will strip out the dull keywords that would return innaccurate results, which also helps performance. For instance:
+
+You can also search by an exact phrase. Let's say you wanted to support a search for '"ryan heath"', where you didn't want EasySearch to search "ryan" and "heath" separately. Well, all you have to do is tell your users to wrap their search terms in quotes (just like Google) and EasySearch will know to search that phrase, in that order, without splitting up the words.
+
+<pre><code>Search.users.with('ryan and a term')</code></pre>
+
+That would only search 'ryan' and 'term' against your columns. @EasySearch@ tries to be somewhat smart about what it searches. And in fact, you can see what @EasySearch@ considers "dull keywords" by doing:
+
+<pre><code>
+# default dull keywords (this is just an example)
+$> EasySearch::Setup.dull_keywords
+$> => ['a', 'and', 'the']
+</code></pre>
+
+The list is _far from complete_. So if you have words that you'd like to add to the "dull keywords" list (meaning words that would not be searched), you can do so quite easily. Going back to the @Setup.config@ block:
+
+<pre><code>
+EasySearch::Setup.config do
+  strip_keywords do
+    ['what', 'then', 'if', 'is', 'it']
+  end
+end
+
+# dull_keywords is now a sum of the defaults plus your custom keywords
+$> EasySearch::Setup.dull_keywords
+$> => ['a', 'and', 'the', 'what', 'then', 'if', 'is', 'it']
+</code></pre>
+
+Those keywords are appended to the existing list (all duplicates are removed). And if you'd rather your custom list replace the existing defaults entirely, just pass 'true' to the @strip_keywords@ method, like so:
+
+<pre><code>
+EasySearch::Setup.config do
+  strip_keywords(true) do
+    ['what', 'then', 'if', 'is', 'it']
+  end
+end
+
+# dull_keywords is now only your custom keywords
+$> EasySearch::Setup.dull_keywords
+$> => ['what', 'then', 'if', 'is', 'it']
+</code></pre>
+
+And finally, if you have additional conditions that you need to apply to all search results, just use a :conditions option on the @with@ method, like so:
+
+<pre><code>
+$> Search.users.with('ryan heath', :conditions => 'active => 1')
+$> # active users matching 'ryan' and/or 'heath'
+</code></pre>
+
+Pretty easy, huh?
+
+Again, this plugin is not meant for searching high-volume Databases. It doesn't handle indexing or any of the other things a full-text solution might handle. But it was a fun plugin to write, and it's a fun API/DSL to use, and that's why I wrote it.
+
+h2. License
+
+Copyright (c) 2008 Ryan Heath, released under the MIT license

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "easy_search"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/easy_search.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'easy_search/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "easy_search"
+  spec.version       = EasySearch::VERSION
+  spec.authors       = ["Ryan Heath"]
+  spec.email         = ["ryan@rpheath.com"]
+
+  spec.summary       = %q{A small DSL for simple searches.}
+  spec.description   = %q{A small Ruby library that provides a DSL for simple LIKE searches.}
+  spec.homepage      = "http://www.github.com/rpheath/easy_search"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+end

data/lib/easy_search.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'easy_search/core')

data/lib/easy_search/constants.rb

@@ -0,0 +1,15 @@
+module EasySearch
+  require 'ostruct'
+  
+  # holds any regexp constants when dealing with search terms
+  Regex = OpenStruct.new(
+    :email => /(\w+@[a-zA-Z_]+?\.[a-zA-Z]{2,6})/
+  )
+  
+  Defaults = OpenStruct.new(
+    # these keywords will be removed from any search terms, as they
+    # provide no value and just increase the size of the query.
+    # (the idea is a small attempt to be as efficient as possible)
+    :dull_keywords => ['a', 'the', 'and', 'or', 'what', 'then', 'if', 'is', 'it']
+  )
+end

data/lib/easy_search/core.rb

@@ -0,0 +1,134 @@
+%w(constants errors setup validations version).each do |f| 
+  require File.join(File.dirname(__FILE__), f)
+end
+
+module EasySearch
+  def self.included(base)
+    base.send(:extend,  ClassMethods)
+    base.send(:include, InstanceMethods)
+    
+    # before continuing, validate that the models identified (if any) in the 
+    # setup_tables block (within `Setup.config') exist and are valid ActiveRecord descendants
+    Validations.validate_settings!
+  end
+  
+  module ClassMethods
+    # "Search.users" translates to "User.find" dynamically
+    def method_missing(name, *args)
+      # instantiate a new instance of self with
+      # the @klass set to the missing method
+      self.new(name.to_sym)
+    end
+  end
+  
+  module InstanceMethods
+    def initialize(klass)
+      @klass = klass
+      
+      # validate that the class derived from the missing method descends from
+      # ActiveRecord and has been "configured" in `Setup.config { setup_tables {...} }'
+      # (i.e. "Search.userz.with(...)" where "userz" is an invalid model)
+      Validations.validate_class!(@klass)
+    end
+    
+    # used to collect/parse the keywords that are to be searched, and return
+    # the search results (hands off to the Rails finder)
+    #
+    # Example:
+    #   Search.users.with("ryan heath")
+    #   # => <#User ... > or []
+    def with(keywords, options={})
+      search_terms = keywords.match(/"(.+)"/) ? extract($1, :exact => true) : extract(keywords)
+      return [] if search_terms.blank?
+      
+      klass = to_model(@klass)
+      
+      conditions = "(#{build_conditions_for(search_terms)})"
+      conditions << " AND (#{options[:conditions]})" unless options[:conditions].blank?
+      sanitized_sql_conditions = klass.send(:sanitize_sql_for_conditions, conditions)
+
+      options = { :select => 'DISTINCT *', :conditions => sanitized_sql_conditions, :order => options[:order], :limit => options[:limit] }
+      options.update :include => associations_to_include
+      klass.find(:all, options)
+    end
+    
+    private
+      # constructs the conditions for the WHERE clause in the SQL statement.
+      # (compares each search term against each configured column for that model)
+      #
+      # ultimately this allows for a single query rather than several small ones,
+      # alleviating the need to open/close DB connections and instantiate multiple
+      # ActiveRecord objects through the loop
+      #
+      # it should be noted that a search with too many keywords against too many columns
+      # in a DB with too many rows will inevitably hurt performance (use ultrasphinx!)
+      def build_conditions_for(terms)
+        klass = to_model(@klass)
+        
+        [].tap do |clause|
+          Setup.table_settings[@klass].each do |column|
+            # handle search associated objects
+            if Hash === column
+              column.each do |association, columns|
+                reflection = klass.reflect_on_association(association.to_sym)
+                next unless reflection
+                model = reflection.class_name.constantize
+                columns.each do |associated_column|
+                  clause << build_conditions_for_terms_on_model(model, associated_column, terms)
+                end  
+              end
+            else
+              clause << build_conditions_for_terms_on_model(klass, column, terms)
+            end  
+          end
+        end.flatten.join(" OR ")
+    	end
+    	
+    	def build_conditions_for_terms_on_model(klass, column, terms)
+        terms.inject([]) do |clause, term|
+          if klass.columns.map(&:name).include?(column.to_s)
+            clause << "`#{klass.table_name}`.`#{column}` LIKE '%#{term}%'"
+          end
+        end
+    	end
+    	
+    	def associations_to_include
+      	Setup.table_settings[@klass].collect do |e| 
+      	  Hash === e ? e.keys : nil
+      	end.compact || []
+      end	
+      
+      # using scan(/\w+/) to parse the words
+      #
+      # emails were being separated (split on the "@" symbol since it's not a word) 
+      # so "rheath@test.com" became ["rheath", "test.com"] as search terms, when we 
+      # really want to keep emails intact. as a work around, the emails are pulled out before 
+      # the words are scanned, then each email is pushed back into the array as its own criteria.
+      #
+      # TODO: refactor this method to be less complex for such a simple problem.
+      def extract(terms, options={})
+        return [terms] if options.delete(:exact)
+        
+        terms.gsub!("'", "")
+        emails = strip_emails_from(terms)
+        
+        keywords = unless emails.blank?            
+          emails.inject(terms.gsub(Regex.email, '').scan(/\w+/)) { |t, email| t << email }
+        else
+          terms.scan(/\w+/)
+        end
+        
+        return (keywords.collect { |k| k.downcase } - Setup.dull_keywords.collect { |k| k.downcase })
+    	end
+           
+      # extracts the emails from the keywords
+      def strip_emails_from(text)
+    	  text.split.reject { |t| t.match(Regex.email) == nil }
+    	end
+    	
+    	# converts the symbol representation of a table to an actual ActiveRecord model
+    	def to_model(klass)
+    	  klass.to_s.singularize.classify.constantize
+    	end
+  end
+end

data/lib/easy_search/errors.rb

@@ -0,0 +1,25 @@
+module EasySearch
+  class Error < RuntimeError
+    def self.message(msg=nil); msg.nil? ? @message : self.message = msg; end
+    def self.message=(msg); @message = msg; end
+  end
+  
+  # raised when a model is attempted to be configured, but doesn't exist
+  class NoModelError < Error
+    message "you've specified a model that doesn't exist"; end
+    
+  # raised when any model (consant) is derived from the `Setup.config' block
+  # and is not a subclass of ActiveRecord::Base
+  class InvalidActiveRecordModel < Error
+    message "all models specified in `Setup.config' must descend from ActiveRecord"; end
+    
+  # raised when a model has not been configured, but is attempted to be searched
+  # (each model used with EasySearch has to be configured, meaning, the columns
+  #  to be searched for that model must be set)
+  class InvalidSettings < Error
+    message "you must specify all Models and the fields to search for each Model in the `Setup.config' block"; end
+  
+  # raised when block passed to `Setup.strip_keywords' does not evaluate as an instance of Array
+  class InvalidDullKeywordsType < Error
+    message "specified keywords must be of type Array in the `Setup.strip_keywords' block"; end
+end

data/lib/easy_search/setup.rb

@@ -0,0 +1,87 @@
+module EasySearch
+  class Setup
+    class << self
+      # returns a hash with the keys as the models to be searched
+      # and the values as arrays of columns for the respective model
+      #
+      # Example:
+      #   $> Setup.settings
+      #   $> => {"users"=>[:first_name, :last_name, :email], "projects"=>[:title, :description]}
+      def table_settings
+        @@table_settings ||= HashWithIndifferentAccess.new
+      end
+      
+      # returns an array of keywords that serve as no benefit in a search
+      #
+      # Example:
+      #   $> Setup.dull_keywords
+      #   $> => ['a', 'and', 'but', 'the', ...]
+      def dull_keywords
+        (@@dull_keywords ||= Defaults.dull_keywords).flatten.uniq
+      end
+      
+      # accepts a block that specifies the columns
+      # to search for each model
+      #
+      # Example:
+      #   Setup.config do
+      #     setup_tables   { ... }
+      #     strip_keywords { ... }
+      #   end
+      def config(&block)
+        return nil unless block_given?
+        self.class_eval(&block)
+      end
+      
+      # REQUIRED
+      # accepts a block that specifies the columns
+      # to search for each model
+      #
+      # Example:
+      #   setup_tables do
+      #     users    :first_name, :last_name, :email
+      #     projects :title, :description
+      #   end
+      def setup_tables(&block)
+        return nil unless block_given?
+        self.class_eval(&block)
+        self.table_settings          
+      end
+      
+      # OPTIONAL 
+      # allows customization of the dull_keywords setting
+      # (can be overwritten or appended)
+      #
+      # Example:
+      #   DEFAULT_DULL_KEYWORDS = ['the', 'and', 'is']
+      # 
+      #  1) appending keywords to the default list
+      #     strip_keywords do
+      #       ['it', 'why', 'is']
+      #     end
+      #     # => ['the', 'and', 'it', 'why', 'is']
+      #
+      #  2) overwriting existing keywords
+      #     strip_keywords(true) do
+      #       ['something', 'whatever']
+      #     end
+      #     # => ['something', 'whatever']
+      def strip_keywords(overwrite=false, &block)
+        return nil unless block_given?
+        raise(InvalidDullKeywordsType, InvalidDullKeywordsType.message) unless block.call.is_a?(Array)
+        
+        overwrite ? @@dull_keywords = block.call : @@dull_keywords = (self.dull_keywords << block.call)
+        self.dull_keywords
+      end
+      
+      # this is the magic that makes `setup_tables' work like it does.
+      # once the block is eval'd those missing methods (i.e. "users" and "projects")
+      # will be caught here and the table_settings hash will be updated with the
+      # key set to the table, and the value set to the columns. this is what allows the
+      # EasySearch plugin to work generically for any rails application.
+      def method_missing(table, *columns)
+        table_settings[table] = columns
+      end
+    end
+  end
+end

data/lib/easy_search/validations.rb

@@ -0,0 +1,39 @@
+module EasySearch
+  class Validations
+    # called once the EasySearch module is included.
+    #
+    # it ensures that any/all models in the settings hash exist
+    # and decend from ActiveRecord::Base
+    def self.validate_settings!
+      unless Setup.table_settings.blank?
+        Setup.table_settings.keys.each do |klass|
+          unless klass.to_s.classify.constantize.ancestors.include?(ActiveRecord::Base)
+            raise( InvalidActiveRecordModel, InvalidActiveRecordModel.message )
+          end
+        end
+      end
+    rescue NameError
+      raise $!
+      raise( NoModelError, "you've specified a table in your `Setup.config' block that doesn't exist" )
+    end
+    
+    # called when a new EasySearch containing class is instantiated.
+    #
+    # For example, `Search.users.with("ryan heath")' would instantiate a
+    # new Search, setting the "users" part to the @klass variable.
+    # the following would ensure that the @klass variable is indeed valid.
+    def self.validate_class!(klass)
+      raise( InvalidActiveRecordModel, InvalidActiveRecordModel.message ) unless valid_model?(klass)
+  	  raise( InvalidSettings, InvalidSettings.message ) unless model_has_settings?(klass)
+    end
+  	
+  	private
+  	  def self.valid_model?(klass)
+    	  klass.to_s.singularize.classify.constantize.ancestors.include?(ActiveRecord::Base) rescue false
+    	end
+  	
+    	def self.model_has_settings?(klass)
+    	  !Setup.table_settings[klass].blank? rescue false
+    	end
+  end
+end

data/lib/easy_search/version.rb

@@ -0,0 +1,3 @@
+module EasySearch
+  VERSION = "0.1.0"
+end

data/tasks/easy_search_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :easy_search do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: easy_search
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ryan Heath
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-06-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A small Ruby library that provides a DSL for simple LIKE searches.
+email:
+- ryan@rpheath.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.textile
+- Rakefile
+- bin/console
+- bin/setup
+- easy_search.gemspec
+- lib/easy_search.rb
+- lib/easy_search/constants.rb
+- lib/easy_search/core.rb
+- lib/easy_search/errors.rb
+- lib/easy_search/setup.rb
+- lib/easy_search/validations.rb
+- lib/easy_search/version.rb
+- tasks/easy_search_tasks.rake
+homepage: http://www.github.com/rpheath/easy_search
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A small DSL for simple searches.
+test_files: []