outoftime-sunspot 0.7.3 → 0.8.0

data/History.txt

@@ -1,6 +1,31 @@
-== 0.0.5 TBD
+== 0.8.0 2009-05-22
+* Access query API directly; instantiate search without running it
+* Dynamic fields
+* Search blocks can be evaluated in calling context
+
+== 0.7.3 2009-05-06
+* Better exception handling when class doesn't have adapter/setup
+
+== 0.7.2 2009-04-29
+* Dirty sessions
+
+== 0.7.1 2009-04-29
+* Removed extlib dependency from gemspec
+
+== 0.7.0 2009-04-28
+* Less magic in the DSL
+* Restrict by empty values
 * Negative scoping using without() method
 * Exclusion by object identity using without(instance)
+* Support for faceting
+* Explicit commits
+* Boolean field type
+* Attribute field flexibility
+* Virtual field blocks can be evaluated in calling context
+* Order available by multiple fields
+* New adapter API
+* Got rid of builder API
+* Full documentation
 
 == 0.0.2 2009-02-14
 * Run sunspot's built-in Solr instance using

data/LICENSE

@@ -0,0 +1,18 @@
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,11 +1,11 @@
-= sunspot
+= Sunspot
 
-http://github.com/outoftime/sunspot
+http://outoftime.github.com/sunspot
 
 Sunspot is a Ruby library for expressive, powerful interaction with the Solr search engine.
 Sunspot is built on top of the solr-ruby gem, which provides a low-level interface for Solr
 interaction; Sunspot provides a simple, intuitive, expressive DSL backed by powerful
-features for indexing objects and searching against them.
+features for indexing objects and searching for them.
 
 Sunspot is designed to be easily plugged in to any ORM, or even non-database-backed
 objects such as the filesystem.
@@ -65,6 +65,13 @@ integrating Sunspot into Rails drop-in easy.
 
 See Sunspot.setup for more information.
 
+Note that in order for a class to be searchable, it must have an adapter
+registered for itself or one of its subclasses. Adapters allow Sunspot to load
+objects out of persistent storage, and to determine their primary key for
+indexing. {Sunspot::Rails}[http://github.com/outoftime/sunspot_rails] comes with
+an adapter for ActiveRecord objects, but for other types of models you will need
+to define your own. See Sunspot::Adapters for more information.
+
 === Search for objects:
   
   search = Sunspot.search Post do
@@ -92,6 +99,23 @@ See Sunspot.search for more information.
   search.per_page
   search.facet(:blog_id)
 
+=== Building searches manually:
+
+The search DSL is great for building searches from fairly static parameters,
+but a highly dynamic search might want to leverage an intermediate approach
+(such as an application of the Builder pattern). For these cases, Sunspot
+exposes direct access to the Query object:
+
+  search = Sunspot.new_search(Post)
+  search.query.keywords = 'great pizza'
+  search.query.add_restriction(:author_name, :equal_to, 'Mark Twain')
+  search.query.add_restriction(:title, :equal_to, 'Bad Title', true) # negate the restriction
+  search.query.exclude_instance(bad_instance)
+  search.query.paginate(3, 15)
+  search.query.order_by(:average_rating, :desc)
+  search.query.add_field_facet(:blog_id)
+  search.execute! 
+
 == About the API documentation
 
 All of the methods documented in the RDoc are considered part of Sunspot's
@@ -105,6 +129,8 @@ me so I can rectify the situation!
 1. solr-ruby
 2. Java
 
+Sunspot has been tested with MRI 1.8.6, YARV 1.9.1, and JRuby 1.2.0
+
 == Bugs
 
 Please submit bug reports to
@@ -112,6 +138,7 @@ http://outoftime.lighthouseapp.com/projects/20339-sunspot
 
 == Further Reading
 
+Sunspot Discussion: http://groups.google.com/group/ruby-sunspot
 Posts about Sunspot from my tumblog: http://outofti.me/tagged/sunspot
 
 == Contributors
@@ -120,25 +147,4 @@ Mat Brown <mat@patch.com>
 
 == LICENSE:
 
-(The MIT License)
-
-Copyright (c) 2008-2009 Mat Brown
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Sunspot is distributed under the MIT License, copyright (c) 2008-2009 Mat Brown

data/Rakefile

@@ -8,4 +8,4 @@ end
 
 Dir['tasks/**/*.rake'].each { |t| load t }
 
-task :default => :spec
+task :default => 'spec:api'

data/TODO

@@ -1,8 +1,4 @@
-=== 0.8 ===
-* Expose Query as part of public API
-* Facet by type
-* Dynamic fields
-* ActiveRecord, DataMapper, File adapters
 === 0.9 ===
+* Facet by type (?)
 * Switch to RSolr
 * Query-based faceting (?)

data/VERSION.yml

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

data/lib/sunspot/adapters.rb

@@ -1,15 +1,32 @@
 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.
+  # 
+  # 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).
   #
-  # See Sunspot::Adapters::DataAccessor.register and
-  # Sunspot::Adapters::InstanceAdapter.register for information on how to enable
-  # an adapter for use by Sunspot.
+  # 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.
@@ -178,7 +195,7 @@ module Sunspot
         # DataAccessor::
         #   DataAccessor implementation which provides access to given class
         #
-        def create(clazz)
+        def create(clazz) #:nodoc:
           self.for(clazz).new(clazz)
         end
 

data/lib/sunspot/data_extractor.rb

@@ -0,0 +1,37 @@
+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
+  end
+end

data/lib/sunspot/dsl/fields.rb

@@ -1,5 +1,5 @@
 module Sunspot
-  module DSL
+  module DSL #:nodoc:
     # 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
@@ -23,7 +23,7 @@ module Sunspot
       #
       def text(*names, &block)
         for name in names
-          @setup.add_text_fields(build_field(name, Type::TextType, &block))
+          @setup.add_text_fields(Field::StaticField.build(name, Type::TextType, &block))
         end
       end
 
@@ -43,26 +43,15 @@ module Sunspot
       #
       def method_missing(method, *args, &block)
         begin
-          type = Type.const_get("#{Util.camel_case(method.to_s)}Type")
+          type = Type.const_get("#{Util.camel_case(method.to_s.sub(/^dynamic_/, ''))}Type")
         rescue(NameError)
           super(method.to_sym, *args, &block) and return
         end
         name = args.shift
-        @setup.add_fields(build_field(name, type, *args, &block))
-      end
-
-      private
-
-      # 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
-          Field::AttributeField.new(name, type, options || {})
+        if method.to_s =~ /^dynamic_/
+          @setup.add_dynamic_fields(Field::DynamicField.build(name, type, *args, &block))
         else
-          Field::VirtualField.new(name, type, options || {}, &block)
+          @setup.add_fields(Field::StaticField.build(name, type, *args, &block))
         end
       end
     end

data/lib/sunspot/dsl/query.rb

@@ -1,19 +1,15 @@
 module Sunspot
-  module DSL
+  module DSL #:nodoc:
     #
     # This class presents a DSL for constructing queries using the
     # Sunspot.search method. Methods of this class are available inside the
-    # search block.
+    # search block. Methods that take field names as arguments are implemented
+    # in the superclass Sunspot::DSL::Scope, as that DSL is also available in
+    # the #dynamic() block.
     #
     # See Sunspot.search for usage examples
     #
-    class Query
-      NONE = Object.new
-
-      def initialize(query) #:nodoc:
-        @query = query
-      end
-
+    class Query < Scope
       # Specify a phrase that should be searched as fulltext. Only +text+
       # fields are searched - see DSL::Fields.text
       #
@@ -31,100 +27,6 @@ module Sunspot
         @query.keywords = keywords
       end
 
-      # 
-      # 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
-
-      # 
-      # 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().
       #
@@ -148,28 +50,28 @@ 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.
       #
+      # Apply restrictions, facets, and ordering to dynamic field instances.
+      # The block API is implemented by Sunspot::DSL::Scope, 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_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.
+      # ==== Example
       #
-      # ==== Parameters
+      #   Sunspot.search Post do
+      #     dynamic :custom do
+      #       with :cuisine, 'Pizza'
+      #       facet :atmosphere
+      #       order_by :chef_name
+      #     end
+      #   end
       #
-      # 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
+      def dynamic(base_name, &block)
+        Scope.new(@query.dynamic_query(base_name)).instance_eval(&block)
       end
     end
   end

data/lib/sunspot/dsl/restriction.rb

@@ -0,0 +1,25 @@
+module Sunspot
+  module DSL #:nodoc:
+    # 
+    # 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 #:nodoc:
+      def initialize(field_name, query, negative)
+        @field_name, @query, @negative = field_name, query, negative
+      end
+
+      Sunspot::Query::Restriction.names.each do |class_name|
+        method_name = Util.snake_case(class_name.to_s)
+        module_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+          def #{method_name}(value)
+            @query.add_restriction(@field_name, Sunspot::Query::Restriction::#{class_name}, value, @negative)
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/scope.rb

@@ -1,24 +1,136 @@
 module Sunspot
-  module DSL
+  module DSL #:nodoc:
     # 
-    # 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.
+    # This DSL presents methods for constructing restrictions and other query
+    # elements that are specific to fields. As well as being a superclass of
+    # Sunspot::DSL::Query, which presents the main query block, this DSL class
+    # is also used directly inside the #dynamic() block, which only allows
+    # operations on specific fields.
     #
-    class Restriction
-      def initialize(field_name, query, negative)
-        @field_name, @query, @negative = field_name, query, negative
+    class Scope
+      NONE = Object.new
+
+      def initialize(query) #:nodoc:
+        @query = query
+      end
+
+      # 
+      # 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::Query::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::Query::Restriction::EqualTo, value, false)
+        end
       end
 
-      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)
+      # 
+      # 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_negated_restriction(field_name, Sunspot::Query::Restriction::EqualTo, value)
+          end
+        else
+          instances = args
+          for instance in instances.flatten
+            @query.exclude_instance(instance)
           end
-        RUBY
+        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.
+      #
+      # ==== 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

data/lib/sunspot/dsl.rb

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