albanpeignier-searchapi 0.1

data/lib/search_api/active_record_integration.rb

@@ -0,0 +1,272 @@
+require 'search_api'
+
+module SearchApi
+  
+  # Module that holds SearchApi integration patterns.
+  module Integration
+    
+    # Module that holds integration of SearchApi into ActiveRecord.
+    module ActiveRecord
+
+      # This module allows the ActiveRecord::Base classes to transparently
+      # integrate SearchApi::Search::Base features.
+      #
+      # It is included in a ActiveRecord::Base subclass by calling has_search_api:
+      #
+      #   class People < ActiveRecord::Base
+      #     has_search_api
+      #   
+      #     # define age search key
+      #     search :age do |search|
+      #       { :conditions => ['birth_date BETWEEN ? AND ?',
+      #                         (Date.today-search.age.years),
+      #                         (Date.today-(search.age-1).years+1.day)]}
+      #     end
+      #   end
+      #
+      #   People.find(:all, :conditions => {:first_name => 'Roger', :age => 30})
+      
+      module Base
+        # Modifies the class including that module so that :find, :count and :with_scope
+        # methods have support for search keys added by the search method.
+        #
+        # <b>Don't include yourself this module !</b> Instead, use
+        # ActiveRecord::Base.has_search_api method.
+        def self.append_features(base)
+          super
+          base.alias_method_chain(:find, :search_support)
+          base.alias_method_chain(:count, :search_support)
+          base.alias_method_chain(:with_scope, :search_support)
+        end
+    
+        # Alteration of the :find method that has support for search keys added by the search method.
+        def find_with_search_support(*args)
+          options = if args.last.is_a?(Hash) then args.last else {} end
+          if options[:conditions].nil? || options[:conditions].is_a?(Hash)
+            send(:with_scope, :find => search_class.new(options.delete(:conditions)).find_options) do
+              find_without_search_support(*args)
+            end
+          else
+            find_without_search_support(*args)
+          end
+        end
+
+        # Alteration of the :count method that has support for search keys added by the search method.
+        def count_with_search_support(*args)
+          options = if args.last.is_a?(Hash) then args.last else {} end
+          if options[:conditions].nil? || options[:conditions].is_a?(Hash)
+            send(:with_scope, :find => search_class.new(options.delete(:conditions)).find_options) do
+              count_without_search_support(*args)
+            end
+          else
+            count_without_search_support(*args)
+          end
+        end
+
+        # Alteration of the :with_scope method that has support for search keys added by the search method.
+        def with_scope_with_search_support(method_scoping = {}, action = :merge, &block)
+          if method_scoping[:find] && method_scoping[:find][:conditions] && method_scoping[:find][:conditions].is_a?(Hash)
+            with_scope_without_search_support(:find => search_class.new(method_scoping[:find].delete(:conditions)).find_options) do
+              with_scope_without_search_support(method_scoping, action, &block)
+            end
+          else
+            with_scope_without_search_support(method_scoping, action, &block)
+          end
+        end
+        
+        # Extends the keys that conditions hashes can hold.
+        #
+        # ActiveRecord::Base.find can take a <tt>:conditions</tt> option. This option
+        # can be raw SQL, a SQL fragment such as <tt>['a=?',1]</tt>, or a condition hash
+        # such as <tt>{:column1 => value, ;column2 => value}</tt>.
+        #
+        # <b>The search method allows you to extend the keys that condition hash
+        # can hold.</b>
+        #
+        # For instance, assuming a :birth_date column exists in your table, you
+        # can define the :age search key:
+        #
+        #   class People < ActiveRecord::Base
+        #     has_search_api
+        #   
+        #     # define age search key
+        #     search :age do |search|
+        #       { :conditions => ['birth_date BETWEEN ? AND ?',
+        #                         (Date.today-search.age.years),
+        #                         (Date.today-(search.age-1).years+1.day)]}
+        #     end
+        #   end
+        #
+        # The options parameter allows you to define some search keys without
+        # providing a block:
+        #
+        #   class People < ActiveRecord::Base
+        #     has_search_api
+        #   
+        #     search :keyword, :operator => :full_text, :columns => [:first_name, :last_name, :email]
+        #     search :email_domain, :operator => :ends_with, :column => :email
+        #   end
+        #
+        # For further details, see:
+        # - how search attributes are defined: SearchApi::Search::Base.search_accessor;
+        # - which options are understood: SearchApi::Bridge::ActiveRecord#rewrite_search_attribute_builder method.
+        def search(name, options={}, &block)
+          search_class.search_accessor(name, options, &block)
+        end
+      end
+        
+
+      # This module allows the ActiveRecord::Base associations to transparently
+      # integrate SearchApi::Search::Base features.
+      #
+      #   class People < ActiveRecord::Base
+      #     belongs_to :company
+      #     has_search_api
+      #   
+      #     # define age search key
+      #     search :age do |search|
+      #       { :conditions => ['birth_date BETWEEN ? AND ?',
+      #                         (Date.today-search.age.years),
+      #                         (Date.today-(search.age-1).years+1.day)]}
+      #     end
+      #   end
+      #
+      #   some_company.people.find(:all, :conditions => {:first_name => 'Roger', :age => 30})
+      module Associations
+
+        # Module that holds integration of SearchApi::Search::Base into
+        # ActiveRecord::Associations::HasManyAssociation,
+        # ActiveRecord::Associations::HasAndBelongsToManyAssociation, and
+        # ActiveRecord::Associations::HasManyThroughAssociation.
+        module Find
+          def self.append_features(base) #:nodoc:
+            super
+            base.alias_method_chain(:find, :search_support)
+          end
+
+          # Alteration of the :find method that has support for search keys added by the search method.
+          def find_with_search_support(*args)
+            if @reflection.klass.respond_to?(:search_class)
+              options = if args.last.is_a?(Hash) then args.last else {} end
+              if options[:conditions].nil? || options[:conditions].is_a?(Hash)
+                @reflection.klass.send(:with_scope, :find => @reflection.klass.search_class.new(options.delete(:conditions)).find_options) do
+                  find_without_search_support(*args)
+                end
+              else
+                find_without_search_support(*args)
+              end
+            else
+              find_without_search_support(*args)
+            end
+          end
+        end
+
+        # Module that holds integration of SearchApi::Search::Base into ActiveRecord::Associations::HasManyAssociation.
+        module Count
+          def self.append_features(base) #:nodoc:
+            super
+            base.alias_method_chain(:count, :search_support)
+          end
+
+          # Alteration of the :count method that has support for search keys added by the search method.
+          def count_with_search_support(*args)
+            if @reflection.klass.respond_to?(:search_class)
+              options = if args.last.is_a?(Hash) then args.last else {} end
+              if options[:conditions].nil? || options[:conditions].is_a?(Hash)
+                @reflection.klass.send(:with_scope, :find => @reflection.klass.search_class.new(options.delete(:conditions)).find_options) do
+                  count_without_search_support(*args)
+                end
+              else
+                count_without_search_support(*args)
+              end
+            else
+              count_without_search_support(*args)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+class ActiveRecord::Base
+  class << self
+    
+    # This method has following consequences:
+    #
+    # - The ActiveRecord::Base class is made searchable.
+    #
+    #   Practically speaking, a SearchApi::Search::Base subclass that targets
+    #   this model is created, prefilled with many automatic search keys
+    #   (see SearchApi::Bridge::ActiveRecord).
+    #
+    # - The ActiveRecord::Base class is able to define its own condition hash keys.
+    #
+    #   Practically speaking, the SearchApi::Integration::ActiveRecord::Base
+    #   methods are included, and specifically its <tt>search</tt> method that allows to
+    #   define custom keys for condition hashes.
+    #
+    # Example:
+    #
+    #   class People < ActiveRecord::Base
+    #     has_search_api
+    #   
+    #     # define age search key
+    #     search :age do |search|
+    #       { :conditions => ['birth_date BETWEEN ? AND ?',
+    #                         (Date.today-search.age.years),
+    #                         (Date.today-(search.age-1).years+1.day)]}
+    #     end
+    #   end
+    #
+    #   People.search_class # => the SearchApi::Search::Base subclass for People.
+    #   People.find(:all, :conditions => { :age => 30 })
+    #
+    # Optional block is for advanced purpose only. It is executed as a
+    # <tt>class_eval</tt> block for the SearchApi::Search::Base subclass.
+    #
+    #   class People < ActiveRecord::Base
+    #     has_search_api do
+    #       ...
+    #     end
+    #   end
+    def has_search_api(&block) # :yields:
+      # Creates a new SearchApi::Search::Base subclass
+      search_class = Class.new(::SearchApi::Search::Base)
+      
+      # Tells the SearchApi::Search::Base subclass which models it searches in
+      search_class.model(self, :type_cast=>true)
+      
+      # Let given block define search keys
+      search_class.class_eval(&block) if block
+            
+      (class << self; self; end).instance_eval do
+        # The search_class method returns the SearchApi::Search::Base subclass.
+        define_method(:search_class) { search_class }
+        
+        # Alter class behavior so that the SearchApi::Search::Base subclass seemlessly integrates.
+        include ::SearchApi::Integration::ActiveRecord::Base
+      end
+      
+      nil # don't pollute class creation
+    end
+  end
+end
+
+
+# Modify associations behaviors
+
+ActiveRecord::Associations::HasManyAssociation.module_eval do
+  include ::SearchApi::Integration::ActiveRecord::Associations::Find
+  include ::SearchApi::Integration::ActiveRecord::Associations::Count
+end
+
+ActiveRecord::Associations::HasAndBelongsToManyAssociation.module_eval do
+  include ::SearchApi::Integration::ActiveRecord::Associations::Find
+end
+
+ActiveRecord::Associations::HasManyThroughAssociation.module_eval do
+  include ::SearchApi::Integration::ActiveRecord::Associations::Find
+end
+

data/lib/search_api/bridge.rb

@@ -0,0 +1,75 @@
+module SearchApi
+
+  # Module that holds SearchApi::Bridge::Base and its default subclasses.
+  module Bridge
+    
+    # Base class for SearchApi bridges.
+    #
+    # Such a bridge have following responsabilities:
+    #
+    # - <b>predefining search attributes</b>, when the model of a SearchApi::Search::Base
+    #   subclass is set.
+    #
+    #   This is done by the automatic_search_attribute_builders method.
+    #
+    # - <b>rewriting SearchAttributeBuilder instances</b>.
+    #
+    #   The SearchApi::Search::Base class defines a generic, dull, way to define search attributes.
+    #
+    #   Precisely speaking, the SearchApi::Search::Base.add_search_attribute method,
+    #   the one that actually defines search attributes, has strong
+    #   requirements on its SearchAttributeBuilder parameter.
+    #
+    #   A bridge is able to define a domain-specific way to define search
+    #   attributes. This is the bridge's reponsability
+    #   to translate these domain-specific SearchAttributeBuilder instances
+    #   into strict SearchAttributeBuilder instances, that
+    #   SearchApi::Search::Base.add_search_attribute can use.
+    #
+    #   This is done by the rewrite_search_attribute_builder method.
+    #
+    # - <b>merging find options</b>, in order to build a single option from
+    #   those built by several search attributes.
+    #
+    #   This is done by the merge_find_options method.
+
+    class Base
+    
+      # This method is called when a SearchApi::Search::Base's model is set, in order to
+      # predefine some relevant search keys.
+      #
+      # Returns an Array of SearchAttributeBuilder instances.
+      #
+      # Each builder can be used as an argument for SearchApi::Search::Base.search_accessor.
+      #
+      # Default SearchApi::Bridge::Base behavior is to return an empty Array: there is no
+      # automatic search attributes by default.
+      def automatic_search_attribute_builders(options)
+        []
+      end
+    
+    
+      # This method is called when a SearchApi::Search::Base.search_accessor is
+      # called, to allow SearchApi::Bridge::Base subclasses to handle special builder options.
+      #
+      # Rewrites a SearchAttributeBuilder.
+      #
+      # On output, search_attribute_builder should be a valid 
+      # SearchApi::Search::Base.add_search_attribute argument.
+      #
+      # Default SearchApi::Bridge::Base behavior is to leave the builder untouched.
+      #
+      # Subclasses may take the chance to use some specific options.
+      def rewrite_search_attribute_builder(search_attribute_builder)
+      end
+    
+    
+      # This methods returns a merge of options in options_array.
+      #
+      # Default SearchApi::Bridge::Base behavior is to raise NotImplementedError.
+      def merge_find_options(options_array)
+        raise NotImplementedError.new
+      end
+    end
+  end
+end

data/lib/search_api/callbacks.rb

@@ -0,0 +1,65 @@
+module SearchApi
+  module Search
+    module Callbacks
+      CALLBACKS = %w(before_find_options)
+
+      def self.append_features(base)  #:nodoc:
+        super
+
+        base.class_eval do
+          %w(find_options).each do |method|
+            alias_method_chain method, :callbacks
+          end
+        end
+
+        CALLBACKS.each do |method|
+          base.class_eval <<-"end_eval"
+            def self.#{method}(*callbacks, &block)
+              callbacks << block if block_given?
+              write_inheritable_array(#{method.to_sym.inspect}, callbacks)
+            end
+          end_eval
+        end
+      end
+    
+      def find_options_with_callbacks
+        callback(:before_find_options)
+        find_options_without_callbacks
+      end
+    
+      def before_find_options
+      end
+
+
+      private
+    
+      def callback(method)
+        callbacks_for(method).each do |callback|
+          result = case callback
+            when Symbol
+              self.send(callback)
+            when String
+              eval(callback, binding)
+            when Proc, Method
+              callback.call(self)
+            else
+              if callback.respond_to?(method)
+                callback.send(method, self)
+              else
+                raise SearchApiError, "Callbacks must be a symbol denoting the method to call, a string to be evaluated, a block to be invoked, or an object responding to the callback method."
+              end
+          end
+          return false if result == false
+        end
+
+        result = send(method) if respond_to?(method)
+
+        return result
+      end
+
+      def callbacks_for(method)
+        self.class.read_inheritable_attribute(method.to_sym) or []
+      end
+    end
+  end
+end

data/lib/search_api/errors.rb

@@ -0,0 +1,11 @@
+# This modules provides a framework for encapsulating and performing searches.
+#
+# - SearchApi::Search module holds the abstract search features and behaviors.
+# - SearchApi::Bridge module allows SearchApi::Search to apply to actual classes, and particularly to ActiveRecord::Base.
+# - SearchApi::Integration makes ActiveRecord transparently use search features.
+
+module SearchApi
+  
+  # Base for all SearchApi errors.
+  class SearchApiError < StandardError; end
+end

data/lib/search_api/search.rb

@@ -0,0 +1,473 @@
+module SearchApi
+
+  # The module holds all SearchApi search features
+  
+  module Search
+    
+    # The SearchApi::Search::Base class is able to encapsulate search parameters for a given model.
+    #
+    # In order to search for instances of your model Stuff, you must:
+    #
+    # - ensure Stuff responds to <tt>search_api_bridge</tt> method.
+    #   This is, by default, the case of ActiveRecord::Base subclasses.
+    #
+    # - define a subclass of SearchApi::Search::Base that uses Stuff as a model:
+    #
+    #     class StuffSearch < SearchApi::Search::Base
+    #       # search for Stuff
+    #       model Stuff
+    #     end
+    #
+    # Assuming Stuff is an ActiveRecord::Base subclass, automatic search attributes
+    # are defined in StuffSearch. You can immediately use them:
+    #
+    # Those two statements are strictly equivalent:
+    #
+    #   Stuff.find(:all, {:birth_date => Time.now})
+    #   Stuff.find(:all, StuffSearch.new(:birth_date => Time.now).find_options)
+    #
+    # So far, so good. But that's not very funky.
+    #
+    # You can also define your own search attributes:
+    #
+    #   class StuffSearch < SearchApi::Search::Base
+    #     # search for Stuff
+    #     model Stuff
+    #     search_accessor :max_age do |search|
+    #       { :conditions => ['birth_date > ?', Time.now - search.max_age.years]}
+    #     end
+    #   end
+    # 
+    # This allows you to perform searches on age:
+    #
+    #   Stuff.find(:all, StuffSearch.new(:max_age => 20).find_options)
+    #
+    # You can mix search keys:
+    #
+    #   Stuff.find(:all, StuffSearch.new(:max_age => 20, :sex => 'M').find_options)
+    class Base
+    
+      VALID_SEARCH_ATTRIBUTE_OPTIONS = [ :store_as, :default ]
+
+      class << self
+
+        # Without any argument, returns the model of this SearchApi::Search::Base class.
+        #
+        # With a single argument, this method defines the model of this SearchApi::Search::Base class.
+        #
+        # The model must respond_to the <tt>search_api_bridge</tt> method,
+        # which should return an object that acts like SearchApi::Bridge::Base.
+        # 
+        # The model can't be defined twice.
+        #
+        # Some automatic search accessors may be defined when the model is set.
+        # See:
+        # - Bridge::Base#automatic_search_attribute_builders
+        # - Bridge::ActiveRecord#automatic_search_attribute_builders
+        #
+        # Example:
+        #   class StuffSearch < SearchApi::Search::Base
+        #     # search for Stuff
+        #     model Stuff
+        #     ...
+        #   end
+        #
+        #   StuffSearch.model # => Stuff
+        def model(*args)
+          # returns model when no arguments
+          return @model if args.empty?
+        
+          # can't set model twice
+          raise "model is already set" if @model
+        
+          # fetch optional options
+          options = if args.last.is_a?(Hash) then args.pop else {} end
+        
+          # make sure model is the only last argument
+          raise ArgumentError.new("Bad arguments for model") unless args.length == 1
+        
+        
+          model = args.first
+        
+          # assert model responds_to search_api_bridge
+          raise ArgumentError.new("#{model} doesn't respond to search_api_bridge") unless model.respond_to?(:search_api_bridge)
+        
+          # set model
+          @model = model
+        
+          # infer automatics search accessors from model
+          add_automatic_search_attributes(options)
+        
+          nil # don't pollute class creation
+        end
+      
+      
+        # This is how you add search attributes to your SearchApi::Search::Base class.
+        #
+        # Adding a search attribute has the following consequences:
+        # - A writer, a reader, an interrogation reader, and a ignored reader are defined.
+        #
+        #   Writer and reader act as usual. Interrogation reader acts as ActiveRecord::Base's one.
+        #
+        #   Ignorer reader tells whether the search attribute is ignored or not.
+        # 
+        #     # Defines following StuffSearch instance methods:
+        #     # - :a, :a=, :a? and :a_ignored?
+        #     # - :b, :b=, :b? and :b_ignored?
+        #     class StuffSearch < SearchApi::Search::Base
+        #       model Stuff
+        #       search_accessor :a, :b
+        #     end
+        #
+        # - The method <tt>find_options_for_[search attribute]</tt> is defined,
+        #   if block is provided.
+        #
+        # The optional block takes a single parameter: a SearchApi::Search::Base instance.
+        #
+        # Its result should be enough to define a model search.
+        #
+        # In case of ActiveRecord models, it should be a valid Hash that can be used as
+        # ActiveRecord::Base.find argument.
+        #
+        # Example:
+        #   class StuffSearch < SearchApi::Search::Base
+        #     model Stuff
+        #     search_accessor :max_age do |search|
+        #       { :conditions => ['birth_date > ?', Time.now - search.max_age.years]}
+        #     end
+        #   end
+        #
+        # You can avoid passing a block, and define the <tt>find_options_for_[search attribute]</tt>
+        # method later:
+        #
+        #   class StuffSearch < SearchApi::Search::Base
+        #     model Stuff
+        #     search_accessor :max_age
+        #     def find_options_for_max_age
+        #       { :conditions => ['birth_date > ?', Time.now - max_age.years]}
+        #     end
+        #   end
+      
+        def search_accessor(*args, &block)
+        
+          # extract SearchAttributeBuilder instances from arguments
+        
+          search_attributes_builders = if block.nil? && args.length == 1 && args.first.is_a?(SearchAttributeBuilder)
+            # argument is a single SearchAttributeBuilder instance
+          
+            args
+          
+          else
+            # arguments are search attribute names and options
+          
+            options = if args.last.is_a?(Hash) then args.pop else {} end
+            args.map do |search_attribute|
+              SearchAttributeBuilder.new(search_attribute, options, &block)
+            end
+          end
+        
+        
+          # define search attributes from builders
+        
+          search_attributes_builders.each do |builder|
+            rewrite_search_attribute_builder(builder)
+            add_search_attribute(builder)
+          end
+        
+          nil # don't pollute class creation
+        end
+
+
+        # Returns an unordered Array of all search attributes defined through search_accessor.
+        #
+        # Example:
+        #   class StuffSearch < SearchApi::Search::Base
+        #     search_accessor :search_key1, :search_key2
+        #   end
+        #
+        #   StuffSearch.search_attributes # => [:search_key1, :search_key2]
+        def search_attributes
+          read_inheritable_attribute(:search_attributes) || []
+        end
+      
+        protected
+      
+        # <b>Unless you're an SearchApi::Bridge::Base subclass designer, you should use
+        # search_accessor method instead.</b>
+        # 
+        # search_attribute_builder is a SearchAttributeBuilder instance.
+        #
+        # This methods adds a search attribute to that SearchApi::Search::Base class:
+        # - search_attribute_builder.name is the name of the search attribute,
+        # - search_attribute_builder.options are options for defining the
+        #   search attribute,
+        # - search_attribute_builder.block is an optional proc that implement
+        #   the search attribute behavior.
+        #
+        # search_attribute_builder.options keys must be in VALID_SEARCH_ATTRIBUTE_OPTIONS.
+        #
+        # Adding a search attributes, precisely, means:
+        #
+        # - A writer, a reader, an interrogation reader, and a ignored reader are defined.
+        #
+        #   Writer and reader act as usual. Interrogation reader acts as ActiveRecord::Base's one.
+        #
+        #   Ignorer reader tells whether the search attribute is ignored or not.
+        # 
+        #     # Defines following StuffSearch instance methods:
+        #     # - :a,
+        #     # - :a=
+        #     # - :a?
+        #     # - :a_ignored?
+        #     class StuffSearch < SearchApi::Search::Base
+        #       model Stuff
+        #       add_search_attribute(SearchApi::Search::SearchAttributeBuilder.new(:a))
+        #     end
+        #
+        # - The method <tt>find_options_for_[search attribute]</tt> is defined,
+        #   if the builder's block is set.
+        #
+        #   That block takes a single parameter: a SearchApi::Search::Base instance. Its result
+        #   should be enough to define a model search.
+        #
+        #   In case of ActiveRecord models, it should be a valid Hash that can be used as
+        #   ActiveRecord::Base.find argument.
+        # 
+        #     # Defines following StuffSearch instance methods:
+        #     # - :a,
+        #     # - :a=
+        #     # - :a?
+        #     # - :a_ignored?
+        #     # - :find_options_for_a
+        #     class StuffSearch < SearchApi::Search::Base
+        #       model Stuff
+        #       add_search_attribute(SearchApi::Search::SearchAttributeBuilder.new(:max_age)) do |search|
+        #         { :conditions => ['birth_date > ?', Time.now - search.max_age.years]}
+        #       end
+        #     end
+        #
+        # You can avoid defining the builder's block, and define the
+        # <tt>find_options_for_[search attribute]</tt> method yourself.
+        #
+        #   class StuffSearch < SearchApi::Search::Base
+        #     model Stuff
+        #     add_search_attribute(SearchApi::Search::SearchAttributeBuilder.new(:max_age))
+        #     def find_options_for_max_age
+        #       { :conditions => ['birth_date > ?', Time.now - max_age.years]}
+        #     end
+        #   end
+        def add_search_attribute(search_attribute_builder)
+          search_attribute =  search_attribute_builder.name
+          options =           search_attribute_builder.options
+          block =             search_attribute_builder.block
+
+
+          # check options
+          options ||= {}
+          invalid_options = options.keys - VALID_SEARCH_ATTRIBUTE_OPTIONS
+          raise ArgumentError.new("invalid options #{invalid_options.inspect}") unless invalid_options.empty?
+
+
+          # fill search_attributes array
+          write_inheritable_array(:search_attributes, [search_attribute])
+        
+        
+          # store default value
+          options[:default] ||= SearchApi::Search.ignored
+          write_inheritable_hash(:search_attribute_default_values, { search_attribute => options[:default]})
+        
+
+          # define reader
+          attr_reader search_attribute
+
+
+          # define writer
+          if store_as_proc = options[:store_as]
+            define_method("#{search_attribute}=") do |value|
+              instance_variable_set("@#{search_attribute}", if SearchApi::Search.ignored?(value) then value else store_as_proc.call(value) end)
+            end
+          else
+            attr_writer search_attribute
+          end
+
+
+          # define interrogation reader
+          define_method("#{search_attribute}?") do
+            !!send(search_attribute)
+          end
+
+
+          # define ignored reader
+          define_method("#{search_attribute}_ignored?") do
+            SearchApi::Search.ignored?(send(search_attribute))
+          end
+
+
+          # Define find_options_for_xxx method
+          if block
+            # user-defined method
+            define_method("find_options_for_#{search_attribute}") do
+              if SearchApi::Search.ignored?(send(search_attribute))
+                {}
+              else
+                block.call(self)
+              end
+            end
+          end
+        end
+
+
+        private
+      
+        # Adds search accessors for automatic attributes
+        def add_automatic_search_attributes(options)  #:nodoc:
+          # define a search attribute for each automatic search attribute
+          model.
+            search_api_bridge.
+            automatic_search_attribute_builders(options).
+            each do |builder|
+              search_accessor(builder)
+            end
+        end
+      
+      
+        # Rewrites a SearchAttributeBuilder.
+        #
+        # On output, search_attribute_builder should be a valid 
+        # SearchApi::Search::Base.add_search_attribute argument.
+        def rewrite_search_attribute_builder(search_attribute_builder)
+          model.search_api_bridge.rewrite_search_attribute_builder(search_attribute_builder) if model
+        end
+      
+      
+      end
+    
+  
+      # Initializes a search with a search attributes Hash.
+      def initialize(attributes=nil)
+        raise "Can't create an instance without model" if self.class.model.nil?
+      
+        # initialize attributes with ignored value
+        self.attributes = self.class.search_attributes.inject((attributes || {}).dup) do |attributes, search_attribute|
+          if attributes.has_key?(search_attribute) || attributes.has_key?(search_attribute.to_s)
+            attributes
+          else
+            attributes.update(search_attribute => self.class.read_inheritable_attribute(:search_attribute_default_values)[search_attribute])
+          end
+        end
+      end
+    
+    
+    
+      # Returns a Hash of search attributes.
+      def attributes
+        self.class.search_attributes.inject({}) do |attributes, search_attribute|
+          attributes.update(search_attribute => send(search_attribute))
+        end
+      end
+    
+      # Sets search attributes via a Hash
+      def attributes=(attributes=nil)
+        (attributes || {}).each do |search_attribute, value|
+          send("#{search_attribute}=", value)
+        end
+      end
+    
+    
+      # Returns whether search_attribute is ignored.
+      def ignored?(search_attribute)
+        SearchApi::Search.ignored?(send(search_attribute))
+      end
+
+      # Ignore given search_attribute.
+      def ignore!(search_attribute)
+        send("#{search_attribute}=", SearchApi::Search.ignored)
+      end
+    
+    
+    
+      # Returns an object that should be enough to define a model search.
+      #
+      # In case of ActiveRecord models, returns a valid Hash that can be used as
+      # ActiveRecord::Base.find argument.
+      def find_options
+        # collect all find_options for not ignored attributes
+      
+        options_array = self.class.search_attributes.
+      
+          # reject ignored attributes
+          reject { |search_attribute| ignored?(search_attribute) }.
+
+          # merge options for all attributes
+          map { |search_attribute| send("find_options_for_#{search_attribute}") }
+
+                          
+        # merge them options for not ignored attributes
+      
+        self.class.model.search_api_bridge.merge_find_options(options_array)
+      end
+    
+    
+      protected
+    
+      def find_options_for_hash(conditions) #:nodoc:
+        # merge options for not ignored attributes
+        model.
+          search_api_bridge.
+          merge_find_options(
+          )
+        conditions.
+      
+          # reject ignored attributes
+          reject { |search_attribute, value| SearchApi::Search.ignored?(value) }.
+        
+          # merge options for all attributes
+          map do |search_attribute, value|
+            send("find_options_for_#{search_attribute}")
+          end
+      end
+    end
+
+    protected
+  
+    # Describes a search attribute with:
+    # - a name,
+    # - some options
+    # - an optional block
+    class SearchAttributeBuilder
+      # name is a search attribute name. It is read-only so that SearchApi::Bridge::Base.rewrite_search_attribute_builder is unable to rename attributes.
+      attr_reader :name
+
+      # options is an options Hash (never nil, may be empty Hash)
+      attr_accessor :options
+
+      # block is an optional proc (may be nil)
+      attr_accessor :block
+    
+      def initialize(name, options={}, &block)
+        @name = name.to_sym
+        @options = options
+        @block = block
+      end
+    end
+  
+    # Class of values ignored by Search instances.
+    class IgnoredValue
+      def inspect #:nodoc:
+        "<ignored>"
+      end
+    end
+
+    class << self
+    
+      def ignored #:nodoc:
+        @ignore ||= IgnoredValue.new
+      end
+  
+      def ignored?(value) #:nodoc:
+        value.is_a? IgnoredValue
+      end
+    end
+
+  end
+end