searchgasm 0.9.6 → 0.9.7

data/CHANGELOG

@@ -1,3 +1,5 @@
+v0.9.7. Complete class restructure, much more organized, added in documentation, added in helpers for using searchgasm in a rails app, updated readme with link to documentation as well as a live example, some bug fixes, more tests
+
 v0.9.6. Fix bug when instantiating with nil options
 
 v0.9.5. Enhanced searching with conditions only. Updated read me to include example on adding your own conditions.

data/Manifest

@@ -1,32 +1,42 @@
 CHANGELOG
+examples/README.rdoc
 init.rb
 lib/searchgasm/active_record/associations.rb
 lib/searchgasm/active_record/base.rb
+lib/searchgasm/condition/base.rb
+lib/searchgasm/condition/begins_with.rb
+lib/searchgasm/condition/child_of.rb
+lib/searchgasm/condition/contains.rb
+lib/searchgasm/condition/descendant_of.rb
+lib/searchgasm/condition/does_not_equal.rb
+lib/searchgasm/condition/ends_with.rb
+lib/searchgasm/condition/equals.rb
+lib/searchgasm/condition/greater_than.rb
+lib/searchgasm/condition/greater_than_or_equal_to.rb
+lib/searchgasm/condition/inclusive_descendant_of.rb
+lib/searchgasm/condition/keywords.rb
+lib/searchgasm/condition/less_than.rb
+lib/searchgasm/condition/less_than_or_equal_to.rb
+lib/searchgasm/condition/sibling_of.rb
+lib/searchgasm/condition/tree.rb
+lib/searchgasm/conditions/base.rb
+lib/searchgasm/conditions/protection.rb
+lib/searchgasm/config.rb
+lib/searchgasm/helpers/form_helper.rb
+lib/searchgasm/helpers/search_helper.rb
+lib/searchgasm/helpers/utilities_helper.rb
 lib/searchgasm/search/base.rb
-lib/searchgasm/search/condition.rb
-lib/searchgasm/search/condition_types/begins_with_condition.rb
-lib/searchgasm/search/condition_types/child_of_condition.rb
-lib/searchgasm/search/condition_types/contains_condition.rb
-lib/searchgasm/search/condition_types/descendant_of_condition.rb
-lib/searchgasm/search/condition_types/does_not_equal_condition.rb
-lib/searchgasm/search/condition_types/ends_with_condition.rb
-lib/searchgasm/search/condition_types/equals_condition.rb
-lib/searchgasm/search/condition_types/greater_than_condition.rb
-lib/searchgasm/search/condition_types/greater_than_or_equal_to_condition.rb
-lib/searchgasm/search/condition_types/inclusive_descendant_of_condition.rb
-lib/searchgasm/search/condition_types/keywords_condition.rb
-lib/searchgasm/search/condition_types/less_than_condition.rb
-lib/searchgasm/search/condition_types/less_than_or_equal_to_condition.rb
-lib/searchgasm/search/condition_types/sibling_of_condition.rb
-lib/searchgasm/search/condition_types/tree_condition.rb
 lib/searchgasm/search/conditions.rb
-lib/searchgasm/search/utilities.rb
+lib/searchgasm/search/ordering.rb
+lib/searchgasm/search/pagination.rb
+lib/searchgasm/search/protection.rb
+lib/searchgasm/utilities.rb
 lib/searchgasm/version.rb
 lib/searchgasm.rb
 Manifest
 MIT-LICENSE
 Rakefile
-README.mdown
+README.rdoc
 test/fixtures/accounts.yml
 test/fixtures/orders.yml
 test/fixtures/users.yml
@@ -34,7 +44,10 @@ test/libs/acts_as_tree.rb
 test/libs/rexml_fix.rb
 test/test_active_record_associations.rb
 test/test_active_record_base.rb
+test/test_condition.rb
+test/test_conditions_base.rb
 test/test_helper.rb
-test/test_searchgasm_base.rb
-test/test_searchgasm_condition_types.rb
-test/test_searchgasm_conditions.rb
+test/test_search_base.rb
+test/test_search_ordering.rb
+test/test_search_pagination.rb
+test/test_search_protection.rb

data/{README.mdown → README.rdoc}

@@ -1,36 +1,19 @@
-# Searchgasm
+= Searchgasm
 
 Searchgasm is orgasmic. Maybe not orgasmic, but you will get aroused. So go grab a towel and let's dive in.
 
-Searchgasm was a super secret tool of mine until I decided to share with the world. It has saved me tons of time, allowed me to write less code, made searching painless, and kept my controllers DRY and simple.
+<b>Searchgasm's inspiration comes right from ActiveRecord. ActiveRecord lets you create objects that represent a record in the database, so why can't you create objects that represent searching the database? Now you can!</b>
 
-It originated to satisfy a VERY simple need: so that I could use my form builder when making search forms. Sounds simple right? The goal was to use an object, that represents a search, just like an ActiveRecord object in form\_for and fields\_for.
+== Under the hood
 
-I'm a big fan of understanding what I'm using, so here's a quick explanation: The design behind this plugin is pretty simple. The search object "santiizes" down into the options passed into ActiveRecord::Base.find(). It basically serves as a transparent filter between you and ActiveRecord::Base.find(). This filter provides "enhancements" that get translated into options that ActiveRecord::Base.find() can understand. It doesn't dig into the ActiveRecord internals, it only uses what is publicly available. It jumps in and helps out only when needed, otherwise it sits back and lets ActiveRecord do all of the work. Between that and the extensive tests this is a solid plugin.
+I'm a big fan of understanding what I'm using, so here's a quick explanation: The design behind this plugin is pretty simple. The search object "sanitizes" down into the options passed into ActiveRecord::Base.find(). It serves as a transparent filter between you and ActiveRecord::Base.find(). This filter provides "enhancements" that get translated into options that ActiveRecord::Base.find() can understand. It doesn't dig into the ActiveRecord internals, it only uses what is publicly available. It jumps in and helps out <em>only</em> when needed, otherwise it sits back and lets ActiveRecord do all of the work. Between that and the extensive tests, this is a solid and fast plugin.
 
-Here's where you get aroused...
+== Quicklinks
 
-## Why I love Searchgasm!
+*	<b>Documentation:</b> http://searchgasm.rubyforge.org
+*	<b>Live rails example:</b> http://searchgasm_example.binarylogic.com
 
-    # app/controllers/users_controller.rb
-    def index
-        @search = User.new_search(:conditions => params[:conditions])
-        @users, @users_count = @search.all, @search.count
-    end
-
-Now your view, isn't it nice to use form builder again?
-
-    # app/views/users/index.html.erb
-    <%= form_for :conditions, @search.conditions, :url => users_path do |f| %>
-        <%= f.text_field :first_name_contains %>
-        <%= f.calendar_date_select :created_after %> # nice rails plugin for replacing date_select
-        <% f.fields_for :orders, f.object.orders do |orders_f| %>
-            <%= f.select :total_gt, (1..100) %>
-        <% end %>
-        <%= f.submit %>
-    <% end %>
-
-## Install and use
+== Install and use
 
     sudo gem install searchgasm
 
@@ -48,11 +31,52 @@ Or as a plugin
 
     script/plugin install git://github.com/binarylogic/searchgasm.git
 
-Now go into your console and try out any of these example with your own models.
+Now try out some of the examples below:
 
-**For all examples, let's assume the following relationships: User => Orders => Line Items**
+<b>For all examples, let's assume the following relationships: User => Orders => Line Items</b>
 
-## Simple Searching Example
+== The beauty of searchgasm
+
+Using Searchgasm in rails is the best part, because rails has all kinds of nifty methods to make dealing with ActiveRecord objects quick and easy, especially with forms. So let's take advantage of them! That's the idea behind this plugin. Searchgasm is searching, ordering, and pagination all rolled into one simple plugin. Take all of that pagination and searching cruft out of your models and let Searchgasm handle it. Check it out:
+
+    # app/controllers/users_controller.rb
+    def index
+        @search = User.new_search(params[:search])
+        @users, @users_count = @search.all, @search.count
+    end
+
+Now your view. Notice you can use your search object <b>just like</b> an ActiveRecord object.
+
+    # app/views/users/index.html.haml
+    - form_for @search do |f|
+     - f.fields_for @search.conditions do |users|
+        = users.text_field :first_name_contains
+        = users.calendar_date_select :created_after # nice rails plugin for replacing date_select
+        - users.fields_for users.object.orders do |orders|
+            = orders.select :total_gt, (1..100)
+        = f.submit "Search"
+    
+    %table
+        %tr
+            %th= order_by :first_name
+            %th= order_by :last_name
+            %th= order_by :email
+        - @users.each do |user|
+            %tr
+                %td= user.first_name
+                %td= user.last_name
+                %td= user.email
+    
+    Per page:
+    = per_page
+    Page:
+    = page
+
+Nice and simple. 2 lines in your controller, no "cruft" in your models, pagination as simple as calling the "page" and "per_page" helpers, ordering as simple as calling "order_by", and all searching conditions in 1 spot: your form. For documentation on helpers see Searchgasm::Helpers::FormHelper and Searchgasm::Helpers::SearchHelper.
+
+<b>See this example live: http://searchgasm_example.binarylogic.com</b>
+
+== Simple Searching Example
 
     User.all(
         :conditions => {
@@ -60,12 +84,12 @@ Now go into your console and try out any of these example with your own models.
             :email_ends_with => "binarylogic.com"   # email like '%binarylogic.com'
         },
         :per_page => 20     # limit 20
-        :page => 3          # offset 60
+        :page => 3          # offset 40, which starts us on page 3
     )
 
-Instead of using the "all" method you could use any search method: first, find(:all), find(:first), count, sum, average, etc
+Instead of using the "all" method you could use any search method: first, find(:all), find(:first), count, sum, average, etc, just like ActiveRecord
 
-## Detailed Example w/ object based searching (great for form\_for or fields\_for)
+== Exhaustive Example w/ Object Based Searching (great for form_for or fields_for)
 
     # Instantiate
     @search = User.new_search(
@@ -80,12 +104,16 @@ Instead of using the "all" method you could use any search method: first, find(:
         :order_as => "DESC"
     )
     
-    # Set conditions on relationships
+    # Set local conditions
     @search.conditions.email_ends_with = "binarylogic.com"
-    @search.conditions.oders.line_items.created_after = Time.now
+
+	# Set conditions on relationships
+    @search.conditions.oders.line_items.created_after = Time.now	# can traverse through all relationships
     
     # Set options
-    @search.per_page = 50 # overrides the 20 set above
+    @search.per_page = 50										# overrides the 20 set above
+	@search.order_by = [:first_name, {:user_group => :name}] 	# order by first name and then by the user group's name it belongs to
+	@search.order_as = "ASC"
     
     # Set ANY of the ActiveRecord options
     @search.group = "last_name"
@@ -94,12 +122,11 @@ Instead of using the "all" method you could use any search method: first, find(:
     
     # Return results just like ActiveRecord
     @search.all
-    @search.search # alias for all
     @search.first
 
 Take the @search object and pass it right into form\_for or fields\_for (see above).
 
-## Calculations
+== Calculations
 
 Using the object from above:
 
@@ -108,7 +135,8 @@ Using the object from above:
     @search.maximum('id')
     @search.minimum('id')
     @search.sum('id')
-    @search.calculate(:sum, 'id') # any of the above calculations
+    @search.calculate(:sum, 'id')
+	# ...any of the above calculations, see ActiveRecord documentation on calculations
 
 Or do it from your model:
 
@@ -116,7 +144,7 @@ Or do it from your model:
     User.sum('id', :conditions => {:first_name_contains => "Ben"})
     # ... all other calcualtions, etc.
 
-## Different ways to search, take your pick
+== Different ways to search, take your pick
 
 Any of the options used in the above example can be used in these, but for the sake of brevity I am only using a few:
 
@@ -133,34 +161,33 @@ 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 be hardcore:
+If you want to use Searchgasm directly:
 
-    search = Searchgasm::Search.new(User, :conditions => {:age_gt => 18})
+    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
+== Search with conditions only
 
     conditions = User.new_conditions(:age_gt => 18)
     conditions.first_name_contains = "Ben"
-    conditions.search
     conditions.all
     # ... all operations above are available
 
 Pass a conditions object right into ActiveRecord:
 
-    User.all(:conditions => conditions) # same as conditions.search
+    User.all(:conditions => conditions)
 
-Again, if you want to be hardcore:
+Again, if you want to use Searchgasm directly:
 
-    conditions = Searchgasm::Conditions.new(User, :age_gt => 18)
+    conditions = Searchgasm::Conditions::Base.new(User, :age_gt => 18)
     conditions.first_name_contains = "Ben"
-    conditions.search
+    conditions.all
 
 Now pass the conditions object right into form\_for or fields\_for (see above for example).
 
-## Scoped searching
+== Scoped searching
 
     @current_user.orders.find(:all, :conditions => {:total_lte => 500})
     @current_user.orders.count(:conditions => {:total_lte => 500})
@@ -168,7 +195,7 @@ Now pass the conditions object right into form\_for or fields\_for (see above fo
     
     search = @current_user.orders.build_search('total', :conditions => {:total_lte => 500})
 
-## Searching trees
+== Searching trees
 
 For tree data structures you get a few nifty methods. Let's assume Users is a tree data structure.
 
@@ -189,25 +216,25 @@ For tree data structures you get a few nifty methods. Let's assume Users is a tr
     User.all(:conditions => {:inclusive_descendant_of => User.roots.first.id})
     
 
-## Available anywhere (relationships & named scopes)
+== Available anywhere (relationships & scopes)
 
-Not only can you use searchgasm when searching, but you can use it when setting up relationships or named scopes:
+Not only can you use searchgasm when searching, but you can use it when setting up relationships or scopes. Anywhere you specify conditions in ActiveRecord.
 
     class User < ActiveRecord::Base
         has_many :expensive_pending_orders, :conditions => {:total_greater_than => 1_000_000, :state => :pending}, :per_page => 20
         named_scope :sexy, :conditions => {:first_name => "Ben", email_ends_with => "binarylogic.com"}, :per_page => 20
     end
 
-## Always use protection...against SQL injections
+== Always use protection...against SQL injections
 
-If there is one thing we all know, it's to always use protection. That's why searchgasm protects you by default. The new\_search and new\_conditions methods are protected by default. This means that various checks are done to ensure it is not possible to perform any type of SQL injection. But this also limits how you can search, meaning you can't write raw SQL. If you want to be daring and search without protection prepare to accept the consequences. All that you have to do is add ! to the end of the methods: new\_search! and new\_conditions!.
+If there is one thing we all know, it's to always use protection against SQL injections. That's why searchgasm protects you by default. The new\_search and new\_conditions methods are protected by default. This means that various checks are done to ensure it is not possible to perform any type of SQL injection. But this also limits how you can search, meaning you can't write raw SQL. If you want to be daring and search without protection, all that you have to do is add ! to the end of the methods: new\_search! and new\_conditions!.
 
-### Protected from SQL injections
+=== Protected from SQL injections
 
     search = Account.new_search(params[:search])
     conditions = Account.new_conditions(params[:conditions])
 
-### *NOT* protected from SQL injections
+=== *NOT* protected from SQL injections
 
     accounts = Account.find(params[:search])
     accounts = Account.all(params[:search])
@@ -217,7 +244,7 @@ If there is one thing we all know, it's to always use protection. That's why sea
 
 Lesson learned: use new\_search and new\_conditions when passing in params as *ANY* of the options.
 
-## Available Conditions
+== Available Conditions
 
 Depending on the type, each column comes preloaded with a bunch of nifty conditions:
 
@@ -246,11 +273,13 @@ Some of these conditions come with aliases, so you have your choice how to call
     :less_than                  => :lt, :before
     :less_than_or_equal_to      => :at_most, :lte
 
-### Enhanced searching and blacklisted words
+For more information on each condition see Searchgasm::Condition. Each condition has it's own class and the source is pretty simple and self explanatory.
+
+=== Enhanced searching and blacklisted words
 
 You will notice above there is "contains" and "keywords". The difference is that "keywords" is an enhanced search. It acts like a real keyword search. It finds those keywords, in any order, and blacklists meaningless words such as "and", "the", etc. "contains" finds the EXACT string in the column you are searching, spaces and all.
 
-### Roll your own conditions
+=== Roll your own conditions
 
 I didn't include this function because its MySQL specific, and it's probably rarely used, but MySQL supports a "SOUNDS LIKE" function.
 
@@ -258,7 +287,7 @@ I want to use it, so let's add it:
 
     # config/initializers/searchgasm.rb
     # Actual function for MySQL databases only
-    class SoundsLikeCondition < Searchgasm::Condition
+    class SoundsLike < Searchgasm::Condition::Base
       class << self
         # I pass you the column, you tell me what you want the method to be called.
         # If you don't want to add this condition for that column, return nil
@@ -281,21 +310,25 @@ I want to use it, so let's add it:
       end
     end
     
-    Searchgasm::Condition.register_condition(SoundsLikeCondition)
+    Searchgasm::Conditions::Base.register_condition(SoundsLike)
 
 Now test it out:
 
     search = User.new_search
-    search.first_name_sounds_like = "Ben"
+    search.conditions.first_name_sounds_like = "Ben"
     search.all  # will return any user that has a first name that sounds like "Ben"
 
-Pretty nifty, huh? You can create any condition ultimately creating any SQL you want. The sky is the limit.
+Pretty nifty, huh? You can create any condition ultimately creating any SQL you want. The sky is the limit. For more information see Searchgasm::Condition::Base
+
+== Reporting problems / bugs
+
+http://binarylogic.lighthouseapp.com/projects/16601-searchgasm
 
-## Credits
+== Credits
 
 Author: [Ben Johnson](http://github.com/binarylogic) of [Binary Logic](http://www.binarylogic.com)
 
-Credit to [Zack Ham](http://github.com/zackham) and [Robert Malko](http://github.com/malkomalko/) for helping with feature suggestions, cleaning up the readme / wiki, and cleaning up my code.
+Credit to [Zack Ham](http://github.com/zackham) and [Robert Malko](http://github.com/malkomalko/) for helping with feature suggestions.
 
 
 Copyright (c) 2008 [Ben Johnson](http://github.com/binarylogic) of [Binary Logic](http://www.binarylogic.com), released under the MIT license 

data/Rakefile

@@ -4,7 +4,7 @@ require 'echoe'
 require File.dirname(__FILE__) << "/lib/searchgasm/version"
 
 Echoe.new 'searchgasm' do |p|
-  p.version = BinaryLogic::Searchgasm::Version::STRING
+  p.version = Searchgasm::Version::STRING
   p.author = "Ben Johnson of Binary Logic"
   p.email  = 'bjohnson@binarylogic.com'
   p.project = 'searchgasm'

data/examples/README.rdoc

@@ -0,0 +1,4 @@
+=== Live example
+
+*	Please see the live example: http://searchgasm_example.binarylogic.com
+*	Source / Github project for the example: http://github.com/binarylogic/searchgasm_example.binarylogic.com

data/lib/searchgasm/active_record/associations.rb

@@ -1,53 +1,51 @@
-module BinaryLogic
-  module Searchgasm
-    module ActiveRecord
-      module Associations
-        module AssociationCollection
-          def find_with_searchgasm(*args)
-            options = args.extract_options!
-            args << sanitize_options_with_searchgasm(options)
-            find_without_searchgasm(*args)
-          end
-          
-          def build_conditions(options = {}, &block)
-            conditions = @reflection.klass.build_conditions(options, &block)
-            conditions.scope = scope(:find)[:conditions]
-            conditions
-          end
-          
-          def build_conditions!(options = {}, &block)
-            conditions = @reflection.klass.build_conditions!(options, &block)
-            conditions.scope = scope(:find)[:conditions]
-            conditions
-          end
+module Searchgasm
+  module ActiveRecord
+    module Associations
+      module AssociationCollection
+        def find_with_searchgasm(*args)
+          options = args.extract_options!
+          args << sanitize_options_with_searchgasm(options)
+          find_without_searchgasm(*args)
+        end
+        
+        def build_conditions(options = {}, &block)
+          conditions = @reflection.klass.build_conditions(options, &block)
+          conditions.scope = scope(:find)[:conditions]
+          conditions
+        end
         
-          def build_search(options = {}, &block)
-            conditions = @reflection.klass.build_search(options, &block)
-            conditions.scope = scope(:find)[:conditions]
-            conditions
-          end
-          
-          def build_search!(options = {}, &block)
-            conditions = @reflection.klass.build_search!(options, &block)
-            conditions.scope = scope(:find)[:conditions]
-            conditions
-          end
+        def build_conditions!(options = {}, &block)
+          conditions = @reflection.klass.build_conditions!(options, &block)
+          conditions.scope = scope(:find)[:conditions]
+          conditions
         end
       
-        module HasManyAssociation
-          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))
-          end
+        def build_search(options = {}, &block)
+          conditions = @reflection.klass.build_search(options, &block)
+          conditions.scope = scope(:find)[:conditions]
+          conditions
+        end
+        
+        def build_search!(options = {}, &block)
+          conditions = @reflection.klass.build_search!(options, &block)
+          conditions.scope = scope(:find)[:conditions]
+          conditions
+        end
+      end
+    
+      module HasManyAssociation
+        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))
         end
       end
     end
   end
 end
 
-ActiveRecord::Associations::AssociationCollection.send(:include, BinaryLogic::Searchgasm::ActiveRecord::Associations::AssociationCollection)
+ActiveRecord::Associations::AssociationCollection.send(:include, Searchgasm::ActiveRecord::Associations::AssociationCollection)
 
-module ::ActiveRecord
+module ActiveRecord
   module Associations
     class AssociationCollection
       alias_method_chain :find, :searchgasm
@@ -55,9 +53,9 @@ module ::ActiveRecord
   end
 end
 
-ActiveRecord::Associations::HasManyAssociation.send(:include, BinaryLogic::Searchgasm::ActiveRecord::Associations::HasManyAssociation)
+ActiveRecord::Associations::HasManyAssociation.send(:include, Searchgasm::ActiveRecord::Associations::HasManyAssociation)
 
-module ::ActiveRecord
+module ActiveRecord
   module Associations
     class HasManyAssociation
       alias_method_chain :count, :searchgasm