ruben-sunspot 1.1.0

data/lib/sunspot/dsl/fulltext.rb

@@ -0,0 +1,243 @@
+module Sunspot
+  module DSL
+    # 
+    # This DSL exposes the functionality provided by Solr's fulltext Dismax
+    # handler.
+    #
+    class Fulltext
+      attr_reader :exclude_fields #:nodoc:
+
+      # accept function in boost
+      include Functional
+
+      def initialize(query, setup) #:nodoc:
+        @query, @setup = query, setup
+        @fields_added = false
+        @exclude_fields = []
+      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
+
+      # 
+      # Exclude the given fields from the search. All fields that are configured
+      # for the types under search and not listed here will be searched.
+      #
+      def exclude_fields(*field_names)
+        @exclude_fields.concat(field_names)
+      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.add_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
+
+      # 
+      # The maximum number of words that can appear between search terms for a
+      # field to qualify for phrase field boost. See #query_phrase_slop for
+      # examples. Phrase slop is only meaningful if phrase fields are specified
+      # (see #phrase_fields), and it does not have an effect on which results
+      # are returned; only on what their respective boosts are.
+      #
+      def phrase_slop(slop)
+        @query.phrase_slop = slop
+      end
+
+      # 
+      # Boost queries allow specification of an arbitrary scope for which
+      # matching documents should receive an extra boost. You can either specify 
+      # a boost factor and a block, or a boost function. The block is evaluated
+      # in the usual scope DSL, and field names are attribute fields, not text
+      # fields, as in other scope.
+      #
+      # The boost function can be a constant (numeric or string literal), 
+      # a field name or another function. You can build arbitrarily complex 
+      # functions, which are passed transparently to solr.
+      #
+      # This method can be called more than once for different boost queries
+      # with different boosts.
+      #
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     keywords 'super fan' do
+      #       boost(2.0) do
+      #         with(:featured, true)
+      #       end
+      #
+      #       boost(function { sum(:average_rating, product(:popularity, 10)) })
+      #     end
+      #   end
+      #
+      # In the above search, featured posts will receive a boost of 2.0 and all posts 
+      # will be boosted by (average_rating + popularity * 10).
+      #
+      def boost(factor_or_function, &block)
+        if factor_or_function.is_a?(Sunspot::Query::FunctionQuery)
+          @query.add_boost_function(factor_or_function)
+        else
+          Sunspot::Util.instance_eval_or_call(
+            Scope.new(@query.create_boost_query(factor_or_function), @setup),
+            &block
+          )
+        end
+      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|
+          begin
+            @setup.text_fields(field_name).each do |field|
+              @query.add_fulltext_field(field, boost)
+            end
+          rescue Sunspot::UnrecognizedFieldError
+            # We'll let this one slide.
+          end
+        end
+      end
+      
+      #
+      # The minimum number of search terms that a result must match. By
+      # default, all search terms must match; if the number of search terms
+      # is less than this number, the default behavior applies.
+      #
+      def minimum_match(minimum_match)
+        @query.minimum_match = minimum_match
+      end
+
+      #
+      # The number of words that can appear between the words in a
+      # user-entered phrase (i.e., keywords in quotes) and still match. For
+      # instance, in a search for "\"great pizza\"" with a query phrase slop of
+      # 1, "great pizza" and "great big pizza" will match, but "great monster of
+      # a pizza" will not. Default behavior is a query phrase slop of zero.
+      #
+      def query_phrase_slop(slop)
+        @query.query_phrase_slop = slop
+      end
+
+      #
+      # A tiebreaker coefficient for scores derived from subqueries that are
+      # lower-scoring than the maximum score subquery. Typically a near-zero
+      # value is useful. See
+      # http://wiki.apache.org/solr/DisMaxRequestHandler#tie_.28Tie_breaker.29
+      # for more information.
+      #
+      def tie(tie)
+        @query.tie = tie
+      end
+
+      def fields_added? #:nodoc:
+        @fields_added
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/function.rb

@@ -0,0 +1,14 @@
+module Sunspot
+  module DSL
+    class Function #:nodoc:
+      def initialize(functional) #:nodoc:
+        @functional = functional
+      end
+
+      def method_missing(method, *args, &block)
+        function_args = args.map { |arg| @functional.create_function_query(arg) }
+        Sunspot::Query::FunctionalFunctionQuery.new(method, function_args)
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/functional.rb

@@ -0,0 +1,41 @@
+module Sunspot
+  module DSL
+    # 
+    # Mixin DSL to accept functions.
+    #
+    module Functional
+
+      #
+      # Specify a function query with a block that returns an expression.
+      #
+      # === Examples
+      #
+      #   function { 10 }
+      #   function { :average_rating }
+      #   function { sum(:average_rating, 10) }
+      #
+      def function(&block)
+        expression = Sunspot::Util.instance_eval_or_call(
+          Function.new(self),
+          &block
+        )
+        create_function_query(expression)
+      end
+
+      #
+      # Creates an AbstractFunctionQuery from an expression, also called by
+      # Sunspot::DSL::Function
+      #
+      def create_function_query(expression) #:nodoc:
+        if expression.is_a?(Sunspot::Query::FunctionQuery)
+          expression
+        elsif expression.is_a?(Symbol)
+          Sunspot::Query::FieldFunctionQuery.new(@setup.field(expression))
+        else
+          Sunspot::Query::ConstantFunctionQuery.new(expression)
+        end
+      end
+    end
+  end
+end
+

data/lib/sunspot/dsl/more_like_this_query.rb

@@ -0,0 +1,56 @@
+module Sunspot
+  module DSL #:nodoc:
+    #
+    # This class provides the DSL for MoreLikeThis queries.
+    #
+    class MoreLikeThisQuery < FieldQuery
+      include Paginatable, Adjustable
+
+      def fields(*field_names)
+        boosted_fields = field_names.pop if field_names.last.is_a?(Hash)
+        field_names.each do |name|
+          mlt_fields = @setup.more_like_this_fields(name)
+          raise(ArgumentError, "Field #{name} is not setup for more_like_this") if mlt_fields.empty?
+          mlt_fields.each { |field| @query.more_like_this.add_field(field) }
+        end
+        if boosted_fields
+          boosted_fields.each_pair do |field_name, boost|
+            @setup.more_like_this_fields(field_name).each do |field|
+              @query.more_like_this.add_field(field, boost)
+            end
+          end
+        end
+      end
+
+      def minimum_term_frequency(value)
+        @query.more_like_this.minimum_term_frequency = value
+      end
+      alias_method :mintf, :minimum_term_frequency
+      
+      def minimum_document_frequency(value)
+        @query.more_like_this.minimum_document_frequency = value
+      end
+      alias_method :mindf, :minimum_document_frequency
+
+      def minimum_word_length(value)
+        @query.more_like_this.minimum_word_length = value
+      end
+      alias_method :minwl, :minimum_word_length
+
+      def maximum_word_length(value)
+        @query.more_like_this.maximum_word_length = value
+      end
+      alias_method :maxwl, :maximum_word_length
+      
+      def maximum_query_terms(value)
+        @query.more_like_this.maximum_query_terms = value
+      end
+      alias_method :maxqt, :maximum_query_terms
+
+      def boost_by_relevance(should_boost)
+        @query.more_like_this.boost_by_relevance = should_boost
+      end
+      alias_method :boost, :boost_by_relevance
+    end
+  end
+end

data/lib/sunspot/dsl/paginatable.rb

@@ -0,0 +1,28 @@
+module Sunspot
+  module DSL #:nodoc
+    module Paginatable
+      # Paginate your search. This works the same way as WillPaginate's
+      # paginate().
+      #
+      # Note that Solr searches are _always_ paginated. Not calling #paginate is
+      # the equivalent of calling:
+      #
+      #   paginate(:page => 1, :per_page => Sunspot.config.pagination.default_per_page)
+      #
+      # ==== Options (options)
+      #
+      # :page<Integer,String>:: The requested page. The default is 1.
+      #
+      # :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)
+        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
+    end
+  end
+end

data/lib/sunspot/dsl/query_facet.rb

@@ -0,0 +1,36 @@
+module Sunspot
+  module DSL
+    # 
+    # This tiny DSL class implements the DSL for the FieldQuery.facet
+    # method.
+    #
+    class QueryFacet
+      def initialize(query, setup, facet) #:nodoc:
+        @query, @setup, @facet = query, setup, facet
+      end
+
+      # 
+      # Add a row to this query facet. The label argument can be anything; it's
+      # simply the value that's passed into the Sunspot::QueryFacetRow object
+      # corresponding to the row that's created. Use whatever seems most
+      # intuitive.
+      #
+      # The block is evaluated in the context of a Sunspot::DSL::Scope, meaning
+      # any restrictions can be placed on the documents matching this facet row.
+      #
+      # ==== Parameters
+      #
+      # label<Object>::
+      #   An object used to identify this facet row in the results.
+      #
+      def row(label, &block)
+        query_facet = Sunspot::Query::QueryFacet.new
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@query.add_query_facet(query_facet), @setup),
+          &block
+        )
+        @facet.add_row(label, query_facet.to_boolean_phrase)
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/restriction.rb

@@ -0,0 +1,25 @@
+module Sunspot
+  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
+    # 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
+      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)
+            @scope.add_restriction(@field_name, Sunspot::Query::Restriction::#{class_name}, value, @negative)
+          end
+        RUBY
+      end
+    end
+  end
+end