kuahyeow-sunspot 0.9.7

data/lib/sunspot/composite_setup.rb

@@ -0,0 +1,186 @@
+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_field(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 text_fields
+      @text_fields ||= text_fields_hash.values
+    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.text_fields.each do |text_field|
+            hash[text_field.name] ||= 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
+          fields_hash = @types.inject({}) do |hash, type|
+            Setup.for(type).fields.each do |field|
+              (hash[field.name.to_sym] ||= {})[type.name] = field
+            end
+            hash
+          end
+          fields_hash.each_pair do |field_name, field_configurations_hash|
+            if @types.any? { |type| field_configurations_hash[type.name].nil? } # at least one type doesn't have this field configured
+              fields_hash.delete(field_name)
+            elsif field_configurations_hash.values.map { |configuration| configuration.indexed_name }.uniq.length != 1 # fields with this name have different configs
+              fields_hash.delete(field_name)
+            else
+              fields_hash[field_name] = field_configurations_hash.values.first
+            end
+          end
+        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,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/date_facet.rb

@@ -0,0 +1,36 @@
+module Sunspot
+  #
+  # Date facets are retrieved by passing a :time_range key into the
+  # DSL::FieldQuery#facet options. They are only available for Date and Time
+  # type fields. The #value for date facet rows is a Range object encapsulating
+  # the time range covered by the row.
+  #
+  class DateFacet < Facet
+    def initialize(facet_values, field) #:nodoc:
+      @gap = facet_values.delete('gap')[/\+(\d+)SECONDS/,1].to_i
+      %w(start end).each { |key| facet_values.delete(key) }
+      super(facet_values.to_a.flatten, field)
+    end
+
+    #
+    # Get the rows of this date facet, which are instances of DateFacetRow.
+    # The rows will always be sorted in chronological order.
+    #
+    #--
+    #
+    # The date facet info comes back from Solr as a hash, so we need to sort
+    # it manually. FIXME this currently assumes we want to do a "lexical"
+    # sort, but we should support count sort as well, even if it's not a
+    # common use case.
+    #
+    def rows
+      super.sort { |a, b| a.value.first <=> b.value.first }
+    end
+
+    private
+
+    def new_row(pair)
+      DateFacetRow.new(pair, @gap, self)
+    end
+  end
+end

data/lib/sunspot/date_facet_row.rb

@@ -0,0 +1,17 @@
+module Sunspot
+  #TODO document
+  class DateFacetRow < FacetRow
+    def initialize(pair, gap, facet)
+      @gap = gap
+      super(pair, facet)
+    end
+
+    def value
+      @value ||=
+        begin
+          start_date = @facet.field.cast(@pair[0])
+          Range.new(start_date, start_date + @gap)
+        end
+    end
+  end
+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