UnderpantsGnome-sunspot 0.9.1.1

data/lib/sunspot/query/field_facet.rb

@@ -0,0 +1,149 @@
+require 'set'
+
+module Sunspot
+  module Query
+    #
+    # Encapsulates a query component representing a field facet. Users create
+    # instances using DSL::Query#facet
+    #
+    class FieldFacet #:nodoc:
+      class <<self
+        protected :new
+
+        # 
+        # Return the appropriate FieldFacet instance for the field and options.
+        # If a :time_range option is specified, and the field type is TimeType,
+        # build a DateFieldFacet. Otherwise, build a normal FieldFacet.
+        #
+        # ==== Returns
+        #
+        # FieldFacet:: FieldFacet instance of appropriate class.
+        #
+        def build(field, options)
+          if options.has_key?(:time_range)
+            unless field.type == Type::TimeType
+              raise(
+                ArgumentError,
+                ":time_range key can only be specified for time fields"
+              )
+            end
+            DateFieldFacet.new(field, options)
+          else
+            FieldFacet.new(field, options)
+          end
+        end
+      end
+
+      def initialize(field, options)
+        @field, @options = field, options
+      end
+
+      # ==== Returns
+      #
+      # Hash:: solr-ruby params for this field facet
+      #
+      def to_params
+        params = { :"facet.field" => [@field.indexed_name], :facet => 'true' }
+        params[param_key(:sort)] = 
+          case @options[:sort]
+          when :count then 'true'
+          when :index then 'false'
+          when nil
+          else raise(ArgumentError, 'Allowed facet sort options are :count and :index')
+          end
+        params[param_key(:limit)] = @options[:limit]
+        params[param_key(:mincount)] =
+          if @options[:minimum_count] then @options[:minimum_count]
+          elsif @options[:zeros] then 0
+          else 1
+          end
+        params
+      end
+
+      private
+
+      # 
+      # Given a facet parameter name, return the appropriate Solr parameter for
+      # this facet.
+      #
+      # ==== Returns
+      #
+      # Symbol:: Solr query parameter key
+      #
+      def param_key(name)
+        :"f.#{@field.indexed_name}.facet.#{name}"
+      end
+    end
+
+    class DateFieldFacet < FieldFacet #:nodoc:
+      ALLOWED_OTHER = Set.new(%w(before after between none all))
+
+      # 
+      # Convert the facet to date params.
+      #
+      def to_params
+        super.merge(
+          :"facet.date" => [@field.indexed_name],
+          param_key('date.start') => start_time.utc.xmlschema,
+          param_key('date.end') => end_time.utc.xmlschema,
+          param_key('date.gap') => "+#{interval}SECONDS",
+          param_key('date.other') => others
+        )
+      end
+
+      private
+
+      # 
+      # Start time for facet range
+      #
+      # ==== Returns
+      #
+      # Time:: Start time
+      #
+      def start_time
+        @options[:time_range].first
+      end
+
+      # 
+      # End time for facet range
+      #
+      # ==== Returns
+      #
+      # Time:: End time
+      #
+      def end_time
+        @options[:time_range].last
+      end
+
+      # 
+      # Time interval that each facet row should cover. Default is 1 day.
+      #
+      # ===== Returns
+      #
+      # Integer:: Time interval in seconds
+      #
+      def interval
+        @options[:time_interval] || 86400
+      end
+
+      # 
+      # Other time ranges to create facet rows for. Allowed values are defined
+      # in ALLOWED_OTHER constant.
+      #
+      def others
+        if others = @options[:time_other]
+          Array(others).map do |other|
+            other = other.to_s
+            unless ALLOWED_OTHER.include?(other)
+              raise(
+                ArgumentError,
+                "#{other.inspect} is not a valid argument for :time_other"
+              )
+            end
+            other
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sunspot/query/field_query.rb

@@ -0,0 +1,57 @@
+module Sunspot
+  module Query
+    # 
+    # This class acts as a base class for query components that encapsulate
+    # operations on fields. It is subclassed by the Query::Query class and the
+    # Query::DynamicQuery class.
+    #
+    class FieldQuery < Scope
+      # 
+      # Add a field facet. See Sunspot::Facet for more information.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field on which to get a facet
+      #
+      # ==== Returns
+      #
+      # FieldFacet:: The field facet object
+      #
+      def add_field_facet(field_name, options = nil)
+        add_component(FieldFacet.build(build_field(field_name), options || {}))
+      end
+
+      # 
+      # Add a query facet.
+      #
+      # ==== Parameters
+      #
+      # name<Symbol>::
+      #   The name associated with the query facet. This is not passed to Solr,
+      #   but allows the user to retrieve the facet result by passing the name
+      #   to the Search#facet method.
+      #
+      # ==== Returns
+      #
+      # QueryFacet:: The query facet object
+      #
+      def add_query_facet(name)
+        add_component(facet = QueryFacet.new(name, setup))
+        query_facets[name.to_sym] = facet
+        facet
+      end
+
+      # 
+      # Set result ordering.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field on which to order
+      # direction<Symbol>:: :asc or :desc (default :asc)
+      #
+      def order_by(field_name, direction = nil)
+        add_sort(Sort.new(build_field(field_name), direction))
+      end
+    end
+  end
+end

data/lib/sunspot/query/pagination.rb

@@ -0,0 +1,39 @@
+module Sunspot
+  module Query
+    # 
+    # A query component that holds information about pagination. Unlike other
+    # query components, this one is mutable, because the query itself holds a
+    # reference to it and updates it if pagination is changed.
+    #
+    class Pagination #:nodoc:
+      attr_reader :page, :per_page
+
+      def initialize(configuration, page = nil, per_page = nil)
+        @configuration = configuration
+        self.page, self.per_page = page, per_page
+      end
+
+      def to_params
+        { :start => start, :rows => rows }
+      end
+
+      def page=(page)
+        @page = page || 1
+      end
+
+      def per_page=(per_page)
+        @per_page = per_page || @configuration.pagination.default_per_page
+      end
+
+      private
+
+      def start
+        (@page - 1) * @per_page
+      end
+
+      def rows
+        @per_page
+      end
+    end
+  end
+end

data/lib/sunspot/query/query_facet.rb

@@ -0,0 +1,72 @@
+module Sunspot
+  module Query
+    # 
+    # QueryFacets encapsulate requests for Sunspot's query faceting capability.
+    # They are created by the FieldQuery#add_query_facet method.
+    #
+    #--
+    #
+    # The actual concept of a QueryFacet is somewhat artificial - it provides a
+    # grouping for the facet at the Sunspot level, which provides a nicer and
+    # more consistent API in Sunspot; Solr does not provide any grouping for
+    # query facet rows, instead returning each requested row individually, keyed
+    # by the boolean phrase used in the facet query.
+    #
+    class QueryFacet
+      attr_reader :name #:nodoc:
+
+      def initialize(name, setup) #:nodoc:
+        @name = name
+        @setup = setup
+        @components = []
+      end
+
+      #
+      # Add a QueryFacetRow to this facet. The label argument becomes the value
+      # of the Sunspot::QueryFacetRow object corresponding to this query facet
+      # row.
+      #
+      # ==== Parameters
+      #
+      # label<Object>::
+      #   An object that will become the value of the result row. Use whatever
+      #   type is most intuitive.
+      #
+      # ==== Returns
+      #
+      # QueryFacetRow:: QueryFacetRow object containing scope for this row
+      #
+      def add_row(label)
+        @components << row = QueryFacetRow.new(label, @setup)
+        row
+      end
+
+      # 
+      # Express this query facet as Solr parameters
+      #
+      # ==== Returns
+      #
+      # Hash:: Solr params hash
+      #
+      def to_params #:nodoc:
+        components = @components.map { |component| component.to_boolean_phrase }
+        components = components.first if components.length == 1
+        {
+          :facet => 'true',
+          :"facet.query" => components
+        }
+      end
+
+      # 
+      # Get query facet rows (used when constructing results)
+      #
+      # ==== Returns
+      #
+      # Array:: Array of QueryFacetRow objects.
+      #
+      def rows #:nodoc:
+        @components
+      end
+    end
+  end
+end

data/lib/sunspot/query/query_facet_row.rb

@@ -0,0 +1,19 @@
+module Sunspot
+  module Query
+    # 
+    # QueryFacetRow objects encapsulate restrictions for a particular
+    # QueryFacet. They also contain a label attribute, which is used as the
+    # value for the search result's corresponding facet row object.
+    #
+    # See Query::Scope for the API provided.
+    #
+    class QueryFacetRow < Connective::Conjunction
+      attr_reader :label #:nodoc:
+
+      def initialize(label, setup) #:nodoc:
+        super(setup)
+        @label = label
+      end
+    end
+  end
+end

data/lib/sunspot/query/restriction.rb

@@ -0,0 +1,225 @@
+module Sunspot
+  module Query
+    module Restriction #:nodoc:
+      class <<self
+        #
+        # Return the names of all of the restriction classes that should be made
+        # available to the DSL.
+        #
+        # ==== Returns
+        # 
+        # Array:: Collection of restriction class names
+        #
+        def names
+          constants - %w(Base SameAs) #XXX this seems ugly
+        end
+
+        def [](restriction_name)
+          @types ||= {}
+          @types[restriction_name.to_sym] ||= const_get(Sunspot::Util.camel_case(restriction_name.to_s))
+        end
+      end
+
+      # 
+      # Subclasses of this class represent restrictions that can be applied to
+      # a Sunspot query. The Sunspot::DSL::Restriction class presents a builder
+      # API for instances of this class.
+      #
+      # Implementations of this class must respond to #to_params and
+      # #to_negative_params. Instead of implementing those methods, they may
+      # choose to implement any of:
+      #
+      # * #to_positive_boolean_phrase, and optionally #to_negative_boolean_phrase
+      # * #to_solr_conditional
+      #
+      class Base #:nodoc:
+        include RSolr::Char
+
+        def initialize(field, value, negative = false)
+          @field, @value, @negative = field, value, negative
+        end
+
+        # 
+        # A hash representing this restriction in solr-ruby's parameter format.
+        # All restriction implementations must respond to this method; however,
+        # the base implementation delegates to the #to_positive_boolean_phrase method, so
+        # subclasses may (and probably should) choose to implement that method
+        # instead.
+        #
+        # ==== Returns
+        #
+        # Hash:: Representation of this restriction as solr-ruby parameters
+        #
+        def to_params
+          { :fq => [to_boolean_phrase] }
+        end
+
+        # 
+        # Return the boolean phrase associated with this restriction object.
+        # Differentiates between positive and negative boolean phrases depending
+        # on whether this restriction is negated.
+        #
+        def to_boolean_phrase
+          unless negative?
+            to_positive_boolean_phrase
+          else
+            to_negative_boolean_phrase
+          end
+        end
+
+        # 
+        # Boolean phrase representing this restriction in the positive. Subclasses
+        # may choose to implement this method rather than #to_params; however,
+        # this method delegates to the abstract #to_solr_conditional method, which
+        # in most cases will be what subclasses will want to implement.
+        # #to_solr_conditional contains the boolean phrase representing the
+        # condition but leaves out the field name (see built-in implementations
+        # for examples)
+        #
+        # ==== Returns
+        #
+        # String:: Boolean phrase for restriction in the positive
+        #
+        def to_positive_boolean_phrase
+          "#{escape(@field.indexed_name)}:#{to_solr_conditional}"
+        end
+
+        # 
+        # Boolean phrase representing this restriction in the negative. Subclasses
+        # may choose to implement this method, but it is not necessary, as the
+        # base implementation delegates to #to_positive_boolean_phrase.
+        #
+        # ==== Returns
+        #
+        # String:: Boolean phrase for restriction in the negative
+        #
+        def to_negative_boolean_phrase
+          "-#{to_positive_boolean_phrase}"
+        end
+
+        protected
+
+        # 
+        # Whether this restriction should be negated from its original meaning
+        #
+        def negative?
+          !!@negative
+        end
+
+        # 
+        # Return escaped Solr API representation of given value
+        #
+        # ==== Parameters
+        #
+        # value<Object>::
+        #   value to convert to Solr representation (default: @value)
+        #
+        # ==== Returns
+        #
+        # String:: Solr API representation of given value
+        #
+        def solr_value(value = @value)
+          escape(@field.to_indexed(value))
+        end
+      end
+
+      # 
+      # Results must have field with value equal to given value. If the value
+      # is nil, results must have no value for the given field.
+      #
+      class EqualTo < Base
+        def to_positive_boolean_phrase
+          unless @value.nil?
+            super
+          else
+            "-#{escape(@field.indexed_name)}:[* TO *]"
+          end
+        end
+
+        def to_negative_boolean_phrase
+          unless @value.nil?
+            super
+          else
+            "#{escape(@field.indexed_name)}:[* TO *]"
+          end
+        end
+
+        private
+
+        def to_solr_conditional
+          "#{solr_value}"
+        end
+      end
+
+      # 
+      # Results must have field with value less than given value
+      #
+      class LessThan < Base
+        private
+
+        def to_solr_conditional
+          "[* TO #{solr_value}]"
+        end
+      end
+
+      # 
+      # Results must have field with value greater than given value
+      #
+      class GreaterThan < Base
+        private
+
+        def to_solr_conditional
+          "[#{solr_value} TO *]"
+        end
+      end
+
+      # 
+      # Results must have field with value in given range
+      #
+      class Between < Base
+        private
+
+        def to_solr_conditional
+          "[#{solr_value(@value.first)} TO #{solr_value(@value.last)}]"
+        end
+      end
+
+      # 
+      # Results must have field with value included in given collection
+      #
+      class AnyOf < Base
+        private
+
+        def to_solr_conditional
+          "(#{@value.map { |v| solr_value v } * ' OR '})"
+        end
+      end
+
+      #
+      # Results must have field with values matching all values in given
+      # collection (only makes sense for fields with multiple values)
+      #
+      class AllOf < Base
+        private
+
+        def to_solr_conditional
+          "(#{@value.map { |v| solr_value v } * ' AND '})"
+        end
+      end
+
+      # 
+      # Result must be the exact instance given (only useful when negated).
+      #
+      class SameAs < Base
+        def initialize(object, negative = false)
+          @object, @negative = object, negative
+        end
+
+        def to_positive_boolean_phrase
+          adapter = Adapters::InstanceAdapter.adapt(@object)
+          "id:#{escape(adapter.index_id)}"
+        end
+      end
+    end
+  end
+end