outoftime-sunspot 0.0.2 → 0.7.0

data/lib/sunspot/dsl/query.rb

@@ -1,22 +1,146 @@
 module Sunspot
   module DSL
+    #
+    # This class presents a DSL for constructing queries using the
+    # Sunspot.search method. Methods of this class are available inside the
+    # search block.
+    #
+    # See Sunspot.search for usage examples
+    #
     class Query
-      def initialize(query)
-        @query = query 
+      NONE = Object.new
+
+      def initialize(query) #:nodoc:
+        @query = query
       end
 
+      # Specify a phrase that should be searched as fulltext. Only +text+
+      # fields are searched - see DSL::Fields.text
+      #
+      # Note that the keywords are passed directly to Solr unadulterated. The
+      # advantage of this is that users can potentially use boolean logic to
+      # make advanced searches. The disadvantage is that syntax errors are
+      # possible. This may get better in a future version; suggestions are
+      # welcome.
+      #
+      # ==== Parameters
+      #
+      # keywords<String>:: phrase to perform fulltext search on
+      #
       def keywords(keywords)
         @query.keywords = keywords
       end
 
-      def with
-        @conditions_builder ||= ::Sunspot::DSL::Scope.new(@query)
+      # 
+      # 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.
+      #
+      # ==== 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
+      #
+      # ==== Returns
+      #
+      # Sunspot::DSL::Restriction::
+      #   Restriction DSL object (if only one argument is passed)
+      #
+      # ==== Examples
+      #
+      # An equality restriction:
+      #
+      #   Sunspot.search do
+      #     with(:blog_id, 1)
+      #   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(field_name.to_sym, @query, false)
+        else
+          @query.add_restriction(field_name, Sunspot::Restriction::EqualTo, value, false)
+        end
       end
 
-      def conditions
-        @query.conditions
+      # 
+      # 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(field_name.to_sym, @query, true)
+          else
+            @query.add_restriction(field_name, Sunspot::Restriction::EqualTo, value, true)
+          end
+        else
+          instances = args
+          for instance in instances.flatten
+            @query.add_component(Sunspot::Restriction::SameAs.new(instance, true))
+          end
+        end
       end
 
+      # 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>:: The requested page (required)
+      #
+      # :per_page<Integer>::
+      #   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) || raise(ArgumentError, "paginate requires a :page argument")
         per_page = options.delete(:per_page)
@@ -24,9 +148,29 @@ module Sunspot
         @query.paginate(page, per_page)
       end
 
+      # Specify the order that results should be returned in. This method can
+      # be called multiple times; precedence will be in the order given.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: the field to use for ordering
+      # direction<Symbol>:: :asc or :desc (default :asc)
+      #
       def order_by(field_name, direction = nil)
         @query.order_by(field_name, direction)
       end
+
+      # Request facets on the given field names. See Sunspot::Search#facet and
+      # Sunspot::Facet for information on what is returned.
+      #
+      # ==== Parameters
+      #
+      # field_names...<Symbol>:: fields for which to return field facets
+      def facet(*field_names)
+        for field_name in field_names
+          @query.add_field_facet(field_name)
+        end
+      end
     end
   end
 end

data/lib/sunspot/dsl/scope.rb

@@ -1,34 +1,24 @@
 module Sunspot
   module DSL
-    class Scope
-      def initialize(query)
-        @query = query
+    # 
+    # 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
+    # Restriction module, with the exception of Base and SameAs. All methods
+    # take a single argument, which is the value to be applied to the
+    # restriction.
+    #
+    class Restriction
+      def initialize(field_name, query, negative)
+        @field_name, @query, @negative = field_name, query, negative
       end
 
-      def method_missing(field_name, *args)
-        if args.length == 0 then RestrictionBuilder.new(field_name, @query)
-        elsif args.length == 1 then @query.add_scope @query.build_condition(field_name, ::Sunspot::Restriction::EqualTo, args.first)
-        else super(field_name.to_sym, *args)
-        end
-      end
-
-      class RestrictionBuilder
-        def initialize(field_name, query)
-          @field_name, @query = field_name, query
-        end
-
-        def method_missing(condition_name, *args)
-          clazz = begin
-                    ::Sunspot::Restriction.const_get(condition_name.to_s.camel_case)
-                  rescue(NameError)
-                    super(condition_name.to_sym, *args)
-                  end
-          if value = args.first
-            @query.add_scope @query.build_condition(@field_name, clazz, args.first)
-          else
-            @query.interpret_condition @field_name, clazz
+      Sunspot::Restriction.names.each do |class_name|
+        method_name = Util.snake_case(class_name)
+        module_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+          def #{method_name}(value)
+            @query.add_restriction(@field_name, Sunspot::Restriction::#{class_name}, value, @negative)
           end
-        end
+        RUBY
       end
     end
   end

data/lib/sunspot/facet.rb

@@ -0,0 +1,37 @@
+module Sunspot
+  #
+  # The facet class encapsulates the information returned by Solr for a
+  # particular facet request.
+  #
+  # See http://wiki.apache.org/solr/SolrFacetingOverview for more information
+  # on Solr's faceting capabilities.
+  #
+  class Facet
+    def initialize(facet_values, field) #:nodoc:
+      @facet_values, @field = facet_values, field
+    end
+
+    # The name of the field that contains this facet's values
+    #
+    # ==== Returns
+    #
+    # Symbol:: The field name
+    # 
+    def field_name
+      @field.name
+    end
+
+    # The rows returned for this facet.
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of FacetRow objects, in the order returned by Solr
+    # 
+    def rows
+      @rows ||=
+        @facet_values.map do |facet_value|
+          FacetRow.new(facet_value, @field)
+        end
+    end
+  end
+end

data/lib/sunspot/facet_row.rb

@@ -0,0 +1,34 @@
+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
+    end
+
+    # The value associated with the facet. This will be cast according to the
+    # field's type; so, for an integer field, this method will return an
+    # integer, etc.
+    #
+    # Note that <strong>+Time+ fields will always return facet values in
+    # UTC</strong>.
+    #
+    # ==== Returns
+    #
+    # Object:: The value associated with the row, cast to the appropriate type
+    #
+    def value
+      @value ||= @field.cast(@facet_value.name)
+    end
+
+    # The number of documents matching the search parameters that have this
+    # value in the facet's field.
+    #
+    # ==== Returns
+    #
+    # Integer:: Document count for this value
+    #
+    def count
+      @count ||= @facet_value.value
+    end
+  end
+end

data/lib/sunspot/facets.rb

@@ -0,0 +1,21 @@
+module Sunspot
+  module Facets
+    #
+    # Encapsulates a query component representing a field facet. Users create
+    # instances using DSL::Query#facet
+    #
+    class FieldFacet #:nodoc:
+      def initialize(field)
+        @field = field
+      end
+
+      # ==== Returns
+      #
+      # Hash:: solr-ruby params for this field facet
+      #
+      def to_params
+        { :facets => { :fields => [@field.indexed_name] }}
+      end
+    end
+  end
+end

data/lib/sunspot/field.rb

@@ -1,39 +1,72 @@
 module Sunspot
-  module Field
+  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, :type
+      attr_accessor :name # The public-facing name of the field
+      attr_accessor :type # The Type of the field
 
-      def initialize(name, type, options = {})
-        @name, @type = name, type
+      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)
-        if value = value_for(model)
+        unless (value = value_for(model)).nil?
           { indexed_name.to_sym => to_indexed(value) }
         else
           {}
         end
       end
 
-      def ==(other)
-        other.respond_to?(:name) &&
-          other.respond_to?(:type) &&
-          self.name == other.name &&
-          self.type == other.type
-      end
-
-      def hash
-        name.hash + 31 * type.hash
-      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
         "#{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.kind_of? Array 
+        if value.is_a? Array
           if multiple?
             value.map { |val| to_indexed(val) }
           else
@@ -44,65 +77,88 @@ module Sunspot
         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
+
+      # ==== Returns
+      #
+      # Boolean:: true if the field allows multiple values; false if not
       def multiple?
         !!@multiple
       end
     end
 
-    class AttributeField < ::Sunspot::Field::Base
+    #
+    # 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.
+    #
+    class AttributeField < Base
+      def initialize(name, type, options = {})
+        @attribute_name = options.delete(:using) || name
+        super
+      end
+
       protected
 
+      #
+      # Call the field's attribute name on the given model and return the value.
+      #
+      # ==== Parameters
+      #
+      # model<Object>:: The object from which to extract the value
+      #
+      # ==== Returns
+      #
+      # Object:: The value to index
+      #
       def value_for(model)
-        model.send(name)
+        model.send(@attribute_name)
       end
     end
 
-    class VirtualField < ::Sunspot::Field::Base
+    #
+    # 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
 
       protected
-      attr_accessor :block
 
+      # 
+      # Evaluate the block in the model's context and return the block's return
+      # value.
+      #
+      # ==== Parameters
+      #
+      # model<Object>:: The object from which to extract the value
+      #
+      # ==== Returns
+      #
+      # Object:: The value to index
       def value_for(model)
-        model.instance_eval(&block)
+        if @block.arity <= 0
+          model.instance_eval(&@block)
+        else
+          @block.call(model)
+        end
       end
     end
   end
-
-  class <<Field
-    def register(clazz, fields)
-      fields = [fields] unless fields.kind_of? Enumerable
-      self.for(clazz).concat fields
-    end
-
-    def register_text(clazz, fields)
-      fields = [fields] unless fields.kind_of? Enumerable
-      self.text_for(clazz).concat fields
-    end
-
-    def text_for(clazz)
-      keyword_fields_hash[clazz.object_id] ||= []
-    end
-
-    def for(clazz)
-      fields_hash[clazz.object_id] ||= []
-    end
-
-    def unregister_all!
-      fields_hash.clear
-    end
-
-    private
-
-    def fields_hash
-      @fields_hash ||= {}
-    end
-
-    def keyword_fields_hash
-      @keyword_fields_hash ||= {}
-    end
-  end
 end

data/lib/sunspot/indexer.rb

@@ -1,65 +1,68 @@
 module Sunspot
-  class Indexer
-    def initialize(connection)
-      @connection = connection
+  # 
+  # This class presents a service for adding, updating, and removing data
+  # from the Solr index. An Indexer instance is associated with a particular
+  # setup, and thus is capable of indexing instances of a certain class (and its
+  # subclasses).
+  #
+  class Indexer #:nodoc:
+    def initialize(connection, setup)
+      @connection, @setup = connection, setup
     end
 
+    # 
+    # Construct a representation of the model for indexing and send it to the
+    # connection for indexing
+    #
+    # ==== Parameters
+    #
+    # model<Object>:: the model to index
+    #
     def add(model)
-      hash = static_hash_for model
-      for field in fields
-        hash.merge! field.pair_for(model)
+      hash = static_hash_for(model)
+      for field in @setup.all_fields
+        hash.merge!(field.pair_for(model))
       end
-      connection.add hash
-    end
-
-    def fields
-      @fields ||= []
-    end
-
-    def add_fields(fields)
-      self.fields.concat fields
+      @connection.add(hash)
     end
 
+    # 
+    # Remove the given model from the Solr index
+    #
     def remove(model)
-      connection.delete(::Sunspot::Adapters.adapt_instance(model).index_id)
+      @connection.delete(Adapters::InstanceAdapter.adapt(model).index_id)
     end
 
-    protected 
-    attr_reader :connection
-
-    def static_hash_for(model)
-      { :id => ::Sunspot::Adapters.adapt_instance(model).index_id,
-        :type => Indexer.superclasses_for(model.class).map { |clazz| clazz.name }}
+    # 
+    # Delete all documents of the class indexed by this indexer from Solr.
+    #
+    def remove_all
+      @connection.delete_by_query("type:#{@setup.clazz.name}")
     end
-  end
 
-  class <<Indexer
-    def add(connection, model)
-      self.for(model.class, connection).add(model)
-    end
-
-    def remove(connection, model)
-      self.for(model.class, connection).remove(model)
-    end
+    protected
 
-    def remove_all(connection, clazz = nil)
-      connection.delete_by_query("type:#{clazz ? clazz.name : '[* TO *]'}")
+    # 
+    # All indexed documents index and store the +id+ and +type+ fields.
+    # This method constructs the document hash containing those key-value
+    # pairs.
+    #
+    def static_hash_for(model)
+      { :id => Adapters::InstanceAdapter.adapt(model).index_id,
+        :type => Util.superclasses_for(model.class).map { |clazz| clazz.name }}
     end
 
-    def for(clazz, connection)
-      indexer = self.new(connection)
-      for superclass in superclasses_for(clazz)
-        indexer.add_fields ::Sunspot::Field.for(superclass)
-        indexer.add_fields ::Sunspot::Field.text_for(superclass)
+    class <<self
+      # 
+      # Delete all documents from the Solr index
+      #
+      # ==== Parameters
+      #
+      # connection<Solr::Connection>::
+      #   connection to which to send the delete request
+      def remove_all(connection)
+        connection.delete_by_query("type:[* TO *]")
       end
-      raise ArgumentError, "Class #{clazz.name} has not been configured for indexing" if indexer.fields.empty?
-      indexer
-    end
-
-    def superclasses_for(clazz)
-      superclasses_for = [clazz]
-      superclasses_for << (clazz = clazz.superclass) while clazz.superclass != Object
-      superclasses_for
     end
   end
 end