searchgasm 1.0.0 → 1.0.1

data/lib/searchgasm/helpers/control_types/links.rb

@@ -16,10 +16,10 @@ module Searchgasm
         # * <tt>:choices</tt> -- default: the models column names, the choices to loop through when calling order_by_link
         def order_by_links(options = {})
           add_order_by_links_defaults!(options)
-          link_options = options.dup
+          link_options = options.deep_dup
           link_options.delete(:choices)
           html = ""
-          options[:choices].each { |choice| html += order_by_link(choice, link_options.dup) }
+          options[:choices].each { |choice| html += order_by_link(choice, link_options.deep_dup) }
           html
         end
         
@@ -37,10 +37,10 @@ module Searchgasm
         # * <tt>:choices</tt> -- default: ["asc", "desc"], the choices to loop through when calling order_as_link
         def order_as_links(options = {})
           add_order_as_links_defaults!(options)
-          link_options = options.dup
+          link_options = options.deep_dup
           link_options.delete(:choices)
           html = ""
-          options[:choices].each { |choice| html += order_as_link(choice, link_options.dup) }
+          options[:choices].each { |choice| html += order_as_link(choice, link_options.deep_dup) }
           html
         end
         
@@ -58,10 +58,10 @@ module Searchgasm
         # * <tt>:choices</tt> -- default: [10, 25, 50, 100, 150, 200, nil], the choices to loop through when calling per_page_link.
         def per_page_links(options = {})
           add_per_page_links_defaults!(options)
-          link_options = options.dup
+          link_options = options.deep_dup
           link_options.delete(:choices)
           html = ""
-          options[:choices].each { |choice| html += per_page_link(choice, link_options.dup) }
+          options[:choices].each { |choice| html += per_page_link(choice, link_options.deep_dup) }
           html
         end
         
@@ -70,38 +70,53 @@ module Searchgasm
         # === Examples
         #
         #   page_links
-        #   page_links(:choices => [25, 50, nil])
+        #   page_links(:first => "<< First", :last => "Last >>")
+        #
+        # === Classes and tag
+        #
+        # If the user is on the current page they will get a <span> tag, not an <a> tag. If they are on the first page the "first" and "prev" options will be a <span> also. The same goes
+        # for "next" and "last" if the user is on the last page. Other than that each element will come with a CSS class so you can style it to your liking. Somtimes the easiest way to understand this
+        # Is to either look at the example (linked in the README) or try it out and view the HTML source. It's pretty simple, but here are the explanations:
+        #
+        # * <tt>page</tt> - This is in *every* element, span or a.
+        # * <tt>first_page</tt> - This is for the "first page" element only.
+        # * <tt>preve_page</tt> - This is for the "prev page" element only.
+        # * <tt>current_page</tt> - This is for the current page element
+        # * <tt>next_page</tt> - This is for the "next page" element only.
+        # * <tt>last_page</tt> - This is for the "last page" element only.
+        # * <tt>disabled_page</tt> - Any element that is a span instead of an a tag.
         #
         # === Options
         #
         # Please look at per_page_link. All options there are applicable here and are passed onto each option.
         #
-        # * <tt>:spread</tt> -- default: 3, how many choices available on each side of the current page
-        # * <tt>:prev</tt> -- default: <, set to nil to omit. This is an extra link on the left side of the page links that will go to the previous page
-        # * <tt>:next</tt> -- default: >, set to nil to omit. This is an extra link on the right side of the page links that will go to the next page
-        # * <tt>:first</tt> -- default: <<, set to nil to omit. This is an extra link on thefar left side of the page links that will go to the first page
-        # * <tt>:last</tt> -- default: >>, set to nil to omit. This is an extra link on the far right side of the page links that will go to the last page
+        # * <tt>:spread</tt> -- default: 3, set to nil to show all page, this represents how many choices available on each side of the current page
+        # * <tt>:prev</tt> -- default: < Prev, set to nil to omit. This is an extra link on the left side of the page links that will go to the previous page
+        # * <tt>:next</tt> -- default: Next >, set to nil to omit. This is an extra link on the right side of the page links that will go to the next page
+        # * <tt>:first</tt> -- default: nil, set to nil to omit. This is an extra link on thefar left side of the page links that will go to the first page
+        # * <tt>:last</tt> -- default: nil, set to nil to omit. This is an extra link on the far right side of the page links that will go to the last page
         def page_links(options = {})
           add_page_links_defaults!(options)
+          return if options[:last_page] <= 1
           
-          current_page = options[:search_obj].page
-          page_start = 0
-          page_end = 0
+          first_page = 0
+          last_page = 0
           if !options[:spread].blank?
-            page_start = current_page - options[:spread]
-            page_start = options[:choices].first unless options[:choices].include?(page_start)
-            page_end = current_page + options[:spread]
-            page_end = options[:choices].last unless options[:choices].include?(page_end)
+            first_page = options[:current_page] - options[:spread]
+            first_page = options[:first_page] if first_page < options[:first_page]
+            last_page = options[:current_page] + options[:spread]
+            last_page = options[:last_page] if last_page > options[:last_page]
           else
-            page_start = options[:choices].first
-            page_end = options[:choices].last
+            first_page = options[:first_page]
+            last_page = options[:last_page]
           end
           
-          
-          link_options = options.dup
-          [:choices, :spread, :prev, :next, :first, :last].each { |option| link_options.delete(option) }
           html = ""
-          (page_start..page_end).each { |choice| html += page_link(choice, link_options.dup) }
+          html += span_or_page_link(:first, options.deep_dup, options[:current_page] == options[:first_page]) if options[:first]
+          html += span_or_page_link(:prev, options.deep_dup, options[:current_page] == options[:first_page]) if options[:prev]
+          (first_page..last_page).each { |page| html += span_or_page_link(page, options.deep_dup, page == options[:current_page]) }
+          html += span_or_page_link(:next, options.deep_dup, options[:current_page] == options[:last_page]) if options[:next]
+          html += span_or_page_link(:last, options.deep_dup, options[:current_page] == options[:last_page]) if options[:last]
           html
         end
         
@@ -133,14 +148,33 @@ module Searchgasm
           
           def add_page_links_defaults!(options)
             add_searchgasm_helper_defaults!(:page, options)
-            options[:choices] ||= (1..options[:search_obj].page_count)
-            options[:spead] ||= 3
-            options[:prev] ||= "<"
-            options[:next] ||= ">"
-            options[:first] ||= "<<"
-            options[:last] ||= ">>"
+            options[:first_page] ||= 1
+            options[:last_page] ||= options[:search_obj].page_count
+            options[:current_page] ||= options[:search_obj].page
+            options[:spread] = 3 unless options.has_key?(:spread)
+            options[:prev] = "< Prev" unless options.has_key?(:prev)
+            options[:next] = "Next >" unless options.has_key?(:next)
             options
           end
+          
+          def span_or_page_link(name, options, span)
+            text = ""
+            page = 0
+            case name
+            when Fixnum
+              text = name
+              page = name
+              searchgasm_add_class!(options[:html], "current_page") if span
+            else
+              text = options[name]
+              page = options[:search_obj].send("#{name}_page")
+              searchgasm_add_class!(options[:html], "#{name}_page")
+            end
+            
+            searchgasm_add_class!(options[:html], "disabled_page") if span
+            options[:text] = text
+            span ? content_tag(:span, text, options[:html]) : page_link(page, options)
+          end
       end
     end
   end

data/lib/searchgasm/helpers/control_types/select.rb

@@ -23,7 +23,7 @@ module Searchgasm
         # Please see page_links. All options are the same and applicable here, excep the :prev, :next, :first, and :last options. The only difference is that instead of a group of links, this gets returned as a select form element that will perform the same function when the value is changed.
         def page_select(options = {})
           add_page_select_defaults!(options)
-          searchgasm_state_for(:page, options) + select(options[:params_scope], :page, options[:choices], options[:tag] || {}, options[:html])
+          searchgasm_state_for(:page, options) + select(options[:params_scope], :page, (options[:first_page]..options[:last_page]), options[:tag] || {}, options[:html])
         end
         
         private

data/lib/searchgasm/helpers/control_types.rb

@@ -4,9 +4,13 @@ module Searchgasm
     #
     # The purpose of these helpers is to make ordering and paginating data, in your view, a breeze. Everyone has their own flavor of displaying data, so I made these helpers extra flexible, just for you.
     #
+    # === Tutorial
+    #
+    # Check out my tutorial on how to implement searchgasm into a rails app: http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchgasm
+    #
     # === How it's organized
     #
-    # Basically you can do 4 different things in your with with your data:
+    # If we break it down, you can do 4 different things with your data in your view:
     #
     # 1. Order your data by a single column or an array of columns
     # 2. Descend or ascend your data
@@ -16,8 +20,9 @@ module Searchgasm
     # Each one of these actions comes with 3 different types of helpers:
     #
     # 1. Link - A single link for a single value. Requires that you pass a value as the first parameter.
-    # 2. Group of links - A group of single links.
+    # 2. Links - A group of single links.
     # 3. Select - A select with choices that perform an action once selected. Basically the same thing as a group of links, but just as a select form element
+    # 4. Remote - lets you prefix any of these helpers with "remote_" and it will use the built in rails ajax helpers. I highly recommend unobstrusive javascript though, using jQuery.
     #
     # === Examples
     #
@@ -33,6 +38,17 @@ module Searchgasm
     #   => produces a select form element with all of the user's columns as choices, when the value is change (onchange) it will act as if they clicked a link.
     #   => This is just order_by_links as a select form element, nothing fancy
     #
+    # What about paginating? I got you covered:
+    #
+    #   page_link(2)
+    #   => creates a link to page 2
+    #
+    #   page_links
+    #   => creates a group of links for pages, similar to a flickr style of pagination
+    #
+    #   page_select
+    #   => creates a drop down instead of a group of links. The user can select the page in the drop down and it will be as if they clicked a link for that page.
+    #
     # You can apply the _link, _links, or _select to any of the following: order_by, order_as, per_page, page. You have your choice on how you want to set up the interface. For more information and options on these individual
     # helpers check out their source files. Look at the sub modules under this one (Ex: Searchgasm::Helpers::ControlTypes::Select)
     module ControlTypes

data/lib/searchgasm/helpers/form.rb

@@ -19,13 +19,14 @@ module Searchgasm
     #
     # If you pass a Searchgasm::Search::Base object it automatically adds the :order_by, :order_as, and :per_page hidden fields. This is done so that when someone
     # creates a new search, their options are remembered. It keeps the search consisten and is much more user friendly. If you want to override this you can pass the
-    # following options. Or you can set this up in your configuration, see Searchgasm::Config for more details.
+    # following options or you can set this up in your configuration, see Searchgasm::Config for more details.
+    #
+    # Lastly some light javascript is added to the "onsubmit" action. You will notice the order_by, per_page, and page helpers also add in a single hidden tag in the page. The form
+    # finds these elements, gets their values and updates its hidden fields so that the correct values will be submitted during the search. The end result is having the "ordering" and "per page" options remembered.
     #
     # === Options
     #
     # * <tt>:hidden_fields</tt> --- Array, a list of hidden fields to include. Defaults to [:order_by, :order_as, :per_page]. Pass false, nil, or a blank array to not include any.
-    # * <tt>:js_lib</tt> --- Accepts :prototype, :jquery, or nil. Javascript is written to keep the :hidden_fields in sync with the other fields on the page. nil will turn javascript off, you will be on your own.
-    #  Keeping these fields in sync allows search to remember their values when they are changed, making search much more user friendly.
     module Form
       module Shared # :nodoc:
         private
@@ -34,9 +35,14 @@ module Searchgasm
           end
         
           def find_searchgasm_object(args)
+            search_object = nil
+            
             case args.first
             when String, Symbol
-              search_object = searchgasm_object?(args[1]) ? args[1] : instance_variable_get("@#{args.first}")
+              begin
+                search_object = searchgasm_object?(args[1]) ? args[1] : instance_variable_get("@#{args.first}")
+              rescue Exception
+              end
             when Array
               search_object = args.first.last
             else

data/lib/searchgasm/helpers/utilities.rb

@@ -8,7 +8,8 @@ module Searchgasm
           options[:search_obj] ||= instance_variable_get("@#{options[:params_scope]}")
           raise(ArgumentError, "@search object could not be inferred, please specify: :search_obj => @search") unless options[:search_obj].is_a?(Searchgasm::Search::Base)
           options[:html] ||= {}
-          options[:html][:class] = (options[:html][:class].blank? ? "" : "#{options[:html][:class]} ") + option.to_s
+          options[:html][:class] ||= ""
+          searchgasm_add_class!(options[:html], option)
           options
         end
         
@@ -17,12 +18,13 @@ module Searchgasm
         end
         
         def searchgasm_url_hash(option, value, options)
-          params_copy = params.dup
+          params_copy = params.deep_dup.with_indifferent_access
           params_copy.delete(:commit)
                     
           # Extract search params from params
           search_params = options[:params_scope].blank? ? params_copy : params_copy[options[:params_scope]]
           search_params ||= {}
+          search_params = search_params.with_indifferent_access
                     
           # Never want to keep page
           search_params.delete(:page)
@@ -33,6 +35,13 @@ module Searchgasm
           search_params
         end
         
+        def searchgasm_add_class!(html_options, new_class)
+          new_class = new_class.to_s
+          classes = html_options[:class].split(" ")
+          classes << new_class unless classes.include?(new_class)
+          html_options[:class] = classes.join(" ")
+        end
+        
         def searchgasm_order_by_value(order_by)
           case order_by
           when String
@@ -52,6 +61,22 @@ module Searchgasm
           end
           html
         end
+        
+        # Need to deep dup a hash otherwise the "child" hashes get modified as its passed around
+        def searchgasm_deep_dup(hash)
+          new_hash = {}
+          
+          hash.each do |k, v|
+            case v
+            when Hash
+              hash[k] = searchgasm_deep_dup(v)
+            else
+              hew_hash[k] = v
+            end
+          end
+          
+          new_hash
+        end
     end
   end
 end

data/lib/searchgasm/helpers.rb

@@ -1,3 +1,9 @@
 module Searchgasm
-  module Helpers #:nodoc:
+  # = Searchgasm Helpers
+  #
+  # Provides helpers for rails applications that make using Searchgasm extremely easy. Please see Searchgasm::Helpers::ControlTypes and Searchgasm::Helpers::Form for more information on how to use these helpers.
+  #
+  # Also, I am always looking to improve these. I feel confident that I made these flexible enough for just about any need, but there is always that one crazy instance. If these helpers restrict you
+  # in any way please contact me and let me know. You can do some on my website: www.binarylogic.com. I will more than likely add in your functionality that week.
+  module Helpers
     module UtilitiesHelper # :nodoc:

data/lib/searchgasm/search/base.rb

@@ -16,20 +16,43 @@ module Searchgasm #:nodoc:
       # Use these methods just like you would in ActiveRecord
       SEARCH_METHODS = [:all, :average, :calculate, :count, :find, :first, :maximum, :minimum, :sum]
       
-      attr_accessor :klass, *::ActiveRecord::Base.valid_find_options
+      attr_accessor *::ActiveRecord::Base.valid_find_options
       
-      # Used in the ActiveRecord methods to determine if Searchgasm should get involved or not.
-      # This keeps Searchgasm out of the way unless it is needed.
-      def self.needed?(klass, options)
-        SPECIAL_FIND_OPTIONS.each do |option|
-          return true if options.symbolize_keys.keys.include?(option)
+      class << self
+        # Used in the ActiveRecord methods to determine if Searchgasm should get involved or not.
+        # This keeps Searchgasm out of the way unless it is needed.
+        def needed?(model_class, options)
+          SPECIAL_FIND_OPTIONS.each do |option|
+            return true if options.symbolize_keys.keys.include?(option)
+          end
+        
+          Searchgasm::Conditions::Base.needed?(model_class, options[:conditions])
+        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}Search"
+          
+          begin
+            class_search_name.constantize
+          rescue NameError
+            eval <<-end_eval
+              class #{class_search_name} < ::Searchgasm::Search::Base; end;
+            end_eval
+          
+            class_search_name.constantize
+          end
         end
         
-        Searchgasm::Conditions::Base.needed?(klass, options[:conditions])
+        # 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(/Search$/, "").constantize
+        end
       end
       
-      def initialize(klass, init_options = {})
-        self.klass = klass
+      def initialize(init_options = {})
         self.options = init_options
       end
       
@@ -44,11 +67,17 @@ module Searchgasm #:nodoc:
         end_eval
       end
       
+      # Makes using searchgasm in the console less annoying and keeps the output meaningful and useful
       def inspect
         options_as_nice_string = ::ActiveRecord::Base.valid_find_options.collect { |name| "#{name}: #{send(name)}" }.join(", ")
         "#<#{klass} #{options_as_nice_string}>"
       end
       
+      # Convenience method for self.class.klass
+      def klass
+        self.class.klass
+      end
+      
       def limit=(value)
         @limit = value.blank? || value == 0 ? nil : value.to_i
       end

data/lib/searchgasm/search/conditions.rb

@@ -1,5 +1,9 @@
 module Searchgasm
   module Search
+    # = Searchgasm Conditions
+    #
+    # Implements all of the conditions functionality into a searchgasm search. All of this functonality is extracted out into its own class Searchgasm::Conditions::Base. This is a separate module to help keep the code
+    # clean and organized.
     module Conditions
       def self.included(klass)
         klass.class_eval do
@@ -10,12 +14,24 @@ module Searchgasm
         end
       end
       
-      def initialize_with_conditions(klass, init_options = {})
-        self.conditions = Searchgasm::Conditions::Base.new(klass)
-        initialize_without_conditions(klass, init_options)
+      def initialize_with_conditions(init_options = {})
+        self.conditions = Searchgasm::Conditions::Base.create_virtual_class(klass).new
+        initialize_without_conditions(init_options)
       end
       
       # Sets conditions on the search. Accepts a hash or a Searchgasm::Conditions::Base object.
+      #
+      # === Examples
+      #
+      #   search.conditions = {:first_name_like => "Ben"}
+      #   search.conditions = User.new_conditions
+      #
+      # or to set a scope
+      #
+      #   search.conditions = "user_group_id = 6"
+      #
+      # now you can create the rest of your search and your "scope" will get merged into your final SQL.
+      # What this does is determine if the value a hash or a conditions object, if not it sets it up as a scope.
       def conditions_with_conditions=(values)
         case values
         when Searchgasm::Conditions::Base
@@ -25,22 +41,26 @@ module Searchgasm
         end
       end
       
+      # Tells searchgasm was relationships to include during the search. This is based on what conditions you set.
+      #
+      # <b>Be careful!</b>
+      # ActiveRecord associations can be an SQL train wreck. Make sure you think about what you are searching and that you aren't joining a table with a million records.
       def include_with_conditions
         includes = [include_without_conditions, conditions.includes].flatten.compact.uniq
         includes.blank? ? nil : (includes.size == 1 ? includes.first : includes)
       end
       
-      def sanitize_with_conditions(for_method = nil)
+      def sanitize_with_conditions(for_method = nil) # :nodoc:
         find_options = sanitize_without_conditions(for_method)
         find_options[:conditions] = find_options[:conditions].sanitize if find_options[:conditions]
         find_options
       end
       
-      def scope
+      def scope # :nodoc:
         conditions.scope
       end
       
-      def scope=(value)
+      def scope=(value) # :nodoc:
         conditions.scope = value
       end
     end

data/lib/searchgasm/search/ordering.rb

@@ -3,7 +3,18 @@ module Searchgasm
     # = Search Ordering
     #
     # The purpose of this module is to provide easy ordering for your searches. All that these options do is
-    # build :order for you. This plays a huge part in ordering your data on the interface. See Searchgasm::Helpers::Search for more information.
+    # build :order for you. This plays a huge part in ordering your data on the interface. See the options and examples below. The readme also touches on ordering. It's pretty simple thought:
+    #
+    # === Examples
+    #
+    #   search.order_by = :id
+    #   search.order_by = [:id, :first_name]
+    #   search.order_by = {:user_group => :name}
+    #   search.order_by = [:id, {:user_group => :name}]
+    #   search.order_by = {:user_group => {:account => :name}} # you can traverse through all of your relationships
+    #
+    #   search.order_as = "DESC"
+    #   search.order_as = "ASC"
     module Ordering
       def self.included(klass)
         klass.class_eval do
@@ -12,12 +23,12 @@ module Searchgasm
         end
       end
       
-      def include_with_ordering
+      def include_with_ordering # :nodoc:
         includes = [include_without_ordering, order_by_includes].flatten.compact.uniq
         includes.blank? ? nil : (includes.size == 1 ? includes.first : includes)
       end
       
-      def order_with_ordering=(value)
+      def order_with_ordering=(value) # :nodoc
         @order_by = nil
         self.order_without_ordering = value
       end

data/lib/searchgasm/search/pagination.rb

@@ -1,5 +1,8 @@
 module Searchgasm
   module Search
+    # = Searchgasm Pagination
+    #
+    # Adds in pagination functionality to searchgasm
     module Pagination
       def self.included(klass)
         klass.class_eval do
@@ -10,23 +13,26 @@ module Searchgasm
         end
       end
       
-      def limit_with_pagination=(value)
+      def limit_with_pagination=(value) # :nodoc:
         r_value = self.limit_without_pagination = value
         self.page = @page unless @page.nil? # retry page now that the limit has changed
         r_value
       end
       
-      def offset_with_pagination=(value)
+      def offset_with_pagination=(value) #:nodoc
         r_value = self.offset_without_pagination = value
         @page = nil
         r_value
       end
       
+      # The current page that the search is on
       def page
         return 1 if offset.blank? || limit.blank?
         (offset.to_f / limit).floor + 1
       end
+      alias_method :current_page, :page
       
+      # Lets you change the page for the next search
       def page=(value)
         # Have to use @offset, since self.offset= resets @page
         if value.nil?
@@ -46,6 +52,7 @@ module Searchgasm
         value
       end
       
+      # The total number of pages in your next search
       def page_count
         return 1 if per_page.blank? || per_page <= 0
         # Letting AR caching kick in with the count query
@@ -53,15 +60,53 @@ module Searchgasm
       end
       alias_method :page_total, :page_count
       
-      def next_page!
-        raise("You are on the last page") if page == page_count
-        self.page += 1
+      # Always returns 1, this is a convenience method
+      def first_page
+        1
+      end
+      
+      # Changes the page to 1 and then runs the "all" search. What's different about this method is that it does not raise an exception if you are on the first page. Unlike prev_page! and next_page!
+      # I don't think an exception raised is warranted, because you are expecting the same results each time it is ran.
+      def first_page!
+        self.page = first_page
         all
       end
       
+      # Changes the page to the page - 1
+      def prev_page
+        self.page - 1
+      end
+      
+      # Changes the page to page - 1 and runs the "all" search. Be careful with this method because if you are on the first page an exception is raised telling you that you are on the first page.
+      # I thought about just running the first page search again, but that seems confusing and unexpected.
       def prev_page!
-        raise("You are on the first page") if page == 1
-        self.page -= 1
+        raise("You are on the first page") if page == first_page
+        self.page = prev_page
+        all
+      end
+      
+      # Change the page to page + 1
+      def next_page
+        self.page + 1
+      end
+      
+      # Changes the page to page + 1 and calls the "all" method. Be careful with this method because if you are on the last page an exception is raised telling you that you are on the last page.
+      # I thought about just running the lat page search again, but that seems confusing and unexpected.
+      def next_page!
+        raise("You are on the last page") if page == last_page
+        self.page = next_page
+        all
+      end
+      
+      # Always returns the page_count, this is a convenience method
+      def last_page
+        page_count
+      end
+      
+      # Changes the page to the last page and runs the "all" search. What's different about this method is that it does not raise an exception if you are on the last page. Unlike prev_page! and next_page!
+      # I don't think an exception raised is warranted, because you are expecting the same results each time it is ran.
+      def last_page!
+        self.page = last_page
         all
       end
     end

data/lib/searchgasm/search/protection.rb

@@ -1,5 +1,25 @@
 module Searchgasm
   module Search
+    # = Searchgasm Protection
+    #
+    # This adds protection during mass asignments *only*. This allows you to pass a params object when doing mass assignments and not have to worry about Billy 13 year old adding in SQL injections.
+    # There is a section in the readme that covers protection but to reiterate:
+    #
+    # === Protected
+    #
+    #   User.new_search(params[:search])
+    #   User.new_conditions(params[:search])
+    #
+    #   search.options = params[:search]
+    #   conditions.conditions = params[:conditions]
+    #
+    # === NOT Protected
+    #
+    #   User.new_search!(params[:search])
+    #   User.new_conditions!(params[:search])
+    #   User.find(:all, params[:search])
+    #   User.first(params[:search])
+    #   User.all(params[:search])
     module Protection
       # Options that are allowed when protecting against SQL injections (still checked though)
       SAFE_OPTIONS = Base::SPECIAL_FIND_OPTIONS + [:conditions, :limit, :offset]
@@ -16,28 +36,30 @@ module Searchgasm
         end
       end
       
-      def limit_with_protection
+      def limit_with_protection # :nodoc:
         return Config.per_page if protected? && !@set_limit
         limit_without_protection
       end
       
-      def limit_with_protection=(value)
+      def limit_with_protection=(value) # :nodoc:
         @set_limit = true
         self.limit_without_protection = value
       end
       
-      def options_with_protection=(values)
+      def options_with_protection=(values) # :nodoc:
         return unless values.is_a?(Hash)
         self.protect = values.delete(:protect) if values.has_key?(:protect) # make sure we do this first
         frisk!(values) if protect?
         self.options_without_protection = values
       end
       
+      # Accepts a boolean. Will protect mass assignemnts if set to true, and unprotect mass assignments if set to false
       def protect=(value)
         conditions.protect = value
         @protect = value
       end
       
+      # Convenience methof for determing if the search is protected or not.
       def protect?
         protect == true
       end

data/lib/searchgasm/version.rb

@@ -67,7 +67,7 @@ module Searchgasm
 
     MAJOR = 1
     MINOR = 0
-    TINY  = 0
+    TINY  = 1
 
     # The current version as a Version instance
     CURRENT = new(MAJOR, MINOR, TINY)