buscando_el_viento 0.0.1

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.8.7-p334@buscando_el_viento

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+# migrations
+gem 'activerecord', '3.1.0.rc1'
+
+# specs
+gem 'rake', '0.8.7'
+gem 'rspec'
+
+# nfi
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    buscando_el_viento (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.1.0.rc1)
+      activesupport (= 3.1.0.rc1)
+      bcrypt-ruby (~> 2.1.4)
+      builder (~> 3.0.0)
+      i18n (~> 0.6.0beta1)
+    activerecord (3.1.0.rc1)
+      activemodel (= 3.1.0.rc1)
+      activesupport (= 3.1.0.rc1)
+      arel (~> 2.1.1)
+      tzinfo (~> 0.3.27)
+    activesupport (3.1.0.rc1)
+      multi_json (~> 1.0)
+    arel (2.1.3)
+    bcrypt-ruby (2.1.4)
+    builder (3.0.0)
+    diff-lcs (1.1.2)
+    i18n (0.6.0)
+    multi_json (1.0.3)
+    rake (0.8.7)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    tzinfo (0.3.29)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (= 3.1.0.rc1)
+  buscando_el_viento!
+  rake (= 0.8.7)
+  rspec

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+# copied from RSpec :-p
+require 'rspec'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec) do |t| 
+  t.rspec_path = 'rspec'
+  t.rspec_opts = %w[--color]
+  t.verbose = false
+end
+

data/buscando_el_viento.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "buscando_el_viento/version"
+
+Gem::Specification.new do |s|
+  s.name        = "buscando_el_viento"
+  s.version     = BuscandoElViento::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["giles bowkett", "xavier shay"]
+  s.email       = ["gilesb@gmail.com"]
+  s.homepage    = "https://github.com/gilesbowkett/buscando_el_viento"
+  s.summary = s.description = %q{Rails migration class methods for PostgreSQL search}
+
+  s.rubyforge_project = "buscando_el_viento"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end
+

data/lib/buscando_el_viento.rb

@@ -0,0 +1,12 @@
+require 'active_record'
+require 'active_record/base' # https://github.com/rails/rails/pull/1999
+
+require File.dirname(__FILE__) + '/buscando_el_viento/vectors'
+require File.dirname(__FILE__) + '/buscando_el_viento/triggers'
+require File.dirname(__FILE__) + '/buscando_el_viento/indexes'
+require File.dirname(__FILE__) + '/buscando_el_viento/search'
+
+class BuscandoMigration < ActiveRecord::Migration
+  include BuscandoElViento
+end
+

data/lib/buscando_el_viento/indexes.rb

@@ -0,0 +1,26 @@
+module BuscandoElViento
+  def index_name(table, column) # FIXME: better variable names
+    case column
+    when String, Symbol
+      "index_#{table}_on_#{column}_search_vector"
+    when Array
+      "index_#{table}_on_#{column.join("_and_")}_search_vector"
+    end
+  end
+
+  # yes, we're overwriting ActiveRecord::Migration's add_index, which, in this
+  # context, is less useful than it should be
+  def add_index(table, column)
+    execute <<-ADD_INDEX
+CREATE INDEX #{index_name(table, column)}
+ON #{table}
+USING gin(search_vector);
+ADD_INDEX
+  end
+
+  # remove_index gets the job done 9 times out of 10 for this stuff, but it
+  # needs a little assistance on composite indices
+  def remove_composite_index(table, columns)
+    remove_index table, vector_name(columns).to_s
+  end
+end

data/lib/buscando_el_viento/search.rb

@@ -0,0 +1,12 @@
+module BuscandoElViento
+  def add_search(table, columns, options = {:fuzzy => false})
+    add_search_vector(table, columns)
+    add_trigger(table, columns, options)
+    add_index(table, columns)
+  end
+  def remove_search(table, columns)
+    remove_search_vector(table, columns)
+    remove_trigger(table, columns)
+    remove_index(table, columns)
+  end
+end

data/lib/buscando_el_viento/triggers.rb

@@ -0,0 +1,32 @@
+module BuscandoElViento
+  def trigger_name(table, column)
+    "#{table}_#{vector_name(column)}_update"
+  end
+  def add_trigger(table, names, options = {:fuzzy => false})
+    dictionary = if options[:fuzzy]
+      "english"
+    else
+      "simple"
+    end
+
+    column = case names
+    when String, Symbol
+      names.to_s
+    when Array
+      names.join(", ")
+    end
+    execute <<TRIGGER
+CREATE TRIGGER #{trigger_name(table, names)}
+BEFORE INSERT OR UPDATE
+ON #{table}
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(#{vector_name(names).to_s},
+                        'pg_catalog.#{dictionary}',
+                        #{column});
+TRIGGER
+  end
+  def remove_trigger(table, column)
+    execute "DROP TRIGGER IF EXISTS #{trigger_name(table, column)} on #{table};"
+  end
+end
+

data/lib/buscando_el_viento/vectors.rb

@@ -0,0 +1,17 @@
+module BuscandoElViento
+  def vector_name(name)
+    case name
+    when String, Symbol
+      "#{name}_search_vector".to_sym
+    when Array
+      "#{name.join("_and_")}_search_vector".to_sym
+    end
+  end
+  def add_search_vector(table, column)
+    add_column(table, vector_name(column), "tsvector")
+  end
+  def remove_search_vector(table, column)
+    remove_column(table, vector_name(column))
+  end
+end
+

data/lib/buscando_el_viento/version.rb

@@ -0,0 +1,4 @@
+module BuscandoElViento
+  VERSION = "0.0.1"
+end
+

data/readme.md

@@ -0,0 +1,77 @@
+buscando el viento
+==================
+
+buscando el viento is a search migrations gem for PostgreSQL and Rails 3. It enables full-text searching by automating the process of creating appropriate migrations, and is largely based on Xavier Shay's PeepCode video on Postgres.
+
+http://peepcode.com/products/postgresql
+
+usage
+-----
+
+Inherit from `BuscandoMigration` instead of `ActiveRecord::Migration`. The `BuscandoElViento` version includes additional class methods. For example,
+
+    add_search_vector :users, :username
+
+will add a search vector attribute to your `users` table, tracking the `username` attribute.
+
+However if you do this
+
+    add_search :users, :username, :fuzzy => true
+
+you get the search vector, a database trigger to keep that vector up to date, and an index to make retrieval fast.
+
+Obviously the `:fuzzy` flag represents fuzzy versus exact search; this simply turns stemming on or off, although PostgreSQL supports a lot of additional features and options in its full-text search capacities. Use `remove_search` in the `down` method, to avoid `IrreversibleMigrations`. (Buscando doesn't support the `def change` approach yet, although there's no real reason why not.)
+
+tests and specs
+---------------
+
+In order to run your Rails tests, if you use PostgreSQL this way, you'll need to modify how Rails handles schema dumps. See the Postgres PeepCode for more info.
+
+http://peepcode.com/products/postgresql
+
+In terms of the gem's own specs, these could be better. They really just test the implementation, which is to say they verify that calling particular methods on the custom migration invokes particular other methods on the ActiveRecord migration.
+
+This makes the specs fast, and I prefer tests and specs which circumvent the database in most circumstances, but if you're noodling around wondering what kind of patches a project this awesome could possibly need, I'd have a look at verifying that the specs actually result in code which can perform searches properly.
+
+wtf? is that name spanish?
+--------------------------
+
+yes. "buscando el viento" means "seeking the wind" and gets its name from a line in a poem by Pablo Neruda.
+
+    mi voz buscaba el viento para tocar su oido
+
+which means
+
+    my voice sought the wind to touch her hearing
+
+(there's a nuance here: where in English, you say a person "plays" a musical instrument, in order to bring forth sound, in Spanish, you say a person "touches" a musical instrument.)
+
+I chose the name because it annoys me how many APIs use `find` where what they really mean is `seek` or `look for`, and this made me think of how useful it is that Spanish has a commonly-used word which means `to look for something`. In English, we have `look for`, which is not really a word but an idiom, and incorporating prepositions into your code is difficult outside of Smalltalk; meanwhile, `seek` is great, but nobody in the United States seems to use it at all, unless they're hippies seeking for truth or sword-bearing elves seeking the Great Chalice Of Whatever The Fuck.
+
+authors
+-------
+
+  + Giles Bowkett
+  + Xavier Shay
+
+license
+-------
+
+MIT License (which document included by reference)
+
+hook a brother up
+-----------------
+
+Patches requested:
+
+  + `setweight()` support (**crucial**)
+  + Rails 3.1 generators, both to generate migrations and relevant model finders
+  + support for `def change` vs `def up` and `def down`
+  + better specs
+  + quite frankly, a better understanding of PostgreSQL would be useful
+
+here be dragons
+---------------
+
+This gem is still very early days status. May explode unexpectedly. Do not taunt Happy Fun Ball.
+

data/spec/buscando_el_viento_spec.rb

@@ -0,0 +1,11 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BuscandoElViento do
+  it "exists" do
+    BuscandoElViento.class.should == Module
+  end
+  it "inherits" do
+    BuscandoMigration.new.should be_a(ActiveRecord::Migration)
+  end
+end
+

data/spec/fuzzy_spec.rb

@@ -0,0 +1,54 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BuscandoElViento do
+  before(:each) do
+    @search_migration = SearchMigration.new
+  end
+
+  # fuzzy search methods, in practice, only affect the definition of the DB trigger;
+  # however, I think requiring the downstream programmer to remember that kind of
+  # implementation detail somewhat defeats the purpose of a convenient API in the
+  # first place. BUT, since nobody's perfect, the search wrapper spec also contains a
+  # *tiny* bit of fuzzy-related whatnot.
+
+  it "enables fuzzy search" do
+    fuzzy_trigger = <<TRIGGER
+CREATE TRIGGER posts_title_search_vector_update
+BEFORE INSERT OR UPDATE
+ON posts
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(title_search_vector,
+                        'pg_catalog.english',
+                        title);
+TRIGGER
+    @search_migration.should_receive(:execute).with(fuzzy_trigger)
+    @search_migration.add_trigger(:posts, :title, :fuzzy => true)
+  end
+  it "disables fuzzy search" do
+    exact_trigger = <<TRIGGER
+CREATE TRIGGER posts_title_search_vector_update
+BEFORE INSERT OR UPDATE
+ON posts
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(title_search_vector,
+                        'pg_catalog.simple',
+                        title);
+TRIGGER
+    @search_migration.should_receive(:execute).with(exact_trigger)
+    @search_migration.add_trigger(:posts, :title, :fuzzy => false)
+  end
+  it "defaults to exact search" do
+    exact_trigger = <<TRIGGER
+CREATE TRIGGER posts_title_search_vector_update
+BEFORE INSERT OR UPDATE
+ON posts
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(title_search_vector,
+                        'pg_catalog.simple',
+                        title);
+TRIGGER
+    @search_migration.should_receive(:execute).with(exact_trigger)
+    @search_migration.add_trigger(:posts, :title)
+  end
+end
+

data/spec/indexes_spec.rb

@@ -0,0 +1,68 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BuscandoElViento do
+  before(:each) do
+    @search_migration = SearchMigration.new
+  end
+
+  it "names indexes" do
+    index_name = "index_users_on_username_search_vector"
+    @search_migration.index_name(:users, :username).should eq(index_name)
+  end
+  it "creates indexes" do
+    create_index = <<-CREATE_INDEX
+CREATE INDEX index_users_on_username_search_vector
+ON users
+USING gin(search_vector);
+CREATE_INDEX
+    @search_migration.should_receive(:execute).with(create_index)
+    @search_migration.add_index(:users, :username)
+  end
+
+  it "names composite indexes for searching multiple attributes" do
+    index_name = "index_posts_on_title_and_body_search_vector"
+    @search_migration.index_name(:posts, [:title, :body]).should eq(index_name)
+
+    index_name = "index_posts_on_title_and_body_and_topic_search_vector"
+    @search_migration.index_name(:posts, [:title, :body, :topic]).should eq(index_name)
+  end
+  it "creates composite indexes for searching multiple attributes" do
+    create_index = <<-CREATE_INDEX
+CREATE INDEX index_posts_on_title_and_body_search_vector
+ON posts
+USING gin(search_vector);
+CREATE_INDEX
+    @search_migration.should_receive(:execute).with(create_index)
+    @search_migration.add_index(:posts, [:title, :body])
+  end
+  it "removes composite indexes for searching multiple attributes" do
+    vector_name = "title_and_body_search_vector"
+    @search_migration.should_receive(:remove_index).with(:posts, vector_name)
+    @search_migration.remove_composite_index(:posts, [:title, :body])
+  end
+
+  # FIXME: spec cleanup...
+    # this last spec, and a few others like it, are maybe a little dumb. now that
+    # I think of it, I should probably just delete these. to create multiple
+    # distinct indices for searching distinct attributes, or to delete same, you
+    # just call add_index() or remove_index() as appropriate.
+
+  it "creates multiple indexes for searching distinct attributes" do
+    create_username_index = <<-CREATE_INDEX
+CREATE INDEX index_users_on_username_search_vector
+ON users
+USING gin(search_vector);
+CREATE_INDEX
+    @search_migration.should_receive(:execute).with(create_username_index)
+    @search_migration.add_index(:users, :username)
+
+    create_email_index = <<-CREATE_INDEX
+CREATE INDEX index_users_on_email_search_vector
+ON users
+USING gin(search_vector);
+CREATE_INDEX
+    @search_migration.should_receive(:execute).with(create_email_index)
+    @search_migration.add_index(:users, :email)
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require File.expand_path("lib/buscando_el_viento")
+%w{rubygems active_record}.each {|lib| require lib}
+
+class SearchMigration < BuscandoMigration; end
+

data/spec/triggers_spec.rb

@@ -0,0 +1,89 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BuscandoElViento do
+  before(:each) do
+    @search_migration = SearchMigration.new
+  end
+
+  it "names triggers" do
+    @search_migration.trigger_name(:users, :username).should eq("users_username_search_vector_update")
+  end
+  it "creates triggers" do
+    @add_trigger = <<TRIGGER
+CREATE TRIGGER users_username_search_vector_update
+BEFORE INSERT OR UPDATE
+ON users
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(username_search_vector,
+                        'pg_catalog.simple',
+                        username);
+TRIGGER
+    @search_migration.should_receive(:execute).with(@add_trigger)
+    @search_migration.add_trigger(:users, :username)
+  end
+
+  it "removes triggers" do
+    @drop_trigger = "DROP TRIGGER IF EXISTS users_username_search_vector_update on users;"
+    @search_migration.should_receive(:execute).with(@drop_trigger)
+    @search_migration.remove_trigger(:users, :username)
+  end
+
+  it "creates triggers for multiple distinct attributes, separately" do
+    @add_trigger = <<TRIGGER
+CREATE TRIGGER users_username_search_vector_update
+BEFORE INSERT OR UPDATE
+ON users
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(username_search_vector,
+                        'pg_catalog.simple',
+                        username);
+TRIGGER
+    @search_migration.should_receive(:execute).with(@add_trigger)
+    @search_migration.add_trigger(:users, :username)
+    @add_trigger = <<TRIGGER
+CREATE TRIGGER users_email_search_vector_update
+BEFORE INSERT OR UPDATE
+ON users
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(email_search_vector,
+                        'pg_catalog.simple',
+                        email);
+TRIGGER
+    @search_migration.should_receive(:execute).with(@add_trigger)
+    @search_migration.add_trigger(:users, :email)
+  end
+  it "removes triggers for multiple distinct attributes, separately" do
+    @username_drop_trigger = "DROP TRIGGER IF EXISTS users_username_search_vector_update on users;"
+    @email_drop_trigger = "DROP TRIGGER IF EXISTS users_email_search_vector_update on users;"
+
+    @search_migration.should_receive(:execute).with(@username_drop_trigger)
+    @search_migration.remove_trigger(:users, :username)
+
+    @search_migration.should_receive(:execute).with(@email_drop_trigger)
+    @search_migration.remove_trigger(:users, :email)
+  end
+
+  # multiple combined attributes, as one
+  it "names triggers with multiple combined attributes" do
+    attributes = [:title, :body]
+    trigger_name = "posts_title_and_body_search_vector_update"
+    @search_migration.trigger_name(:posts, attributes).should eq(trigger_name)
+  end
+  it "creates triggers for multiple combined attributes, as one" do
+    # FIXME: join these multi-line heredocs to eliminate indentation
+    #        before executing, simply because getting the indentation
+    #        right in the specs is an irritating waste of time
+    @add_trigger = <<TRIGGER
+CREATE TRIGGER posts_title_and_body_search_vector_update
+BEFORE INSERT OR UPDATE
+ON posts
+FOR EACH ROW EXECUTE PROCEDURE
+tsvector_update_trigger(title_and_body_search_vector,
+                        'pg_catalog.simple',
+                        title, body);
+TRIGGER
+    @search_migration.should_receive(:execute).with(@add_trigger)
+    @search_migration.add_trigger(:posts, [:title, :body])
+  end
+end
+

data/spec/vectors_spec.rb

@@ -0,0 +1,27 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BuscandoElViento do
+  before(:each) do
+    @search_migration = SearchMigration.new
+  end
+
+  it "names vectors" do
+    @search_migration.vector_name(:username).should eq(:username_search_vector)
+  end
+  it "creates vector names for multiple combined attributes, as one" do
+    attributes = [:title, :description]
+    @search_migration.vector_name(attributes).should eq(:title_and_description_search_vector)
+  end
+  it "auto-adds search vectors" do
+    @search_migration.should_receive(:add_column).with(:users,
+                                                       :username_search_vector,
+                                                       "tsvector")
+    @search_migration.add_search_vector :users, :username
+  end
+  it "removes search vectors" do
+    @search_migration.should_receive(:remove_column).with(:users,
+                                                          :username_search_vector)
+    @search_migration.remove_search_vector :users, :username
+  end
+end
+

data/spec/wrapper_spec.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BuscandoElViento do
+  before(:each) do
+    @search_migration = SearchMigration.new
+  end
+
+  it "adds search, defaulting to exact search" do
+    @search_migration.should_receive(:add_search_vector).with(:users, :username)
+    @search_migration.should_receive(:add_trigger).with(:users, :username, :fuzzy => false)
+    @search_migration.should_receive(:add_index).with(:users, :username)
+
+    @search_migration.add_search :users, :username
+  end
+  it "supports fuzzy search (stemming)" do
+    @search_migration.should_receive(:add_search_vector).with(:users, :username)
+    @search_migration.should_receive(:add_trigger).with(:users, :username, :fuzzy => true)
+    @search_migration.should_receive(:add_index).with(:users, :username)
+
+    @search_migration.add_search :users, :username, :fuzzy => true
+  end
+
+  it "removes search" do
+    @search_migration.should_receive(:remove_search_vector).with(:users, :username)
+    @search_migration.should_receive(:remove_trigger).with(:users, :username)
+    @search_migration.should_receive(:remove_index).with(:users, :username)
+
+    @search_migration.remove_search :users, :username
+  end
+end
+

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: buscando_el_viento
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- giles bowkett
+- xavier shay
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-14 00:00:00 Z
+dependencies: []
+
+description: Rails migration class methods for PostgreSQL search
+email: 
+- gilesb@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- buscando_el_viento.gemspec
+- lib/buscando_el_viento.rb
+- lib/buscando_el_viento/indexes.rb
+- lib/buscando_el_viento/search.rb
+- lib/buscando_el_viento/triggers.rb
+- lib/buscando_el_viento/vectors.rb
+- lib/buscando_el_viento/version.rb
+- readme.md
+- spec/buscando_el_viento_spec.rb
+- spec/fuzzy_spec.rb
+- spec/indexes_spec.rb
+- spec/spec_helper.rb
+- spec/triggers_spec.rb
+- spec/vectors_spec.rb
+- spec/wrapper_spec.rb
+homepage: https://github.com/gilesbowkett/buscando_el_viento
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: buscando_el_viento
+rubygems_version: 1.8.3
+signing_key: 
+specification_version: 3
+summary: Rails migration class methods for PostgreSQL search
+test_files: 
+- spec/buscando_el_viento_spec.rb
+- spec/fuzzy_spec.rb
+- spec/indexes_spec.rb
+- spec/spec_helper.rb
+- spec/triggers_spec.rb
+- spec/vectors_spec.rb
+- spec/wrapper_spec.rb