searchgasm 1.0.0 → 1.0.1

data/CHANGELOG.rdoc

@@ -0,0 +1,64 @@
+== 1.0.1 released 2008-09-08
+
+* Cached "searchers" so when a new search object is instantiated it doesn't go through all of the meta programming and method creation. Helps a lot with performance. You will see the speed benefits after the first instantiation.
+* Added in new options for page_links.
+* Fixed minor bugs when doing page_links.
+* Updated documentation to be more detailed and inclusive.
+
+== 1.0.0 released 2008-09-08
+
+* Major changes in the helpers, they were completely re-engineered. Hence the new version. I established a pattern between all helpers giving you complete flexibility as to how they are used. All helpers are called differently now (see documentation).
+
+== 0.9.10 released 2008-09-08
+
+* Fixed bug with setting the per_page configuration to only take effect on protected searches, thus staying out of the way of normal searching.
+* Hardened more tests
+
+== 0.9.9 released 2008-09-07
+
+* Fixed setting per_page to nil, false, or ''. This is done to "show all" results.
+
+== 0.9.8 released 2008-09-06
+
+* Fixed order_by helper bug when guessing the text with arrays. Should use the first value instead of last.
+* Added in per_page config option.
+
+== 0.9.7 released 2008-09-06
+
+* Complete class restructure. Moved the 3 main components into their own base level class: Search, Conditions, Condition
+* Split logic and functionality into their own modules, implemented via alias_chain_method
+* Added in helpers for using in a rails app
+* Added link to documentation and live example in README
+* Various small bug fixes
+* Hardened tests
+
+== 0.9.6 released 2008-09-04
+
+* Fixed bug when instantiating with nil options
+
+== 0.9.5 released 2008-09-03
+
+* Enhanced searching with conditions only, added in search methods and calculations
+* Updated README to include examples
+
+== 0.9.4 released 2008-09-03
+
+* Cleaned up search methods
+* Removed reset!method for both searching and searching by conditions
+
+== 0.9.3 released 2008-09-02
+
+* Changed structure of conditions to have their own class
+* Added API for adding your own conditions.
+
+== 0.9.2 released 2008-09-02
+
+* Enhanced protection from SQL injections (made more efficient)
+
+== 0.9.1 released 2008-09-02
+
+* Added aliases for datetime, date, time, and timestamp attrs. You could call created_at_after, now you can also call created_after. Just removed the "at" requirement.
+
+== 0.9.0 released 2008-09-01
+
+* First release

data/Manifest

@@ -1,8 +1,9 @@
-CHANGELOG
+CHANGELOG.rdoc
 examples/README.rdoc
 init.rb
 lib/searchgasm/active_record/associations.rb
 lib/searchgasm/active_record/base.rb
+lib/searchgasm/active_record.rb
 lib/searchgasm/condition/base.rb
 lib/searchgasm/condition/begins_with.rb
 lib/searchgasm/condition/child_of.rb
@@ -22,6 +23,7 @@ lib/searchgasm/condition/tree.rb
 lib/searchgasm/conditions/base.rb
 lib/searchgasm/conditions/protection.rb
 lib/searchgasm/config.rb
+lib/searchgasm/core_ext/hash.rb
 lib/searchgasm/helpers/control_types/link.rb
 lib/searchgasm/helpers/control_types/links.rb
 lib/searchgasm/helpers/control_types/remote_link.rb

data/README.rdoc

@@ -8,7 +8,7 @@ Searchgasm is orgasmic. Maybe not orgasmic, but you will get aroused. So go grab
 
 *	<b>Documentation:</b> http://searchgasm.rubyforge.org
 *	<b>Easy pagination, ordering, and searching tutorial:</b> http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchgasm
-*	<b>The tutorial above, live:</b> http://searchgasm_example.binarylogic.com
+*	<b>Live example of the tutorial above (with source):</b> http://searchgasm_example.binarylogic.com
 
 == Install and use
 
@@ -67,8 +67,8 @@ Now your view. Things to note in this view:
 
 1.  Passing a search object right into form\_for and fields\_for
 2.  The built in conditions for each column and how you can traverse the relationships and set conditions on them
-3.  The order_by helper
-4.  The page and per_page helpers
+3.  The order_by_link helper
+4.  The page_select and per_page_select helpers
 5.  All of your search logic is in 1 spot: your view. Nice and DRY.
 
 Your view:
@@ -82,25 +82,28 @@ Your view:
         = orders.select :total_gt, (1..100)
     = f.submit "Search"
   
-  %table
-    %tr
-      %th= order_by_link :account => :name
-      %th= order_by_link :first_name
-      %th= order_by_link :last_name
-      %th= order_by_link :email
-    - @users.each do |user|
+  - if @users_count > 0
+    %table
+      %tr
+        %th= order_by_link :account => :name
+        %th= order_by_link :first_name
+        %th= order_by_link :last_name
+        %th= order_by_link :email
+      - @users.each do |user|
         %tr
           %td= user.account? ? user.account.name : "-"
           %td= user.first_name
           %td= user.last_name
           %td= user.email
   
-  Per page:
-  = per_page_select
-  Page:
-  = page_select
+    Per page:
+    = per_page_select
+    Page:
+    = page_select
+  - else
+    No users were found.
 
-<b>{See my tutorial on this example}(http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchgasm)</b>
+<b>See my tutorial on this example: http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchgasm</b>
 
 == Exhaustive Example w/ Object Based Searching (great for form_for or fields_for)
 
@@ -174,13 +177,6 @@ Any of the options used in the above example can be used in these, but for the s
   search.per_page = 20
   search.all
 
-If you want to use Searchgasm directly:
-
-  search = Searchgasm::Search::Base.new(User, :conditions => {:age_gt => 18})
-  search.conditions.first_name_contains = "Ben"
-  search.per_page = 20
-  search.all
-
 == Search with conditions only
 
 Don't need pagination, ordering, or any of the other options? Search with conditions only.
@@ -194,19 +190,13 @@ Pass a conditions object right into ActiveRecord:
 
   User.all(:conditions => conditions)
 
-Again, if you want to use Searchgasm directly:
-
-  conditions = Searchgasm::Conditions::Base.new(User, :age_gt => 18)
-  conditions.first_name_contains = "Ben"
-  conditions.all
-
 == Scoped searching
 
   @current_user.orders.find(:all, :conditions => {:total_lte => 500})
   @current_user.orders.count(:conditions => {:total_lte => 500})
   @current_user.orders.sum('total', :conditions => {:total_lte => 500})
   
-  search = @current_user.orders.build_search('total', :conditions => {:total_lte => 500})
+  search = @current_user.orders.build_search(:conditions => {:total_lte => 500})
 
 == Searching trees
 

data/lib/searchgasm/active_record/associations.rb

@@ -1,31 +1,39 @@
 module Searchgasm
   module ActiveRecord
+    # = Searchgasm ActiveRecord Associations
+    #
+    # These methods hook into ActiveRecords association methods and add in searchgasm functionality.
     module Associations
       module AssociationCollection
+        # This is an alias method chain. It hook into ActiveRecord's "find" method for associations and checks to see if Searchgasm should get involved.
         def find_with_searchgasm(*args)
           options = args.extract_options!
           args << sanitize_options_with_searchgasm(options)
           find_without_searchgasm(*args)
         end
         
+        # See build_conditions under Searchgasm::ActiveRecord::Base. This is the same thing but for associations.
         def build_conditions(options = {}, &block)
           conditions = @reflection.klass.build_conditions(options, &block)
           conditions.scope = scope(:find)[:conditions]
           conditions
         end
         
+        # See build_conditions! under Searchgasm::ActiveRecord::Base. This is the same thing but for associations.
         def build_conditions!(options = {}, &block)
           conditions = @reflection.klass.build_conditions!(options, &block)
           conditions.scope = scope(:find)[:conditions]
           conditions
         end
-      
+        
+        # See build_search under Searchgasm::ActiveRecord::Base. This is the same thing but for associations.
         def build_search(options = {}, &block)
           conditions = @reflection.klass.build_search(options, &block)
           conditions.scope = scope(:find)[:conditions]
           conditions
         end
         
+        # See build_conditions! under Searchgasm::ActiveRecord::Base. This is the same thing but for associations.
         def build_search!(options = {}, &block)
           conditions = @reflection.klass.build_search!(options, &block)
           conditions.scope = scope(:find)[:conditions]
@@ -34,6 +42,7 @@ module Searchgasm
       end
     
       module HasManyAssociation
+        # This is an alias method chain. It hook into ActiveRecord's "calculate" method for has many associations and checks to see if Searchgasm should get involved.
         def count_with_searchgasm(*args)
           column_name, options = @reflection.klass.send(:construct_count_options_from_args, *args)
           count_without_searchgasm(column_name, sanitize_options_with_searchgasm(options))

data/lib/searchgasm/active_record/base.rb

@@ -1,13 +1,17 @@
 module Searchgasm
-  module ActiveRecord #:nodoc: all
+  module ActiveRecord
+    # = Searchgasm ActiveRecord Base
+    # Adds in base level functionality to ActiveRecord
     module Base
+      # This is an alias method chain. It hook into ActiveRecord's "calculate" method and checks to see if Searchgasm should get involved.
       def calculate_with_searchgasm(*args)
         options = args.extract_options!
         options = sanitize_options_with_searchgasm(options)
         args << options
         calculate_without_searchgasm(*args)
       end
-    
+      
+      # This is an alias method chain. It hooks into ActiveRecord's "find" method and checks to see if Searchgasm should get involved.
       def find_with_searchgasm(*args)
         options = args.extract_options!
         options = sanitize_options_with_searchgasm(options)
@@ -15,12 +19,31 @@ module Searchgasm
         find_without_searchgasm(*args)
       end
     
+      # This is an alias method chain. It hooks into ActiveRecord's scopes and checks to see if Searchgasm should get involved. Allowing you to use all of Searchgasms conditions and tools
+      # in scopes as well.
+      #
+      # === Examples
+      #
+      #   named_scope :top_expensive, :conditions => {:total_gt => 1_000_000}, :per_page => 10
+      #
+      #   with_scope(:find => {:conditions => {:total_gt => 1_000_000}, :per_page => 10}) do
+      #     find(:all)
+      #   end
       def scope_with_searchgasm(method, key = nil)
         scope = scope_without_searchgasm(method, key)
         return sanitize_options_with_searchgasm(scope) if key.nil? && method == :find && !scope.blank?
         scope
       end
-    
+      
+      # This is a special method that Searchgasm adds in. It returns a new conditions object on the model. So you can search by conditions *only*.
+      #
+      # <b>This method is "protected". Meaning it checks the passed options for SQL injections. So trying to write raw SQL in *any* of the option will result in a raised exception. It's safe to pass a params object when instantiating.</b>
+      #
+      # === Examples
+      #
+      #   conditions = User.new_conditions
+      #   conditions.first_name_contains = "Ben"
+      #   conditions.all # can call any search method: first, find(:all), find(:first), sum("id"), etc...
       def build_conditions(values = {}, &block)
         conditions = searchgasm_conditions
         conditions.protect = true
@@ -28,13 +51,28 @@ module Searchgasm
         yield conditions if block_given?
         conditions
       end
-    
+      
+      # See build_conditions. This is the same method but *without* protection. Do *NOT* pass in a params object to this method.
       def build_conditions!(values = {}, &block)
         conditions = searchgasm_conditions(values)
         yield conditions if block_given?
         conditions
       end
-    
+      
+      # This is a special method that Searchgasm adds in. It returns a new search object on the model. So you can search via an object.
+      #
+      # <b>This method is "protected". Meaning it checks the passed options for SQL injections. So trying to write raw SQL in *any* of the option will result in a raised exception. It's safe to pass a params object when instantiating.</b>
+      #
+      # This method has an alias "new_search"
+      #
+      # === Examples
+      #
+      #   search = User.new_search
+      #   search.conditions.first_name_contains = "Ben"
+      #   search.per_page = 20
+      #   search.page = 2
+      #   search.order_by = {:user_group => :name}
+      #   search.all # can call any search method: first, find(:all), find(:first), sum("id"), etc...
       def build_search(options = {}, &block)
         search = searchgasm_searcher
         search.protect = true
@@ -42,26 +80,38 @@ module Searchgasm
         yield search if block_given?
         search
       end
-    
+      
+      # See build_search. This is the same method but *without* protection. Do *NOT* pass in a params object to this method.
+      #
+      # This also has an alias "new_search!"
       def build_search!(options = {}, &block)
         search = searchgasm_searcher(options)
         yield search if block_given?
         search
       end
       
+      # Similar to ActiveRecord's attr_protected, but for conditions. It will block any conditions in this array that are being mass assigned. Mass assignments are:
+      #
+      # === Examples
+      #
+      # search = User.new_search(:conditions => {:first_name_like => "Ben", :email_contains => "binarylogic.com"})
+      # search.options = {:conditions => {:first_name_like => "Ben", :email_contains => "binarylogic.com"}}
+      #
+      # If first_name_like is in the list of conditions_protected then it will be removed from the hash.
       def conditions_protected(*conditions)
         write_inheritable_attribute(:conditions_protected, Set.new(conditions.map(&:to_s)) + (protected_conditions || []))
       end
 
-      def protected_conditions
+      def protected_conditions # :nodoc:
         read_inheritable_attribute(:conditions_protected)
       end
       
+      # This is the reverse of conditions_protected. You can specify conditions here and *only* these conditions will be allowed in mass assignment. Any condition not specified here will be blocked.
       def conditions_accessible(*conditions)
         write_inheritable_attribute(:conditions_accessible, Set.new(conditions.map(&:to_s)) + (protected_conditions || []))
       end
 
-      def accessible_conditions
+      def accessible_conditions # :nodoc:
         read_inheritable_attribute(:conditions_accessible)
       end
     
@@ -72,11 +122,11 @@ module Searchgasm
         end
       
         def searchgasm_conditions(options = {})
-          Searchgasm::Conditions::Base.new(self, options)
+          Searchgasm::Conditions::Base.create_virtual_class(self).new(options)
         end
       
         def searchgasm_searcher(options = {})
-          Searchgasm::Search::Base.new(self, options)
+          Searchgasm::Search::Base.create_virtual_class(self).new(options)
         end
     end
   end

data/lib/searchgasm/active_record.rb

@@ -0,0 +1,8 @@
+module Searchgasm
+  # == Searchgasm ActiveRecord
+  #
+  # Hooks into ActiveRecord to add all of the searchgasm functionality into your models. Only uses what is publically available, doesn't dig into internals, and
+  # searchgasm only gets involved when needed.
+  module ActiveRecord
+  end
+end

data/lib/searchgasm/conditions/base.rb

@@ -7,9 +7,11 @@ module Searchgasm
     class Base
       include Utilities
       
-      attr_accessor :klass, :relationship_name, :scope
+      attr_accessor :relationship_name, :scope
       
       class << self
+        attr_accessor :added_klass_conditions, :added_column_conditions, :added_associations
+        
         # Registers a condition as an available condition for a column or a class.
         #
         # === Example
@@ -40,9 +42,9 @@ module Searchgasm
         #   end
         #
         #   Searchgasm::Seearch::Conditions.register_condition(SoundsLikeCondition)
-        def register_condition(klass)
-          raise(ArgumentError, "You can only register conditions that extend Searchgasm::Condition::Base") unless klass.ancestors.include?(Searchgasm::Condition::Base)
-          conditions << klass unless conditions.include?(klass)
+        def register_condition(condition_class)
+          raise(ArgumentError, "You can only register conditions that extend Searchgasm::Condition::Base") unless condition_class.ancestors.include?(Searchgasm::Condition::Base)
+          conditions << condition_class unless conditions.include?(condition_class)
         end
         
         # A list of available condition type classes
@@ -50,19 +52,50 @@ module Searchgasm
           @@conditions ||= []
         end
         
-        def needed?(klass, conditions) # :nodoc:
+        # A list of all associations created, used for caching and performance
+        def association_names
+          @association_names ||= []
+        end
+        
+        # A list of all conditions available, users for caching and performance
+        def condition_names
+          @condition_names ||= []
+        end
+        
+        def needed?(model_class, conditions) # :nodoc:
           if conditions.is_a?(Hash)
             conditions.stringify_keys.keys.each do |condition|
-              return true unless klass.column_names.include?(condition)
+              return true unless model_class.column_names.include?(condition)
             end
           end
           
           false
         end
+        
+        # Creates virtual classes for the class passed to it. This is a neccesity for keeping dynamically created method
+        # names specific to models. It provides caching and helps a lot with performance.
+        def create_virtual_class(model_class)
+          class_search_name = "::#{model_class.name}Conditions"
+          
+          begin
+            class_search_name.constantize
+          rescue NameError
+            eval <<-end_eval
+              class #{class_search_name} < ::Searchgasm::Conditions::Base; end;
+            end_eval
+                        
+            class_search_name.constantize
+          end
+        end
+        
+        # The class / model we are searching
+        def klass
+          # Can't cache this because thin and mongrel don't play nice with caching constants
+          name.split("::").last.gsub(/Conditions$/, "").constantize
+        end
       end
       
-      def initialize(klass, init_conditions = {})
-        self.klass = klass
+      def initialize(init_conditions = {})
         add_klass_conditions!
         add_column_conditions!
         add_associations!
@@ -90,6 +123,10 @@ module Searchgasm
         i.blank? ? nil : (i.size == 1 ? i.first : i)
       end
       
+      def klass
+        self.class.klass
+      end
+      
       # Sanitizes the conditions down into conditions that ActiveRecord::Base.find can understand.
       def sanitize
         conditions = merge_conditions(*objects.collect { |object| object.sanitize })
@@ -128,11 +165,15 @@ module Searchgasm
       
       private
         def add_associations!
+          return true if self.class.added_associations
+          
           klass.reflect_on_all_associations.each do |association|
+            self.class.association_names << association.name.to_s
+            
             self.class.class_eval <<-"end_eval", __FILE__, __LINE__
               def #{association.name}
                 if @#{association.name}.nil?
-                  @#{association.name} = self.class.new(#{association.class_name})
+                  @#{association.name} = #{association.class_name}.new_conditions
                   @#{association.name}.relationship_name = "#{association.name}"
                   objects << @#{association.name}
                 end
@@ -143,9 +184,13 @@ module Searchgasm
               def reset_#{association.name}!; objects.delete(#{association.name}); @#{association.name} = nil; end
             end_eval
           end
+          
+          self.class.added_associations = true
         end
         
         def add_column_conditions!
+          return true if self.class.added_column_conditions
+          
           klass.columns.each do |column|
             self.class.conditions.each do |condition_klass|
               name = condition_klass.name_for_column(column)
@@ -154,10 +199,13 @@ module Searchgasm
               condition_klass.aliases_for_column(column).each { |alias_name| add_condition_alias!(alias_name, name) }
             end
           end
+          
+          self.class.added_column_conditions = true
         end
         
         def add_condition!(condition, name, column = nil)
-          condition_names << name
+          self.class.condition_names << name
+          
           self.class.class_eval <<-"end_eval", __FILE__, __LINE__
             def #{name}_object
               if @#{name}.nil?
@@ -174,7 +222,8 @@ module Searchgasm
         end
         
         def add_condition_alias!(alias_name, name)
-          condition_names << alias_name
+          self.class.condition_names << alias_name
+          
           self.class.class_eval do
             alias_method alias_name, name
             alias_method "#{alias_name}=", "#{name}="
@@ -182,26 +231,24 @@ module Searchgasm
         end
         
         def add_klass_conditions!
+          return true if self.class.added_klass_conditions
+          
           self.class.conditions.each do |condition|
             name = condition.name_for_klass(klass)
             next if name.blank?
             add_condition!(condition, name)
             condition.aliases_for_klass(klass).each { |alias_name| add_condition_alias!(alias_name, name) }
           end
+          
+          self.class.added_klass_conditions = true
         end
         
         def assert_valid_conditions(conditions)
-          keys = condition_names.collect { |condition_name| condition_name.to_sym }
-          keys += klass.reflect_on_all_associations.collect { |association| association.name }
-          conditions.symbolize_keys.assert_valid_keys(keys)
+          conditions.stringify_keys.assert_valid_keys(self.class.condition_names + self.class.association_names)
         end
         
         def associations
-          objects.select { |object| object.is_a?(self.class) }
-        end
-        
-        def condition_names
-          @condition_names ||= []
+          objects.select { |object| object.class < ::Searchgasm::Conditions::Base }
         end
         
         def objects

data/lib/searchgasm/core_ext/hash.rb

@@ -0,0 +1,22 @@
+module Searchgasm
+  module CoreExt # :nodoc: all
+    module Hash
+      def deep_dup
+        new_hash = {}
+        
+        self.each do |k, v|
+          case v
+          when Hash
+            new_hash[k] = v.deep_dup
+          else
+            new_hash[k] = v
+          end
+        end
+        
+        new_hash
+      end
+    end
+  end
+end
+
+Hash.send(:include, Searchgasm::CoreExt::Hash)