sunspot 0.9.8 → 0.10.0

data/lib/sunspot/dsl/fulltext.rb

@@ -0,0 +1,168 @@
+module Sunspot
+  module DSL
+    # 
+    # This DSL exposes the functionality provided by Solr's fulltext Dismax
+    # handler.
+    #
+    class Fulltext
+      def initialize(query, setup) #:nodoc:
+        @query, @setup = query, setup
+        @fields_added = false
+      end
+
+      # 
+      # Specify which fields to search. Field names specified as arguments are
+      # given default boost; field boosts can be specified by passing a hash of
+      # field names keyed to boost values as the last argument.
+      #
+      # If you wish to boost certain fields without restricting which fields are
+      # searched, use #boost_fields
+      #
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     keywords 'search is cool' do
+      #       fields(:body, :title => 2.0)
+      #     end
+      #   end
+      #
+      # This would search the :body field with default boost (1.0), and the :title
+      # field with a boost of 2.0
+      #
+      def fields(*field_names)
+        @fields_added = true
+        boosted_fields = field_names.pop if field_names.last.is_a?(Hash)
+        field_names.each do |field_name|
+          @setup.text_fields(field_name).each do |field|
+            @query.add_fulltext_field(field, field.default_boost)
+          end
+        end
+        if boosted_fields
+          boosted_fields.each_pair do |field_name, boost|
+            @setup.text_fields(field_name).each do |field|
+              @query.add_fulltext_field(field, boost)
+            end
+          end
+        end
+      end
+
+      # 
+      # Enable keyword highlighting for this search. By default, the fields 
+      # under search will be highlighted; you may also may pass one or more
+      # symbol arguments indicating fields to be highlighted (they don't even
+      # have to be the same fields you're searching).
+      #
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     keywords 'show me the highlighting' do
+      #       highlight :title, :body
+      #     end
+      #   end
+      #
+      # You may also pass a hash of options as the last argument. Options are
+      # the following:
+      #
+      # Full disclosure: I barely understand what these options actually do;
+      # this documentation is pretty much just copied from the
+      # (http://wiki.apache.org/solr/HighlightingParameters#head-23ecd5061bc2c86a561f85dc1303979fe614b956)[Solr Wiki]
+      # 
+      # :max_snippets::
+      #   The maximum number of highlighted snippets to generate per field
+      # :fragment_size::
+      #   The number of characters to consider for a highlighted fragment
+      # :merge_continuous_fragments::
+      #   Collapse continuous fragments into a single fragment
+      # :phrase_highlighter::
+      #   Highlight phrase terms only when they appear within the query phrase
+      #   in the document
+      # :require_field_match::
+      #   If true, a field will only be highlighted if the query matched in
+      #   this particular field (only has an effect if :phrase_highlighter is
+      #   true as well)
+      #
+      def highlight(*args)
+        options = args.last.kind_of?(Hash) ? args.pop : {}
+        fields = []
+        args.each { |field_name| fields.concat(@setup.text_fields(field_name)) }
+
+        @query.set_highlight(fields, options)
+      end
+
+      # 
+      # Phrase fields are an awesome dismax feature that adds extra boost to
+      # documents for which all the fulltext keywords appear in close proximity
+      # in one of the given fields. Excellent for titles, headlines, etc.
+      #
+      # Boosted fields are specified in a hash of field names to a boost, as
+      # with the #fields and #boost_fields methods.
+      #
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     keywords 'nothing reveals like relevance' do
+      #       phrase_fields :title => 2.0
+      #     end
+      #   end
+      #
+      def phrase_fields(boosted_fields)
+        if boosted_fields
+          boosted_fields.each_pair do |field_name, boost|
+            @setup.text_fields(field_name).each do |field|
+              @query.add_phrase_field(field, boost)
+            end
+          end
+        end
+      end
+
+      # 
+      # Boost queries allow specification of an arbitrary scope for which
+      # matching documents should receive an extra boost. The block is evaluated
+      # in the usual scope DSL, and field names are attribute fields, not text
+      # fields, as in other scope.
+      #
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     keywords 'super fan' do
+      #       boost(2.0) do
+      #         with(:featured, true)
+      #       end
+      #     end
+      #   end
+      #
+      # In the above search, featured posts will receive a boost of 2.0.
+      #
+      def boost(factor, &block)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@query.create_boost_query(factor), @setup),
+          &block
+        )
+      end
+
+      #
+      # Add boost to certain fields, without restricting which fields are
+      # searched.
+      #
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     keywords('pork sandwich') do
+      #       boost_fields :title => 1.5
+      #     end
+      #   end
+      #
+      def boost_fields(boosts)
+        boosts.each_pair do |field_name, boost|
+          @setup.text_fields(field_name).each do |field|
+            @query.add_fulltext_field(field, boost)
+          end
+        end
+      end
+
+      def fields_added? #:nodoc:
+        @fields_added
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/query.rb

@@ -18,6 +18,9 @@ module Sunspot
       # + and - modifiers work as expected. All other special Solr boolean
       # syntax is escaped, and mismatched quotes are ignored entirely.
       #
+      # This method can optionally take a block, which is evaluated by the
+      # Fulltext DSL class, and exposes several powerful dismax features.
+      #
       # ==== Parameters
       #
       # keywords<String>:: phrase to perform fulltext search on
@@ -27,10 +30,49 @@ module Sunspot
       # :fields<Array>::
       #   List of fields that should be searched for keywords. Defaults to all
       #   fields configured for the types under search.
+      # :highlight<Boolean,Array>::
+      #   If true, perform keyword highlighting on all searched fields. If an
+      #   array of field names, perform highlighting on the specified fields.
+      #   This can also be called from within the fulltext block.
       #
-      def keywords(keywords, options = {})
-        @query.set_keywords(keywords, options)
+      def fulltext(keywords, options = {}, &block)
+        if keywords && !(keywords.to_s =~ /^\s*$/)
+          fulltext_query = @query.set_fulltext(keywords)
+          if field_names = options.delete(:fields)
+            Array(field_names).each do |field_name|
+              @setup.text_fields(field_name).each do |field|
+                fulltext_query.add_fulltext_field(field, field.default_boost)
+              end
+            end
+          end
+          if highlight_field_names = options.delete(:highlight)
+            if highlight_field_names == true
+              fulltext_query.set_highlight
+            else
+              highlight_fields = []
+              Array(highlight_field_names).each do |field_name|
+                highlight_fields.concat(@setup.text_fields(field_name))
+              end
+              fulltext_query.set_highlight(highlight_fields)
+            end
+          end
+          if block && fulltext_query
+            fulltext_dsl = Fulltext.new(fulltext_query, @setup)
+            Util.instance_eval_or_call(
+              fulltext_dsl,
+              &block
+            )
+          end
+          if !field_names && (!fulltext_dsl || !fulltext_dsl.fields_added?)
+            @setup.all_text_fields.each do |field|
+              unless fulltext_query.has_fulltext_field?(field)
+                fulltext_query.add_fulltext_field(field, field.default_boost)
+              end
+            end
+          end
+        end
       end
+      alias_method :keywords, :fulltext
 
       # Paginate your search. This works the same way as WillPaginate's
       # paginate().
@@ -42,18 +84,53 @@ module Sunspot
       #
       # ==== Options (options)
       #
-      # :page<Integer>:: The requested page (required)
+      # :page<Integer,String>:: The requested page. The default is 1.
       #
-      # :per_page<Integer>::
+      # :per_page<Integer,String>::
       #   How many results to return per page. The default is the value in
       #   +Sunspot.config.pagination.default_per_page+
       #
       def paginate(options = {})
-        page = options.delete(:page) || raise(ArgumentError, "paginate requires a :page argument")
+        page = options.delete(:page)
         per_page = options.delete(:per_page)
         raise ArgumentError, "unknown argument #{options.keys.first.inspect} passed to paginate" unless options.empty?
         @query.paginate(page, per_page)
       end
+
+      # 
+      # Scope the search by geographical distance from a given point.
+      # +coordinates+ should either respond to #first and #last (e.g. a
+      # two-element array), or to #lat and one of #lng, #lon, or #long.
+      # +miles+ is the radius around the point for which to return documents.
+      #
+      def near(coordinates, miles)
+        @query.add_location_restriction(coordinates, miles)
+      end
+
+      # 
+      # Apply scope-type restrictions on fulltext fields. In certain situations,
+      # it may be desirable to place logical restrictions on text fields.
+      # Remember that text fields are tokenized; your mileage may very.
+      #
+      # The block works exactly like a normal scope, except that the field names
+      # refer to text fields instead of attribute fields.
+      # 
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     text_fields do
+      #       with :body, nil
+      #     end
+      #   end
+      #
+      # This will return all documents that do not have a body.
+      #
+      def text_fields(&block)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@scope, TextFieldSetup.new(@setup)),
+          &block
+        )
+      end
     end
   end
 end

data/lib/sunspot/dsl/query_facet.rb

@@ -5,8 +5,8 @@ module Sunspot
     # method.
     #
     class QueryFacet
-      def initialize(query_facet) #:nodoc:
-        @query_facet = query_facet
+      def initialize(query_facet, setup) #:nodoc:
+        @query_facet, @setup = query_facet, setup
       end
 
       # 
@@ -24,7 +24,7 @@ module Sunspot
       #   An object used to identify this facet row in the results.
       #
       def row(label, &block)
-        Scope.new(@query_facet.add_row(label)).instance_eval(&block)
+        Scope.new(@query_facet.add_row(label), @setup).instance_eval(&block)
       end
     end
   end

data/lib/sunspot/dsl/restriction.rb

@@ -1,22 +1,22 @@
 module Sunspot
-  module DSL #:nodoc:
+  module DSL
     # 
     # This class presents an API for building restrictions in the query DSL. The
     # methods exposed are the snake-cased names of the classes defined in the
-    # Restriction module, with the exception of Base and SameAs. All methods
-    # take a single argument, which is the value to be applied to the
+    # Sunspot::Restriction module, with the exception of Base. All
+    # methods take a single argument, which is the value to be applied to the
     # restriction.
     #
-    class Restriction #:nodoc:
-      def initialize(field_name, query, negative)
-        @field_name, @query, @negative = field_name, query, negative
+    class Restriction
+      def initialize(field_name, query, negative) #:nodoc:
+        @field_name, @scope, @negative = field_name, query, negative
       end
 
       Sunspot::Query::Restriction.names.each do |class_name|
         method_name = Util.snake_case(class_name.to_s)
         module_eval(<<-RUBY, __FILE__, __LINE__ + 1)
           def #{method_name}(value)
-            @query.add_restriction(@field_name, Sunspot::Query::Restriction::#{class_name}, value, @negative)
+            @scope.add_restriction(@field_name, Sunspot::Query::Restriction::#{class_name}, value, @negative)
           end
         RUBY
       end

data/lib/sunspot/dsl/scope.rb

@@ -10,8 +10,8 @@ module Sunspot
     class Scope
       NONE = Object.new
 
-      def initialize(query) #:nodoc:
-        @query = query
+      def initialize(scope, setup) #:nodoc:
+        @scope, @setup = scope, setup
       end
 
       # 
@@ -62,9 +62,9 @@ module Sunspot
       #
       def with(field_name, value = NONE)
         if value == NONE
-          DSL::Restriction.new(field_name.to_sym, @query, false)
+          DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, false)
         else
-          @query.add_shorthand_restriction(field_name, value)
+          @scope.add_shorthand_restriction(@setup.field(field_name), value)
         end
       end
 
@@ -111,14 +111,18 @@ module Sunspot
           field_name = args[0]
           value = args.length > 1 ? args[1] : NONE
           if value == NONE
-            DSL::Restriction.new(field_name.to_sym, @query, true)
+            DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, true)
           else
-            @query.add_negated_shorthand_restriction(field_name, value)
+            @scope.add_negated_shorthand_restriction(@setup.field(field_name.to_sym), value)
           end
         else
           instances = args
           for instance in instances.flatten
-            @query.exclude_instance(instance)
+            @scope.add_negated_restriction(
+              IdField.instance,
+              Sunspot::Query::Restriction::EqualTo,
+              Sunspot::Adapters::InstanceAdapter.adapt(instance).index_id
+            )
           end
         end
       end
@@ -140,7 +144,7 @@ module Sunspot
       # future, or who do not have any expiration time at all.
       #
       def any_of(&block)
-        Util.instance_eval_or_call(Scope.new(@query.add_disjunction), &block)
+        Util.instance_eval_or_call(Scope.new(@scope.add_disjunction, @setup), &block)
       end
 
       # 
@@ -162,7 +166,7 @@ module Sunspot
       #   end
       #
       def all_of(&block)
-        Util.instance_eval_or_call(Scope.new(@query.add_conjunction), &block)
+        Util.instance_eval_or_call(Scope.new(@scope.add_conjunction, @setup), &block)
       end
 
       #
@@ -186,7 +190,10 @@ module Sunspot
       #   end
       #
       def dynamic(base_name, &block)
-        FieldQuery.new(@query.dynamic_query(base_name)).instance_eval(&block)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@scope, @setup.dynamic_field_factory(base_name)),
+          &block
+        )
       end
     end
   end

data/lib/sunspot/dsl/search.rb

@@ -6,9 +6,9 @@ module Sunspot
     # Sunspot::DSL::Scope for the full API presented.
     #
     class Search < Query
-      def initialize(search) #:nodoc:
+      def initialize(search, setup) #:nodoc:
         @search = search
-        @query = search.query
+        super(search.query, setup)
       end
 
       # 

data/lib/sunspot/dsl.rb

@@ -1,3 +1,4 @@
-%w(fields scope field_query query query_facet restriction search).each do |file|
+%w(fields scope field_query query fulltext query_facet restriction
+   search).each do |file|
   require File.join(File.dirname(__FILE__), 'dsl', file)
 end

data/lib/sunspot/facet.rb

@@ -1,14 +1,22 @@
 module Sunspot
   class Facet
-    def initialize(facet_data)
+    def initialize(facet_data) #:nodoc:
       @facet_data = facet_data
     end
 
+    # 
+    # For field facets, this is the field name. For query facets, this is the
+    # name given to the #facet method in the DSL.
+    #
     def name
       @facet_data.name
     end
     alias_method :field_name, :name
 
+    # 
+    # Collection of FacetRow objects containing the individual values returned
+    # by the facet.
+    #
     def rows
       @facet_data.rows { |value, count| FacetRow.new(value, count) }
     end

data/lib/sunspot/facet_data.rb

@@ -1,14 +1,29 @@
 require 'enumerator'
 
 module Sunspot
-  module FacetData
+  # 
+  # The FacetData classes encapsulate various sources of facet data (field
+  # facet, # date facet, query facet), presenting a polymorphic API to the Facet
+  # class.
+  #
+  module FacetData #:nodoc:all
+    # 
+    # Base class for facet data.
+    #
     class Abstract
       attr_reader :field #:nodoc:
 
+      # 
+      # The class that the field references, if any.
+      #
       def reference
         @field.reference if @field
       end
 
+      # 
+      # Cast the given value to the field's type, if it has one; otherwise just
+      # return the string.
+      #
       def cast(value)
         if @field
           @field.cast(value)
@@ -17,13 +32,20 @@ module Sunspot
         end
       end
 
+      # 
+      # Given the raw facet row value, return what the Sunspot facet row object
+      # should present as the value. This can be overridden by subclasses.
+      #
       def row_value(value)
         cast(value)
       end
     end
 
+    # 
+    # FieldFacetData encapsulates the data returned by field facets
+    #
     class FieldFacetData < Abstract
-      def initialize(facet_values, field) #:nodoc:
+      def initialize(facet_values, field)
         @facet_values, @field = facet_values, field
       end
 
@@ -55,8 +77,11 @@ module Sunspot
       end
     end
 
+    # 
+    # DateFacetData encapsulates facet date for date-range facets.
+    #
     class DateFacetData < FieldFacetData
-      def initialize(facet_values, field) #:nodoc:
+      def initialize(facet_values, field)
         @gap = facet_values.delete('gap')[/\+(\d+)SECONDS/,1].to_i
         %w(start end).each { |key| facet_values.delete(key) }
         super(facet_values.to_a.flatten, field)
@@ -84,12 +109,18 @@ module Sunspot
       end
     end
 
+    # 
+    # QueryFacetData encapsulates the data returned by a query facet.
+    #
     class QueryFacetData < Abstract
       def initialize(outgoing_query_facet, row_data) #:nodoc:
         @outgoing_query_facet, @row_data = outgoing_query_facet, row_data
         @field = @outgoing_query_facet.field
       end
 
+      # 
+      # Use the name defined by the user
+      #
       def name
         outgoing_query_facet.name
       end
@@ -106,13 +137,31 @@ module Sunspot
         @rows ||=
           begin
             rows = []
-            for row in  @outgoing_query_facet.rows
-              row_query = row.to_boolean_phrase
+            options = @outgoing_query_facet.options
+            minimum_count =
+              if options[:zeros] then 0
+              elsif options[:minimum_count] then options[:minimum_count]
+              else 1
+              end
+            for outgoing_row in  @outgoing_query_facet.rows
+              row_query = outgoing_row.to_boolean_phrase
               if @row_data.has_key?(row_query)
-                rows << yield(row.label, @row_data[row_query])
+                row = yield(outgoing_row.label, @row_data[row_query])
+                rows << row if row.count >= minimum_count
               end
             end
-            rows.sort! { |x, y| y.count <=> x.count }
+            if options[:sort] == :index || !options[:limit] && options[:sort] != :count
+              if rows.all? { |row| row.value.respond_to?(:<=>) }
+                rows.sort! { |x, y| x.value <=> y.value }
+              end
+            else
+              rows.sort! { |x, y| y.count <=> x.count }
+            end
+            if limit = options[:limit]
+              rows[0, limit]
+            else
+              rows
+            end
           end
       end
     end

data/lib/sunspot/facet_row.rb

@@ -1,5 +1,7 @@
 module Sunspot
+  #
   # This class encapsulates a facet row (value) for a facet.
+  #
   class FacetRow
     attr_reader :value, :count