outoftime-sunspot 0.0.2 → 0.7.0

data/lib/sunspot/session.rb

@@ -1,43 +1,110 @@
 module Sunspot
+  # 
+  # A Sunspot session encapsulates a connection to Solr and a set of
+  # configuration choices. Though users of Sunspot may manually instantiate
+  # Session objects, in the general case it's easier to use the singleton
+  # stored in the Sunspot module. Since the Sunspot module provides all of
+  # the instance methods of Session as class methods, they are not documented
+  # again here.
+  #
   class Session
     attr_reader :config
 
-    def initialize(config = Sunspot::Configuration.build, connection = nil)
+    # 
+    # Sessions are initialized with a Sunspot configuration and a Solr
+    # connection. Usually you will want to stick with the default arguments
+    # when instantiating your own sessions.
+    #
+    def initialize(config = Configuration.build, connection = nil)
       @config = config
       yield(@config) if block_given?
       @connection = connection
     end
 
+    #
+    # See Sunspot.search
+    #
     def search(*types, &block)
-      ::Sunspot::Search.new(connection, @config, *types, &block).execute!
+      types.flatten!
+      Search.new(connection, @config, *types, &block).execute!
     end
 
+    #
+    # See Sunspot.index
+    #
     def index(*objects)
+      objects.flatten!
       for object in objects
-        ::Sunspot::Indexer.add(connection, object)
+        setup_for(object).indexer(connection).add(object)
       end
     end
 
+    # 
+    # See Sunspot.index!
+    #
+    def index!(*objects)
+      index(*objects)
+      commit
+    end
+
+    #
+    # See Sunspot.commit!
+    #
+    def commit
+      connection.commit
+    end
+
+    # 
+    # See Sunspot.remove
+    #
     def remove(*objects)
+      objects.flatten!
       for object in objects
-        ::Sunspot::Indexer.remove(connection, object)
+        setup_for(object).indexer(connection).remove(object)
       end
     end
 
+    #
+    # See Sunspot.remove_all
+    #
     def remove_all(*classes)
+      classes.flatten!
       if classes.empty?
-        ::Sunspot::Indexer.remove_all(connection)
+        Indexer.remove_all(connection)
       else
-        classes.each do |clazz|
-          ::Sunspot::Indexer.remove_all(connection, clazz)
+        for clazz in classes
+          Setup.for(clazz).indexer(connection).remove_all
         end
       end
     end
 
     private
 
+    # 
+    # Get the Setup object for the given object's class.
+    #
+    # ==== Parameters
+    #
+    # object<Object>:: The object whose setup is to be retrieved
+    #
+    # ==== Returns
+    #
+    # Sunspot::Setup:: The setup for the object's class
+    #
+    def setup_for(object)
+      Setup.for(object.class) || raise(ArgumentError, "Sunspot is not configured for #{object.class.inspect}")
+    end
+
+    # 
+    # Retrieve the Solr connection for this session, creating one if it does not
+    # already exist.
+    #
+    # ==== Returns
+    #
+    # Solr::Connection:: The connection for this session
+    #
     def connection
-      @connection ||= Solr::Connection.new(config.solr.url, :autocommit => :on)
+      @connection ||= Solr::Connection.new(config.solr.url)
     end
   end
 end

data/lib/sunspot/setup.rb

@@ -0,0 +1,171 @@
+module Sunspot
+  # 
+  # This class encapsulates the search/indexing setup for a given class. Its
+  # contents are built using the Sunspot.setup method.
+  #
+  class Setup #:nodoc:
+    def initialize(clazz)
+      @class_name = clazz.name
+      @fields, @text_fields = [], []
+      @dsl = DSL::Fields.new(self)
+    end
+
+    # 
+    # Add fields for scope/ordering
+    # 
+    # ==== Parameters
+    #
+    # fields<Array>:: Array of Sunspot::Field objects
+    #
+    def add_fields(fields)
+      @fields.concat(Array(fields))
+    end
+
+    # 
+    # Add fields for fulltext search
+    #
+    # ==== Parameters
+    #
+    # fields<Array>:: Array of Sunspot::Field objects
+    #
+    def add_text_fields(fields)
+      @text_fields.concat(Array(fields))
+    end
+
+    # 
+    # Builder method for evaluating the setup DSL
+    #
+    def setup(&block)
+      @dsl.instance_eval(&block)
+    end
+
+    # 
+    # Get the fields associated with this setup as well as all inherited fields
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of all fields associated with this setup
+    #
+    def fields
+      fields = @fields.dup
+      fields.concat(parent.fields) if parent
+      fields
+    end
+
+    # 
+    # Get the text fields associated with this setup as well as all inherited
+    # text fields
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of all text fields associated with this setup
+    #
+    def text_fields
+      text_fields = @text_fields.dup
+      text_fields.concat(parent.text_fields) if parent
+      text_fields
+    end
+
+    # 
+    # Get all scope and text fields associated with this setup as well as all
+    # inherited fields
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of all text and scope fields associated with this setup
+    #
+    def all_fields
+      fields + text_fields
+    end
+
+    # 
+    # Factory method for an Indexer object configured to use this setup
+    #
+    # ==== Returns
+    #
+    # Sunspot::Indexer:: Indexer configured with this setup
+    def indexer(connection)
+      Indexer.new(connection, self)
+    end
+
+    # 
+    # Return the class associated with this setup.
+    #
+    # ==== Returns
+    #
+    # clazz<Class>:: Class setup is configured for
+    #
+    def clazz
+      Util.full_const_get(@class_name)
+    end
+
+    protected
+
+    # 
+    # Get the nearest inherited setup, if any
+    #
+    # ==== Returns
+    # 
+    # Sunspot::Setup:: Setup for the nearest ancestor of this setup's class
+    #
+    def parent
+      Setup.for(clazz.superclass)
+    end
+
+    class <<self
+      # 
+      # Retrieve or create the Setup instance for the given class, evaluating
+      # the given block to add to the setup's configuration
+      #
+      def setup(clazz, &block) #:nodoc:
+        self.for!(clazz).setup(&block)
+      end
+
+      # 
+      # Retrieve the setup instance for the given class, or for the nearest
+      # ancestor that has a setup, if any.
+      #
+      # ==== Parameters
+      #
+      # clazz<Class>:: Class for which to retrieve a setup
+      #
+      # ==== Returns
+      #
+      # Sunspot::Setup::
+      #   Setup instance associated with the given class or its nearest ancestor
+      #   
+      def for(clazz) #:nodoc:
+        setups[clazz.name.to_sym] || self.for(clazz.superclass) if clazz
+      end
+
+      protected
+
+      # 
+      # Retrieve or create a Setup instance for this class
+      #
+      # ==== Parameters
+      #
+      # clazz<Class>:: Class for which to retrieve a setup
+      #
+      # ==== Returns
+      #
+      # Sunspot::Setup:: New or existing setup for this class
+      #
+      def for!(clazz) #:nodoc:
+        setups[clazz.name.to_sym] ||= new(clazz)
+      end
+
+      private
+
+      # Singleton hash of class names to Setup instances
+      #
+      # ==== Returns
+      #
+      # Hash:: Class names keyed to Setup instances
+      #
+      def setups
+        @setups ||= {}
+      end
+    end
+  end
+end

data/lib/sunspot/type.rb

@@ -1,60 +1,144 @@
 module Sunspot
+  # 
+  # This module contains singleton objects that represent the types that can be
+  # indexed and searched using Sunspot. Plugin developers should be able to
+  # add new constants to the Type module; as long as they implement the
+  # appropriate methods, Sunspot should be able to integrate them (note that
+  # this capability is untested at the moment). The required methods are:
+  #
+  # +indexed_name+::
+  #   Convert a given field name into its form as stored in Solr. This
+  #   generally means adding a suffix to match a Solr dynamicField definition.
+  # +to_indexed+::
+  #   Convert a value of this type into the appropriate Solr string
+  #   representation.
+  # +cast+::
+  #   Convert a Solr string representation of a value into the appropriate
+  #   Ruby type.
+  #
   module Type
-    TextType = Module.new
-    StringType = Module.new
-    IntegerType = Module.new
-    FloatType = Module.new
-    TimeType = Module.new
-
-    class <<TextType
-      def indexed_name(name)
+    # 
+    # Text is a special type that stores data for fulltext search. Unlike other
+    # types, Text fields are tokenized and are made available to the keyword
+    # search phrase. Text fields cannot be faceted, ordered upon, or used in
+    # restrictions. Similarly, text fields are the only fields that are made
+    # available to keyword search.
+    #
+    module TextType
+      class <<self
+        def indexed_name(name) #:nodoc:
         "#{name}_text"
-      end
+        end
 
-      def to_indexed(value)
-        value.to_s if value
+        def to_indexed(value) #:nodoc:
+          value.to_s if value
+        end
       end
     end
 
-    class <<StringType
-      def indexed_name(name)
+    # 
+    # The String type represents string data.
+    #
+    module StringType
+      class <<self
+        def indexed_name(name) #:nodoc:
         "#{name}_s"
-      end
+        end
+
+        def to_indexed(value) #:nodoc:
+          value.to_s if value
+        end
 
-      def to_indexed(value)
-        value.to_s if value
+        def cast(string) #:nodoc:
+          string
+        end
       end
     end
 
-    class <<IntegerType
-      def indexed_name(name)
+    # 
+    # The Integer type represents integers.
+    #
+    module IntegerType
+      class <<self
+        def indexed_name(name) #:nodoc:
         "#{name}_i"
-      end
+        end
 
-      def to_indexed(value)
-        value.to_i.to_s if value
+        def to_indexed(value) #:nodoc:
+          value.to_i.to_s if value
+        end
+
+        def cast(string) #:nodoc:
+          string.to_i
+        end
       end
     end
 
-    class <<FloatType
-      def indexed_name(name)
+    # 
+    # The Float type represents floating-point numbers.
+    #
+    module FloatType
+      class <<self
+        def indexed_name(name) #:nodoc:
         "#{name}_f"
-      end
+        end
+
+        def to_indexed(value) #:nodoc:
+          value.to_f.to_s if value
+        end
 
-      def to_indexed(value)
-        value.to_f.to_s if value
+        def cast(string) #:nodoc:
+          string.to_f
+        end
       end
     end
 
-    class <<TimeType
-      def indexed_name(name)
+    # 
+    # The time type represents times. Note that times are always converted to
+    # UTC before indexing, and facets of Time fields always return times in UTC.
+    #
+    module TimeType
+      class <<self
+        def indexed_name(name)
         "#{name}_d"
+        end
+
+        def to_indexed(value)
+          if value
+            time = value.respond_to?(:to_time) ? value.to_time : Time.parse(value.to_s)
+            time.utc.xmlschema
+          end
+        end
+
+        def cast(string)
+          Time.xmlschema(string)
+        end
       end
+    end
+
+    # 
+    # The boolean type represents true/false values. Note that +nil+ will not be
+    # indexed at all; only +false+ will be indexed with a false value.
+    #
+    module BooleanType
+      class <<self
+        def indexed_name(name)
+        "#{name}_b"
+        end
+
+        def to_indexed(value)
+          unless value.nil?
+            value ? 'true' : 'false'
+          end
+        end
 
-      def to_indexed(value)
-        if value
-          time = value.respond_to?(:to_time) ? value.to_time : Time.parse(value.to_s)
-          time.utc.strftime('%FT%TZ')
+        def cast(string)
+          case string
+          when 'true'
+            true
+          when 'false'
+            false
+          end
         end
       end
     end

data/lib/sunspot/util.rb

@@ -1,12 +1,146 @@
 module Sunspot
-  module Util
-    class ClosedStruct
-      def initialize(data)
-        (class <<self; self; end).module_eval do
-          data.each_pair do |attr_name, value|
-            define_method(attr_name.to_s) { value }
-          end
+  # 
+  # The Sunspot::Util module provides utility methods used elsewhere in the
+  # library.
+  #
+  module Util #:nodoc:
+    class <<self
+      # 
+      # Get all of the superclasses for a given class, including the class
+      # itself.
+      # 
+      # ==== Parameters
+      #
+      # clazz<Class>:: class for which to get superclasses
+      #
+      # ==== Returns
+      #
+      # Array:: Collection containing class and its superclasses
+      #
+      def superclasses_for(clazz)
+        superclasses = [clazz]
+        superclasses << (clazz = clazz.superclass) while clazz.superclass != Object
+        superclasses
+      end
+
+      # 
+      # Convert a string to snake case
+      #
+      # ==== Parameters
+      #
+      # string<String>:: String to convert to snake case
+      #
+      # ==== Returns
+      #
+      # String:: String in snake case
+      #
+      def snake_case(string)
+        string.scan(/(^|[A-Z])([^A-Z]+)/).map! { |word| word.join.downcase }.join('_')
+      end
+
+      # 
+      # Convert a string to camel case
+      #
+      # ==== Parameters
+      #
+      # string<String>:: String to convert to camel case
+      #
+      # ==== Returns
+      #
+      # String:: String in camel case
+      #
+      def camel_case(string)
+        string.split('_').map! { |word| word.capitalize }.join
+      end
+
+      # 
+      # Get a constant from a fully qualified name
+      #
+      # ==== Parameters
+      #
+      # string<String>:: The fully qualified name of a constant
+      #
+      # ==== Returns
+      #
+      # Object:: Value of constant named
+      #
+      def full_const_get(string)
+        string.split('::').inject(Object) do |context, const_name|
+          context.const_get(const_name)
+        end
+      end
+
+      # 
+      # Perform a deep merge of hashes, returning the result as a new hash.
+      # See #deep_merge_into for rules used to merge the hashes
+      #
+      # ==== Parameters
+      #
+      # left<Hash>:: Hash to merge
+      # right<Hash>:: The other hash to merge
+      #
+      # ==== Returns
+      #
+      # Hash:: New hash containing the given hashes deep-merged.
+      #
+      def deep_merge(left, right)
+        deep_merge_into({}, left, right)
+      end
+
+      # 
+      # Perform a deep merge of the right hash into the left hash
+      #
+      # ==== Parameters
+      #
+      # left:: Hash to receive merge
+      # right:: Hash to merge into left
+      #
+      # ==== Returns
+      #
+      # Hash:: left
+      #
+      def deep_merge!(left, right)
+        deep_merge_into(left, left, right)
+      end
+
+      private
+
+      # 
+      # Deep merge two hashes into a third hash, using rules that produce nice
+      # merged parameter hashes. The rules are as follows, for a given key:
+      #
+      # * If only one hash has a value, or if both hashes have the same value,
+      #   just use the value.
+      # * If either of the values is not a hash, create arrays out of both
+      #   values and concatenate them.
+      # * Otherwise, deep merge the two values (which are both hashes)
+      #
+      # ==== Parameters
+      #
+      # destination<Hash>:: Hash into which to perform the merge
+      # left<Hash>:: One hash to merge
+      # right<Hash>:: The other hash to merge
+      #
+      # ==== Returns
+      #
+      # Hash:: destination
+      #
+      def deep_merge_into(destination, left, right)
+        left.each_pair do |name, left_value|
+          right_value = right[name]
+          destination[name] =
+            if right_value.nil? || left_value == right_value
+              left_value
+            elsif !left_value.respond_to?(:each_pair) || !right_value.respond_to?(:each_pair)
+              Array(left_value) + Array(right_value)
+            else
+              merged_value = {}
+              deep_merge_into(merged_value, left_value, right_value)
+            end
         end
+        left_keys = Set.new(left.keys)
+        destination.merge!(right.reject { |k, v| left_keys.include?(k) })
+        destination
       end
     end
   end