sunspot 0.9.8 → 0.10.0

data/lib/sunspot/field.rb

@@ -3,12 +3,13 @@ module Sunspot
     attr_accessor :name # The public-facing name of the field
     attr_accessor :type # The Type of the field
     attr_accessor :reference # Model class that the value of this field refers to
-    attr_accessor :attributes
+    attr_reader :attributes
 
     # 
     #
-    def initialize(name, type) #:nodoc
+    def initialize(name, type, options = {}) #:nodoc
       @name, @type = name.to_sym, type
+      @stored = !!options.delete(:stored)
       @attributes = {}
     end
 
@@ -76,6 +77,15 @@ module Sunspot
     def multiple?
       !!@multiple
     end
+
+    def hash
+      indexed_name.hash
+    end
+
+    def eql?(field)
+      indexed_name == field.indexed_name
+    end
+    alias_method :==, :eql?
   end
 
   # 
@@ -87,14 +97,21 @@ module Sunspot
   # to do otherwise). FulltextField instances always have the type TextType.
   #
   class FulltextField < Field #:nodoc:
+    attr_reader :boost, :default_boost
+
     def initialize(name, options = {})
-      super(name, Type::TextType)
-      if options.has_key?(:boost)
-        @attributes[:boost] = options.delete(:boost)
-      end
+      super(name, Type::TextType, options)
       @multiple = true
+      if boost = options.delete(:boost)
+        @attributes[:boost] = boost
+      end
+      @default_boost = options.delete(:default_boost)
       raise ArgumentError, "Unknown field option #{options.keys.first.inspect} provided for field #{name.inspect}" unless options.empty?
     end
+
+    def indexed_name
+      "#{super}#{'s' if @stored}"
+    end
   end
 
   # 
@@ -106,7 +123,7 @@ module Sunspot
   #
   class AttributeField < Field #:nodoc:
     def initialize(name, type, options = {})
-      super(name, type)
+      super(name, type, options)
       @multiple = !!options.delete(:multiple)
       @reference =
         if (reference = options.delete(:references)).respond_to?(:name)
@@ -114,7 +131,6 @@ module Sunspot
         elsif reference.respond_to?(:to_sym)
           reference.to_sym
         end
-      @stored = !!options.delete(:stored)
       raise ArgumentError, "Unknown field option #{options.keys.first.inspect} provided for field #{name.inspect}" unless options.empty?
     end
 
@@ -131,27 +147,35 @@ module Sunspot
     end
   end
 
-  # 
-  # RandomField instances are used for random sorting.
-  #
-  class RandomField #:nodoc:
-    # 
-    # Never multiple, but this has to return false so Sunspot doesn't barf
-    # when you try to order by it.
-    #
-    def multiple?
-      false
+  class TypeField #:nodoc:
+    class <<self
+      def instance
+        @instance ||= new
+      end
+    end
+
+    def indexed_name
+      'type'
+    end
+
+    def to_indexed(clazz)
+      clazz.name
+    end
+  end
+
+  class IdField #:nodoc:
+    class <<self
+      def instance
+        @instance ||= new
+      end
     end
 
-    # 
-    # Solr uses the dynamic field name as a seed for random, so we randomize the
-    # field name accordingly.
-    #
-    # #XXX I think it's bad to use a random number as a seed. Would it be
-    # better to pass in the current timestamp or some such thing?
-    #
     def indexed_name
-      "random_#{rand(1<<16)}"
+      'id'
+    end
+
+    def to_indexed(id)
+      id.to_s
     end
   end
 end

data/lib/sunspot/field_factory.rb

@@ -122,5 +122,20 @@ module Sunspot
         [@name, @type]
       end
     end
+
+    #XXX Right now this doubles as a Field and a FieldFactory - good idea?
+    class Coordinates
+      def initialize(name)
+        @data_extractor = DataExtractor::AttributeExtractor.new(name)
+      end
+
+      def populate_document(document, model)
+        if coordinates = @data_extractor.value_for(model)
+          coordinates = Util::Coordinates.new(coordinates)
+          document.add_field(:lat, coordinates.lat)
+          document.add_field(:long, coordinates.lng)
+        end
+      end
+    end
   end
 end

data/lib/sunspot/indexer.rb

@@ -49,10 +49,16 @@ module Sunspot
       @connection.delete_by_query("type:#{escape(clazz.name)}")
     end
 
+    # 
+    # Start batch processing
+    #
     def start_batch
       @batch = []
     end
 
+    #
+    # Write batch out to Solr and clear it
+    #
     def flush_batch
       add_documents(@batch)
       @batch = nil

data/lib/sunspot/instantiated_facet.rb

@@ -4,6 +4,9 @@ module Sunspot
   # primary key stored in facet rows' values. The rows are hydrated lazily, but
   # all rows are hydrated the first time #instance is called on any of the rows.
   #
+  # Instatiated facets are possible for fields which are defined with a
+  # :references option.
+  #
   # The #rows method returns InstantiatedFacetRow objects.
   #
   class InstantiatedFacet < Facet
@@ -26,17 +29,11 @@ module Sunspot
       end
     end
 
-    def rows
-      @facet_data.rows { |value, count| InstantiatedFacetRow.new(value, count, self) }
-    end
-
-    private
-
     # 
-    # Override the Facet#new_row method to return an InstantiateFacetRow
+    # A collection of InstantiatedFacetRow objects
     #
-    def new_row(pair)
-      InstantiatedFacetRow.new(pair, self)
+    def rows
+      @facet_data.rows { |value, count| InstantiatedFacetRow.new(value, count, self) }
     end
   end
 end

data/lib/sunspot/instantiated_facet_row.rb

@@ -1,8 +1,13 @@
 module Sunspot
+  # 
+  # InstantiatedFacetRow objects represent a single value for an instantiated
+  # facet. As well as the usual FacetRow methods, InstantedFacetRow objects
+  # provide access to the persistent object referenced by the row's value.
+  #
   class InstantiatedFacetRow < FacetRow
-    attr_writer :instance
+    attr_writer :instance #:nodoc:
 
-    def initialize(value, count, facet)
+    def initialize(value, count, facet) #:nodoc:
       super(value, count)
       @facet = facet
     end

data/lib/sunspot/query/boost_query.rb

@@ -0,0 +1,20 @@
+module Sunspot
+  module Query
+    # 
+    # Representation of a BoostQuery, which allows the searcher to specify a
+    # scope for which matching documents should have an extra boost. This is
+    # essentially a conjunction, with an extra instance variable containing
+    # the boost that should be applied.
+    #
+    class BoostQuery < Connective::Conjunction #:nodoc:
+      def initialize(boost)
+        super(false)
+        @boost = boost
+      end
+
+      def to_boolean_phrase
+        "#{super}^#{@boost}"
+      end
+    end
+  end
+end

data/lib/sunspot/query/connective.rb

@@ -1,55 +1,110 @@
 module Sunspot
   module Query
-    module Connective #:nodoc:
+    module Connective #:nodoc:all
       # 
       # Base class for connectives (conjunctions and disjunctions).
       #
-      class Abstract < Scope
-        def initialize(setup, negated = false) #:nodoc:
-          @setup, @negated = setup, negated
+      class Abstract
+        def initialize(negated = false) #:nodoc:
+          @negated = negated
           @components = []
         end
 
         # 
-        # Connective as solr params.
+        # Add a restriction to the connective.
         #
-        def to_params #:nodoc:
-          { :fq => to_boolean_phrase }
+        def add_restriction(field, restriction_type, value, negated = false)
+          @components << restriction_type.new(field, value, negated)
         end
 
         # 
-        # Express the connective as a Lucene boolean phrase.
+        # Add a shorthand restriction; the restriction type is determined by
+        # the value.
         #
-        def to_boolean_phrase #:nodoc:
-          phrase = if @components.length == 1
-            @components.first.to_boolean_phrase
-          else
-            component_phrases = @components.map do |component|
-              component.to_boolean_phrase
+        def add_shorthand_restriction(field, value, negated = false)
+          restriction_type =
+            case value
+            when Array then Restriction::AnyOf
+            when Range then Restriction::Between
+            else Restriction::EqualTo
             end
-            "(#{component_phrases.join(" #{connector} ")})"
-          end
-          if negated?
-            "-#{phrase}"
-          else
-            phrase
-          end
+          add_restriction(field, restriction_type, value, negated)
+        end
+
+        # 
+        # Add a negated restriction. The added restriction will match all
+        # documents who do not match the terms of the restriction.
+        #
+        def add_negated_restriction(field, restriction_type, value)
+          add_restriction(field, restriction_type, value, true)
+        end
+
+        # 
+        # Add a negated shorthand restriction (see add_shorthand_restriction)
+        #
+        def add_negated_shorthand_restriction(field, value)
+          add_shorthand_restriction(field, value, true)
+        end
+
+        # 
+        # Add a new conjunction and return it.
+        #
+        def add_conjunction
+          add_component(Conjunction.new)
+        end
+
+        # 
+        # Add a new disjunction and return it.
+        #
+        def add_disjunction
+          add_component(Disjunction.new)
         end
 
         # 
-        # Add a component to the connective. All components must implement the
-        # #to_boolean_phrase method.
+        # Add an arbitrary component to the conjunction, and return it.
+        # The component must respond to #to_boolean_phrase
         #
-        def add_component(component) #:nodoc:
+        def add_component(component)
           @components << component
+          component
         end
 
+        # 
+        # Express the connective as a Lucene boolean phrase.
+        #
+        def to_boolean_phrase #:nodoc:
+          unless @components.empty?
+            phrase =
+              if @components.length == 1
+                @components.first.to_boolean_phrase
+              else
+                component_phrases = @components.map do |component|
+                  component.to_boolean_phrase
+                end
+                "(#{component_phrases.join(" #{connector} ")})"
+              end
+            if negated?
+              "-#{phrase}"
+            else
+              phrase
+            end
+          end
+        end
+
+        # 
+        # Connectives can be negated during the process of denormalization that
+        # is performed when a disjunction contains a negated component. This
+        # method conforms to the duck type for all boolean query components.
+        #
         def negated?
           @negated
         end
 
+        # 
+        # Returns a new connective that's a negated version of this one.
+        #
         def negate
-          negated = self.class.new(@setup, !negated?)
+          negated = self.class.new(!negated?)
           for component in @components
             negated.add_component(component)
           end
@@ -67,6 +122,9 @@ module Sunspot
           end
         end
 
+        # 
+        # Express this disjunction as a Lucene boolean phrase
+        #
         def to_boolean_phrase
           if @components.any? { |component| component.negated? }
             denormalize.to_boolean_phrase
@@ -76,16 +134,8 @@ module Sunspot
         end
 
         # 
-        # Add a conjunction to the disjunction. This overrides the method in
-        # the Scope class since scopes are implicitly conjunctive and thus
-        # can return themselves as a conjunction. Inside a disjunction, however,
-        # a conjunction must explicitly be created.
+        # No-op - this is already a disjunction
         #
-        def add_conjunction
-          @components << conjunction = Conjunction.new(setup)
-          conjunction
-        end
-
         def add_disjunction
           self
         end
@@ -96,8 +146,17 @@ module Sunspot
           'OR'
         end
 
+        # 
+        # If a disjunction contains negated components, it must be
+        # "denormalized", because the Lucene parser interprets any negated
+        # boolean phrase using AND semantics (this isn't a bug, it's just a
+        # subtlety of how Lucene parses queries). So, per DeMorgan's law we
+        # create a negated conjunction and add to it all of our components,
+        # negated themselves, which creates a query whose Lucene semantics are
+        # in line with our intentions.
+        #
         def denormalize
-          denormalized = self.class.inverse.new(@setup, !negated?)
+          denormalized = self.class.inverse.new(!negated?)
           for component in @components
             denormalized.add_component(component.negate)
           end
@@ -115,6 +174,10 @@ module Sunspot
           end
         end
 
+        def add_conjunction
+          self
+        end
+
         private
 
         def connector

data/lib/sunspot/query/dismax.rb

@@ -0,0 +1,69 @@
+module Sunspot
+  module Query
+    class Dismax
+      def initialize(keywords)
+        @keywords = keywords
+        @fulltext_fields = {}
+      end
+
+      # 
+      # The query as Solr parameters
+      #
+      def to_params
+        params = { :q => @keywords }
+        params[:fl] = '* score'
+        params[:qf] = @fulltext_fields.values.map { |field| field.to_boosted_field }.join(' ')
+        params[:defType] = 'dismax'
+        if @phrase_fields
+          params[:pf] = @phrase_fields.map { |field| field.to_boosted_field }.join(' ')
+        end
+        if @boost_query
+          params[:bq] = @boost_query.to_boolean_phrase
+        end
+        if @highlight
+          Sunspot::Util.deep_merge!(params, @highlight.to_params)
+        end
+        params
+      end
+
+      # 
+      # Assign a new boost query and return it.
+      #
+      def create_boost_query(factor)
+        @boost_query = BoostQuery.new(factor)
+      end
+
+      # 
+      # Add a fulltext field to be searched, with optional boost
+      #
+      def add_fulltext_field(field, boost = nil)
+        @fulltext_fields[field.indexed_name] = TextFieldBoost.new(field, boost)
+      end
+
+      #
+      # Add a phrase field for extra boost
+      #
+      def add_phrase_field(field, boost = nil)
+        @phrase_fields ||= []
+        @phrase_fields << TextFieldBoost.new(field, boost)
+      end
+
+      # 
+      # Set highlighting options for the query. If fields is empty, the
+      # Highlighting object won't pass field names at all, which means
+      # the dismax's :qf parameter will be used by Solr.
+      #
+      def set_highlight(fields=[], options={})
+        @highlight = Highlighting.new(fields, options)
+      end
+
+      # 
+      # Determine if a given field is being searched. Used by DSL to avoid
+      # overwriting boost parameters when injecting defaults.
+      #
+      def has_fulltext_field?(field)
+        @fulltext_fields.has_key?(field.indexed_name)
+      end
+    end
+  end
+end

data/lib/sunspot/query/field_facet.rb

@@ -29,7 +29,7 @@ module Sunspot
             end
             DateFieldFacet.new(field, options)
           elsif options.has_key?(:only)
-            QueryFieldFacet.new(field, options.delete(:only))
+            QueryFieldFacet.new(field, options.delete(:only), options)
           else
             FieldFacet.new(field, options)
           end
@@ -78,8 +78,6 @@ module Sunspot
     end
 
     class DateFieldFacet < FieldFacet #:nodoc:
-      ALLOWED_OTHER = Set.new(%w(before after between none all))
-
       # 
       # Convert the facet to date params.
       #
@@ -126,25 +124,6 @@ module Sunspot
       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/fulltext_base_query.rb

@@ -0,0 +1,47 @@
+module Sunspot
+  module Query
+    class FulltextBaseQuery < BaseQuery #:nodoc:
+      def initialize(keywords, options, types, setup)
+        super(types, setup)
+        @keywords = keywords
+
+        if highlight_options = options.delete(:highlight)
+          set_highlight(highlight_options == true ? [] : highlight_options)
+        end
+
+        if fulltext_fields = options.delete(:fields)
+          Array(fulltext_fields).each do |field|
+            add_fulltext_field(field)
+          end
+        end
+      end
+
+
+      private
+
+      def text_fields(field_names)
+        field_names.inject([]) do |fields, name|
+          fields.concat(@setup.text_fields(name))
+        end
+      end
+
+      # 
+      # Returns the names of text fields that should be queried in a keyword
+      # search. If specific fields are requested, use those; otherwise use the
+      # union of all fields configured for the types under search.
+      #
+      def query_fields
+        @query_fields ||=
+          begin
+            fulltext_fields =
+              @fulltext_fields || @setup.all_text_fields.map do |field|
+                TextFieldBoost.new(field)
+              end
+            fulltext_fields.map do |fulltext_field|
+              fulltext_field.to_boosted_field
+            end.join(' ')
+          end
+      end
+    end
+  end
+end

data/lib/sunspot/query/highlighting.rb

@@ -0,0 +1,43 @@
+module Sunspot
+  module Query
+    #
+    # A query component that builds parameters for requesting highlights
+    #
+    class Highlighting #:nodoc:
+      def initialize(fields=[], options={})
+        @fields  = fields
+        @options = options
+      end
+
+      # 
+      # Return Solr highlighting params
+      #
+      def to_params
+        params = {
+          :hl => 'on',
+          :"hl.simple.pre" => '@@@hl@@@',
+          :"hl.simple.post" => '@@@endhl@@@'
+        }
+        unless @fields.empty?
+          params[:"hl.fl"] = @fields.map { |field| field.indexed_name }
+        end
+        if max_snippets = @options[:max_snippets]
+          params[:"hl.snippets"] = max_snippets
+        end
+        if fragment_size = @options[:fragment_size]
+          params[:"hl.fragsize"] = fragment_size
+        end
+        if @options[:merge_continuous_fragments]
+          params[:"hl.mergeContinuous"] = 'true'
+        end
+        if @options[:phrase_highlighter]
+          params[:"hl.usePhraseHighlighter"] = 'true'
+          if @options[:require_field_match]
+            params[:"hl.requireFieldMatch"] = 'true'
+          end
+        end
+        params
+      end
+    end
+  end
+end

data/lib/sunspot/query/local.rb

@@ -0,0 +1,24 @@
+module Sunspot
+  module Query
+    # 
+    # This query component generates parameters for LocalSolr geo-radial
+    # searches. The LocalSolr API is fairly rigid, so the Local component
+    # doesn't have any options - it just takes coordinates and a radius, and
+    # generates the appropriate parameters.
+    #
+    class Local #:nodoc:
+      def initialize(coordinates, radius)
+        @coordinates, @radius = Util::Coordinates.new(coordinates), radius
+      end
+
+      def to_params
+        {
+          :qt => 'geo',
+          :lat => @coordinates.lat,
+          :long => @coordinates.lng,
+          :radius => @radius
+        }
+      end
+    end
+  end
+end

data/lib/sunspot/query/pagination.rb

@@ -8,8 +8,7 @@ module Sunspot
     class Pagination #:nodoc:
       attr_reader :page, :per_page
 
-      def initialize(configuration, page = nil, per_page = nil)
-        @configuration = configuration
+      def initialize(page = nil, per_page = nil)
         self.page, self.per_page = page, per_page
       end
 
@@ -18,11 +17,11 @@ module Sunspot
       end
 
       def page=(page)
-        @page = page || 1
+        @page = page.to_i if page
       end
 
       def per_page=(per_page)
-        @per_page = per_page || @configuration.pagination.default_per_page
+        @per_page = per_page.to_i if per_page
       end
 
       private