sunspot 0.9.7

data/lib/sunspot/configuration.rb

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

data/lib/sunspot/data_extractor.rb

@@ -0,0 +1,47 @@
+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
+
+    class Constant
+      def initialize(value)
+        @value = value
+      end
+
+      def value_for(object)
+        @value
+      end
+    end
+  end
+end

data/lib/sunspot/dsl.rb

@@ -0,0 +1,3 @@
+%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/dsl/field_query.rb

@@ -0,0 +1,72 @@
+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
+
+      # 
+      # Order results randomly. This will (generally) return the results in a
+      # different order each time a search is called.
+      #
+      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
+          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)).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

data/lib/sunspot/dsl/fields.rb

@@ -0,0 +1,86 @@
+module Sunspot
+  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
+    # 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(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.
+      #
+      # If options are passed, they will be applied to all the given fields.
+      #
+      # ==== Parameters
+      #
+      # names...<Symbol>:: One or more field names
+      #
+      # ==== Options
+      #
+      # :boost<Float>::
+      #   Boost that should be applied to this field for keyword search
+      #
+      def text(*names, &block)
+        options = names.pop if names.last.is_a?(Hash)
+        for name in names
+          @setup.add_text_field_factory(
+            name,
+            options || {},
+            &block
+          )
+        end
+      end
+
+      # 
+      # Specify a document-level boost. As with fields, you have the option of
+      # passing an attribute name which will be called on each model, or a block
+      # to be evaluated in the model's context. As well as these two options,
+      # this method can also take a constant number, meaning that all indexed
+      # documents of this class will have the specified boost.
+      #
+      # ==== Parameters
+      #
+      # attr_name<Symbol,~.to_f>:: Attribute name to call or a numeric constant
+      #
+      def boost(attr_name = nil, &block)
+        @setup.add_document_boost(attr_name, &block)
+      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 = 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
+        if method.to_s =~ /^dynamic_/
+          @setup.add_dynamic_field_factory(name, type, *args, &block)
+        else
+          @setup.add_field_factory(name, type, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/query.rb

@@ -0,0 +1,59 @@
+module Sunspot
+  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. Much of the DSL's functionality is implemented by this
+    # class's superclasses, Sunspot::DSL::FieldQuery and Sunspot::DSL::Scope
+    #
+    # See Sunspot.search for usage examples
+    #
+    class Query < FieldQuery
+      # Specify a phrase that should be searched as fulltext. Only +text+
+      # fields are searched - see DSL::Fields.text
+      #
+      # Keyword search is executed using Solr's dismax handler, which strikes
+      # a good balance between powerful and foolproof. In particular,
+      # well-matched quotation marks can be used to group phrases, and the
+      # + and - modifiers work as expected. All other special Solr boolean
+      # syntax is escaped, and mismatched quotes are ignored entirely.
+      #
+      # ==== Parameters
+      #
+      # keywords<String>:: phrase to perform fulltext search on
+      #
+      # ==== Options
+      #
+      # :fields<Array>::
+      #   List of fields that should be searched for keywords. Defaults to all
+      #   fields configured for the types under search.
+      #
+      def keywords(keywords, options = {})
+        @query.set_keywords(keywords, options)
+      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)
+        raise ArgumentError, "unknown argument #{options.keys.first.inspect} passed to paginate" unless options.empty?
+        @query.paginate(page, per_page)
+      end
+    end
+  end
+end

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/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

@@ -0,0 +1,193 @@
+module Sunspot
+  module DSL #:nodoc:
+    # 
+    # 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 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, 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<Object,Range,Array>::
+      #   If passed, creates an equality, range, or any-of restriction based on
+      #   the type of value passed.
+      #
+      # ==== 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
+      #
+      # 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:
+      #
+      #   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_shorthand_restriction(field_name, value)
+        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_negated_shorthand_restriction(field_name, value)
+          end
+        else
+          instances = args
+          for instance in instances.flatten
+            @query.exclude_instance(instance)
+          end
+        end
+      end
+
+      # 
+      # Create a disjunction, scoping the results to documents that match any
+      # of the enclosed restrictions.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     any_of do
+      #       with(:expired_at).greater_than Time.now
+      #       with :expired_at, nil
+      #     end
+      #   end
+      #
+      # 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 any_of(&block)
+        Util.instance_eval_or_call(Scope.new(@query.add_disjunction), &block)
+      end
+
+      # 
+      # 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
+      #
+      # ==== Example
+      #
+      #   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
+end