textacular 3.0.0

data/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Change Log
+
+## 3.0.0
+
+* All deprecations have been resolved. This breaks backwards compatibility.
+* Rename gem to Textacular.
+
+## 2.2.0
+
+* 1 DEPRECATION
+  * The whole gem is being renamed and will no longer be maintained as Texticle.
+    The new name it Textacular.
+* 1 new feature
+  * Expand gemspec to allow Rails 4.
+
+## 2.1.1
+
+* 1 bugfix
+  * Include `lib/textacular/version.rb` in the gemspec so the gem will load. Sorry!
+
+
+## 2.1.0
+
+* 1 DEPRECATION
+  * `search` aliases new `advanced_search` method (same functionality as before), but will
+    alias `basic_search` in 3.0! Should print warnings.
+* 3 new features
+  * Generate full text search indexes from a rake task (sort of like in 1.x). Supply a specific
+    model name.
+  * New search methods: `basic_search`, `advanced_search` and `fuzzy_search`. Basic allows special
+    characters like &, and % in search terms. Fuzzy is based on Postgres's trigram matching extension
+    pg_trgm. Advanced is the same functionality from `search` previously.
+  * Rake task that installs pg_trgm now works on Postgres 9.1 and up.
+* 2 dev improvements
+  * Test database configuration not automatically generated from a rake task and ignored by git.
+  * New interactive developer console (powered by pry).
+
+
+## 2.0.3
+
+* 1 new feature
+  * Allow searching through relations. Model.join(:relation).search(:relation => {:column => "query"})
+    works, and reduces the need for multi-model tables. Huge thanks to Ben Hamill for the pull request.
+  * Allow searching through all model columns irrespective of the column's type; we cast all columns to text
+    in the search query. Performance may degrade when searching through anything but a string column.
+* 2 bugfixes
+  * Fix exceptions when adding Textacular to a table-less model.
+  * Column names in a search query are now scoped to the current table.
+* 1 dev improvement
+  * Running `rake` from the project root will setup the test environment by creating a test database
+    and running the necessary migrations. `rake` can also be used to run all the project tests.
+
+
+## 2.0.2
+
+* 1 bugfix
+  * Our #respond_to? overwritten method was causing failures when a model didn't have
+    a table (e.g. if migrations hadn't been run yet). Not the case anymore.
+
+
+## 2.0.1
+
+* 1 new feature
+  * Can now define #searchable_language to specify the language used for the query. This changes
+    what's considered a stop word on Postgres' side. 'english' is the default language.
+* 1 bugfix
+  * We were only specifying a language in to_tsvector() and not in to_tsquery(), which could
+    cause queries to fail if the default database language wasn't set to 'english'.
+
+
+## 2.0.pre4
+
+* 1 new feature
+  * Searchable is now available to specify which columns you want searched:
+
+      ```ruby
+      require 'textacular/searchable'
+      class Game
+        extend Searchable(:title)
+      end
+      ```
+
+      This also allows Textacular use in Rails without having #search available to all models:
+
+      ```
+      gem 'textacular', '~> 2.0.pre4', :require => 'textacular/searchable'
+      ```
+* 1 bugfix
+  * ActiveRecord::Base.extend(Textacular) doesn't break #method_missing and #respond_to? anymore
+
+
+## 2.0.pre3
+
+* 1 new feature
+  * #select calls now limit the columns that are searched
+* 1 bugfix
+  * #search calls without an argument assume an empty string as a search term (it errored out previously)
+
+
+## 2.0.pre2
+
+* 1 bugfix
+  * #respond_to? wasn't overwritten correctly
+
+## 2.0.pre
+
+* Complete refactoring of Textacular
+  * For users:
+    * Textacular should only be used for its simplicity; if you need to deeply configure your text search, please give `gem install pg_search` a try.
+    * `#search` method is now included in all ActiveRecord models by default, and searches across a model's :string columns.
+    * `#search_by_<column>` dynamic methods are now available.
+    * `#search` can now be chained; `Game.search_by_title("Street Fighter").search_by_system("PS3")` works.
+    * `#search` now accepts a hash to specify columns to be searched, e.g. `Game.search(:name => "Mario")`
+    * No more access to `#rank` values for results (though they're still ordered by rank).
+    * No way to give different weights to different columns in this release.
+  * For devs:
+    * We now have actual tests to run against; this will make accepting pull requests much more enjoyable.
+
+
+## HEAD (unreleased)
+
+* 1 minor bugfix
+  * Multiple named indices are now supported.
+
+
+## 1.0.4 / 2010-08-19
+
+* 2 major enhancements
+  * use Rails.root instead of RAILS_ROOT
+  * refactored tasks to ease maintainance and patchability
+* 3 minor enhancements
+  * fix timestamp for migrationfile
+  * fixed deprecation warning for rails3 (dropping rails2-support)
+  * prevented warning about defined constant
+
+
+## 1.0.3 / 2010-07-07
+
+* 1 major enhancement
+  * Added Rails 3 support.
+* 1 bugfix
+  * Model names that end in double 's's (like Address) don't choke the rake tasks anymore.
+
+
+## 1.0.2 / 2009-10-17
+
+* 1 bugfix
+  * Generated migration now uses UTC time rather than local time.
+
+
+## 1.0.1 / 2009-04-14
+
+* 1 minor enhancement
+  * Textical adds a rake task to generate FTS index migrations.  Just run:
+
+      ```
+      rake textical:migration
+      ```
+
+
+## 1.0.0 / 2009-04-14
+
+* 1 major enhancement
+  * Birthday!

data/Gemfile

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

data/README.md

@@ -0,0 +1,143 @@
+# textacular
+
+Further documentation available at http://textacular.github.com/textacular.
+
+
+## DESCRIPTION:
+
+Textacular exposes full text search capabilities from PostgreSQL,
+extending ActiveRecord with scopes making search easy and fun!
+
+
+## FEATURES/PROBLEMS:
+
+* Only works with PostgreSQL
+
+
+## SYNOPSIS:
+
+### Quick Start
+
+#### Rails 3 (or 4!)
+
+In the project's Gemfile add
+
+    gem 'textacular', '~> 3.0', require: 'textacular/rails'
+
+
+#### ActiveRecord outside of Rails
+
+```ruby
+require 'textacular'
+
+ActiveRecord::Base.extend(Textacular)
+```
+
+
+### Usage
+
+Your models now have access to search methods:
+
+The `#basic_search` method is what you might expect: it looks literally for what
+you send to it, doing nothing fancy with the input:
+
+```ruby
+Game.basic_search('Sonic') # will search through the model's :string columns
+Game.basic_search(title: 'Mario', system: 'Nintendo')
+```
+
+The `#advanced_search` method lets you use Postgres's search syntax like '|',
+'&' and '!' ('or', 'and', and 'not') as well as some other craziness. Check [the
+Postgres
+docs](http://www.postgresql.org/docs/9.2/static/datatype-textsearch.html) for more:
+
+```ruby
+Game.advanced_search(title: 'Street|Fantasy')
+Game.advanced_search(system: '!PS2')
+```
+
+Finally, the `#fuzzy_search` method lets you use Postgres's trigram search
+funcionality:
+
+```ruby
+Comic.fuzzy_search(title: 'Questio') # matches Questionable Content
+```
+
+Searches are also chainable:
+
+```ruby
+Game.fuzzy_search(title: 'tree').basic_search(system: 'SNES')
+```
+
+
+### Setting Language
+
+To set proper searching dictionary just override class method on your model:
+
+```ruby
+def self.searchable_language
+  'russian'
+end
+```
+
+And all your queries would go right! And don`t forget to change the migration for indexes, like shown below.
+
+
+### Creating Indexes for Super Speed
+You can have Postgresql use an index for the full-text search.  To declare a full-text index, in a
+migration add code like the following:
+
+```ruby
+execute "
+    create index on email_logs using gin(to_tsvector('english', subject));
+    create index on email_logs using gin(to_tsvector('english', email_address));"
+```
+
+In the above example, the table email_logs has two text columns that we search against, subject and email_address.
+You will need to add an index for every text/string column you query against, or else Postgresql will revert to a
+full table scan instead of using the indexes.
+
+If you create these indexes, you should also switch to sql for your schema_format in `config/application.rb`:
+
+```ruby
+config.active_record.schema_format = :sql
+```
+
+
+## REQUIREMENTS:
+
+* ActiveRecord
+* Ruby 1.9.2
+
+
+## INSTALL:
+
+```
+$ gem install textacular
+```
+
+
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Aaron Patterson
+
+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/Rakefile

@@ -0,0 +1,154 @@
+require 'rubygems'
+
+require 'rake'
+require 'yaml'
+require 'pg'
+require 'active_record'
+require 'benchmark'
+
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/spec')
+
+task :default do
+  Rake::Task["db:setup"].invoke
+  Rake::Task["test"].invoke
+end
+
+desc "Fire up an interactive terminal to play with"
+task :console do
+  require 'pry'
+  require File.expand_path(File.dirname(__FILE__) + '/lib/textacular')
+
+  config = YAML.load_file File.expand_path(File.dirname(__FILE__) + '/spec/config.yml')
+  ActiveRecord::Base.establish_connection config.merge(:adapter => :postgresql)
+
+  class Character < ActiveRecord::Base
+    belongs_to :web_comic
+  end
+
+  class WebComic < ActiveRecord::Base
+    has_many :characters
+  end
+
+  class Game < ActiveRecord::Base
+  end
+
+  # add ability to reload console
+  def reload
+    reload_msg = '# Reloading the console...'
+    puts CodeRay.scan(reload_msg, :ruby).term
+    Pry.save_history
+    exec('rake console')
+  end
+
+  # start the console! :-)
+  welcome = <<-EOS
+    Welcome to the Textacular devloper console. You have some classes you can play with:
+
+      class Character < ActiveRecord::Base
+        # string :name
+        # string :description
+        # integer :web_comic_id
+
+        belongs_to :web_comic
+      end
+
+      class WebComic < ActiveRecord::Base
+        # string :name
+        # string :author
+        # integer :id
+
+        has_many :characters
+      end
+
+      class Game < ActiveRecord::Base
+        # string :system
+        # string :title
+        # text :description
+      end
+  EOS
+
+  puts CodeRay.scan(welcome, :ruby).term
+  Pry.start
+end
+
+task :test do
+  require 'textacular_spec'
+  require 'textacular/searchable_spec'
+  require 'textacular/full_text_indexer_spec'
+end
+
+namespace :db do
+  desc 'Create and configure the test database'
+  task :setup do
+    spec_directory = "#{File.expand_path(File.dirname(__FILE__))}/spec"
+
+    STDOUT.puts "Detecting database configuration..."
+
+    if File.exists?("#{spec_directory}/config.yml")
+      STDOUT.puts "Configuration detected. Skipping confguration."
+    else
+      STDOUT.puts "Would you like to create and configure the test database? y/N"
+      continue = STDIN.gets.chomp
+
+      unless continue =~ /^[y]$/i
+        STDOUT.puts "Done."
+        exit 0
+      end
+
+      STDOUT.puts "Creating database..."
+      `createdb textacular`
+
+      STDOUT.puts "Writing configuration file..."
+
+      config_example = File.read("#{spec_directory}/config.yml.example")
+
+      File.open("#{spec_directory}/config.yml", "w") do |config|
+        config << config_example.sub(/<username>/, `whoami`.chomp)
+      end
+
+      STDOUT.puts "Running migrations..."
+      Rake::Task["db:migrate"].invoke
+
+      STDOUT.puts 'Done.'
+    end
+  end
+
+  desc 'Run migrations for test database'
+  task :migrate do
+    config = YAML.load_file File.expand_path(File.dirname(__FILE__) + '/spec/config.yml')
+    ActiveRecord::Base.establish_connection config.merge(:adapter => :postgresql)
+
+    ActiveRecord::Migration.instance_eval do
+      create_table :games do |table|
+        table.string :system
+        table.string :title
+        table.text :description
+      end
+      create_table :web_comics do |table|
+
+        table.string :name
+        table.string :author
+        table.text :review
+        table.integer :id
+      end
+
+      create_table :characters do |table|
+        table.string :name
+        table.string :description
+        table.integer :web_comic_id
+      end
+    end
+  end
+
+  desc 'Drop tables from test database'
+  task :drop do
+    config = YAML.load_file File.expand_path(File.dirname(__FILE__) + '/spec/config.yml')
+    ActiveRecord::Base.establish_connection config.merge(:adapter => :postgresql)
+
+    ActiveRecord::Migration.instance_eval do
+      drop_table :games
+      drop_table :web_comics
+      drop_table :characters
+    end
+  end
+end