outoftime-sunspot 0.0.2 → 0.7.0

data/lib/sunspot.rb

@@ -1,49 +1,278 @@
 gem 'solr-ruby'
-gem 'extlib'
 require 'solr'
-require 'extlib'
 require File.join(File.dirname(__FILE__), 'light_config')
 
-%w(adapters builder restriction configuration field indexer query search session type util dsl).each do |filename|
+%w(adapters restriction configuration setup field facets indexer query search facet facet_row session type util dsl).each do |filename|
   require File.join(File.dirname(__FILE__), 'sunspot', filename)
 end
 
+#
+# The Sunspot module provides class-method entry points to most of the
+# functionality provided by the Sunspot library. Internally, the Sunspot
+# singleton class contains a (non-thread-safe!) instance of Sunspot::Session,
+# to which it delegates most of the class methods it exposes. In the method
+# documentation below, this instance is referred to as the "singleton session".
+#
+# Though the singleton session provides a convenient entry point to Sunspot,
+# it is by no means required to use the Sunspot class methods. Multiple sessions
+# may be instantiated and used (if you need to connect to multiple Solr
+# instances, for example.)
+#
+# Note that the configuration of classes for index/search (the +setup+
+# method) is _not_ session-specific, but rather global.
+#
 module Sunspot
-  VERSION='0.0.1'
-end
+  UnrecognizedFieldError = Class.new(Exception)
+  UnrecognizedRestrictionError = Class.new(Exception)
 
-class <<Sunspot
-  def setup(clazz, &block)
-    ::Sunspot::DSL::Fields.new(clazz).instance_eval(&block) if block
-  end
+  class <<self
+    # Configures indexing and search for a given class.
+    #
+    # ==== Parameters
+    #
+    # clazz<Class>:: class to configure
+    #
+    # ==== Example
+    #
+    #   Sunspot.setup(Post) do
+    #     text :title, :body
+    #     string :author_name
+    #     integer :blog_id
+    #     integer :category_ids
+    #     float :average_rating, :using => :ratings_average
+    #     time :published_at
+    #     string :sort_title do
+    #       title.downcase.sub(/^(an?|the)\W+/, ''/) if title = self.title
+    #     end
+    #   end
+    #
+    # ====== Attribute Fields vs. Virtual Fields
+    #
+    # Attribute fields call a method on the indexed object and index the
+    # return value. All of the fields defined above except for the last one are
+    # attribute fields. By default, the field name will also be the attribute
+    # used; this can be overriden with the +:using+ option, as in
+    # +:average_rating+ above. In that case, the attribute +:ratings_average+
+    # will be indexed with the field name +:average_rating+.
+    #
+    # +:sort_title+ is a virtual field, which evaluates the block inside the
+    # context of the instance being indexed, and indexes the value returned
+    # by the block. If the block you pass takes an argument, it will be passed
+    # the instance rather than being evaluated inside of it; so, the following
+    # example is equivalent to the one above (assuming #title is public):
+    #
+    #   Sunspot.setup(Post) do
+    #     string :sort_title do |post|
+    #       post.title.downcase.sub(/^(an?|the)\W+/, ''/) if title = self.title
+    #     end
+    #   end
+    #
+    # ===== Field Types
+    #
+    # The available types are:
+    # 
+    # * +text+
+    # * +string+
+    # * +integer+
+    # * +float+
+    # * +time+
+    # * +boolean+
+    #
+    # Note that the +text+ type behaves quite differently from the others -
+    # this is the type that is indexed as fulltext, and is searched using the
+    # +keywords+ method inside the search DSL. Text fields cannot have
+    # restrictions set on them, nor can they be used in order statements or
+    # for facets. All other types are indexed literally, and thus can be used
+    # for all of those operations. They will not, however, be searched in
+    # fulltext. In this way, Sunspot provides a complete barrier between
+    # fulltext fields and value fields.
+    #
+    # It is fine to specify a field both as a text field and a string field;
+    # internally, the fields will have different names so there is no danger
+    # of conflict.
+    # 
+    def setup(clazz, &block)
+      Setup.setup(clazz, &block)
+    end
 
-  def index(*objects)
-    session.index(*objects)
-  end
+    # Indexes objects on the singleton session.
+    #
+    # ==== Parameters
+    #
+    # objects...<Object>:: objects to index (may pass an array or varargs)
+    #
+    # ==== Example
+    #
+    #   post1, post2 = Array(2) { Post.create }
+    #   Sunspot.index(post1, post2)
+    #
+    # Note that indexed objects won't be reflected in search until a commit is
+    # sent - see Sunspot.index! and Sunspot.commit
+    #
+    def index(*objects)
+      session.index(*objects)
+    end
 
-  def search(*types, &block)
-    session.search(*types, &block)
-  end
-  
-  def remove(*objects)
-    session.remove(*objects)
-  end
+    # Indexes objects on the singleton session and commits immediately.
+    #
+    # See: Sunspot.index and Sunspot.commit
+    #
+    # ==== Parameters
+    #
+    # objects...<Object>:: objects to index (may pass an array or varargs)
+    #
+    def index!(*objects)
+      session.index!(*objects)
+    end
 
-  def remove_all(*classes)
-    session.remove_all(*classes)
-  end
+    # Commits the singleton session
+    #
+    # When documents are added to or removed from Solr, the changes are
+    # initially stored in memory, and are not reflected in Solr's existing
+    # searcher instance. When a commit message is sent, the changes are written
+    # to disk, and a new searcher is spawned. Commits are thus fairly
+    # expensive, so if your application needs to index several documents as part
+    # of a single operation, it is advisable to index them all and then call
+    # commit at the end of the operation.
+    #
+    # Note that Solr can also be configured to automatically perform a commit
+    # after either a specified interval after the last change, or after a
+    # specified number of documents are added. See
+    # http://wiki.apache.org/solr/SolrConfigXml
+    #
+    def commit
+      session.commit
+    end
 
-  def config
-    session.config
-  end
+    # Search for objects in the index.
+    #
+    # ==== Parameters
+    #
+    # types<Class>...::
+    #   Zero, one, or more types to search for. If no types are passed, all
+    #   configured types will be searched.
+    #
+    # ==== Returns
+    #
+    # Sunspot::Search:: Object containing results, facets, count, etc.
+    #
+    # The fields available for restriction, ordering, etc. are those that meet
+    # the following criteria:
+    #
+    # * They are not of type +text+.
+    # * They are defined for all of the classes being searched
+    # * They have the same data type for all of the classes being searched
+    # * They have the same multiple flag for all of the classes being searched.
+    #
+    # The restrictions available are the constants defined in the
+    # Sunspot::Restriction class. The standard restrictions are:
+    #
+    #   with(:field_name).equal_to(value)
+    #   with(:field_name, value) # shorthand for above
+    #   with(:field_name).less_than(value)
+    #   with(:field_name).greater_than(value)
+    #   with(:field_name).between(value1..value2)
+    #   with(:field_name).any_of([value1, value2, value3])
+    #   with(:field_name).all_of([value1, value2, value3])
+    #   without(some_instance) # exclude that particular instance
+    #
+    # +without+ can be substituted for +with+, causing the restriction to be
+    # negated. In the last example above, only +without+ works, as it does not
+    # make sense to search only for an instance you already have.
+    #
+    # Equality restrictions can take +nil+ as a value, which restricts the
+    # results to documents that have no value for the given field. Passing +nil+
+    # as a value to other restriction types is illegal. Thus:
+    #
+    #   with(:field_name, nil) # ok
+    #   with(:field_name).equal_to(nil) # ok
+    #   with(:field_name).less_than(nil) # bad
+    #
+    # ==== Example
+    #
+    #   Sunspot.search(Post) do
+    #     keywords 'great pizza'
+    #     with(:published_at).less_than Time.now
+    #     with :blog_id, 1
+    #     without current_post
+    #     facet :category_ids
+    #     order_by :published_at, :desc
+    #     paginate 2, 15
+    #   end
+    #
+    # See Sunspot::DSL::Query for the full API presented inside the block.
+    #
+    def search(*types, &block)
+      session.search(*types, &block)
+    end
 
-  def reset!
-    @session = nil
-  end
+    # Remove objects from the index. Any time an object is destroyed, it must
+    # be removed from the index; otherwise, the index will contain broken
+    # references to objects that do not exist, which will cause errors when
+    # those objects are matched in search results.
+    #
+    # ==== Parameters
+    #
+    # objects...<Object>::
+    #   Objects to remove from the index (may pass an array or varargs)
+    #
+    # ==== Example
+    #
+    #   post.destroy
+    #   Sunspot.remove(post)
+    #
+    def remove(*objects)
+      session.remove(*objects)
+    end
+
+    # Remove all objects of the given classes from the index. There isn't much
+    # use for this in general operations but it can be useful for maintenance,
+    # testing, etc.
+    #
+    # ==== Parameters
+    #
+    # classes...<Class>::
+    #   classes for which to remove all instances from the index (may pass an
+    #   array or varargs)
+    #
+    # ==== Example
+    #
+    #   Sunspot.remove_all(Post, Blog)
+    #
+    def remove_all(*classes)
+      session.remove_all(*classes)
+    end
+
+    # Returns the configuration associated with the singleton session. See
+    # Sunspot::Configuration for details.
+    #
+    # ==== Returns
+    #
+    # LightConfig::Configuration:: configuration for singleton session
+    #
+    def config
+      session.config
+    end
+
+    # 
+    # Resets the singleton session. This is useful for clearing out all
+    # static data between tests, but probably nowhere else.
+    #
+    def reset!
+      @session = nil
+    end
 
-  private
+    private
 
-  def session
-    @session ||= ::Sunspot::Session.new
+    # 
+    # Get the singleton session, creating it if none yet exists.
+    #
+    # ==== Returns
+    #
+    # Sunspot::Session:: the singleton session
+    #
+    def session #:nodoc:
+      @session ||= Session.new
+    end
   end
 end

data/spec/api/build_search_spec.rb

@@ -13,50 +13,51 @@ describe 'Search' do
     connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['title_s:My\ Pet\ Post'])).twice
     session.search Post, :conditions => { :title => 'My Pet Post' }
     session.search Post do
-      with.title 'My Pet Post'
+      with :title, 'My Pet Post'
     end
   end
 
   it 'should ignore nonexistant fields in hash scope' do
-    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => []))
+    connection.should_receive(:query).with('(type:Post)', hash_not_including(:filter_queries))
     session.search Post, :conditions => { :bogus => 'Field' }
   end
 
-  it 'should raise an ArgumentError for nonexistant fields in block scope' do
-    lambda do 
-      session.search Post do
-        with.bogus 'Field'
-      end
-    end.should raise_error(ArgumentError)
-  end
-
   it 'should scope by exact match with time' do
     connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['published_at_d:1983\-07\-08T09\:00\:00Z'])).twice
     time = Time.parse('1983-07-08 05:00:00 -0400')
     session.search Post, :conditions => { :published_at => time }
     session.search Post do
-      with.published_at time
+      with :published_at, time
+    end
+  end
+  
+  it 'should scope by exact match with boolean' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['featured_b:false'])).twice
+    session.search Post, :conditions => { :featured => false }
+    session.search Post do
+      with :featured, false
     end
   end
 
   it 'should scope by less than match with float' do
     connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['average_rating_f:[* TO 3\.0]']))
     session.search Post do
-      with.average_rating.less_than 3.0
+      with(:average_rating).less_than 3.0
     end
   end
 
   it 'should scope by greater than match with float' do
     connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['average_rating_f:[3\.0 TO *]']))
     session.search Post do
-      with.average_rating.greater_than 3.0
+      with(:average_rating).greater_than 3.0
     end
   end
 
   it 'should scope by between match with float' do
-    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['average_rating_f:[2\.0 TO 4\.0]']))
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['average_rating_f:[2\.0 TO 4\.0]'])).twice
+    session.search Post, :conditions => { :average_rating => 2.0..4.0 }
     session.search Post do
-      with.average_rating.between 2.0..4.0
+      with(:average_rating).between 2.0..4.0
     end
   end
 
@@ -64,14 +65,95 @@ describe 'Search' do
     connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['category_ids_im:(2 OR 7 OR 12)'])).twice
     session.search Post, :conditions => { :category_ids => [2, 7, 12] }
     session.search Post do
-      with.category_ids.any_of [2, 7, 12]
+      with(:category_ids).any_of [2, 7, 12]
     end
   end
 
   it 'should scope by all match with integer' do
     connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['category_ids_im:(2 AND 7 AND 12)']))
     session.search Post do
-      with.category_ids.all_of [2, 7, 12]
+      with(:category_ids).all_of [2, 7, 12]
+    end
+  end
+
+  it 'should scope by not equal match with string' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-title_s:Bad\ Post']))
+    session.search Post do
+      without :title, 'Bad Post'
+    end
+  end
+
+  it 'should scope by not less than match with float' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-average_rating_f:[* TO 3\.0]']))
+    session.search Post do
+      without(:average_rating).less_than 3.0
+    end
+  end
+
+  it 'should scope by not greater than match with float' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-average_rating_f:[3\.0 TO *]']))
+    session.search Post do
+      without(:average_rating).greater_than 3.0
+    end
+  end
+
+  it 'should scope by not between match with float' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-average_rating_f:[2\.0 TO 4\.0]']))
+    session.search Post do
+      without(:average_rating).between 2.0..4.0
+    end
+  end
+
+  it 'should scope by not any match with integer' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-category_ids_im:(2 OR 7 OR 12)']))
+    session.search Post do
+      without(:category_ids).any_of [2, 7, 12]
+    end
+  end
+
+
+  it 'should scope by not all match with integer' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-category_ids_im:(2 AND 7 AND 12)']))
+    session.search Post do
+      without(:category_ids).all_of [2, 7, 12]
+    end
+  end
+
+  it 'should scope by empty field' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['-average_rating_f:[* TO *]']))
+    session.search Post do
+      with :average_rating, nil
+    end
+  end
+
+  it 'should scope by non-empty field' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ['average_rating_f:[* TO *]']))
+    session.search Post do
+      without :average_rating, nil
+    end
+  end
+
+  it 'should exclude by object identity' do
+    post = Post.new
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ["-id:Post\\ #{post.id}"]))
+    session.search Post do
+      without post
+    end
+  end
+
+  it 'should exclude multiple objects passed as varargs by object identity' do
+    post1, post2 = Post.new, Post.new
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ["-id:Post\\ #{post1.id}", "-id:Post\\ #{post2.id}"]))
+    session.search Post do
+      without post1, post2
+    end
+  end
+
+  it 'should exclude multiple objects passed as array by object identity' do
+    posts = [Post.new, Post.new]
+    connection.should_receive(:query).with('(type:Post)', hash_including(:filter_queries => ["-id:Post\\ #{posts.first.id}", "-id:Post\\ #{posts.last.id}"]))
+    session.search Post do
+      without posts
     end
   end
 
@@ -89,7 +171,7 @@ describe 'Search' do
   end
 
   it 'should paginate using provided per_page' do
-    connection.should_receive(:query).with('(type:Post)', :filter_queries => [], :rows => 15, :start => 45).twice
+    connection.should_receive(:query).with('(type:Post)', hash_including(:rows => 15, :start => 45)).twice
     session.search Post, :page => 4, :per_page => 15
     session.search Post do
       paginate :page => 4, :per_page => 15
@@ -104,6 +186,30 @@ describe 'Search' do
     end
   end
 
+  it 'should order by multiple columns' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:sort => [{ :average_rating_f => :descending },
+                                                                                   { :sort_title_s => :ascending }])).twice
+    session.search Post, :order => ['average_rating desc', 'sort_title asc']
+    session.search Post do
+      order_by :average_rating, :desc
+      order_by :sort_title, :asc
+    end
+  end
+
+  it 'should request single field facet' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:facets => { :fields => %w(category_ids_im) }))
+    session.search Post do
+      facet :category_ids
+    end
+  end
+
+  it 'should request multiple field facet' do
+    connection.should_receive(:query).with('(type:Post)', hash_including(:facets => { :fields => %w(category_ids_im blog_id_i) }))
+    session.search Post do
+      facet :category_ids, :blog_id
+    end
+  end
+
   it 'should build search for multiple types' do
     connection.should_receive(:query).with('(type:(Post OR Comment))', hash_including)
     session.search(Post, Comment)
@@ -114,43 +220,43 @@ describe 'Search' do
     time = Time.parse('1983-07-08 05:00:00 -0400')
     session.search Post, Comment, :conditions => { :published_at => time }
     session.search Post, Comment do
-      with.published_at time
+      with :published_at, time
     end
   end
 
-  it 'should raise exception if search scoped to field not common to all types' do
+  it 'should raise Sunspot::UnrecognizedFieldError if search scoped to field not common to all types' do
     lambda do
       session.search Post, Comment do
-        with.blog_id 1
+        with :blog_id, 1
       end
-    end.should raise_error(ArgumentError)
+    end.should raise_error(Sunspot::UnrecognizedFieldError)
   end
 
-  it 'should raise exception if search scoped to field configured differently between types' do
+  it 'should raise Sunspot::UnrecognizedFieldError if search scoped to field configured differently between types' do
     lambda do
       session.search Post, Comment do
-        with.average_rating 2.2 # this is a float in Post but an integer in Comment
+        with :average_rating, 2.2 # this is a float in Post but an integer in Comment
       end
-    end.should raise_error(ArgumentError)
+    end.should raise_error(Sunspot::UnrecognizedFieldError)
   end
 
   it 'should ignore condition if field is not common to all types' do
-    connection.should_receive(:query).with('(type:(Post OR Comment))', hash_including(:filter_queries => []))    
+    connection.should_receive(:query).with('(type:(Post OR Comment))', hash_not_including(:filter_queries))
     session.search Post, Comment, :conditions => { :blog_id => 1 }
   end
 
-  it 'should raise ArgumentError if bogus field scoped' do
+  it 'should raise Sunspot::UnrecognizedFieldError for nonexistant fields in block scope' do
     lambda do
       session.search Post do
-        with.bogus.equal_to :field
+        with :bogus, 'Field'
       end
-    end.should raise_error(ArgumentError)
+    end.should raise_error(Sunspot::UnrecognizedFieldError)
   end
 
   it 'should raise NoMethodError if bogus operator referenced' do
     lambda do
       session.search Post do
-        with.category_ids.resembling :bogus_condition
+        with(:category_ids).resembling :bogus_condition
       end
     end.should raise_error(NoMethodError)
   end
@@ -171,12 +277,12 @@ describe 'Search' do
     end.should raise_error(ArgumentError)
   end
 
-  it 'should raise NoMethodError if more than one argument passed to scope method' do # or should it?
+  it 'should raise ArgumentError if more than two arguments passed to scope method' do
     lambda do
       session.search Post do
-        with.category_ids 4, 5
+        with(:category_ids, 4, 5)
       end
-    end.should raise_error(NoMethodError)
+    end.should raise_error(ArgumentError)
   end
 
   private

data/spec/api/indexer_spec.rb

@@ -13,7 +13,7 @@ describe 'indexer' do
       session.index post
     end
 
-    it 'should correctly index a string attribute field' do 
+    it 'should correctly index a string attribute field' do
       post :title => 'A Title'
       connection.should_receive(:add).with(hash_including(:title_s => 'A Title'))
       session.index post
@@ -26,7 +26,7 @@ describe 'indexer' do
     end
 
     it 'should correctly index a float attribute field' do
-      post :average_rating => 2.23
+      post :ratings_average => 2.23
       connection.should_receive(:add).with(hash_including(:average_rating_f => '2.23'))
       session.index post
     end
@@ -43,12 +43,36 @@ describe 'indexer' do
       session.index post
     end
 
+    it 'should correctly index a boolean field' do
+      post :featured => true
+      connection.should_receive(:add).with(hash_including(:featured_b => 'true'))
+      session.index post
+    end
+
+    it 'should correctly index a false boolean field' do
+      post :featured => false
+      connection.should_receive(:add).with(hash_including(:featured_b => 'false'))
+      session.index post
+    end
+
+    it 'should not index a nil boolean field' do
+      post
+      connection.should_receive(:add).with(hash_not_including(:featured_b))
+      session.index post
+    end
+
     it 'should correctly index a virtual field' do
       post :title => 'The Blog Post'
       connection.should_receive(:add).with(hash_including(:sort_title_s => 'blog post'))
       session.index post
     end
 
+    it 'should correctly index an external virtual field' do
+      post :category_ids => [1, 2, 3]
+      connection.should_receive(:add).with(hash_including(:primary_category_id_i => '1'))
+      session.index post
+    end
+
     it 'should correctly index a field that is defined on a superclass' do
       Sunspot.setup(BaseClass) { string :author_name }
       post :author_name => 'Mat Brown'
@@ -56,6 +80,13 @@ describe 'indexer' do
       session.index post
     end
 
+    it 'should commit immediately after index! called' do
+      post :title => 'The Blog Post'
+      connection.should_receive(:add).ordered
+      connection.should_receive(:commit).ordered
+      session.index!(post)
+    end
+
     it 'should remove an object from the index' do
       connection.should_receive(:delete).with("Post #{post.id}")
       session.remove(post)