outoftime-sunspot 0.8.9 → 0.9.0

data/lib/sunspot/dsl/query_facet.rb

@@ -0,0 +1,31 @@
+module Sunspot
+  module DSL
+    # 
+    # This tiny DSL class implements the DSL for the FieldQuery.facet
+    # method.
+    #
+    class QueryFacet
+      def initialize(query_facet) #:nodoc:
+        @query_facet = query_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)
+        Scope.new(@query_facet.add_row(label)).instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/scope.rb

@@ -17,14 +17,17 @@ module Sunspot
       # 
       # Build a positive restriction. With one argument, this method returns
       # another DSL object which presents methods for attaching various
-      # restriction types. With two arguments, acts as a shorthand for creating
-      # an equality restriction.
+      # 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<Symbol>::
-      #   If passed, creates an equality restriction with this value
+      # value<Object,Range,Array>::
+      #   If passed, creates an equality, range, or any-of restriction based on
+      #   the type of value passed.
       #
       # ==== Returns
       #
@@ -38,6 +41,18 @@ module Sunspot
       #   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:
       #
@@ -49,7 +64,7 @@ module Sunspot
         if value == NONE
           DSL::Restriction.new(field_name.to_sym, @query, false)
         else
-          @query.add_restriction(field_name, Sunspot::Query::Restriction::EqualTo, value, false)
+          @query.add_shorthand_restriction(field_name, value)
         end
       end
 
@@ -98,7 +113,7 @@ module Sunspot
           if value == NONE
             DSL::Restriction.new(field_name.to_sym, @query, true)
           else
-            @query.add_negated_restriction(field_name, Sunspot::Query::Restriction::EqualTo, value)
+            @query.add_negated_shorthand_restriction(field_name, value)
           end
         else
           instances = args
@@ -108,29 +123,70 @@ module Sunspot
         end
       end
 
-      # Specify the order that results should be returned in. This method can
-      # be called multiple times; precedence will be in the order given.
+      # 
+      # Create a disjunction, scoping the results to documents that match any
+      # of the enclosed restrictions.
       #
-      # ==== Parameters
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     any_of do
+      #       with(:expired_at).greater_than Time.now
+      #       with :expired_at, nil
+      #     end
+      #   end
       #
-      # field_name<Symbol>:: the field to use for ordering
-      # direction<Symbol>:: :asc or :desc (default :asc)
+      # 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 order_by(field_name, direction = nil)
-        @query.order_by(field_name, direction)
+      def any_of(&block)
+        Util.instance_eval_or_call(Scope.new(@query.add_disjunction), &block)
       end
 
-      # Request facets on the given field names. See Sunspot::Search#facet and
-      # Sunspot::Facet for information on what is returned.
+      # 
+      # 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(@query.add_conjunction), &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
       #
-      # field_names...<Symbol>:: fields for which to return field facets
+      # ==== Example
       #
-      def facet(*field_names)
-        for field_name in field_names
-          @query.add_field_facet(field_name)
-        end
+      #   Sunspot.search Post do
+      #     dynamic :custom do
+      #       with :cuisine, 'Pizza'
+      #       facet :atmosphere
+      #       order_by :chef_name
+      #     end
+      #   end
+      #
+      def dynamic(base_name, &block)
+        FieldQuery.new(@query.dynamic_query(base_name)).instance_eval(&block)
       end
     end
   end

data/lib/sunspot/dsl/search.rb

@@ -0,0 +1,30 @@
+module Sunspot
+  module DSL
+    # 
+    # This top-level DSL class is the context in which the block passed to
+    # Sunspot.query. See Sunspot::DSL::Query, Sunspot::DSL::FieldQuery, and
+    # Sunspot::DSL::Scope for the full API presented.
+    #
+    class Search < Query
+      def initialize(search) #:nodoc:
+        @search = search
+        @query = search.query
+      end
+
+      # 
+      # Retrieve the data accessor used to load instances of the given class
+      # out of persistent storage. Data accessors are free to implement any
+      # extra methods that may be useful in this context.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search Post do
+      #     data_acccessor_for(Post).includes = [:blog, :comments]
+      #   end
+      #
+      def data_accessor_for(clazz)
+        @search.data_accessor_for(clazz)
+      end
+    end
+  end
+end

data/lib/sunspot/dsl.rb

@@ -1,3 +1,3 @@
-%w(fields scope query restriction).each do |file|
+%w(fields scope field_query query query_facet restriction search).each do |file|
   require File.join(File.dirname(__FILE__), 'dsl', file)
 end

data/lib/sunspot/facet.rb

@@ -1,12 +1,16 @@
+require 'enumerator'
+
 module Sunspot
   #
   # The facet class encapsulates the information returned by Solr for a
-  # particular facet request.
+  # field facet request.
   #
   # See http://wiki.apache.org/solr/SolrFacetingOverview for more information
   # on Solr's faceting capabilities.
   #
   class Facet
+    attr_reader :field
+
     def initialize(facet_values, field) #:nodoc:
       @facet_values, @field = facet_values, field
     end
@@ -29,9 +33,19 @@ module Sunspot
     # 
     def rows
       @rows ||=
-        @facet_values.map do |facet_value|
-          FacetRow.new(facet_value, @field)
+        begin
+          rows = []
+          @facet_values.each_slice(2) do |pair|
+            rows << new_row(pair)
+          end
+          rows
         end
     end
+
+    private
+
+    def new_row(pair)
+      FacetRow.new(pair, self)
+    end
   end
 end

data/lib/sunspot/facet_row.rb

@@ -1,8 +1,8 @@
 module Sunspot
   # This class encapsulates a facet row (value) for a facet.
   class FacetRow
-    def initialize(facet_value, field) #:nodoc:
-      @facet_value, @field = facet_value, field
+    def initialize(pair, facet) #:nodoc:
+      @pair, @facet = pair, facet
     end
 
     # The value associated with the facet. This will be cast according to the
@@ -17,7 +17,7 @@ module Sunspot
     # Object:: The value associated with the row, cast to the appropriate type
     #
     def value
-      @value ||= @field.cast(@facet_value.name)
+      @value ||= @facet.field.cast(@pair[0])
     end
 
     # The number of documents matching the search parameters that have this
@@ -28,7 +28,7 @@ module Sunspot
     # Integer:: Document count for this value
     #
     def count
-      @count ||= @facet_value.value
+      @count ||= @pair[1]
     end
   end
 end

data/lib/sunspot/field.rb

@@ -1,234 +1,157 @@
 module Sunspot
-  # 
-  # 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
-    #
-    # 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.
-      #
-      # ==== Returns
-      #
-      # String:: The field's indexed name
-      #
-      def indexed_name
-        "#{@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.
-      #
-      # ==== Parameters
-      #
-      # value<Object>:: Value to convert to Solr representation
-      #
-      # ==== Returns
-      #
-      # String:: Solr representation of the object
-      #
-      # ==== Raises
-      #
-      # ArgumentError::
-      #   the value is an array, but this field does not allow multiple values
-      #
-      def to_indexed(value)
-        if value.is_a? Array
-          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)
-        end
-      end
+  class Field #:nodoc:
+    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
 
-      # Cast the value into the appropriate Ruby class for the field's type
-      #
-      # ==== Parameters
-      #
-      # value<String>:: Solr's representation of the value
-      #
-      # ==== Returns
-      #
-      # Object:: The cast value
-      #
-      def cast(value)
-        @type.cast(value)
-      end
-    end
-
-    # 
-    # 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
+    #
+    def initialize(name, type) #:nodoc
+      @name, @type = name.to_sym, type
+      @attributes = {}
     end
 
+    # Convert a value to its representation for Solr indexing. This delegates
+    # to the #to_indexed method on the field's type.
     #
-    # Field classes encapsulate information about a field that has been configured
-    # for search and indexing. They expose methods that are useful for both
-    # operations.
+    # ==== Parameters
     #
-    # Subclasses of Field::Base must implement the method #value_for
+    # value<Object>:: Value to convert to Solr representation
     #
-    class StaticField
-      include FieldInstance
-      extend Buildable
-
-      attr_accessor :name # The public-facing name of the field
-      attr_accessor :type # The Type of the field
-
-      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 model from which to extract the value
-      #
-      # ==== Returns
-      #
-      # Hash:: a single key-value pair with the field name and value
-      #
-      def pairs_for(model)
-        unless (value = @data_extractor.value_for(model)).nil?
-          { indexed_name.to_sym => to_indexed(value) }
+    # ==== Returns
+    #
+    # String:: Solr representation of the object
+    #
+    # ==== Raises
+    #
+    # ArgumentError::
+    #   the value is an array, but this field does not allow multiple values
+    #
+    def to_indexed(value)
+      if value.is_a? Array
+        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)
       end
     end
 
+    # Cast the value into the appropriate Ruby class for the field's type
+    #
+    # ==== Parameters
+    #
+    # value<String>:: Solr's representation of the value
+    #
+    # ==== Returns
+    #
+    # Object:: The cast value
+    #
+    def cast(value)
+      @type.cast(value)
+    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.
-    #
-    # 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
+    # Name with which this field is indexed internally. Based on public name and
+    # type.
+    #
+    # ==== Returns
+    #
+    # String:: Internal name of the field
+    #
+    def indexed_name
+      @type.indexed_name(@name)
+    end
 
-      attr_accessor :name # Base name of the dynamic field.
+    # 
+    # Whether this field accepts multiple values.
+    #
+    # ==== Returns
+    #
+    # Boolean:: True if this field accepts multiple values.
+    #
+    def multiple?
+      !!@multiple
+    end
+  end
 
-      def initialize(name, type, data_extractor, options)
-        @name, @type, @data_extractor = name, type, data_extractor
-        @multiple = !!options.delete(:multiple)
+  # 
+  # FulltextField instances represent fields that are indexed as fulltext.
+  # These fields are tokenized in the index, and can have boost applied to
+  # them. They also always allow multiple values (since the only downside of
+  # allowing multiple values is that it prevents the field from being sortable,
+  # and sorting on tokenized fields is nonsensical anyway, there is no reason
+  # to do otherwise). FulltextField instances always have the type TextType.
+  #
+  class FulltextField < Field #:nodoc:
+    def initialize(name, options = {})
+      super(name, Type::TextType)
+      if options.has_key?(:boost)
+        @attributes[:boost] = options.delete(:boost)
       end
+      @multiple = true
+      raise ArgumentError, "Unknown field option #{options.keys.first.inspect} provided for field #{name.inspect}" unless options.empty?
+    end
+  end
 
-      # 
-      # 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 model from which to extract the value
-      #
-      # ==== Returns
-      #
-      # 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
+  # 
+  # AttributeField instances encapsulate non-tokenized attribute data.
+  # AttributeFields can have any type except TextType, and can also have
+  # a reference (for instantiated facets), optionally allow multiple values
+  # (false by default), and can store their values (false by default). All
+  # scoping, sorting, and faceting is done with attribute fields.
+  #
+  class AttributeField < Field #:nodoc:
+    def initialize(name, type, options = {})
+      super(name, type)
+      @multiple = !!options.delete(:multiple)
+      @reference =
+        if (reference = options.delete(:references)).respond_to?(:name)
+          reference.name
+        elsif reference.respond_to?(:to_sym)
+          reference.to_sym
         end
-        pairs
-      end
+      @stored = !!options.delete(:stored)
+      raise ArgumentError, "Unknown field option #{options.keys.first.inspect} provided for field #{name.inspect}" unless options.empty?
+    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
+    # 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.
+    #
+    # ==== Returns
+    #
+    # String:: The field's indexed name
+    #
+    def indexed_name
+      "#{super}#{'m' if @multiple}#{'s' if @stored}"
     end
+  end
 
+  # 
+  # RandomField instances are used for random sorting.
+  #
+  class RandomField #:nodoc:
     # 
-    # 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
+    # Never multiple, but this has to return false so Sunspot doesn't barf
+    # when you try to order by it.
+    #
+    def multiple?
+      false
+    end
 
-      def name
-        "#{@base_name}:#{@dynamic_name}"
-      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)}"
     end
   end
 end