pg_search 0.0.2

data/.autotest

@@ -0,0 +1,5 @@
+Autotest.add_hook :initialize do |at|
+  at.add_mapping(%r%^lib/.*\.rb$%, true) { |filename, _|
+    at.files_matching %r%^spec/.*_spec.rb$%
+  }
+end

data/.gitignore

@@ -0,0 +1,7 @@
+pkg/*
+*.gem
+.bundle
+.idea
+tags
+*~
+gemfiles/**/Gemfile.lock

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ree@pg_search

data/CHANGELOG

@@ -0,0 +1,7 @@
+### 0.0.2
+
+Fix gem ownership.
+
+### 0.0.1
+
+Initial release.

data/Gemfile

@@ -0,0 +1,5 @@
+puts <<-MESSAGE
+This project uses multiple Gemfiles in subdirectories of ./gemfiles.
+The rake tasks automatically install these bundles as necessary. See rake -T.
+MESSAGE
+exit 1

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010-11 Case Commons, LLC
+
+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,290 @@
+= pg_search
+
+* http://github.com/casecommons/pg_search/
+
+== DESCRIPTION:
+
+PgSearch builds named scopes that take advantage of PostgreSQL's full text search
+
+== INSTALL:
+
+ gem install pg_search
+
+=== Rails 3
+
+In Gemfile
+
+ gem 'pg_search'
+
+=== Rails 2
+
+In environment.rb
+
+ config.gem 'pg_search'
+
+In Rakefile
+
+ require 'rubygems'
+ require 'pg_search/tasks'
+
+== USAGE
+
+To add PgSearch to an ActiveRecord model, simply include the PgSearch module.
+
+ class Shape < ActiveRecord::Base
+   include PgSearch
+ end
+
+=== pg_search_scope
+
+You can use pg_search_scope to build a search scope. The first parameter is a scope name, and the second parameter is an options hash. The only required option is :against, which tells pg_search_scope which column or columns to search against.
+
+==== Searching against one column
+
+To search against a column, pass a symbol as the :against option.
+
+ class BlogPost < ActiveRecord::Base
+   include PgSearch
+   pg_search_scope :search_by_title, :against => :title
+ end
+
+We now have an ActiveRecord scope named search_by_title on our BlogPost model. It takes one parameter, a search query string.
+
+ BlogPost.create!(:title => "Recent Developments in the World of Pastrami")
+ BlogPost.create!(:title => "Prosciutto and You: A Retrospective")
+ BlogPost.search_by_title("pastrami") # => [#<BlogPost id: 2, title: "Recent Developments in the World of Pastrami">]
+
+==== Searching against multiple columns
+
+Just pass an Array if you'd like to search more than one column.
+
+ class Person < ActiveRecord::Base
+   include PgSearch
+   pg_search_scope :search_by_full_name, :against => [:first_name, :last_name]
+ end
+
+Now our search query can match either or both of the columns.
+
+ person_1 = Person.create!(:first_name => "Grant", :last_name => "Hill")
+ person_2 = Person.create!(:first_name => "Hugh", :last_name => "Grant")
+
+ Person.search_by_full_name("Grant") # => [person_1, person_2]
+ Person.search_by_full_name("Grant Hill") # => [person_1]
+
+==== Dynamic search scopes
+
+Just like with Active Record named scopes, you can pass in a Proc object that returns a hash of options. For instance, the following scope takes a parameter that dynamically chooses which column to search against.
+
+Important: The returned hash must include a :query key. Its value does not necessary have to be dynamic. You could choose to hard-code it to a specific value if you wanted.
+
+ class Person < ActiveRecord::Base
+   include PgSearch
+   pg_search_scope :search_by_name, lambda do |name_part, query|
+     raise ArgumentError unless [:first, :last].include?(name_part)
+     {
+       :against => name_part,
+       :query => query
+     }
+   end
+ end
+
+ person_1 = Person.create!(:first_name => "Grant", :last_name => "Hill")
+ person_2 = Person.create!(:first_name => "Hugh", :last_name => "Grant")
+
+ Person.search_by_name :first, "Grant" # => [person_1]
+ Person.search_by_name :last, "Grant" # => [person_2]
+
+==== Searching through associations
+
+You can pass a Hash into the :associated_against option to search columns on other models. The keys are the names of the associations and the value works just like an :against option for the other model.
+
+  class Cracker < ActiveRecord::Base
+  end
+
+  class Cheese < ActiveRecord::Base
+    has_many :cheeses
+  end
+
+  class Salami < ActiveRecord::Base
+    include PgSearch
+
+    belongs_to :cracker
+    has_many :cheeses, :through => :cracker
+
+    pg_search_scope :tasty_search, :associated_against => {
+      :cheeses => [:kind, :brand],
+      :cracker => :kind
+    }
+  end
+
+  salami_1 = Salami.create!
+  salami_2 = Salami.create!
+  salami_3 = Salami.create!
+
+  limburger = Cheese.create!(:kind => "Limburger")
+  brie = Cheese.create!(:kind => "Brie")
+  pepper_jack = Cheese.create!(:kind => "Pepper Jack")
+
+  Cracker.create!(:kind => "Black Pepper", :cheeses => [brie], :salami => salami_1)
+  Cracker.create!(:kind => "Ritz", :cheeses => [limburger, pepper_jack], :salami => salami_2)
+  Cracker.create!(:kind => "Graham", :cheeses => [limburger], :salami => salami_3)
+
+  Salami.tasty_search("pepper") # => [salami_1, salami_2]
+
+=== Searching using different search features
+
+By default, pg_search_scope uses the built-in {PostgreSQL text search}[http://www.postgresql.org/docs/current/static/textsearch-intro.html]. If you pass the :features option to pg_search_scope, you can choose alternative search techniques.
+
+  class Beer < ActiveRecord::Base
+    include PgSearch
+    pg_search_scope :against => :name, :features => [:tsearch, :trigram, :dmetaphone]
+  end
+
+The currently implemented features are
+
+* :tsearch - {Full text search}[http://www.postgresql.org/docs/current/static/textsearch-intro.html] (built-in with 8.3 and later, available as a contrib package for some earlier versions)
+* :trigram - {Trigram search}[http://www.postgresql.org/docs/current/static/pgtrgm.html], which requires the trigram contrib package
+* :dmetaphone - {Double Metaphone search}[http://www.postgresql.org/docs/9.0/static/fuzzystrmatch.html#AEN120188], which requires the fuzzystrmatch contrib package
+
+==== :tsearch (Full Text Search)
+
+PostgreSQL's built-in full text search supports weighting, prefix searches, and stemming in multiple languages.
+
+===== Weighting
+Each searchable column can be given a weight of "A", "B", "C", or "D". Columns with earlier letters are weighted higher than those with later letters. So, in the following example, the title is the most important, followed by the subtitle, and finally the content.
+
+ class NewsArticle < ActiveRecord::Base
+   include PgSearch
+   pg_search_scope :against => {
+     :title => 'A',
+     :subtitle => 'B',
+     :content => 'C'
+   }
+ end
+
+You can also pass the weights in as an array of arrays, or any other structure that responds to #each and yields either a single symbol or a symbol and a weight. If you omit the weight, a default will be used.
+
+ class NewsArticle < ActiveRecord::Base
+   include PgSearch
+   pg_search_scope :against => [
+     [:title, 'A'],
+     [:subtitle, 'B'],
+     [:content, 'C']
+   ]
+ end
+
+ class NewsArticle < ActiveRecord::Base
+   include PgSearch
+   pg_search_scope :against => [
+     [:title, 'A'],
+     {:subtitle => 'B'},
+     :content
+   ]
+ end
+
+===== :prefix
+
+PostgreSQL's full text search matches on whole words by default. If you want to search for partial words, however, you can set :prefix to true. Since this is a :tsearch-specific option, you should pass it to :tsearch directly, as shown in the following example.
+
+  class Superhero < ActiveRecord::Base
+    include PgSearch
+    pg_search_scope :whose_name_starts_with,
+                    :against => :name,
+                    :using => {
+                      :tsearch => {:prefix => true}
+                    }
+  end
+
+  batman = Superhero.create :name => 'Batman'
+  batgirl = Superhero.create :name => 'Batgirl'
+  robin = Superhero.create :name => 'Robin'
+
+  Superhero.whose_name_starts_with("Bat") # => [batman, batgirl]
+
+===== :dictionary
+
+PostgreSQL full text search also support multiple dictionaries for stemming. The default dictionary depends on your PostgreSQL setup. You can learn more about how dictionaries work by reading the {PostgreSQL documention}[http://www.postgresql.org/docs/current/static/textsearch-dictionaries.html]. If you use one of the language dictionaries, such as "english", then variants of words (e.g. "jumping" and "jumped") will match each other. If you don't want stemming, you should pick the "simple" dictionary which does not do any stemming.
+
+  class BoringTweet < ActiveRecord::Base
+    include PgSearch
+    pg_search_scope :kinda_matching,
+                    :against => :text,
+                    :using => {
+                      :tsearch => {:dictionary => "english"}
+                    }
+    pg_search_scope :literally_matching,
+                    :against => :text,
+                    :using => {
+                      :tsearch => {:dictionary => "simple"}
+                    }
+  end
+
+  sleepy = BoringTweet.create! :text => "I snoozed my alarm for fourteen hours today. I bet I can beat that tomorrow! #sleepy"
+  sleeping = BoringTweet.create! :text => "You know what I like? Sleeping. That's what. #enjoyment"
+  sleeper = BoringTweet.create! :text => "Have you seen Woody Allen's movie entitled Sleeper? Me neither. #boycott"
+
+  BoringTweet.kinda_matching("sleeping") # => [sleepy, sleeping, sleeper]
+  BoringTweet.literally_matching("sleeping") # => [sleeping]
+
+==== :dmetaphone (Double Metaphone soundalike search)
+
+{Double Metaphone}[http://en.wikipedia.org/wiki/Double_Metaphone] is an algorithm for matching words that sound alike even if they are spelled very differently. For example, "Geoff" and "Jeff" sound identical and thus match. Currently, this is not a true double-metaphone, as only the first metaphone is used for searching.
+
+Double Metaphone support is currently available as part of the {fuzzystrmatch contrib package}[http://www.postgresql.org/docs/current/static/fuzzystrmatch.html] that must be installed before this feature can be used. In addition to the contrib package, you must install a utility function into your database. To generate a migration for this, add the following line to your Rakefile:
+
+  include "pg_search/tasks"
+
+and then run:
+
+  $ rake pg_search:migration:dmetaphone
+
+The following example shows how to use :dmetaphone.
+
+  class Word < ActiveRecord::Base
+    include PgSearch
+    pg_search_scope :that_sounds_like,
+                    :against => :spelling,
+                    :using => :dmetaphone
+  end
+
+  four = Word.create! :spelling => 'four'
+  far = Word.create! :spelling => 'far'
+  fur = Word.create! :spelling => 'fur'
+  five = Word.create! :spelling => 'five'
+
+  Word.that_sounds_like("fir") # => [four, far, fur]
+
+==== :trigram (Trigram search)
+
+Trigram search works by counting how many three-letter substrings (or "trigrams") match between the query and the text. For example, the string "Lorem ipsum" can be split into the following trigrams:
+
+  [" Lo", "Lor", "ore", "rem", "em ", "m i", " ip", "ips", "psu", "sum", "um ", "m  "]
+
+Trigram search has some ability to work even with typos and misspellings in the query or text.
+
+Trigram support is currently available as part of the {pg_trgm contrib package}[http://www.postgresql.org/docs/current/static/pgtrgm.html] that must be installed before this feature can be used.
+
+
+  class Website < ActiveRecord::Base
+    include PgSearch
+    pg_search_scope :kinda_spelled_like,
+                    :against => :name,
+                    :using => :trigram
+  end
+
+  yahooo = Website.create! :name => "Yahooo!"
+  yohoo = Website.create! :name => "Yohoo!"
+  gogle = Website.create! :name => "Gogle"
+  facebook = Website.create! :name => "Facebook"
+
+  Website.kinda_spelled_like("Yahoo!") # => [yahooo, yohoo]
+
+== REQUIREMENTS
+
+* ActiveRecord 2 or 3
+* Postgresql
+* Postgresql contrib modules for certain features
+
+== LICENSE:
+
+MIT

data/Rakefile

@@ -0,0 +1,35 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task :default => :spec
+
+environments = %w[rails2 rails3]
+
+in_environment = lambda do |environment, command|
+  sh %Q{export BUNDLE_GEMFILE="gemfiles/#{environment}/Gemfile"; bundle --quiet update && bundle exec #{command}}
+end
+
+in_all_environments = lambda do |command|
+  environments.each do |environment|
+    puts "\n---#{environment}---\n"
+    in_environment.call(environment, command)
+  end
+end
+
+desc "Run all specs against ActiveRecord 2 and 3"
+task "spec" do
+  in_all_environments.call('rspec spec')
+end
+
+task "doc" do
+  in_environment.call("rails3", "rspec --format d spec")
+end
+
+namespace "autotest" do
+  environments.each do |environment|
+    desc "Run autotest in #{environment}"
+    task environment do
+      in_environment.call(environment, 'autotest -s rspec2')
+    end
+  end
+end

data/TODO

@@ -0,0 +1,12 @@
+ * Railtie for rake tasks
+ * README
+ * Tracker project
+ * Mailing list
+ * License
+ * Publish gem
+ * Exceptions for missing trigram, dmetaphone, etc. support
+ * LIKE search
+ * ability to specify multiple ranks: :ranked_by => [:tsearch, :trigram]
+ * ability to mix ranks together with weights: :ranked_by => {:tsearch => 1.0, :trigram => 0.5}
+ * accept a block and pass it to the underlying scope
+ * ability to search again a tsvector column

data/gemfiles/Gemfile.common

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+gem "pg"
+
+group :test do
+  gem "rspec"
+  gem "autotest"
+  gem "with_model", '0.1'
+end

data/gemfiles/rails2/Gemfile

@@ -0,0 +1,4 @@
+filename = File.join(File.dirname(__FILE__), '..', 'Gemfile.common')
+eval(File.read(filename), binding, filename, 1)
+
+gem "activerecord", "~>2.3.5"

data/gemfiles/rails3/Gemfile

@@ -0,0 +1,4 @@
+filename = File.join(File.dirname(__FILE__), '..', 'Gemfile.common')
+eval(File.read(filename), binding, filename, 1)
+
+gem "activerecord", "~>3.0.1"

data/lib/pg_search.rb

@@ -0,0 +1,32 @@
+require "active_record"
+require "pg_search/configuration"
+require "pg_search/features"
+require "pg_search/normalizer"
+require "pg_search/scope"
+require "pg_search/scope_options"
+require "pg_search/version"
+#require "pg_search/railtie" if defined?(Rails) && defined?(Rails::Railtie)
+
+module PgSearch
+  def self.included(base)
+    base.send(:extend, ClassMethods)
+  end
+
+  module ClassMethods
+    def pg_search_scope(name, options)
+      scope = PgSearch::Scope.new(name, self, options)
+      scope_method =
+        if respond_to?(:scope) && !protected_methods.include?('scope')
+          :scope # ActiveRecord 3.x
+        else
+          :named_scope # ActiveRecord 2.x
+        end
+
+      send(scope_method, name, scope.to_proc)
+    end
+  end
+
+  def rank
+    attributes['pg_search_rank'].to_f
+  end
+end