outoftime-sunspot 0.0.2 → 0.7.0

data/History.txt

@@ -1,3 +1,7 @@
+== 0.0.5 TBD
+* Negative scoping using without() method
+* Exclusion by object identity using without(instance)
+
 == 0.0.2 2009-02-14
 * Run sunspot's built-in Solr instance using
   sunspot-solr executable

data/README.rdoc

@@ -19,18 +19,16 @@ Sunspot is currently under active development and is not feature-complete.
 * Define fields based on existing attributes or "virtual fields" for custom indexing
 * Indexes each object's entire superclass hierarchy, for easy searching for all objects inheriting from a parent class
 * Intuitive DSL for scoping searches, with all the usual boolean operators available
-* Ability to pass dynamic conditions in as a hash, and define which operator to use for each condition
+* Intuitive interface for requesting facets on indexed fields
+* Extensible adapter architecture for easy integration of other ORMs or non-model classes
 * Full compatibility with will_paginate
 * Ordering
 
 === Sunspot will have these features:
 
 * Adapters for DataMapper, ActiveRecord, and File objects
-* Extensible adapter architecture for easy integration of other ORMs or non-model classes
 * High-power integration with ORM features for maximum efficiency (e.g., specify AR :include argument for eager loading associations when hydrating search results)
-* Intuitive interface for requesting facets on indexed fields
 * Define association facets, which return model objects as row values
-* Access search parameters as hash or object attributes, for easy integration with form helpers or query string builders
 * Plugins for drop-in integration with Merb and Rails
 
 == Installation
@@ -62,58 +60,49 @@ You can change the URL at which Sunspot accesses Solr with:
     string :author_name
     integer :blog_id
     integer :category_ids
-    float :average_rating
+    float :average_rating, :using => :ratings_average
     time :published_at
     string :sort_title do
       title.downcase.sub(/^(an?|the)\W+/, ''/) if title = self.title
     end
   end
 
+See Sunspot.setup for more information.
+
 === Search for objects:
   
   search = Sunspot.search Post do
     keywords 'great pizza'
-    with.author_name 'Mark Twain'
-    with.blog_id.any_of [2, 14]
-    with.category_ids.all_of [4, 10]
-    with.published_at.less_than Time.now
+    with :author_name, 'Mark Twain'
+    with(:blog_id).any_of [2, 14]
+    with(:category_ids).all_of [4, 10]
+    with(:published_at).less_than Time.now
+    without :title, 'Bad Title'
+    without bad_instance # specifically exclude this instance from results
 
     paginate :page => 3, :per_page => 15
     order_by :average_rating, :desc
+
+    facet :blog_id
   end
 
+See Sunspot.search for more information.
+
 === Get data from search:
 
   search.results
   search.total
   search.page
   search.per_page
+  search.facet(:blog_id)
 
-=== Build search from a hash (e.g., params) and retrieve them later:
-
-  search = Sunspot.search Post, :keywords => 'great pizza',
-                                :conditions => { :author_name => 'Mark Twain',
-                                                 :blog_id => [4, 10] },
-                                :order => 'published_at desc'
-  search.builder.keywords
-    #=> "great pizza"
-  search.builder.conditions.author_name
-    #=> "Mark Twain"
-  search.builder.params[:conditions][:blog_id]
-    #=> [4, 10]
-
-This functionality is great for building a search from user input; if you're
-building a search using business logic in your application, the block DSL
-is the way to go. Note you can mix-and-match the two:
-
-  search = Sunspot.search Post, :keywords => 'great pizza' do
-    with.blog_id 1
-  end
+== About the API documentation
 
-  search.builder.keywords
-    #=> "great pizza"
-  search.builder.blog_id
-    #=> nil
+All of the methods documented in the RDoc are considered part of Sunspot's
+public API. Methods that are not part of the public API are documented in the
+code, but excluded from the RDoc. If you find yourself needing to access methods
+that are not part of the public API in order to do what you need, please contact
+me so I can rectify the situation!
 
 == Requirements
 
@@ -121,6 +110,10 @@ is the way to go. Note you can mix-and-match the two:
 2. solr-ruby
 3. Java
 
+== Further Reading
+
+Posts about Sunspot from my tumblog: http://outofti.me/tagged/sunspot
+
 == LICENSE:
 
 (The MIT License)

data/TODO

@@ -0,0 +1,7 @@
+=== 0.8 ===
+* Facet by type
+* Dynamic fields
+* ActiveRecord, DataMapper, File adapters
+=== 0.9 ===
+* Switch to RSolr
+* Query-based faceting (?)

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
+:patch: 0
 :major: 0
-:minor: 0
-:patch: 2
+:minor: 7

data/lib/light_config.rb

@@ -9,7 +9,7 @@ module LightConfig
           define_method property do
             @properties[property]
           end
-          
+
           define_method "#{property}=" do |value|
             @properties[property] = value
           end
@@ -31,10 +31,10 @@ module LightConfig
       @configuration.instance_variable_get(:@properties)[method] = value
     end
   end
-end
 
-class <<LightConfig
-  def build(&block)
-    LightConfig::Configuration.new(&block)
+  class <<self
+    def build(&block)
+      LightConfig::Configuration.new(&block)
+    end
   end
 end

data/lib/sunspot/adapters.rb

@@ -1,54 +1,230 @@
 module Sunspot
+  # Sunspot provides an adapter architecture that allows applications or plugin
+  # developers to define adapters for any type of object. An adapter is composed
+  # of two classes, an InstanceAdapter and a DataAccessor. Note that an adapter
+  # does not need to provide both classes - InstanceAdapter is only needed if
+  # you wish to index instances of the class, and DataAccessor is only needed if
+  # you wish to retrieve instances of this class in search results. Of course,
+  # both will be the case most of the time.
+  #
+  # See Sunspot::Adapters::DataAccessor.register and
+  # Sunspot::Adapters::InstanceAdapter.register for information on how to enable
+  # an adapter for use by Sunspot.
+  #
+  # See spec/mocks/mock_adapter.rb for an example of how adapter classes should
+  # be implemented.
+  #
   module Adapters
-    module InstanceAdapter
-      def initialize(instance)
+    # 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
 
-      def index_id
-        "#{instance.class.name} #{id}"
+      # 
+      # The universally-unique ID for this instance that will be stored in solr
+      #
+      # ==== Returns
+      #
+      # String:: ID for use in Solr
+      #
+      def index_id #:nodoc:
+        "#{@instance.class.name} #{id}"
       end
 
-      protected
-      attr_accessor :instance
+      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
+        #
+        def for(clazz) #:nodoc:
+          while clazz != Object
+            class_name = clazz.name.to_sym
+            return instance_adapters[class_name] if instance_adapters[class_name]
+            clazz = clazz.superclass
+          end
+          nil
+        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
 
-    module ClassAdapter
-      def initialize(clazz)
+    # 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
 
-      protected
-      attr_reader :clazz
-    end
-  end
-
-  class <<Adapters
-    def register(adapter, *classes)
-      for clazz in classes
-        adapters[clazz.name] = adapter
+      # 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
-    end
 
-    def adapt_class(clazz)
-      self.for(clazz).const_get('ClassAdapter').new(clazz)
-    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)
+          self.for(clazz).new(clazz)
+        end
 
-    def adapt_instance(instance)
-      self.for(instance.class).const_get('InstanceAdapter').new(instance)
-    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
 
-    def for(clazz)
-      while clazz != Object
-        return adapters[clazz.name] if adapters[clazz.name]
-        clazz = clazz.superclass
-      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, or nil if none found
+        #
+        def for(clazz) #:nodoc:
+          while clazz != Object
+            class_name = clazz.name.to_sym
+            return data_accessors[class_name] if data_accessors[class_name]
+            clazz = clazz.superclass
+          end
+        end
 
-    private
+        protected
 
-    def adapters
-      @adapters ||= {}
+        # 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/configuration.rb

@@ -1,15 +1,30 @@
 module Sunspot
+  # The Sunspot::Configuration module provides a factory method for Sunspot
+  # configuration objects. Available properties are:
+  #
+  # 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
-  end
-  
-  class <<Configuration
-    def build
-      LightConfig.build do
-        solr do
-          url 'http://localhost:8983/solr'
-        end
-        pagination do
-          default_per_page 30
+    class <<self
+      # Factory method to build configuration instances.
+      #
+      # ==== Returns
+      #
+      # LightConfig::Configuration:: new configuration instance with defaults
+      #
+      def build #:nodoc:
+        LightConfig.build do
+          solr do
+            url 'http://localhost:8983/solr'
+          end
+          pagination do
+            default_per_page 30
+          end
         end
       end
     end

data/lib/sunspot/dsl/fields.rb

@@ -1,37 +1,68 @@
 module Sunspot
   module DSL
+    # The Fields class provides a DSL for specifying field definitions in the
+    # Sunspot.setup block. As well as the #text method, which creates fulltext
+    # fields, uses #method_missing to allow definition of typed fields. The
+    # available methods are determined by the constants defined in 
+    # Sunspot::Type - in theory (though this is untested), plugin developers
+    # should be able to add support for new types simply by creating new
+    # implementations in Sunspot::Type
+    #
     class Fields
-      def initialize(clazz)
-        @clazz = clazz
+      def initialize(setup) #:nodoc:
+        @setup = setup
       end
 
+      # Add a text field. Text fields are tokenized before indexing and are
+      # the only fields searched in fulltext searches. If a block is passed,
+      # create a virtual field; otherwise create an attribute field.
+      #
+      # ==== Parameters
+      #
+      # names...<Symbol>:: One or more field names
+      #
       def text(*names, &block)
         for name in names
-          ::Sunspot::Field.register_text clazz, build_field(name, ::Sunspot::Type::TextType, &block)
+          @setup.add_text_fields(build_field(name, Type::TextType, &block))
         end
       end
 
+      # method_missing is used to provide access to typed fields, because
+      # developers should be able to add new Sunspot::Type implementations
+      # dynamically and have them recognized inside the Fields DSL. Like #text,
+      # these methods will create a VirtualField if a block is passed, or an
+      # AttributeField if not.
+      #
+      # ==== Example
+      #
+      #   Sunspot.setup(File) do
+      #     time :mtime
+      #   end
+      #
+      # The call to +time+ will create a field of type Sunspot::Types::TimeType
+      #
       def method_missing(method, *args, &block)
         begin
-          type = ::Sunspot::Type.const_get "#{method.to_s.camel_case}Type"
+          type = Type.const_get("#{Util.camel_case(method.to_s)}Type")
         rescue(NameError)
           super(method.to_sym, *args, &block) and return
         end
         name = args.shift
-        ::Sunspot::Field.register clazz, build_field(name, type, *args, &block)
+        @setup.add_fields(build_field(name, type, *args, &block))
       end
 
-      protected
-      attr_reader :clazz
-
       private
 
-      def build_field(name, type, *args, &block)
+      # Factory method for field instances, used by the public methods in this
+      # class. Create a VirtualField if a block is passed, or an AttributeField
+      # if not.
+      #
+      def build_field(name, type, *args, &block) #:nodoc:
         options = args.shift if args.first.is_a?(Hash)
         unless block
-          ::Sunspot::Field::AttributeField.new(name, type, options || {})
+          Field::AttributeField.new(name, type, options || {})
         else
-          ::Sunspot::Field::VirtualField.new(name, type, options || {}, &block)
+          Field::VirtualField.new(name, type, options || {}, &block)
         end
       end
     end