simple_search 0.0.2 → 0.1.0

data/README.rdoc

@@ -57,7 +57,9 @@ Then in your view:
 Remember, searches are idempotent so to appease the HTTP gods (and make it easy to bookmark
 search results) they should be executed with GET.
   
-That should get you started, for now.
+That should get you started, for now. Read up on SimpleSearch::Search for more details, and keep in
+mind that this gem was extracted from code designed to serve a specific purpose -- it has not spent
+much time in the wild, so you may (will) find bugs. Please let me know about them.
 
 == Copyright
 

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.1.0

data/lib/simple_search/search.rb

@@ -1,7 +1,78 @@
 module SimpleSearch
+  # == How it works
+  #
+  # Okay, so +form_for+ is a really handy helper, right? Yes. But it expects that whatever
+  # object you are building a form... er, for, responds to methods that match the name of
+  # the first parameter. So, for instance ...
+  #
+  #   f.text_field :headly_von_headdington
+  #
+  # ... expects that the object you passed to form_for responds to the +headly_von_headdington+
+  # method. SimpleSearch uses this to its advantage by auto-creating methods that will
+  # help it build a set of conditions to search on.
+  #
+  # So, when you instantiate an object of class SimpleSearch::Search, it takes a look at the
+  # model you want it to search, and goes about creating a bunch of methods you will find
+  # handy to have available in your form_for block, based on the persistent attributes of your
+  # model -- that is, the columns in the database table.
+  #
+  # The methods vary by the type of data to be searched. For example purposes, let's assume
+  # the attribute is question is named "gipe", and see what kinds of conditions SimpleSearch
+  # will create depending on its data type.
+  #
+  # == Strings
+  #
+  # * +gipe+ - Matches if the searched attribute contains this string. In SQL terms, this is a
+  #   fragment that looks like <tt>gipe LIKE '%value%'</tt>
+  # * +gipe_starts_with+ - Matches if the attribute starts with this string. SQL:
+  #   <tt>gipe LIKE 'value%'</tt>
+  # * +gipe_exact+ - Exact match. In SQL terms: <tt>gipe = 'value'</tt>
+  # * +gipe_not+, +gipe_not_starts_with+, +gipe_not_exact+ - Negation of the previous examples.
+  #   Matches if the attribute doesn't contain, start with, or equal the value, respectively.
+  #
+  # == Numbers
+  #
+  # * +gipe+ - Matches if the searched attribute equals the supplied numeric value.
+  # * +gipe_not+ - Matches if the searched attribute doesn't equal the value.
+  # * +gipe_min+ - Matches if the searched attribute is greater than or equal to the value.
+  # * +gipe_max+ - Matches if the searched attribute is less than or equal to the value.
+  #
+  # == Dates/DateTimes
+  #
+  # * +gipe+ - Supplied value is can be a String, Date or DateTime. This method will always search on
+  #   a range against a datetime column.
+  #   
+  #   If a string, it will be parsed to a Date or DateTime, depending on the type of column it is
+  #   being compared against, and converted to a range from beginning_of_day to end_of_day in the
+  #   current time zone, if a range is needed. If it contains the text " to " it will be treated
+  #   as a specific date range. So "12/25/2009 to 12/31/2009" will return results from midnight on
+  #   Christmas day to just before the ball drops at Times Square.
+  # * +gipe_from+, +gipe_to+ - Sets the start or endpoint of a date/time range explicitly, much
+  #   as min/max do on numeric values. Keep in mind that range specifications are still locked to
+  #   a day boundary, so +gipe_from+ will be beginning_of_day and +gipe_to+ will be end_of_day when
+  #   searching against datetime columns.
+  #
+  # == Associations
+  #
+  # When you pass a list of associations to SimpleSearch::Search#new (in the +:search_associations+
+  # option) SimpleSearch will add methods for that association as well. These work as you might expect,
+  # so a <tt>:search_association => [:manufacturer, :owner, :users]</tt> on a model that +belongs_to+ a
+  # manufacturer and owner, and +has_many+ users will gain methods like users_first_name_starts_with and
+  # manufacturer_years_in_operation_min, depending on the attributes of the associated models.
   class Search
     attr_reader :options, :associations
-
+    
+    # SimpleSearch always needs a +model+ parameter to know which ActiveRecord model
+    # it will be wrapping around and squeezing juicy attribute goodness from.
+    # +options+ are, oddly enough, optional. That being said, without at least a few
+    # search criteria specified, SimpleSearch isn't going to be doing much besides
+    # providing a poorly-optimized alternative to Model.all in its +search+ method.
+    #
+    # One special option is the <tt>:search_associations</tt> option. This is a list
+    # of one or more associations on the model (as referenced by +has_many+, +belongs_to+,
+    # etc) that you would like to autogenerate search methods for, as well.
+    #
+    # Wait, what? Scroll up and read "How it works" for more details.
     def initialize(model, options = {})
       @model = model
       @associations = [*options.delete(:search_associations)].compact
@@ -14,6 +85,9 @@ module SimpleSearch
       @options = options.reject{|k, v| !respond_to?(k)}.merge dates
     end
 
+    # Returns the array of conditions that is passed to ActiveRecord's find or paginate
+    # method by this search. Useful for debugging or to do your own custom searches without
+    # using the +search+ or +count+ methods.
     def conditions
       conditions = []
       parameters = []
@@ -35,6 +109,10 @@ module SimpleSearch
       conditions.blank? ? [] : [conditions.join(" AND "), *parameters]
     end
     
+    # Runs the current search against the database, returning all results, or paginated
+    # results, depending on whether a +:page+ parameter has been received (and, of course,
+    # whether your model responds to paginate). All other options are passed through to the
+    # paginate/find call.
     def search(args = {})
       args.merge!(
         :conditions => self.conditions,
@@ -47,6 +125,8 @@ module SimpleSearch
       end
     end
   
+    # Get the count of records matched by the current search. All arguments are passed to
+    # ActiveRecord's count method.
     def count(args = {})
       args.merge!(
         :conditions => self.conditions,
@@ -217,7 +297,6 @@ module SimpleSearch
             date_str = options[meth]
             return nil if date_str.blank?
             from, to = date_str.split(/\s+to\s+/)
-            Rails.logger.info "from = #{from}, to = #{to}"
             to ||= from
             from = cast_to_date_or_time(model, n, from, :from).to_s(:db) rescue nil
             to = cast_to_date_or_time(model, n, to, :to).to_s(:db) rescue nil
@@ -275,7 +354,7 @@ module SimpleSearch
         if endpoint == :to
           date_or_time = date_or_time.end_of_day.in_time_zone
         else
-          date_or_time.beginning_of_day.in_time_zone
+          date_or_time = date_or_time.beginning_of_day.in_time_zone
         end
       end
       date_or_time

data/simple_search.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{simple_search}
-  s.version = "0.0.2"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ernie Miller"]

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 2
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - Ernie Miller