outoftime-sunspot 0.7.3 → 0.8.0

data/lib/sunspot/field.rb

@@ -1,42 +1,31 @@
 module Sunspot
-  module Field #:nodoc[all]
+  # 
+  # The Field functionality in Sunspot is comprised of two roles:
+  #
+  # Field definitions::
+  #   Field definitions encompass the information that the user enters when
+  #   setting up the field, such as field name, type of access, data type,
+  #   whether multiple values are allowed, etc.
+  #   They are also capable of extracting data from a model in a format
+  #   that can be passed directly to the indexer.
+  # Field instances::
+  #   Field instances represent an actual field in Solr; thus, they are able to
+  #   return the indexed field name, convert the value to its appropriate type,
+  #   etc.
+  #
+  # StaticField objects play both the definition and the instance role.
+  # DynamicField objects act only as definitions, and spawn DynamicFieldInstance
+  # objects to play the instance role.
+  # 
+  module Field #:nodoc: all
     #
-    # Field classes encapsulate information about a field that has been configured
-    # for search and indexing. They expose methods that are useful for both
-    # operations.
-    #
-    # Subclasses of Field::Base must implement the method #value_for
-    #
-    class Base
-      attr_accessor :name # The public-facing name of the field
-      attr_accessor :type # The Type of the field
-
-      def initialize(name, type, options = {}) #:nodoc
-        @name, @type = name.to_sym, type
-        @multiple = options.delete(:multiple)
-        raise ArgumentError, "Unknown field option #{options.keys.first.inspect} provided for field #{name.inspect}" unless options.empty?
-      end
-
-      # A key-value pair where the key is the field's indexed name and the
-      # value is the value that should be indexed for the given model. This can
-      # be merged directly into the document hash for adding to solr-ruby.
-      #
-      # ==== Parameters
-      #
-      # model<Object>:: the model from which to extract the value
-      #
-      # ==== Returns
-      #
-      # Hash:: a single key-value pair with the field name and value
-      #
-      def pair_for(model)
-        unless (value = value_for(model)).nil?
-          { indexed_name.to_sym => to_indexed(value) }
-        else
-          {}
-        end
-      end
-
+    # The FieldInstance module encapsulates functionality associated with
+    # acting as a concrete instance of a field for the purposes of search.
+    # In particular, FieldInstances need to be able to return indexed names,
+    # convert values to their indexed representation, and cast returned values
+    # to the appropriate native Ruby type.
+    # 
+    module FieldInstance
       # The name of the field as it is indexed in Solr. The indexed name
       # contains a suffix that contains information about the type as well as
       # whether the field allows multiple values for a document.
@@ -46,9 +35,9 @@ module Sunspot
       # String:: The field's indexed name
       #
       def indexed_name
-        "#{type.indexed_name(name)}#{'m' if multiple?}"
+        "#{@type.indexed_name(name)}#{'m' if @multiple}"
       end
-
+      
       # Convert a value to its representation for Solr indexing. This delegates
       # to the #to_indexed method on the field's type.
       #
@@ -67,13 +56,13 @@ module Sunspot
       #
       def to_indexed(value)
         if value.is_a? Array
-          if multiple?
+          if @multiple
             value.map { |val| to_indexed(val) }
           else
             raise ArgumentError, "#{name} is not a multiple-value field, so it cannot index values #{value.inspect}"
           end
         else
-          type.to_indexed(value)
+          @type.to_indexed(value)
         end
       end
 
@@ -88,76 +77,157 @@ module Sunspot
       # Object:: The cast value
       #
       def cast(value)
-        type.cast(value)
+        @type.cast(value)
       end
+    end
 
-      # ==== Returns
-      #
-      # Boolean:: true if the field allows multiple values; false if not
-      def multiple?
-        !!@multiple
+    # 
+    # This module adds a (class) method for building a field definition given
+    # a standard set of arguments
+    # 
+    module Buildable
+      #
+      # Build a field definition based on a standard argument API. If a block
+      # is passed, use virtual extraction; otherwise, use attribute extraction.
+      # 
+      def build(name, type, options = {}, &block)
+        data_extractor =
+          if block
+            DataExtractor::BlockExtractor.new(&block)
+          else
+            DataExtractor::AttributeExtractor.new(options.delete(:using) || name)
+          end
+        new(name, type, data_extractor, options)
       end
     end
 
     #
-    # AttributeFields call methods directly on indexed objects and index the
-    # return value of the method. By default, the field name is also the
-    # attribute that provides the value for indexing, but this can be overridden
-    # with the :using option.
+    # Field classes encapsulate information about a field that has been configured
+    # for search and indexing. They expose methods that are useful for both
+    # operations.
     #
-    class AttributeField < Base
-      def initialize(name, type, options = {})
-        @attribute_name = options.delete(:using) || name
-        super
-      end
+    # Subclasses of Field::Base must implement the method #value_for
+    #
+    class StaticField
+      include FieldInstance
+      extend Buildable
 
-      protected
+      attr_accessor :name # The public-facing name of the field
+      attr_accessor :type # The Type of the field
 
-      #
-      # Call the field's attribute name on the given model and return the value.
+      def initialize(name, type, data_extractor, options = {}) #:nodoc
+        unless name.to_s =~ /^\w+$/
+          raise ArgumentError, "Invalid field name #{name}: only letters, numbers, and underscores are allowed."
+        end
+        @name, @type, @data_extractor = name.to_sym, type, data_extractor
+        @multiple = !!options.delete(:multiple)
+        raise ArgumentError, "Unknown field option #{options.keys.first.inspect} provided for field #{name.inspect}" unless options.empty?
+      end
+
+      # A key-value pair where the key is the field's indexed name and the
+      # value is the value that should be indexed for the given model. This can
+      # be merged directly into the document hash for adding to solr-ruby.
       #
       # ==== Parameters
       #
-      # model<Object>:: The object from which to extract the value
+      # model<Object>:: the model from which to extract the value
       #
       # ==== Returns
       #
-      # Object:: The value to index
+      # Hash:: a single key-value pair with the field name and value
       #
-      def value_for(model)
-        model.send(@attribute_name)
+      def pairs_for(model)
+        unless (value = @data_extractor.value_for(model)).nil?
+          { indexed_name.to_sym => to_indexed(value) }
+        else
+          {}
+        end
       end
     end
 
+    # 
+    # A DynamicField is a field definition that allows actual fields to be
+    # dynamically specified at search/index time. Indexed objects specify
+    # the actual fields to be indexed using a hash, whose keys are the dynamic
+    # field names and whose values are the values to be indexed.
     #
-    # VirtualFields extract data by evaluating the provided block in the context
-    # of the model instance.
-    #
-    class VirtualField < Base
-      def initialize(name, type, options = {}, &block)
-        super(name, type, options)
-        @block = block
-      end
+    # When indexed, dynamic fields are stored using the dynamic field's base
+    # name, and the runtime-specified dynamic name, separated by a colon. Since
+    # colons are not permitted in static Sunspot field names, namespace
+    # collisions are prevented.
+    # 
+    # The use cases for dynamic fields are fairly limited, but certain
+    # applications with highly dynamic data models might find them userful.
+    # 
+    class DynamicField
+      extend Buildable
 
-      protected
+      attr_accessor :name # Base name of the dynamic field.
+
+      def initialize(name, type, data_extractor, options)
+        @name, @type, @data_extractor = name, type, data_extractor
+        @multiple = !!options.delete(:multiple)
+      end
 
       # 
-      # Evaluate the block in the model's context and return the block's return
-      # value.
+      # Return a hash whose keys are fully-qualified field names and whose
+      # values are values to be indexed, representing the data to be indexed
+      # by this field definition for this model.
       #
       # ==== Parameters
       #
-      # model<Object>:: The object from which to extract the value
+      # model<Object>:: the model from which to extract the value
       #
       # ==== Returns
       #
-      # Object:: The value to index
-      def value_for(model)
-        if @block.arity <= 0
-          model.instance_eval(&@block)
-        else
-          @block.call(model)
+      # Hash::
+      #   Key-value pairs representing field names and values to be indexed.
+      #
+      # 
+      def pairs_for(model)
+        pairs = {}
+        if values = @data_extractor.value_for(model)
+          values.each_pair do |dynamic_name, value|
+            field_instance = build(dynamic_name)
+            pairs[field_instance.indexed_name.to_sym] = field_instance.to_indexed(value)
+          end
         end
+        pairs
+      end
+
+      # 
+      # Build a DynamicFieldInstance representing an actual field to be indexed
+      # or searched in Solr.
+      # 
+      # ==== Parameters
+      #
+      # dynamic_name<Symbol>:: dynamic name for the field instance
+      #
+      # ==== Returns
+      # 
+      # DynamicFieldInstance:: Dynamic field instance
+      # 
+      def build(dynamic_name)
+        DynamicFieldInstance.new(@name, dynamic_name, @type, @data_extractor, @multiple)
+      end
+    end
+
+    # 
+    # This class represents actual dynamic fields as they are indexed in Solr.
+    # Thus, they have knowledge of the base name and dynamic name, type, etc.
+    # 
+    class DynamicFieldInstance
+      include FieldInstance
+
+      def initialize(base_name, dynamic_name, type, data_extractor, multiple)
+        @base_name, @dynamic_name, @type, @data_extractor, @multiple =
+          base_name, dynamic_name, type, data_extractor, multiple
+      end
+
+      protected
+
+      def name
+        "#{@base_name}:#{@dynamic_name}"
       end
     end
   end

data/lib/sunspot/indexer.rb

@@ -21,7 +21,7 @@ module Sunspot
     def add(model)
       hash = static_hash_for(model)
       for field in @setup.all_fields
-        hash.merge!(field.pair_for(model))
+        hash.merge!(field.pairs_for(model))
       end
       @connection.add(hash)
     end

data/lib/sunspot/query/dynamic_query.rb

@@ -0,0 +1,86 @@
+module Sunspot
+  class Query
+    #
+    # A dynamic query is a proxy object that implements a subset of the API of
+    # the Query class, but wraps a dynamic field definition and thus applies the
+    # query components using dynamic field instances.
+    #--
+    # Dynamic queries do not hold their own state, but rather proxy to the query
+    # that generated them, adding components directly to the owning query's
+    # internal state.
+    #++
+    # DynamicQuery instances are publicly generated by the Query#dynamic_query
+    # factory method.
+    # 
+    class DynamicQuery
+      def initialize(dynamic_field, query) #:nodoc:
+        @dynamic_field, @query = dynamic_field, query
+      end
+
+      # 
+      # Add a restriction based on the dynamic field definition and dynamic name
+      # given.
+      #
+      # ==== Parameters
+      #
+      # dynamic_name<Symbol>::
+      #   Dynamic name to apply to the field in the restriction.
+      # restriction_type<Symbol,Class>::
+      #   Type of restriction to apply (e.g. Sunspot::Query::Restriction::EqualTo), or
+      #   symbol shorthand (e.g. :equal_to)
+      # value::
+      #   Value to apply to the restriction.
+      # negated::
+      #   Whether to negate the restriction (prefer #add_negated_restriction)
+      # 
+      def add_restriction(dynamic_name, restriction_type, value, negated = false)
+        if restriction_type.is_a?(Symbol)
+          restriction_type = Restriction[restriction_type]
+        end
+        @query.add_component(restriction_type.new(@dynamic_field.build(dynamic_name), value, negated))
+      end
+
+      # 
+      # Add a negated restriction based on the dynamic field definition and
+      # dynamic name given.
+      # 
+      # ==== Parameters
+      # 
+      # dynamic_name<Symbol>::
+      #   Dynamic name to apply to the field in the restriction.
+      # restriction_type<Symbol,Class>::
+      #   Type of restriction to apply (e.g. Sunspot::Query::Restriction::EqualTo), or
+      #   symbol shorthand (e.g. :equal_to)
+      # value::
+      #   Value to apply to the restriction.
+      # 
+      def add_negated_restriction(dynamic_name, restriction_type, value)
+        add_restriction(dynamic_name, restriction_type, value, true)
+      end
+
+      # 
+      # Add a field facet based on the dynamic field definition and dynamic name
+      # given.
+      #
+      # ==== Parameters
+      #
+      # dynamic_name<Symbol>:: Dynamic name to facet on
+      # 
+      def add_field_facet(dynamic_name)
+        @query.add_component(FieldFacet.new(@dynamic_field.build(dynamic_name)))
+      end
+
+      # 
+      # Order by the given dynamic field.
+      #
+      # ==== Parameters
+      #
+      # dynamic_name<Symbol>:: Dynamic name of ordering field
+      # direction<Symbol>:: Direction in which to order (:asc, :desc)
+      # 
+      def order_by(dynamic_name, direction)
+        @query.add_component(Sort.new(@dynamic_field.build(dynamic_name), direction))
+      end
+    end
+  end
+end

data/lib/sunspot/{facets.rb → query/field_facet.rb}

@@ -1,5 +1,5 @@
 module Sunspot
-  module Facets
+  class Query
     #
     # Encapsulates a query component representing a field facet. Users create
     # instances using DSL::Query#facet

data/lib/sunspot/query/pagination.rb

@@ -0,0 +1,39 @@
+module Sunspot
+  class 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/restriction.rb

@@ -0,0 +1,223 @@
+module Sunspot
+  class 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:
+        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
+          { :filter_queries => [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
+          "#{Solr::Util.query_parser_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)
+          Solr::Util.query_parser_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
+            "-#{Solr::Util.query_parser_escape(@field.indexed_name)}:[* TO *]"
+          end
+        end
+
+        def to_negative_boolean_phrase
+          unless @value.nil?
+            super
+          else
+            "#{Solr::Util.query_parser_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:#{Solr::Util.query_parser_escape(adapter.index_id)}"
+        end
+      end
+    end
+  end
+end

data/lib/sunspot/query/sort.rb

@@ -0,0 +1,33 @@
+module Sunspot
+  class Query
+    # 
+    # The Sort class is a query component representing a sort by a given field.
+    # 
+    class Sort #:nodoc:
+      ASCENDING = Set.new([:asc, :ascending])
+      DESCENDING = Set.new([:desc, :descending])
+
+      def initialize(field, direction = nil)
+        @field, @direction = field, (direction || :asc).to_sym
+      end
+
+      def to_params
+        { :sort => [{ @field.indexed_name.to_sym => direction_for_solr }] }
+      end
+
+      private
+
+      def direction_for_solr
+        case
+        when ASCENDING.include?(@direction)
+          :ascending
+        when DESCENDING.include?(@direction)
+          :descending
+        else
+          raise ArgumentError,
+                "Unknown sort direction #{@direction}. Acceptable input is: #{(ASCENDING + DESCENDING).map { |input| input.inspect } * ', '}"
+        end
+      end
+    end
+  end
+end