pose 1.2.3 → 1.2.4

data/README.md

@@ -1,60 +1,52 @@
 # Pose <a href="http://travis-ci.org/#!/kevgo/pose" target="_blank"><img src="https://secure.travis-ci.org/kevgo/pose.png" alt="Build status"></a> <a href="https://codeclimate.com/github/kevgo/pose" target="_blank"><img src="https://codeclimate.com/badge.png" /></a>
 
-Pose  ("Polymorphic Search") allows fulltext search for ActiveRecord objects.
+Pose  ("Polymorphic Search") allows fulltext search for ActiveRecord objects in Ruby on Rails.
 
-* Searches over several ActiveRecord classes at once.
-* The searchable fulltext content per document can be freely customized.
-* Uses the main Rails database, no sparate search engines are necessary.
-* Does not require to add attributes to the searchable classes or their database tables.
+* Searches over several classes at once.
+* The searchable content of each class and document can be freely customized.
+* Uses the main Rails database, no separate servers, databases, or search engines are necessary.
+* Does not pollute the searchable classes or their database tables with any attributes.
+* Allows to combine the fulltext search with any other custom database searches.
 * The algorithm is designed to work with any data store that allows for range queries, which covers pretty much every SQL or NoSQL database.
 * The search is very fast, doing only simple queries over fully indexed columns.
-* The search index provides data for autocomplete search fields.
 
 
 # Installation
 
-1.  Add the gem to your Gemfile.
+## Set up the gem.
 
-    ```ruby
-    gem 'pose'
-    ```
+Add the gem to your Gemfile and run `bundle install`
 
-2.  Update your gem bundle.
-
-    ```bash
-    $ bundle install
-    ```
+```ruby
+gem 'pose'
+```
 
-3.  Create the database tables for pose.
+## Create the database tables for pose.
 
-    ```bash
-    $ rails generate pose
-    $ rake db:migrate
-    ```
+```bash
+$ rails generate pose:install
+$ rake db:migrate
+```
 
-    Pose creates two tables in your database:
+Pose creates two tables in your database. These tables are automatically populated and kept up to date.
 
-    * _pose_words_: index of all the words that occur in the searchable content.
-    * _pose_assignments_: lists which word occurs in which document.
+* _pose_words_: index of all the words that occur in the searchable content.
+* _pose_assignments_: lists which word occurs in which document.
 
 
-# Make your ActiveRecord models searchable
+## Make your ActiveRecord models searchable
 
 ```ruby
 class MyClass < ActiveRecord::Base
 
-  # This line tells Pose that your class should be searchable.
-  # Once Pose knows that, it will update the search index every time an instance is saved or deleted.
-  #
+  # This line makes your class searchable.
   # The given block must return the searchble content as a string.
-  # Note that you can return whatever content you want here,
-  # not only data from this object but also data from related objects, class names, etc.
   posify do
 
     # Only active instances should show up in search results.
-    return unless status == :active
+    return nil unless status == :active
 
-    # Return the fulltext content.
+    # The searchable content.
     [ self.foo,
       self.parent.bar,
       self.children.map &:name ].join ' '
@@ -62,44 +54,31 @@ class MyClass < ActiveRecord::Base
 end
 ```
 
+Note that you can return whatever content you want in the `posify` block,
+not only data from this object, but also data from related objects, class names, etc. 
 
-# Maintain the search index
+Now that this class is posified, any `create`, `update`, or `delete` operation on any instance of this class will update the search index automatically.
 
-The search index is automatically updated when Objects are saved or deleted.
 
-## Indexing existing objects in the database
-If you had existing data in your database before adding Pose, it isn't automatically included in the search index.
-They will be added on the next save/update operation on them.
-You can also manually add existing objects to the search index.
+## Index existing records in your database
 
-```bash
-$ rake pose:reindex_all[MyClass]
-```
+Data that existed in your database before adding Pose isn't automatically included in the search index.
+You have to index those records manually once. Future updates will happen automatically.
 
-## Optimizing the search index
-The search index keeps all the words that were ever used around, in order to try to reuse them in the future.
-If you deleted a lot of objects, you can shrink the memory consumption of the search index by removing unused words.
-
-```bash
-$ rake pose:cleanup_index
-```
+To index all entries of `MyClass`, run `rake pose:reindex_all[MyClass]` on the command line.
 
-## Removing the search index
-For development purposes, or if something went wrong, you can remove the search index for a class
-(let's call it "MyClass") completely.
+At this point, you are all set up. Let's perform a search!
 
-```bash
-rake pose:delete_index[MyClass]
-```
 
+# Searching
 
-# Perform a search
+To search, simply call Pose's `search` method, and tell it the search query as well as in which classes it should search.
 
 ```ruby
 result = Pose.search 'foo', [MyClass, MyOtherClass]
 ```
 
-This searches for all instances of MyClass and MyOtherClass that contain the word 'foo'.
+This searches for all instances of `MyClass` and `MyOtherClass` that contain the word 'foo'.
 The method returns a hash that looks like this:
 
 ```ruby
@@ -110,34 +89,92 @@ The method returns a hash that looks like this:
 ```
 
 In this example, it found two results of type _MyClass_ and no results of type _MyOtherClass_.
-
-Happy searching!  :)
+A Pose search returns the object instances that match the query. This behavior, as well as many others, is configurable through
+search options.
 
 
 ## Search options
 
+### Configure the searched classes
+
+Pose accepts an array of classes to search over. When searching a single class, it can be provided directly, i.e. not as an array.
+
+```ruby
+result = Pose.search 'foo', MyClass
+```
+
+
+### Configure the result data
+
+By default, search results are the instances of the objects matching the search query. 
+If you want to just get the ids of the search results, and not the full instances, use the parameter `:result_type`.
+
+```ruby
+result = Pose.search 'foo', MyClass, result_type: :ids   # Returns ids instead of object instances.
+```
+
+
+### Limit the amount of search results
+
+By default, Pose returns all matching items. Large result sets can become very slow and resource intensive to process.
+To limit the result set, use the `:limit` search parameter.
+
 ```ruby
-result = Pose.search 'foo',
-                     MyClass,
-                     limit: 3,            # Limit the result count to 3.
-                     result_type: :ids    # Don't load the resulting objects, return just their ids.
-                     where: [ public: true, ['user_id <> ?', @user.id] ]    # Additional where clauses for when the result entries are loaded from the database.
+result = Pose.search 'foo', MyClass, limit: 20    # Returns only 20 search results.
 ```
 
 
-# Autocomplete support
+### Combine fulltext search with structured data search
 
-Because the search index contains a list of all the words known to the search engine,
-it can provide data for autocompletion functionality through the following convenience method:
+You can add your own ActiveRecord query clauses to a fulltext search operation. 
+For example, given a class `Note` that belongs to a `User` class and has a boolean attribute `public`,
+finding all public notes from other users containing "foo" is as easy as:
 
 ```ruby
-# Returns an array of strings that start with 'cat'.
-autocomplete_words = Pose.autocomplete_words 'cat'
+result = Pose.search 'foo', MyClass, where: [ public: true, ['user_id <> ?', @current_user.id] ]    
+```
+
+
+# Maintenance
+
+Besides an accasional search index cleanup, Pose is relatively maintenance free. 
+The search index is automatically updated when objects are created, updated, or deleted.
+
+
+## Optimizing the search index
+
+For performance reasons, the search index keeps all the words that were ever used around, in order to try to reuse them as much as possible.
+After deleting or changing a large number of objects, you can shrink the memory consumption of Pose's search index by 
+removing no longer used search terms from it.
+
+```bash
+$ rake pose:index:vacuum
+```
+
+
+## Recreating the search index from scratch
+To index existing data in your database, or after loading additional data outside of ActiveRecord into your database,
+you should recreate the search index from scratch.
+
+```bash
+rake pose:index:recreate[MyClass]
 ```
 
+
+# Uninstalling
+
+To remove all traces of Pose from your database, run:
+
+```bash
+rails generate pose:remove
+```
+
+Also don't forget to remove the `posify` block from your models as well as the gem entry from your Gemfile.
+
+
 # Use Pose in your tests
 
-By default, Pose doesn't run in Rails' test environment. This is to not slow down tests due to constant updating of the search index when objects are created.
+By default, Pose doesn't run in Rails' `test` environment. This is to not slow down tests due to constant updating of the search index when objects are created.
 If you want to test your models search functionality, you need to enable searching in tests:
 
 ```ruby
@@ -153,6 +190,7 @@ If you find a bug, have a question, or a better idea, please open an issue on th
 <a href="https://github.com/kevgo/pose/issues">Pose issue tracker</a>.
 Or, clone the repository, make your changes, and submit a pull request.
 
+
 ## Run the unit tests for the Pose Gem
 
 Pose uses Postgresql for tests, since it is the most strict database.
@@ -171,6 +209,8 @@ $ rake spec
 
 ## Road Map
 
-Pose's algorithm works with all sorts of storage technologies that support range queries, i.e. relational databases,
-Google's DataStore, and other NoSQL stores. Right now, only relational databases are supported. NoSQL support is easy,
-but not yet implemented.
+* add `join` to search parameters
+* pagination of search results
+* ordering
+* weighting search results
+* test Pose with more types of data stores (NoSQL, Google DataStore etc)

data/lib/generators/pose_generator.rb

@@ -1,15 +1,19 @@
 require 'rails/generators'
 require 'rails/generators/migration'
 
-class PoseGenerator < Rails::Generators::Base
-  include Rails::Generators::Migration
-  source_root File.expand_path('../templates', __FILE__)
-  
-  def create_migration_file
-    migration_template 'migration.rb', 'db/migrate/add_pose_tables.rb'
-  end
-  
-  def self.next_migration_number(path)
-      Time.now.utc.strftime("%Y%m%d%H%M%S")
+module Pose
+
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_migration_file
+      migration_template 'add_migration.rb', 'db/migrate/add_pose.rb'
+    end
+
+    def self.next_migration_number(path)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
   end
+
 end

data/lib/generators/remove_pose_generator.rb

@@ -0,0 +1,19 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Pose
+
+  class RemoveGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_migration_file
+      migration_template 'remove_migration.rb', 'db/migrate/remove_pose.rb'
+    end
+
+    def self.next_migration_number(path)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+  end
+
+end

data/lib/generators/templates/remove_migration.rb

@@ -0,0 +1,25 @@
+class AddPoseTables < ActiveRecord::Migration
+
+  def self.up
+    drop_table 'pose_assignments'
+    drop_table 'pose_words'
+  end
+
+  def self.down
+    create_table "pose_assignments" do |t|
+      t.integer "pose_word_id",            null: false
+      t.integer "posable_id",              null: false
+      t.string  "posable_type", limit: 40, null: false
+    end
+
+    add_index "pose_assignments", :pose_word_id
+    add_index "pose_assignments", :posable_id
+
+    create_table "pose_words" do |t|
+      t.string "text", limit: 80, null: false
+    end
+
+    add_index "pose_words", :text
+  end
+end
+

data/lib/pose/internal_helpers.rb

@@ -3,17 +3,6 @@ module Pose
   module Helpers
     class <<self
 
-      # Returns all words that begin with the given query string.
-      # This can be used for autocompletion functionality.
-      #
-      # @param [String]
-      # @return [Array<String>]
-      def autocomplete_words query
-        return [] if query.blank?
-        PoseWord.where('text LIKE ?', "#{Pose::Helpers.root_word(query)[0]}%").map(&:text)
-      end
-
-
       # Returns all strings that are in new_words, but not in existing_words.
       # Helper method.
       #

data/lib/pose/static_api.rb

@@ -1,4 +1,5 @@
-# Static helper methods of the Pose gem. 
+# This is the public API of static helper methods of the Pose gem.
+
 module Pose
 
   # By default, doesn't run in tests.
@@ -7,9 +8,16 @@ module Pose
 
   class <<self
 
-    ######################
-    # PUBLIC METHODS
+    # Returns all words that begin with the given query string.
+    # This can be used for autocompletion functionality.
     #
+    # @param [String]
+    # @return [Array<String>]
+    def autocomplete_words query
+      return [] if query.blank?
+      PoseWord.where('text LIKE ?', "#{Pose::Helpers.root_word(query)[0]}%").map(&:text)
+    end
+
 
     # Returns whether Pose is configured to perform search.
     # This setting exists to disable search in tests.

data/lib/pose/version.rb

@@ -1,3 +1,3 @@
 module Pose
-  VERSION = "1.2.3"
+  VERSION = "1.2.4"
 end

data/lib/rails/generators/pose/pose_generator.rb

@@ -0,0 +1,21 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Pose
+  module Generators
+
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../templates', __FILE__)
+
+      def create_migration_file
+        migration_template 'add_migration.rb', 'db/migrate/add_pose.rb'
+      end
+
+      def self.next_migration_number(path)
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+    end
+
+  end
+end

data/lib/rails/generators/pose/remove_pose_generator.rb

@@ -0,0 +1,21 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Pose
+  module Generators
+
+    class RemoveGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../templates', __FILE__)
+
+      def create_migration_file
+        migration_template 'remove_migration.rb', 'db/migrate/remove_pose.rb'
+      end
+
+      def self.next_migration_number(path)
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+    end
+
+  end
+end

data/lib/rails/generators/templates/add_migration.rb

@@ -0,0 +1,24 @@
+class AddPoseTables < ActiveRecord::Migration
+
+  def self.up
+    create_table "pose_assignments" do |t|
+      t.integer "pose_word_id",            null: false
+      t.integer "posable_id",              null: false
+      t.string  "posable_type", limit: 40, null: false
+    end
+
+    add_index "pose_assignments", :pose_word_id
+    add_index "pose_assignments", :posable_id
+
+    create_table "pose_words" do |t|
+      t.string "text", limit: 80, null: false
+    end
+
+    add_index "pose_words", :text
+  end
+
+  def self.down
+    drop_table 'pose_assignments'
+    drop_table 'pose_words'
+  end
+end

data/lib/rails/generators/templates/remove_migration.rb

@@ -0,0 +1,25 @@
+class AddPoseTables < ActiveRecord::Migration
+
+  def self.up
+    drop_table 'pose_assignments'
+    drop_table 'pose_words'
+  end
+
+  def self.down
+    create_table "pose_assignments" do |t|
+      t.integer "pose_word_id",            null: false
+      t.integer "posable_id",              null: false
+      t.string  "posable_type", limit: 40, null: false
+    end
+
+    add_index "pose_assignments", :pose_word_id
+    add_index "pose_assignments", :posable_id
+
+    create_table "pose_words" do |t|
+      t.string "text", limit: 80, null: false
+    end
+
+    add_index "pose_words", :text
+  end
+end
+

data/lib/tasks/pose_tasks.rake

@@ -2,36 +2,39 @@ include Rake::DSL if defined?(Rake::DSL)
 require 'progressbar'
 namespace :pose do
 
-  desc "Cleans out unused data from the search index."
-  task :cleanup_index => :environment do |t, args|
-    puts "Cleaning Pose search index ...\n\n"
-    progress_bar = ProgressBar.new '  assignments', PoseAssignment.count
-    PoseAssignment.cleanup_orphaned_pose_assignments progress_bar
-    progress_bar.finish
+  namespace :index do
 
-    progress_bar = ProgressBar.new '  words', PoseWord.count
-    PoseWord.remove_unused_words progress_bar
-    progress_bar.finish
+    desc "Cleans out unused data from the search index."
+    task :vacuum => :environment do |t, args|
+      puts "Cleaning Pose search index ...\n\n"
+      progress_bar = ProgressBar.new '  assignments', PoseAssignment.count
+      PoseAssignment.cleanup_orphaned_pose_assignments progress_bar
+      progress_bar.finish
 
-    puts "\nPose search index cleanup complete.\n\n"
-  end
+      progress_bar = ProgressBar.new '  words', PoseWord.count
+      PoseWord.remove_unused_words progress_bar
+      progress_bar.finish
 
-  desc "Removes the search index for all instances of the given classes."
-  task :delete_index, [:class_name] => :environment do |t, args|
-    clazz = Kernel.const_get args.class_name
-    PoseAssignment.cleanup_class_index clazz
-    puts "Search index for class #{clazz.name} deleted.\n\n"
-  end
+      puts "\nPose search index cleanup complete.\n\n"
+    end
+
+    desc "Removes the search index for all instances of the given classes."
+    task :remove, [:class_name] => :environment do |t, args|
+      clazz = Kernel.const_get args.class_name
+      PoseAssignment.cleanup_class_index clazz
+      puts "Search index for class #{clazz.name} deleted.\n\n"
+    end
 
-  desc "Deletes and recreates the search index for all instances of the given class."
-  task :reindex_all, [:class_name] => [:environment] do |t, args|
-    clazz = Kernel.const_get args.class_name
-    progress_bar = ProgressBar.new "  reindexing", clazz.count
-    clazz.find_each do |instance|
-      instance.update_pose_words
-      progress_bar.inc
+    desc "Deletes and recreates the search index for all instances of the given class."
+    task :reindex_all, [:class_name] => [:environment] do |t, args|
+      clazz = Kernel.const_get args.class_name
+      progress_bar = ProgressBar.new "  reindexing", clazz.count
+      clazz.find_each do |instance|
+        instance.update_pose_words
+        progress_bar.inc
+      end
+      progress_bar.finish
     end
-    progress_bar.finish
+    
   end
-  
 end

data/spec/pose_api_spec.rb

@@ -273,7 +273,7 @@ describe Pose do
     it 'returns words that start with the given phrase' do
       PosableOne.create text: 'great green pine tree'
 
-      result = Pose::Helpers.autocomplete_words 'gr'
+      result = Pose.autocomplete_words 'gr'
 
       result.should have(2).words
       result.should include 'great'
@@ -282,20 +282,20 @@ describe Pose do
 
     it 'returns words that match the given phrase exactly' do
       PoseWord.create text: 'cat'
-      result = Pose::Helpers.autocomplete_words 'cat'
+      result = Pose.autocomplete_words 'cat'
       result.should == ['cat']
     end
 
     it 'stems the search query' do
       PosableOne.create text: 'car'
-      result = Pose::Helpers.autocomplete_words 'cars'
+      result = Pose.autocomplete_words 'cars'
       result.should have(1).words
       result[0].should == 'car'
     end
 
     it 'returns nothing if the search query is empty' do
       PosableOne.create text: 'foo bar'
-      result = Pose::Helpers.autocomplete_words ''
+      result = Pose.autocomplete_words ''
       result.should be_empty
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pose
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.2.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-07 00:00:00.000000000 Z
+date: 2012-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -198,7 +198,9 @@ files:
 - doc/PoseWord.html
 - doc/top-level-namespace.html
 - lib/generators/pose_generator.rb
-- lib/generators/templates/migration.rb
+- lib/generators/remove_pose_generator.rb
+- lib/generators/templates/add_migration.rb
+- lib/generators/templates/remove_migration.rb
 - lib/pose/activerecord_base_additions.rb
 - lib/pose/internal_helpers.rb
 - lib/pose/model_additions.rb
@@ -208,6 +210,10 @@ files:
 - lib/pose/static_api.rb
 - lib/pose/version.rb
 - lib/pose.rb
+- lib/rails/generators/pose/pose_generator.rb
+- lib/rails/generators/pose/remove_pose_generator.rb
+- lib/rails/generators/templates/add_migration.rb
+- lib/rails/generators/templates/remove_migration.rb
 - lib/tasks/pose_tasks.rake
 - MIT-LICENSE
 - Rakefile