pose 2.0.1 → 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a28304ad3e5a60d843f3df073cc68a0842b3a157
+  data.tar.gz: 8e1bb1ea33bcc319b84c06e8cd13a2332453bbfb
+SHA512:
+  metadata.gz: 0c8b59c95e6a5cc7d1abf04743ece0b64882080c23a8e1dc96966ab2550ca6e858899ac2ef3d05f6d997df01d324c98598ba158dadede884d7fbf1dd77d23ed0
+  data.tar.gz: a628c6936417db7d987fb88a84b60149364507be84c4b3ad4808366e28885013f7867c8c99bf5d81853bec730ea423c94cd2d00170c39d581b5fb8eb1306201a

data/README.md

@@ -1,14 +1,13 @@
-# 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>
+# POlymorphic SEarch <a href="http://travis-ci.org/#!/kevgo/pose" target="_blank"><img src="https://secure.travis-ci.org/kevgo/pose.png" alt="Build status"></a> [![Code Climate](https://codeclimate.com/github/kevgo/pose.png)](https://codeclimate.com/github/kevgo/pose) [![Coverage Status](https://coveralls.io/repos/kevgo/pose/badge.png?branch=master)](https://coveralls.io/r/kevgo/pose) [![Dependency Status](https://gemnasium.com/kevgo/pose.png)](https://gemnasium.com/kevgo/pose)
 
-Pose  ("Polymorphic Search") allows fulltext search for ActiveRecord objects in Ruby on Rails.
+A database agnostic fulltext search engine for ActiveRecord objects in Ruby on Rails.
 
 * 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.
+* Uses the main Rails database - no separate servers, databases, or search engines required.
+* Does not pollute the searchable classes nor their database tables.
+* Very fast search, doing only simple queries over fully indexed columns.
+* Allows to augment the fulltext search query with your own joins and where clauses.
 
 
 ## Installation
@@ -40,7 +39,7 @@ Pose creates two tables in your database. These tables are automatically populat
 class MyClass < ActiveRecord::Base
 
   # This line makes your class searchable.
-  # The given block must return the searchble content as a string.
+  # The given block must return the searchable content as a string.
   posify do
 
     # Only active instances should show up in search results.
@@ -65,12 +64,12 @@ Now that this class is posified, any `create`, `update`, or `delete` operation o
 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.
 
-To index all entries of `MyClass`, run `rake pose:reindex_all[MyClass]` on the command line.
+To index all entries of `MyClass`, run `rake 'pose:reindex_all[MyClass]'` on the command line.
 
 At this point, you are all set up. Let's perform a search!
 
 
-## Upgrading from version 1.x
+### Upgrading from version 1.x
 
 Version 2 is a proper Rails engine, and comes with a slightly different database table schema.
 Upgrading is as simple as
@@ -108,7 +107,13 @@ 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.
+Pose accepts an array of classes to search over.
+
+```ruby
+result = Pose.search 'search text', [MyClass, MyOtherClass]
+```
+
+When searching a single class, it can be provided directly, i.e. not as an array.
 
 ```ruby
 result = Pose.search 'foo', MyClass
@@ -117,34 +122,42 @@ result = Pose.search 'foo', MyClass
 
 ### Configure the result data
 
-By default, search results are the instances of the objects matching the search query.
+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.
+# Returns ids instead of object instances.
+result = Pose.search 'foo', MyClass, result_type: :ids
 ```
 
 
 ### 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.
+By default, Pose returns all matching items.
 To limit the result set, use the `:limit` search parameter.
 
 ```ruby
-result = Pose.search 'foo', MyClass, limit: 20    # Returns only 20 search results.
+# Returns only 20 search results.
+result = Pose.search 'foo', MyClass, limit: 20
 ```
 
 
 ### Combine fulltext search with structured data search
 
-You can add your own ActiveRecord query clauses to a fulltext search operation.
+You can add your own ActiveRecord query clauses (JOINs and WHEREs) 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
-result = Pose.search 'foo', MyClass, where: [ public: true, ['user_id <> ?', @current_user.id] ]
+result = Pose.search 'foo',
+                     Note,
+                     joins: Note,
+                     where: [ ['notes.public = ?', true],
+                              ['user_id <> ?', @current_user.id] ] ]
 ```
 
+Combining ActiveRecord query clauses with fulltext search only works when searching over a single class.
+
 
 ## Maintenance
 
@@ -154,8 +167,8 @@ The search index is automatically updated when objects are created, updated, or
 
 ### 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
+The search index keeps all the words that were ever used around.
+After deleting or changing a large number of objects, you can shrink the database storage consumption of Pose's search index by
 removing no longer used search terms from it.
 
 ```bash
@@ -164,7 +177,7 @@ $ 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,
+To index existing data in your database, or after buld-loading data outside of ActiveRecord into your database,
 you should recreate the search index from scratch.
 
 ```bash
@@ -180,14 +193,14 @@ To remove all traces of Pose from your database, run:
 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.
+Also don't forget to remove the `posify` block from your models as well as the _pose_ gem from your Gemfile.
 
 
 ## Use Pose in your tests
 
 Pose can slow down your tests, because it updates the search index on every `:create`, `:update`, and `:delete`
 operation in the database.
-If this becomes a problem, you can disable Pose in your `test` environments,
+To avoid that in your not search-related tests, you can disable Pose in your `test` environments,
 and only enable it for the tests that actually need search functionality.
 
 To disable Pose for tests, add this line to `config/environments/test.rb`
@@ -196,7 +209,8 @@ To disable Pose for tests, add this line to `config/environments/test.rb`
 Pose::CONFIGURATION[:perform_search] = false
 ```
 
-Now, with search disabled in the test environment, enable Pose in some of your tests by setting the same value to `true` inside the tests:
+Now, with search disabled in the test environment, enable Pose in some of your tests
+by setting the same value to `true` inside the tests:
 
 ```ruby
 
@@ -221,27 +235,29 @@ end
 
 If you find a bug, have a question, or a better idea, please open an issue on the
 <a href="https://github.com/kevgo/pose/issues">Pose issue tracker</a>.
-Or, clone the repository, make your changes, and submit a pull request.
+Or, clone the repository, make your changes, and submit a unit-tested pull request!
 
 ### Run the unit tests for the Pose Gem
 
-For now, Pose uses Postgresql for tests, since it is free, and one of the most strict databases.
+Pose uses Sqlite3 for tests.
 To run tests, first create a test database.
 
 ```bash
-createdb pose_test
+bundle
+rake app:db:create
+rake app:db:migrate
+rake app:db:test:prepare
 ```
 
 Then run the tests.
 
 ```bash
-$ rake spec
+rake
 ```
 
 
 ### Road Map
 
-* add `join` to search parameters
 * pagination of search results
 * ordering
 * weighting search results

data/lib/generators/pose/install/install_generator.rb

@@ -0,0 +1,56 @@
+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(File.join(File.dirname(__FILE__), 'templates')) 
+
+      def create_migration_file
+        say ''
+        say '  Creating database migration for the Pose tables.'
+        say ''
+        migration_template 'install_migration.rb', 'db/migrate/install_pose.rb'
+        say ''
+      end
+
+      def installation_instructions
+        say ''
+        say '  All done! You need to do two things now:'
+        say ''
+        say '    1. Run the database migration'
+        say ''
+        say '       rake db:migrate', Thor::Shell::Color::BOLD
+        say ''
+        say ''
+        say '    2. Add a posify block to all your models.'
+        say '       Here is an example:'
+        say ''
+        say '         class MyClass < ActiveRecord::Base'
+        say '           ...'
+        say ''
+        say '           posify do', Thor::Shell::Color::BOLD
+        say '             # return searchable text as a string here', Thor::Shell::Color::BOLD
+        say '           end', Thor::Shell::Color::BOLD
+        say ''
+        say '           ...'
+        say '         end'
+        say ''
+        say ''
+        say '  Happy searching! :)'
+        say ''
+      end
+
+
+      private
+
+      # Helper method for creating the migration.
+      def self.next_migration_number(path)
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+    end
+
+  end
+end

data/lib/generators/pose/install/templates/install_migration.rb

@@ -0,0 +1,24 @@
+class InstallPose < ActiveRecord::Migration
+
+  def self.up
+    create_table "pose_assignments" do |t|
+      t.integer "word_id",            null: false
+      t.integer "posable_id",              null: false
+      t.string  "posable_type", limit: 40, null: false
+    end
+
+    add_index "pose_assignments", :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/pose.rb

@@ -1,6 +1,8 @@
 require "pose/engine"
+require 'pose/query'
+require 'pose/search'
 require 'pose/static_api'
-require 'pose/internal_helpers'
+require 'pose/helpers'
 require 'pose/activerecord_base_additions'
 require 'pose/model_class_additions'
 require 'pose/railtie' if defined? Rails

data/lib/pose/{internal_helpers.rb → helpers.rb}

@@ -1,4 +1,5 @@
 # Internal helper methods for the Pose module.
+# TODO: remove
 module Pose
   module Helpers
     class <<self
@@ -41,33 +42,13 @@ module Pose
       #
       # @return [Boolean]
       def is_url? word
-        URI::parse(word).scheme == 'http'
-      rescue URI::InvalidURIError
-        false
+        /https?:\/\/(\w)+\.(\w+)/ =~ word
       end
 
 
-      # Merges the given posable object ids for a single query word into the given search result.
-      def merge_search_result_word_matches result, class_name, ids
-        if result.has_key? class_name
-          result[class_name] = result[class_name] & ids
-        else
-          result[class_name] = ids
-        end
-      end
-
-
-      # Returns a hash mapping classes to ids for the a single given word.
-      def search_classes_and_ids_for_word word, class_names
-        result = {}.tap { |hash| class_names.each { |class_name| hash[class_name] = [] }}
-        query = Pose::Assignment.joins(:word) \
-                          .select('pose_assignments.posable_id, pose_assignments.posable_type') \
-                          .where('pose_words.text LIKE ?', "#{word}%") \
-                          .where('posable_type IN (?)', class_names)
-        Pose::Assignment.connection.select_all(query.to_sql).each do |pose_assignment|
-          result[pose_assignment['posable_type']] << pose_assignment['posable_id'].to_i
-        end
-        result
+      # Makes the given input an array.
+      def make_array input
+        [input].flatten
       end
 
 
@@ -77,11 +58,6 @@ module Pose
       end
 
 
-      # Returns the search terms that are contained in the given query.
-      def query_terms query
-        query.split(' ').map{|query_word| Helpers.root_word query_word}.flatten.uniq
-      end
-
       # Simplifies the given word to a generic search form.
       #
       # @param [String] raw_word The word to make searchable.

data/lib/pose/model_class_additions.rb

@@ -29,7 +29,7 @@ module Pose
 
       # Step 1: get an array of all words for the current object.
       search_text = instance_eval &(self.class.pose_content)
-      new_words = Helpers.query_terms search_text.to_s
+      new_words = Query.new([], search_text.to_s).query_words
 
       # Step 2: Add new words to the search index.
       Helpers.get_words_to_add(self.pose_words, new_words).each do |word_to_add|

data/lib/pose/query.rb

@@ -0,0 +1,85 @@
+module Pose
+  # Represents a search query.
+  #
+  # Provides convenient access to all elements of the search query:
+  #   * fulltext
+  #   * classes to search in
+  #   * additional JOINs
+  #   * additional WHEREs
+  class Query
+
+    attr_reader :classes, :text, :options
+
+
+    def initialize classes, text, options = {}
+      @classes = [classes].flatten
+      @text = text
+      @options = options
+    end
+
+
+    # The names of the classes to search in.
+    # @return [Array<String>]
+    def class_names
+      classes.map &:name
+    end
+
+
+    # Returns whether this query contains custom JOIN expressions.
+    def has_joins?
+      !@options[:joins].blank?
+    end
+
+
+    # Returns whether the query defines a limit on the number of results.
+    def has_limit?
+      !@options[:limit].blank?
+    end
+
+
+    # Returns whether this query contains WHERE clauses.
+    def has_where?
+      !@options[:where].blank?
+    end
+
+
+    # Returns whether only result ids are requested,
+    # opposed to full objects.
+    def ids_requested?
+      @options[:result_type] == :ids
+    end
+
+
+    # Returns the custom JOIN expressions of this query.
+    def joins
+      @joins ||= [@options[:joins]].flatten.compact
+    end
+
+
+    # Returns the limitation on the number of results.
+    def limit
+      @options[:limit]
+    end
+
+
+    # Returns the search terms that are contained in the given query.
+    def query_words
+      @query_words ||= Query.query_words @text
+    end
+
+
+    def self.query_words query_string
+      query_string.split(' ').map{|query_word| Helpers.root_word query_word}.flatten.uniq
+    end
+
+
+    # Returns the WHERE clause of this query.
+    def where
+      return [] unless has_where?
+      if @options[:where].size == 2 and @options[:where][0].class == String
+        return [ @options[:where] ]
+      end
+      @options[:where]
+    end
+  end
+end

data/lib/pose/search.rb

@@ -0,0 +1,135 @@
+module Pose
+
+  # A search operation.
+  #
+  # Is given a query and search options, and returns the search results.
+  class Search
+
+    # @param [Array<Class>] classes The classes to search over.
+    # @param [String] query_string The full-text part of the search query.
+    # @param options Additional search options:
+    #    * where: additional where clauses
+    #    * join: additional join clauses
+    def initialize classes, query_string, options = {}
+      @query = Query.new classes, query_string, options
+    end
+
+
+    # Adds the given join expression to the given arel query.
+    def add_join arel, join_expression
+      case join_expression.class.name
+        when 'Class'
+          table_name = join_expression.name.tableize
+          return arel.joins "INNER JOIN #{table_name} ON pose_assignments.posable_id=#{table_name}.id AND pose_assignments.posable_type='#{join_expression.name}'"
+        when 'String', 'Symbol'
+          return arel.joins join_expression
+        else
+          raise "Unknown join expression: #{join_expression}"
+      end
+    end
+
+
+    # Creates a JOIN to the given expression.
+    def add_joins arel
+      @query.joins.inject(arel) do |memo, join_data|
+        add_join memo, join_data
+      end
+    end
+
+
+    # Adds the WHERE clauses from the given query to the given arel construct.
+    def add_wheres arel
+      @query.where.inject(arel) { |memo, where| memo.where where }
+    end
+
+
+    # Returns an empty result structure.
+    def empty_result
+      {}.tap do |result|
+        @query.class_names.each do |class_name|
+          result[class_name] = []
+        end
+      end
+    end
+
+
+    # Truncates the result set based on the :limit parameter in the query.
+    def limit_ids result
+      return unless @query.has_limit?
+      result.each do |clazz, ids|
+        result[clazz] = ids.slice 0, @query.limit
+      end
+    end
+
+
+    # Converts the ids to classes, if the user wants classes.
+    def load_classes result
+      return if @query.ids_requested?
+      result.each do |clazz, ids|
+        if ids.size > 0
+          result[clazz] = clazz.where(id: ids)
+        end
+      end
+    end
+
+
+    # Merges the given posable object ids for a single query word into the given search result.
+    # Helper method for :search_words.
+    def merge_search_result_word_matches result, class_name, ids
+      if result.has_key? class_name
+        result[class_name] = result[class_name] & ids
+      else
+        result[class_name] = ids
+      end
+    end
+
+
+    # Returns the search results cached.
+    # Use this method to access the results of the search.
+    def results
+      @results ||= search
+    end
+
+
+    # Performs a complete search.
+    # Clients should use :results to perform a search,
+    # since it caches the results.
+    def search
+      {}.tap do |result|
+        search_words.each do |class_name, ids|
+          result[class_name.constantize] = ids
+        end
+        limit_ids result
+        load_classes result
+      end
+    end
+
+
+    # Finds all matching ids for a single word of the search query.
+    def search_word word
+      empty_result.tap do |result|
+        data = Pose::Assignment.joins(:word) \
+                               .select('pose_assignments.posable_id, pose_assignments.posable_type') \
+                               .where('pose_words.text LIKE ?', "#{word}%") \
+                               .where('pose_assignments.posable_type IN (?)', @query.class_names)
+        data = add_joins data
+        data = add_wheres data
+        Pose::Assignment.connection.select_all(data.to_sql).each do |pose_assignment|
+          result[pose_assignment['posable_type']] << pose_assignment['posable_id'].to_i
+        end
+      end
+    end
+
+
+    # Returns all matching ids for all words of the search query.
+    def search_words
+      {}.tap do |result|
+        @query.query_words.each do |query_word|
+          search_word(query_word).each do |class_name, ids|
+            merge_search_result_word_matches result, class_name, ids
+          end
+        end
+      end
+    end
+  end
+end