outoftime-sunspot 0.8.9 → 0.9.0

data/README.rdoc

@@ -3,7 +3,7 @@
 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
+Sunspot is built on top of the RSolr 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 for them.
 
@@ -19,6 +19,7 @@ objects such as the filesystem.
 * Intuitive DSL for scoping searches, with all the usual boolean operators available
 * Intuitive interface for requesting facets on indexed fields
 * Extensible adapter architecture for easy integration of other ORMs or non-model classes
+* Refine search using field facets, date range facets, or ultra-powerful query facets
 * Full compatibility with will_paginate
 * Ordering
 
@@ -87,6 +88,10 @@ to define your own. See Sunspot::Adapters for more information.
     with(:blog_id).any_of [2, 14]
     with(:category_ids).all_of [4, 10]
     with(:published_at).less_than Time.now
+    any_of do
+      with(:expired_at).greater_than(Time.now)
+      with(:expired_at, nil)
+    end
     without :title, 'Bad Title'
     without bad_instance # specifically exclude this instance from results
 
@@ -106,23 +111,6 @@ 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
@@ -133,10 +121,14 @@ me so I can rectify the situation!
 
 == Dependencies
 
-1. solr-ruby
-2. Java
+1. RSolr
+2. Daemons
+3. OptiFlag
+4. Haml
+5. Java
 
-Sunspot has been tested with MRI 1.8.6, YARV 1.9.1, and JRuby 1.2.0
+Sunspot has been tested with MRI 1.8.6 and 1.8.7, REE 1.8.6, YARV 1.9.1, and
+JRuby 1.2.0
 
 == Bugs
 

data/Rakefile

@@ -1,5 +1,3 @@
-require 'rubygems'
-
 ENV['RUBYOPT'] = '-W1'
 
 task :environment do

data/TODO

@@ -1,17 +1,4 @@
 === 0.9 ===
-* Descriptive error messages during indexing
-* Date type
-* High-endian fields
-* Add omitNorms to typed fields
-* Instantiated facets!
-* Direct access to adapter
-* sunspot-configure-solr
-* Text fields allow multiple
-* Don't allow ordering on multiple-allowed fields
-* Detect Ranges in short-form #with()
-* Expose delete by ID
-* Support composite IDs
-* Transactions
-* Switch to RSolr
-* Facet by type (?)
 * Query-based faceting (?)
+=== 0.10 ===
+* Intelligently decide whether to instantiate all facet rows at once

data/VERSION.yml

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

data/bin/sunspot-configure-solr

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+using_gems = false
+begin
+  require 'fileutils'
+  require 'optiflag'
+  require File.join(File.dirname(__FILE__), '..', 'lib', 'sunspot', 'schema')
+rescue LoadError => e
+  if using_gems
+    raise(e)
+  else
+    using_gems = true
+    require 'rubygems'
+    retry
+  end
+end
+
+module ConfigureSolrFlags extend OptiFlagSet
+  optional_flag 'tokenizer'
+  optional_flag 'extra_filters'
+  optional_flag 'dir'
+  and_process!
+end
+
+solr_directory = ARGV.flags.dir || FileUtils.pwd
+conf_directory = File.join(solr_directory, 'conf')
+schema_file = File.join(conf_directory, 'schema.xml')
+FileUtils.mkdir_p(conf_directory)
+
+schema = Sunspot::Schema.new
+schema.tokenizer = ARGV.flags.tokenizer if ARGV.flags.tokenizer
+if ARGV.flags.extra_filters
+  for filter in ARGV.flags.extra_filters.split(',')
+    schema.add_filter(filter)
+  end
+end
+
+if File.exist?(schema_file)
+  backup_file = File.join(conf_directory, "schema-#{File.mtime(schema_file).strftime('%Y%m%d%H%M%S')}.xml")
+  STDERR.puts("Backing up current schema file to #{File.expand_path(backup_file)}")
+  FileUtils.mv(schema_file, backup_file)
+end
+
+File.open(File.join(conf_directory, 'schema.xml'), 'w') do |file|
+  file << schema.to_xml
+end

data/bin/sunspot-solr

@@ -1,11 +1,19 @@
 #!/usr/bin/env ruby
-require 'rubygems'
-gem 'daemons', '~> 1.0'
-gem 'optiflag', '~> 0.6.5'
-require 'fileutils'
-require 'tmpdir'
-require 'daemons'
-require 'optiflag'
+using_gems = false
+begin
+  require 'fileutils'
+  require 'tmpdir'
+  require 'daemons'
+  require 'optiflag'
+rescue LoadError => e
+  if using_gems
+    raise(e)
+  else
+    using_gems = true
+    require 'rubygems'
+    retry
+  end
+end
 
 working_directory = FileUtils.pwd
 solr_home = File.join(File.dirname(__FILE__), '..', 'solr')

data/lib/sunspot/adapters.rb

@@ -61,7 +61,7 @@ module Sunspot
       # String:: ID for use in Solr
       #
       def index_id #:nodoc:
-        "#{@instance.class.name} #{id}"
+        InstanceAdapter.index_id_for(@instance.class.name, id)
       end
 
       class <<self
@@ -127,6 +127,10 @@ module Sunspot
                 "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)
+          "#{class_name} #{id}"
+        end
+
         protected
 
         # Lazy-initialize the hash of registered instance adapters

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

@@ -2,6 +2,11 @@ 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')
@@ -19,8 +24,9 @@ module Sunspot
       #
       def build #:nodoc:
         LightConfig.build do
+          http_client :net_http
           solr do
-            url 'http://localhost:8983/solr'
+            url 'http://127.0.0.1:8983/solr'
           end
           pagination do
             default_per_page 30

data/lib/sunspot/data_extractor.rb

@@ -33,5 +33,15 @@ module Sunspot
         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

@@ -17,16 +17,43 @@ module Sunspot
       # 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_fields(Field::StaticField.build(name, Type::TextType, &block))
+          @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,
@@ -49,9 +76,9 @@ module Sunspot
         end
         name = args.shift
         if method.to_s =~ /^dynamic_/
-          @setup.add_dynamic_fields(Field::DynamicField.build(name, type, *args, &block))
+          @setup.add_dynamic_field_factory(name, type, *args, &block)
         else
-          @setup.add_fields(Field::StaticField.build(name, type, *args, &block))
+          @setup.add_field_factory(name, type, *args, &block)
         end
       end
     end

data/lib/sunspot/dsl/query.rb

@@ -3,28 +3,33 @@ module Sunspot
     #
     # This class presents a DSL for constructing queries using the
     # Sunspot.search method. Methods of this class are available inside the
-    # 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.
+    # 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 < Scope
+    class Query < FieldQuery
       # Specify a phrase that should be searched as fulltext. Only +text+
       # fields are searched - see DSL::Fields.text
       #
-      # Note that the keywords are passed directly to Solr unadulterated. The
-      # advantage of this is that users can potentially use boolean logic to
-      # make advanced searches. The disadvantage is that syntax errors are
-      # possible. This may get better in a future version; suggestions are
-      # welcome.
+      # 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
       #
-      def keywords(keywords)
-        @query.keywords = keywords
+      # ==== 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
@@ -49,30 +54,6 @@ module Sunspot
         raise ArgumentError, "unknown argument #{options.keys.first.inspect} passed to paginate" unless options.empty?
         @query.paginate(page, per_page)
       end
-
-      #
-      # 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
-      #
-      # ==== Example
-      #
-      #   Sunspot.search Post do
-      #     dynamic :custom do
-      #       with :cuisine, 'Pizza'
-      #       facet :atmosphere
-      #       order_by :chef_name
-      #     end
-      #   end
-      #
-      def dynamic(base_name, &block)
-        Scope.new(@query.dynamic_query(base_name)).instance_eval(&block)
-      end
     end
   end
 end