nxa-sunspot 0.10.7

data/lib/sunspot/dsl/query.rb

@@ -0,0 +1,162 @@
+module Sunspot
+  module DSL #:nodoc:
+    #
+    # This class presents a DSL for constructing queries using the
+    # Sunspot.search method. Methods of this class are available inside the
+    # search block. Much of the DSL's functionality is implemented by this
+    # class's superclasses, Sunspot::DSL::FieldQuery and Sunspot::DSL::Scope
+    #
+    # See Sunspot.search for usage examples
+    #
+    class Query < FieldQuery
+      # Specify a phrase that should be searched as fulltext. Only +text+
+      # fields are searched - see DSL::Fields.text
+      #
+      # Keyword search is executed using Solr's dismax handler, which strikes
+      # a good balance between powerful and foolproof. In particular,
+      # well-matched quotation marks can be used to group phrases, and the
+      # + 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
+      #
+      # ==== Options
+      #
+      # :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.
+      # :minimum_match<Integer>::
+      #   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.
+      # :tie<Float>::
+      #   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.
+      # :query_phrase_slop<Integer>::
+      #   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 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 fulltext(keywords, options = {}, &block)
+        if keywords && !(keywords.to_s =~ /^\s*$/)
+          fulltext_query = @query.set_fulltext(keywords)
+          if field_names = options.delete(:fields)
+            Util.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 minimum_match = options.delete(:minimum_match)
+            fulltext_query.minimum_match = minimum_match.to_i
+          end
+          if tie = options.delete(:tie)
+            fulltext_query.tie = tie.to_f
+          end
+          if query_phrase_slop = options.delete(:query_phrase_slop)
+            fulltext_query.query_phrase_slop = query_phrase_slop.to_i
+          end
+          if highlight_field_names = options.delete(:highlight)
+            if highlight_field_names == true
+              fulltext_query.add_highlight
+            else
+              highlight_fields = []
+              Util.Array(highlight_field_names).each do |field_name|
+                highlight_fields.concat(@setup.text_fields(field_name))
+              end
+              fulltext_query.add_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)
+                unless fulltext_dsl && fulltext_dsl.exclude_fields.include?(field.name)
+                  fulltext_query.add_fulltext_field(field, field.default_boost)
+                end
+              end
+            end
+          end
+        end
+      end
+      alias_method :keywords, :fulltext
+
+      # 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
+
+      # <strong>Expert:</strong> Adjust or reset the parameters passed to Solr.
+      # The adjustment will take place just before sending the params to solr,
+      # after Sunspot builds the Solr params based on the methods called in the
+      # DSL.
+      #
+      # Under normal circumstances, using this method should not be necessary;
+      # if you find that it is, please consider submitting a feature request.
+      # Using this method requires knowledge of Sunspot's internal Solr schema
+      # and Solr query representations, which are not part of Sunspot's public
+      # API; they could change at any time. <strong>This method is unsupported
+      # and your mileage may vary.</strong>
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     adjust_solr_params do |params|
+      #       params[:q] += ' AND something_s:more'
+      #     end
+      #   end
+      # 
+      def adjust_solr_params( &block )
+        @query.set_solr_parameter_adjustment( block )
+      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
+    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

data/lib/sunspot/dsl/scope.rb

@@ -0,0 +1,225 @@
+module Sunspot
+  module DSL #:nodoc:
+    # 
+    # This DSL presents methods for constructing restrictions and other query
+    # elements that are specific to fields. As well as being a superclass of
+    # Sunspot::DSL::Query, which presents the main query block, this DSL class
+    # is also used directly inside the #dynamic() block, which only allows
+    # operations on specific fields.
+    #
+    class Scope
+      NONE = Object.new
+
+      def initialize(scope, setup) #:nodoc:
+        @scope, @setup = scope, setup
+      end
+
+      # 
+      # Build a positive restriction. With one argument, this method returns
+      # another DSL object which presents methods for attaching various
+      # restriction types. With two arguments, this creates a shorthand
+      # restriction: if the second argument is a scalar, an equality restriction
+      # is created; if it is a Range, a between restriction will be created; and
+      # if it is an Array, an any_of restriction will be created.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field on which to place the restriction
+      # value<Object,Range,Array>::
+      #   If passed, creates an equality, range, or any-of restriction based on
+      #   the type of value passed.
+      #
+      # ==== Returns
+      #
+      # Sunspot::DSL::Query::Restriction::
+      #   Restriction DSL object (if only one argument is passed)
+      #
+      # ==== Examples
+      #
+      # An equality restriction:
+      #
+      #   Sunspot.search do
+      #     with(:blog_id, 1)
+      #   end
+      #
+      # Restrict by range:
+      #
+      #   Sunspot.search do
+      #     with(:average_rating, 3.0..5.0)
+      #   end
+      #
+      # Restrict by a set of allowed values:
+      #
+      #   Sunspot.search do
+      #     with(:category_ids, [1, 5, 9])
+      #   end
+      # 
+      # Other restriction types:
+      #
+      #   Sunspot.search(Post) do
+      #     with(:average_rating).greater_than(3.0)
+      #   end
+      #
+      def with(field_name, value = NONE)
+        if value == NONE
+          DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, false)
+        else
+          @scope.add_shorthand_restriction(@setup.field(field_name), value)
+        end
+      end
+
+      # 
+      # Build a negative restriction (exclusion). This method can take three
+      # forms: equality exclusion, exclusion by another restriction, or identity
+      # exclusion. The first two forms work the same way as the #with method;
+      # the third excludes a specific instance from the search results.
+      #
+      # ==== Parameters (exclusion by field value)
+      #
+      # field_name<Symbol>:: Name of the field on which to place the exclusion
+      # value<Symbol>::
+      #   If passed, creates an equality exclusion with this value
+      #
+      # ==== Parameters (exclusion by identity)
+      #
+      # args<Object>...::
+      #   One or more instances that should be excluded from the results
+      #
+      # ==== Examples
+      #
+      # An equality exclusion:
+      #
+      #   Sunspot.search(Post) do
+      #     without(:blog_id, 1)
+      #   end
+      # 
+      # Other restriction types:
+      #
+      #   Sunspot.search(Post) do
+      #     without(:average_rating).greater_than(3.0)
+      #   end
+      #
+      # Exclusion by identity:
+      #
+      #   Sunspot.search(Post) do
+      #     without(some_post_instance)
+      #   end
+      #
+      def without(*args)
+        case args.first
+        when String, Symbol
+          field_name = args[0]
+          value = args.length > 1 ? args[1] : NONE
+          if value == NONE
+            DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, true)
+          else
+            @scope.add_negated_shorthand_restriction(@setup.field(field_name.to_sym), value)
+          end
+        else
+          instances = args
+          instances.flatten.each do |instance|
+            @scope.add_negated_restriction(
+              IdField.instance,
+              Sunspot::Query::Restriction::EqualTo,
+              Sunspot::Adapters::InstanceAdapter.adapt(instance).index_id
+            )
+          end
+        end
+      end
+
+      # 
+      # Create a disjunction, scoping the results to documents that match any
+      # of the enclosed restrictions.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     any_of do
+      #       with(:expired_at).greater_than Time.now
+      #       with :expired_at, nil
+      #     end
+      #   end
+      #
+      # This will return all documents who either have an expiration time in the
+      # future, or who do not have any expiration time at all.
+      #
+      def any_of(&block)
+        Util.instance_eval_or_call(Scope.new(@scope.add_disjunction, @setup), &block)
+      end
+
+      # 
+      # Create a conjunction, scoping the results to documents that match all of
+      # the enclosed restrictions. When called from the top level of a search
+      # block, this has no effect, but can be useful for grouping a conjunction
+      # inside a disjunction.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     any_of do
+      #       with(:blog_id, 1)
+      #       all_of do
+      #         with(:blog_id, 2)
+      #         with(:category_ids, 3)
+      #       end
+      #     end
+      #   end
+      #
+      def all_of(&block)
+        Util.instance_eval_or_call(Scope.new(@scope.add_conjunction, @setup), &block)
+      end
+
+      #
+      # Apply restrictions, facets, and ordering to dynamic field instances.
+      # The block API is implemented by Sunspot::DSL::FieldQuery, which is a
+      # superclass of the Query DSL (thus providing a subset of the API, in
+      # particular only methods that refer to particular fields).
+      # 
+      # ==== Parameters
+      # 
+      # base_name<Symbol>:: The base name for the dynamic field definition
+      #
+      # ==== Example
+      #
+      #   Sunspot.search Post do
+      #     dynamic :custom do
+      #       with :cuisine, 'Pizza'
+      #       facet :atmosphere
+      #       order_by :chef_name
+      #     end
+      #   end
+      #
+      def dynamic(base_name, &block)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@scope, @setup.dynamic_field_factory(base_name)),
+          &block
+        )
+      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