sunspot.rb in outoftime-sunspot-0.8.0

- old
+ new

@@ -1,10 +1,11 @@
 gem 'solr-ruby'
 require 'solr'
 require File.join(File.dirname(__FILE__), 'light_config')
 
-%w(adapters restriction configuration setup field facets indexer query search facet facet_row session type util dsl).each do |filename|
+%w(adapters configuration setup field data_extractor indexer
+   query search facet facet_row session type util dsl).each do |filename|
   require File.join(File.dirname(__FILE__), 'sunspot', filename)
 end
 
 #
 # The Sunspot module provides class-method entry points to most of the
@@ -91,10 +92,45 @@
     #
     # It is fine to specify a field both as a text field and a string field;
     # internally, the fields will have different names so there is no danger
     # of conflict.
     # 
+    # ===== Dynamic Fields
+    # 
+    # For use cases which have highly dynamic data models (for instance, an
+    # open set of key-value pairs attached to a model), it may be useful to
+    # defer definition of fields until indexing time. Sunspot exposes dynamic
+    # fields, which define a data accessor (either attribute or virtual, see
+    # above), which accepts a hash of field names to values. Note that the field
+    # names in the hash are internally scoped to the base name of the dynamic
+    # field, so any time they are referred to, they are referred to using both
+    # the base name and the dynamic (runtime-specified) name.
+    #
+    # Dynamic fields are speficied in the setup block using the type name
+    # prefixed by +dynamic_+. For example:
+    # 
+    #   Sunspot.setup(Post) do
+    #     dynamic_string :custom_values do
+    #       key_value_pairs.inject({}) do |hash, key_value_pair|
+    #         hash[key_value_pair.key.to_sym] = key_value_pair.value
+    #       end
+    #     end
+    #   end
+    # 
+    # If you later wanted to facet all of the values for the key "cuisine",
+    # you could issue:
+    # 
+    #   Sunspot.search(Post) do
+    #     dynamic :custom_values do
+    #       facet :cuisine
+    #     end
+    #   end
+    # 
+    # In the documentation, +:custom_values+ is referred to as the "base name" -
+    # that is, the one specified statically - and +:cuisine+ is referred to as
+    # the dynamic name, which is the part that is specified at indexing time.
+    # 
     def setup(clazz, &block)
       Setup.setup(clazz, &block)
     end
 
     # Indexes objects on the singleton session.
@@ -144,18 +180,53 @@
     #
     def commit
       session.commit
     end
 
+    # 
+    # Create a new Search instance, but do not execute it immediately. Generally
+    # you will want to use the #search method to execute searches using the
+    # DSL; however, if you are building searches dynamically (using the Builder
+    # pattern, for instance), it may be easier to access the Query API directly.
+    # 
+    # ==== Parameters
+    #
+    # types<Class>...::
+    #   Zero, one, or more types to search for. If no types are passed, all
+    #   configured types will be searched for.
+    #
+    # ==== Returns
+    #
+    # Sunspot::Search::
+    #   Search object, not yet executed. Query parameters can be added manually;
+    #   then #execute! should be called.
+    # 
+    def new_search(*types)
+      session.new_search(*types)
+    end
+
+
     # Search for objects in the index.
     #
     # ==== Parameters
     #
     # types<Class>...::
     #   Zero, one, or more types to search for. If no types are passed, all
     #   configured types will be searched.
     #
+    # ==== Options (last argument, optional)
+    #
+    # :keywords<String>:: Fulltext search string
+    # :conditions<Hash>::
+    #   Hash of key-value pairs to be used as restrictions. Keys are field
+    #   names. Scalar values are used as equality restrictions; arrays are used
+    #   as "any of" restrictions; and Ranges are used as range restrictions.
+    # :order<String>:: order field and direction (e.g., 'updated_at desc')
+    # :page<Integer>:: Page to start on for pagination
+    # :per_page<Integer>::
+    #   Number of results to use per page. Ignored if :page is not specified.
+    #
     # ==== Returns
     #
     # Sunspot::Search:: Object containing results, facets, count, etc.
     #
     # The fields available for restriction, ordering, etc. are those that meet
@@ -199,11 +270,21 @@
     #     without current_post
     #     facet :category_ids
     #     order_by :published_at, :desc
     #     paginate 2, 15
     #   end
+    #  
+    # If the block passed to #search takes an argument, that argument will
+    # present the DSL, and the block will be evaluated in the calling context.
+    # This will come in handy for building searches using instance data or
+    # methods, e.g.:
     #
-    # See Sunspot::DSL::Query for the full API presented inside the block.
+    #   Sunspot.search(Post) do |query|
+    #     query.with(:blog_id, @current_blog.id)
+    #   end
+    #
+    # See Sunspot::DSL::Scope and Sunspot::DSL::Query for the full API presented
+    # inside the block.
     #
     def search(*types, &block)
       session.search(*types, &block)
     end
 