benjaminkrause-sunspot 0.9.7

data/lib/sunspot/adapters.rb

@@ -0,0 +1,265 @@
+module Sunspot
+  # 
+  # Sunspot works by saving references to the primary key (or natural ID) of
+  # each indexed object, and then retrieving the objects from persistent storage
+  # when their IDs are referenced in search results. In order for Sunspot to
+  # know what an object's primary key is, and how to retrieve objects from
+  # persistent storage given a primary key, an adapter must be registered for
+  # that object's class or one of its superclasses (for instance, an adapter
+  # registered for ActiveRecord::Base would be used for all ActiveRecord
+  # models).
+  #
+  # To provide Sunspot with this ability, adapters must have two roles:
+  #
+  # Data accessor::
+  #   A subclass of Sunspot::Adapters::DataAccessor, this object is instantiated
+  #   with a particular class and must respond to the #load() method, which
+  #   returns an object from persistent storage given that object's primary key.
+  #   It can also optionally implement the #load_all() method, which returns
+  #   a collection of objects given a collection of primary keys, if that can be
+  #   done more efficiently than calling #load() on each key.
+  # Instance adapter::
+  #   A subclass of Sunspot::Adapters::InstanceAdapter, this object is
+  #   instantiated with a particular instance. Its only job is to tell Sunspot
+  #   what the object's primary key is, by implementing the #id() method.
+  #
+  # Adapters are registered by registering their two components, telling Sunspot
+  # that they are available for one or more classes, and all of their
+  # subclasses. See Sunspot::Adapters::DataAccessor.register and
+  # Sunspot::Adapters::InstanceAdapter.register for the details.
+  #
+  # See spec/mocks/mock_adapter.rb for an example of how adapter classes should
+  # be implemented.
+  #
+  module Adapters
+    # Subclasses of the InstanceAdapter class should implement the #id method,
+    # which returns the primary key of the instance stored in the @instance
+    # variable. The primary key must be unique within the scope of the
+    # instance's class.
+    #
+    # ==== Example:
+    #
+    #   class FileAdapter < Sunspot::Adapters::InstanceAdapter
+    #     def id
+    #       File.expand_path(@instance.path)
+    #     end
+    #   end
+    #
+    #   # then in your initializer
+    #   Sunspot::Adapters::InstanceAdapter.register(MyAdapter, File)
+    #
+    class InstanceAdapter
+      def initialize(instance) #:nodoc:
+        @instance = instance
+      end
+
+      # 
+      # The universally-unique ID for this instance that will be stored in solr
+      #
+      # ==== Returns
+      #
+      # String:: ID for use in Solr
+      #
+      def index_id #:nodoc:
+        InstanceAdapter.index_id_for(@instance.class.name, id)
+      end
+
+      class <<self
+        # Instantiate an InstanceAdapter for the given object, searching for
+        # registered adapters for the object's class.
+        #
+        # ==== Parameters
+        #
+        # instance<Object>:: The instance to adapt
+        #
+        # ==== Returns
+        #
+        # InstanceAdapter::
+        #   An instance of an InstanceAdapter implementation that
+        #   wraps the given instance
+        #
+        def adapt(instance) #:nodoc:
+          self.for(instance.class).new(instance)
+        end
+
+        # Register an instance adapter for a set of classes. When searching for
+        # an adapter for a given instance, Sunspot starts with the instance's
+        # class, and then searches for registered adapters up the class's
+        # ancestor chain.
+        #
+        # ==== Parameters
+        #
+        # instance_adapter<Class>:: The instance adapter class to register
+        # classes...<Class>::
+        #   One or more classes that this instance adapter adapts
+        #
+        def register(instance_adapter, *classes)
+          for clazz in classes
+            instance_adapters[clazz.name.to_sym] = instance_adapter
+          end
+        end
+
+        # Find the best InstanceAdapter implementation that adapts the given
+        # class.  Starting with the class and then moving up the ancestor chain,
+        # looks for registered InstanceAdapter implementations.
+        #
+        # ==== Parameters
+        #
+        # clazz<Class>:: The class to find an InstanceAdapter for
+        #
+        # ==== Returns
+        #
+        # Class:: Subclass of InstanceAdapter, or nil if none found
+        #
+        # ==== Raises
+        #
+        # Sunspot::NoAdapterError:: If no adapter is registered for this class
+        #
+        def for(clazz) #:nodoc:
+          original_class_name = clazz.name
+          clazz.ancestors.each do |ancestor_class|
+            next if ancestor_class.name.nil? || ancestor_class.name.empty?
+            class_name = ancestor_class.name.to_sym
+            return instance_adapters[class_name] if instance_adapters[class_name]
+          end
+
+          raise(Sunspot::NoAdapterError,
+                "No adapter is configured for #{original_class_name} or its superclasses. See the documentation for Sunspot::Adapters")
+        end
+
+        def index_id_for(class_name, id) #:nodoc:
+          "#{class_name} #{id}"
+        end
+
+        protected
+
+        # Lazy-initialize the hash of registered instance adapters
+        #
+        # ==== Returns
+        #
+        # Hash:: Hash containing class names keyed to instance adapter classes
+        #
+        def instance_adapters #:nodoc:
+          @instance_adapters ||= {}
+        end
+      end
+    end
+
+    # Subclasses of the DataAccessor class take care of retreiving instances of
+    # the adapted class from (usually persistent) storage. Subclasses must
+    # implement the #load method, which takes an id (the value returned by
+    # InstanceAdapter#id, as a string), and returns the instance referenced by
+    # that ID. Optionally, it can also override the #load_all method, which
+    # takes an array of IDs and returns an array of instances in the order
+    # given. #load_all need only be implemented if it can be done more
+    # efficiently than simply iterating over the IDs and calling #load on each
+    # individually.
+    #
+    # ==== Example
+    #
+    #   class FileAccessor < Sunspot::Adapters::InstanceAdapter
+    #     def load(id)
+    #       @clazz.open(id)
+    #     end
+    #   end
+    #
+    #   Sunspot::Adapters::DataAccessor.register(FileAccessor, File)
+    #
+    class DataAccessor
+      def initialize(clazz) #:nodoc:
+        @clazz = clazz
+      end
+
+      # Subclasses can override this class to provide more efficient bulk
+      # loading of instances. Instances must be returned in the same order
+      # that the IDs were given.
+      #
+      # ==== Parameters
+      #
+      # ids<Array>:: collection of IDs
+      #
+      # ==== Returns
+      #
+      # Array:: collection of instances, in order of IDs given
+      #
+      def load_all(ids)
+        ids.map { |id| self.load(id) }
+      end
+
+      class <<self
+        # Create a DataAccessor for the given class, searching registered
+        # adapters for the best match. See InstanceAdapter#adapt for discussion
+        # of inheritence.
+        #
+        # ==== Parameters
+        #
+        # clazz<Class>:: Class to create DataAccessor for
+        #
+        # ==== Returns
+        #
+        # DataAccessor::
+        #   DataAccessor implementation which provides access to given class
+        #
+        def create(clazz) #:nodoc:
+          self.for(clazz).new(clazz)
+        end
+
+        # Register data accessor for a set of classes. When searching for
+        # an accessor for a given class, Sunspot starts with the class,
+        # and then searches for registered adapters up the class's ancestor
+        # chain.
+        #
+        # ==== Parameters
+        #
+        # data_accessor<Class>:: The data accessor class to register
+        # classes...<Class>::
+        #   One or more classes that this data accessor providess access to
+        #
+        def register(data_accessor, *classes)
+          for clazz in classes
+            data_accessors[clazz.name.to_sym] = data_accessor
+          end
+        end
+
+        # Find the best DataAccessor implementation that adapts the given class.
+        # Starting with the class and then moving up the ancestor chain, looks
+        # for registered DataAccessor implementations.
+        #
+        # ==== Parameters
+        #
+        # clazz<Class>:: The class to find a DataAccessor for
+        #
+        # ==== Returns
+        #
+        # Class:: Implementation of DataAccessor
+        #
+        # ==== Raises
+        #
+        # Sunspot::NoAdapterError:: If no data accessor exists for the given class
+        #
+        def for(clazz) #:nodoc:
+          original_class_name = clazz.name
+          clazz.ancestors.each do |ancestor_class|
+            next if ancestor_class.name.nil? || ancestor_class.name.empty?
+            class_name = ancestor_class.name.to_sym
+            return data_accessors[class_name] if data_accessors[class_name]
+          end
+          raise(Sunspot::NoAdapterError,
+                "No data accessor is configured for #{original_class_name} or its superclasses. See the documentation for Sunspot::Adapters")
+        end
+
+        protected
+
+        # Lazy-initialize the hash of registered data accessors
+        #
+        # ==== Returns
+        #
+        # Hash:: Hash containing class names keyed to data accessor classes
+        #
+        def data_accessors #:nodoc:
+          @adapters ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/sunspot/composite_setup.rb

@@ -0,0 +1,184 @@
+module Sunspot
+  # 
+  # The CompositeSetup class encapsulates a collection of setups, and responds
+  # to a subset of the methods that Setup responds to (in particular, the
+  # methods required to build queries).
+  #
+  class CompositeSetup #:nodoc:
+    class << self
+      alias_method :for, :new
+    end
+
+    def initialize(types)
+      @types = types
+    end
+
+    # 
+    # Collection of Setup objects for the enclosed types
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of Setup objects
+    #
+    def setups
+      @setups ||= @types.map { |type| Setup.for(type) }
+    end
+
+    # 
+    # Return the names of the encapsulated types
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of class names
+    #
+    def type_names
+      @type_names ||= @types.map { |clazz| clazz.name }
+    end
+
+    # 
+    # Get a text field object by its public name. A field will be returned if
+    # it is configured for any of the enclosed types.
+    #
+    # ==== Returns
+    #
+    # Sunspot::FulltextField:: Text field with the given public name
+    #
+    # ==== Raises
+    #
+    # UnrecognizedFieldError::
+    #   If no field with that name is configured for any of the enclosed types.
+    #
+    def text_fields(field_name)
+      text_fields_hash[field_name.to_sym] || raise(
+        UnrecognizedFieldError,
+        "No text field configured for #{@types * ', '} with name '#{field_name}'"
+      )
+    end
+
+    # 
+    # Get a Sunspot::AttributeField instance corresponding to the given field name
+    #
+    # ==== Parameters
+    #
+    # field_name<Symbol>:: The public field name for which to find a field
+    #
+    # ==== Returns
+    #
+    # Sunspot::AttributeField The field object corresponding to the given name
+    #
+    # ==== Raises
+    #
+    # ArgumentError::
+    #   If the given field name is not configured for the types being queried
+    #
+    def field(field_name) #:nodoc:
+      fields_hash[field_name.to_sym] || raise(
+        UnrecognizedFieldError,
+        "No field configured for #{@types * ', '} with name '#{field_name}'"
+      )
+    end
+
+    # 
+    # Get a dynamic field factory for the given base name.
+    #
+    # ==== Returns
+    #
+    # DynamicFieldFactory:: Factory for dynamic fields with the given base name
+    #
+    # ==== Raises
+    #
+    # UnrecognizedFieldError::
+    #   If the given base name is not configured as a dynamic field for the types being queried
+    #
+    def dynamic_field_factory(field_name)
+      dynamic_field_factories_hash[field_name.to_sym] || raise(
+        UnrecognizedFieldError,
+        "No dynamic field configured for #{@types * ', '} with name #{field_name.inspect}"
+      )
+    end
+
+    # 
+    # Collection of all text fields configured for any of the enclosed types.
+    #
+    # === Returns
+    #
+    # Array:: Text fields configured for the enclosed types
+    #
+    def all_text_fields
+      @text_fields ||= text_fields_hash.values.map { |set| set.to_a }.flatten
+    end
+
+    private
+
+    # 
+    # Return a hash of field names to text field objects, containing all fields
+    # that are configured for any of the types enclosed.
+    #
+    # ==== Returns
+    #
+    # Hash:: Hash of field names to text field objects.
+    #
+    def text_fields_hash
+      @text_fields_hash ||=
+        setups.inject({}) do |hash, setup|
+          setup.all_text_fields.each do |text_field|
+            (hash[text_field.name] ||= Set.new) << text_field
+          end
+          hash
+        end
+    end
+
+    # 
+    # Return a hash of field names to field objects, containing all fields
+    # that are common to all of the classes enclosed. In order for fields
+    # to be common, they must be of the same type and have the same
+    # value for allow_multiple? and stored?. This method is memoized.
+    #
+    # ==== Returns
+    #
+    # Hash:: field names keyed to field objects
+    #
+    def fields_hash
+      @fields_hash ||=
+        begin
+          field_sets_hash = Hash.new { |h, k| h[k] = Set.new }
+          @types.each do |type|
+            Setup.for(type).fields.each do |field|
+              field_sets_hash[field.name.to_sym] << field
+            end
+          end
+          fields_hash = {}
+          field_sets_hash.each_pair do |field_name, set|
+            if set.length == 1
+              fields_hash[field_name] = set.to_a.first
+            end
+          end
+          fields_hash
+        end
+    end
+
+    # 
+    # Return a hash of dynamic field base names to dynamic field factories for
+    # those base names. Criteria for the inclusion are the same as for
+    # #fields_hash()
+    #
+    def dynamic_field_factories_hash
+      @dynamic_field_factories_hash ||=
+        begin
+          dynamic_field_factories_hash = @types.inject({}) do |hash, type|
+            Setup.for(type).dynamic_field_factories.each do |field_factory|
+              (hash[field_factory.name.to_sym] ||= {})[type.name] = field_factory
+            end
+            hash
+          end
+          dynamic_field_factories_hash.each_pair do |field_name, field_configurations_hash|
+            if @types.any? { |type| field_configurations_hash[type.name].nil? }
+              dynamic_field_factories_hash.delete(field_name)
+            else
+              dynamic_field_factories_hash[field_name] = field_configurations_hash.values.first
+            end
+          end
+        end
+    end
+  end
+end

data/lib/sunspot/configuration.rb

@@ -0,0 +1,49 @@
+module Sunspot
+  # The Sunspot::Configuration module provides a factory method for Sunspot
+  # configuration objects. Available properties are:
+  #
+  # Sunspot.config.http_client::
+  #   The client to use for HTTP communication with Solr. Available options are
+  #   :net_http, which is the default and uses Ruby's built-in pure-Ruby HTTP
+  #   library; and :curb, which uses Ruby's libcurl bindings and requires
+  #   installation of the 'curb' gem.
+  # Sunspot.config.solr.url::
+  #   The URL at which to connect to Solr
+  #   (default: 'http://localhost:8983/solr')
+  # Sunspot.config.pagination.default_per_page::
+  #   Solr always paginates its results. This sets Sunspot's default result
+  #   count per page if it is not explicitly specified in the query.
+  #
+  module Configuration
+    class <<self
+      # Factory method to build configuration instances.
+      #
+      # ==== Returns
+      #
+      # LightConfig::Configuration:: new configuration instance with defaults
+      #
+      def build #:nodoc:
+        LightConfig.build do
+          http_client :net_http
+          solr do
+            url 'http://127.0.0.1:8983/solr'
+          end
+          pagination do
+            default_per_page 30
+          end
+        end
+      end
+      
+      # Location for the default solr configuration files,
+      # required for bootstrapping a new solr installation
+      #
+      # ==== Returns
+      #
+      # String:: Directory with default solr config files
+      #
+      def solr_default_configuration_location
+        File.join( File.dirname(__FILE__), '../../solr/solr/conf' )
+      end
+    end
+  end
+end

data/lib/sunspot/data_extractor.rb

@@ -0,0 +1,50 @@
+module Sunspot
+  # 
+  # DataExtractors present an internal API for the indexer to use to extract
+  # field values from models for indexing. They must implement the #value_for
+  # method, which takes an object and returns the value extracted from it.
+  #
+  module DataExtractor #:nodoc: all
+    # 
+    # AttributeExtractors extract data by simply calling a method on the block.
+    #
+    class AttributeExtractor
+      def initialize(attribute_name)
+        @attribute_name = attribute_name
+      end
+
+      def value_for(object)
+        object.send(@attribute_name)
+      end
+    end
+
+    # 
+    # BlockExtractors extract data by evaluating a block in the context of the
+    # object instance, or if the block takes an argument, by passing the object
+    # as the argument to the block. Either way, the return value of the block is
+    # the value returned by the extractor.
+    #
+    class BlockExtractor
+      def initialize(&block)
+        @block = block
+      end
+
+      def value_for(object)
+        Util.instance_eval_or_call(object, &@block)
+      end
+    end
+
+    # 
+    # Constant data extractors simply return the same value for every object.
+    #
+    class Constant
+      def initialize(value)
+        @value = value
+      end
+
+      def value_for(object)
+        @value
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/field_query.rb

@@ -0,0 +1,77 @@
+module Sunspot
+  module DSL
+    # 
+    # Provides an API for areas of the query DSL that operate on specific
+    # fields. This functionality is provided by the query DSL and the dynamic
+    # query DSL.
+    #
+    class FieldQuery < Scope
+      # 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
+
+      # 
+      # DEPRECATED Use <code>order_by(:random)</code>
+      #
+      def order_by_random
+        @query.order_by(:random)
+      end
+
+      # Request facets on the given field names. If the last argument is a hash,
+      # the given options will be applied to all specified fields. See
+      # Sunspot::Search#facet and Sunspot::Facet for information on what is
+      # returned.
+      #
+      # ==== Parameters
+      #
+      # field_names...<Symbol>:: fields for which to return field facets
+      #
+      # ==== Options
+      #
+      # :sort<Symbol>::
+      #   Either :count (values matching the most terms first) or :index (lexical)
+      # :limit<Integer>::
+      #   The maximum number of facet rows to return
+      # :minimum_count<Integer>::
+      #   The minimum count a facet row must have to be returned
+      # :zeros<Boolean>::
+      #   Return facet rows for which there are no matches (equivalent to
+      #   :minimum_count => 0). Default is false.
+      #
+      def facet(*field_names, &block)
+        if block
+          options =
+            if field_names.last.is_a?(Hash)
+              field_names.pop
+            else
+              {}
+            end
+          if field_names.length != 1
+            raise(
+              ArgumentError,
+              "wrong number of arguments (#{field_names.length} for 1)"
+            )
+          end
+          name = field_names.first
+          DSL::QueryFacet.new(@query.add_query_facet(name, options)).instance_eval(&block)
+        else
+          options = 
+            if field_names.last.is_a?(Hash)
+              field_names.pop
+            end
+          for field_name in field_names
+            @query.add_field_facet(field_name, options)
+          end
+        end
+      end
+    end
+  end
+end