searchlogic 1.5.3

data/CHANGELOG.rdoc

@@ -0,0 +1,228 @@
+== 1.5.3 released 2008-10-30
+
+* Removed ilike conditions and let the like condition determine if it should use like or ilike depending on the connection adapter.
+* Fixed bug where the keywords condition was removing foreign characters.
+* Added configuration option for specifying your javascript library, to cut down on the javascript Searchlogic adds into the form helpers
+* Fixed bug with "not" conditions to use sanitize method, like it should, instead of to_conditions.
+* Only pass :distinct option for the count calculation
+* Fixed not_nil and not_blank conditions to use boolean values configuration option.
+
+== 1.5.2 released 2008-10-21
+
+* Added ilike conditions
+* Removed configatron dependency (was accidentally added)
+
+== 1.5.1 released 2008-10-20
+
+* Fixed bug with per_page_links
+* Added "ordering_by" class for per_page_links
+
+== 1.5.0 released 2008-10-20
+
+* Merge array of conditions with or or and where it makes sense. Begins with condition does not make sense to join with and, so instead join with or.
+* Cleaned up html validity so it will pass W3C validators
+* Restructure configuration to be more organized and allow for more configuration options.
+* Added more configuration options, especially for class names.
+
+== 1.4.1 released 2008-10-15
+
+* Extracted english text into configuration to support alternate languages. I18n support.
+* Improved method detection in add_joins to use respond_to? with the private method option set to true
+
+== 1.4.0 released 2008-10-15
+
+* Fixed bug when duping or cloning to copy over instance vars instead of method values
+* Fixed bug with older versions of ActiveRecord and creating an alias method chain on find in AssociationCollection
+* Added modifiers: upper, lower, trim, ltrim, rtrim
+* Added not_nil and not_blank conditions
+* Modified conditions so that table name is a variable, this allows table name to be switched on the fly.
+* Modified auto joins to return symbols instead of SQL. This allows AR to properly merge the joins and ultimately result in proper SQL when performing multiple complex scopes.
+* Fixed conflicts between includes and joins, duplicate joins are not added. Includes are prioritized. This also makes ActiveRecord much more flexible. Now you can cherry pick included associations. And not have to worry about conflicting with joins.
+* Modified ActiveRecord's default behavior to use inner joins with the :joins option. Inner joins impose limitations. When providing this as a "convenience", inner joins do not make sense. The don't allow OR conditions to be across associations, nor does it properly order when an ordering by an association attribute when that association is optional.
+
+== 1.3.5 released 2008-10-08
+
+* Since joins are now strings, AR doesn't know how to merge them properly. So searchlogic now checks which joins to skip over to avoid conflicts.
+
+== 1.3.4 released 2008-10-07
+
+* Fixed method names creation for conditions with modifiers
+* Create local column conditions, incase there are method conflicts. Such as "id".
+* All joins are switched to left outer joins. When search with *any* conditions, inner joins return incorrect results. Also when ordering by an association that allows for blanks, inner joins exclude the records with blank values. Only option is left outer joins.
+* If joins is manually set with a string, treat it as SQL, just like ActiveRecord
+
+== 1.3.3 released 2008-10-03
+
+* Fixed modifiers being double escaped on equals condition
+* Fixed bug when merging conditions with array substitutions
+* Updated blank condition to check if the values is false or not
+* Fixed type for the year modifier in the mysql adapter
+
+== 1.3.2 released 2008-10-03
+
+* Fixed condition to type cast all values in an array
+* Fixed bug to properly set the type for the type cast column
+* Fixed bug to allow conditions on local columns
+* Apparently ActiveRecord 2.2 doesnt remove duplicates on all joins, need to enforce this for ALL versions of ActiveRecord
+* Fixed bug when passing a symbol as the SQL type for condition return types
+* Moved duplicate removal to only apply when searching or calculating from a search object. Anything done in a normal ActiveRecord method should remain untouched and let ActiveRecord handle it. Just like in ActiveRecord if you do a User.all search and pass some :joins, you might get duplicate records. Searchlogic should not change that behavior, unless called from a searchlogic object.
+* Discard meaningless array values when setting a condition.
+* Delete blank strings from mass assignments on conditions.
+
+== 1.3.1 released 2008-10-02
+
+* Fixed bug when requiring a connection adapter that is not present
+* Fixes bug in "not" conditions
+
+== 1.3.0 released 2008-10-02
+
+* Added modifiers into the mix: hour_of_created_at_less_than = 10, etc.
+* Changed how the Searchlogic::Conditions::Base class works. Instead of predefining all methods for all conditions upon instantiation, they are defined as needed via method_missing. Similar to
+  ActiveRecord's dynamic finders: User.find_by_name_and_email(name, email). Once the are defined they never hit method_missing again, acts like a cache.
+* Altered how values are handled for each condition, meaningless values are ignored completely.
+* Added in more "not" conditions: not_like, not_begin_with, not_have_keywords, etc
+
+== 1.2.2 released 2008-09-29
+
+* Fixed bug when reverse engineering order to order_by, assumed ASC and DESC would always be present when they are not.
+* False is a meaningful value for some conditions, and false.blank? == true. So instead of using value.blank? to ignore conditions we use meaningless?(value), which returns false if it is false.
+* Fixed aliases for lt, lte, gt, and gte.
+* Fixed bug when writing conditions on associations via a hash with string keys
+* Added Config.remove_duplicates to turn off the "automatic" removing of duplicates if desired.
+* Updated searchlogic_state helper to insert the entire state all at once.
+* Added CSS class "ordering" to order_by_link if the search is being ordered by that.
+
+== 1.2.1 released 2008-09-25
+
+* Fixed problem when determining if an order_by_link is currently being ordered. Just "stringified" both comparable values.
+* Removed default order_by and order_as. They will ONLY have values if you specify how to order, otherwise they are nil.
+* Removed order_as requirement. order_as is optional.
+* Added in deep_merge methods for hash, copied over from ActiveSupport 2.1
+* Improved order by auto joins to be based off of what order_by returns instead of setting it when setting order_by.
+* Added priority_order_by. Useful if you want to order featured products first and then order as usual. See documentation in Searchlogic::Search::Ordering for more info.
+* Added in base64 support for order_by and priority_order_by so that it's value is safe in the URL
+* Added priority_order_by_link
+
+== 1.2.0 released 2008-09-24
+
+* Added searchlogic_params and searchlogic_url helper to use outside of the control type helpers.
+* Added dup and clone methods that work properly for searchlogic objects
+* Fixed bug to remove nil scope values, HABTM likes to add :limit => nil
+* Removed unnecessary build_search methods for associations
+* Removed support for searching with conditions only. This just made things much more complicated when you can accomplish the same thing by starting a new search and only setting conditions.
+* Fixed bug when searching with *any* conditions to use left outer joins instead of inner joins.
+
+== 1.1.3 released 2008-09-23
+
+* Setting a condition to nil removes it if the condition is set to ignore blanks
+* Setting search.conditions = "some sql" will reset ALL conditions. Alternatively search.conditions => {:first_name_contains => "Ben"} will overwrite "some sql". The same goes with search.conditions.first_name_contains = "Ben".
+* Fixed bug with inspect
+* Other small performance enhancements with memoized attributes
+
+== 1.1.2 released 2008-09-22
+
+* Fixed bug with select control types not using :search_obj to determine its select values.
+* Added is_nil and is_blank condition types.
+* "memoized" various attributes for performance enhancements
+* Removed the :order option from calculation options when :order is useless and just slows down query.
+* Switched from using :include to :joins, big performance increase
+
+== 1.1.1 released 2008-09-19
+
+* Fixed typo in "next page" button.
+* Updated valid options for searching and performing calculations, fixed some bugs when searching and performing calculations with advanced options.
+* Fixed bug in ordering where table name was assumed by the hash. Now assumed by the reflection.
+* Added default for per_page, so pagination comes implemented by default
+* On mass assignments blank strings for *any* conditions are ignored. Sometimes blank strings are meaningful for "equals" and "does not equal", those only takes effect if you explicitly call these conditions: search.conditions.name = "". User.new_search(:conditions => {:name => ""}) will be ignored. Also, Searchlogic should never change how ActiveRecord behaves by default. So User.all(:conditions => {:name => ""}) will NOT be ignored.
+
+== 1.1.0 released 2008-09-18
+
+* Added the options :inner_spread and :outer_spread to the page_links helper. Also added various config options for setting page_links defaults.
+* Updated calculation methods to ignore :limit and :offset. AR returns 0 or nil on calculations that provide an offset.
+* Added support to allow for "any" of the conditions, instead of all of them. Joins conditions with "or" instead of "and". See Searchlogic::Conditions::Base or the readme
+
+== 1.0.4 released 2008-09-18
+
+* Fixed bugs when performing calculations and searches on has_many through relationships.
+* Instead of merging the find_options myself, I delegated that to AR's with_scope function, which already does this. Much more solid, less intrusive.
+
+== 1.0.3 released 2008-09-18
+
+* Updated inspect to show the current options for your search. Plays nicer in the console.
+* Made sure protection state is persistent among relationship conditions.
+* Fixed bug with backwards compatibility of rails. concat requires a proc in older version.
+* Defaulted remote control types to use GET requests instead of POST.
+* Completely reengineered integration with ActiveRecord. Searchlogic is properly using scopes letting you do use serachgasm where scope are implemented. @current_users.orders.new_search, etc. If your search is scoped and you want a search object, that search object will represent a new search in the context of those scopes, meaning the scopes get merged into Searchlogic as options.
+* Dropped support for Searchlogic functionality when defining relationships: has_many :order, :conditions => {:total_gt => 100}, will not work anymore. It's a chicken and the egg thing. Searchlogic needs AR constants, some models get loaded before others, therefore the Order model may not have been loaded yet, causing an unknown constant error.
+* Clean up redundant code and moved it into the Searchlogic::Shared namespace.
+
+== 1.0.2 released 2008-09-12
+
+* Moved cached searchers out of the global namespace and into the Searchlogic::Cache namespce.
+* Various changes to improve performance through profiling / benchmarking. http://pastie.org/271936
+* Config.per_page works with new_search & new_search! only. Where as before it was only working if the search was protected.
+
+== 1.0.1 released 2008-09-11
+
+* 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/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Ben Johnson of Binary Logic (binarylogic.com)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -0,0 +1,123 @@
+CHANGELOG.rdoc
+examples/README.rdoc
+init.rb
+lib/searchlogic/active_record/associations.rb
+lib/searchlogic/active_record/base.rb
+lib/searchlogic/active_record/connection_adapters/mysql_adapter.rb
+lib/searchlogic/active_record/connection_adapters/postgresql_adapter.rb
+lib/searchlogic/active_record/connection_adapters/sqlite_adapter.rb
+lib/searchlogic/condition/base.rb
+lib/searchlogic/condition/begins_with.rb
+lib/searchlogic/condition/blank.rb
+lib/searchlogic/condition/child_of.rb
+lib/searchlogic/condition/descendant_of.rb
+lib/searchlogic/condition/ends_with.rb
+lib/searchlogic/condition/equals.rb
+lib/searchlogic/condition/greater_than.rb
+lib/searchlogic/condition/greater_than_or_equal_to.rb
+lib/searchlogic/condition/inclusive_descendant_of.rb
+lib/searchlogic/condition/keywords.rb
+lib/searchlogic/condition/less_than.rb
+lib/searchlogic/condition/less_than_or_equal_to.rb
+lib/searchlogic/condition/like.rb
+lib/searchlogic/condition/nil.rb
+lib/searchlogic/condition/not_begin_with.rb
+lib/searchlogic/condition/not_blank.rb
+lib/searchlogic/condition/not_end_with.rb
+lib/searchlogic/condition/not_equal.rb
+lib/searchlogic/condition/not_have_keywords.rb
+lib/searchlogic/condition/not_like.rb
+lib/searchlogic/condition/not_nil.rb
+lib/searchlogic/condition/sibling_of.rb
+lib/searchlogic/condition/tree.rb
+lib/searchlogic/conditions/base.rb
+lib/searchlogic/conditions/protection.rb
+lib/searchlogic/config/helpers.rb
+lib/searchlogic/config/search.rb
+lib/searchlogic/config.rb
+lib/searchlogic/core_ext/hash.rb
+lib/searchlogic/helpers/control_types/link.rb
+lib/searchlogic/helpers/control_types/links.rb
+lib/searchlogic/helpers/control_types/remote_link.rb
+lib/searchlogic/helpers/control_types/remote_links.rb
+lib/searchlogic/helpers/control_types/remote_select.rb
+lib/searchlogic/helpers/control_types/select.rb
+lib/searchlogic/helpers/form.rb
+lib/searchlogic/helpers/utilities.rb
+lib/searchlogic/modifiers/absolute.rb
+lib/searchlogic/modifiers/acos.rb
+lib/searchlogic/modifiers/asin.rb
+lib/searchlogic/modifiers/atan.rb
+lib/searchlogic/modifiers/base.rb
+lib/searchlogic/modifiers/ceil.rb
+lib/searchlogic/modifiers/char_length.rb
+lib/searchlogic/modifiers/cos.rb
+lib/searchlogic/modifiers/cot.rb
+lib/searchlogic/modifiers/day_of_month.rb
+lib/searchlogic/modifiers/day_of_week.rb
+lib/searchlogic/modifiers/day_of_year.rb
+lib/searchlogic/modifiers/degrees.rb
+lib/searchlogic/modifiers/exp.rb
+lib/searchlogic/modifiers/floor.rb
+lib/searchlogic/modifiers/hex.rb
+lib/searchlogic/modifiers/hour.rb
+lib/searchlogic/modifiers/log.rb
+lib/searchlogic/modifiers/log10.rb
+lib/searchlogic/modifiers/log2.rb
+lib/searchlogic/modifiers/lower.rb
+lib/searchlogic/modifiers/ltrim.rb
+lib/searchlogic/modifiers/md5.rb
+lib/searchlogic/modifiers/microseconds.rb
+lib/searchlogic/modifiers/milliseconds.rb
+lib/searchlogic/modifiers/minute.rb
+lib/searchlogic/modifiers/month.rb
+lib/searchlogic/modifiers/octal.rb
+lib/searchlogic/modifiers/radians.rb
+lib/searchlogic/modifiers/round.rb
+lib/searchlogic/modifiers/rtrim.rb
+lib/searchlogic/modifiers/second.rb
+lib/searchlogic/modifiers/sign.rb
+lib/searchlogic/modifiers/sin.rb
+lib/searchlogic/modifiers/square_root.rb
+lib/searchlogic/modifiers/tan.rb
+lib/searchlogic/modifiers/trim.rb
+lib/searchlogic/modifiers/upper.rb
+lib/searchlogic/modifiers/week.rb
+lib/searchlogic/modifiers/year.rb
+lib/searchlogic/search/base.rb
+lib/searchlogic/search/conditions.rb
+lib/searchlogic/search/ordering.rb
+lib/searchlogic/search/pagination.rb
+lib/searchlogic/search/protection.rb
+lib/searchlogic/search/searching.rb
+lib/searchlogic/shared/utilities.rb
+lib/searchlogic/shared/virtual_classes.rb
+lib/searchlogic/version.rb
+lib/searchlogic.rb
+Manifest
+MIT-LICENSE
+Rakefile
+README.rdoc
+test/fixtures/accounts.yml
+test/fixtures/cats.yml
+test/fixtures/dogs.yml
+test/fixtures/orders.yml
+test/fixtures/user_groups.yml
+test/fixtures/users.yml
+test/test_active_record_associations.rb
+test/test_active_record_base.rb
+test/test_condition_base.rb
+test/test_condition_types.rb
+test/test_conditions_base.rb
+test/test_conditions_protection.rb
+test/test_config.rb
+test/test_helper.rb
+test/test_search_base.rb
+test/test_search_conditions.rb
+test/test_search_ordering.rb
+test/test_search_pagination.rb
+test/test_search_protection.rb
+test_libs/acts_as_tree.rb
+test_libs/ordered_hash.rb
+test_libs/rexml_fix.rb
+TODO.rdoc

data/README.rdoc

@@ -0,0 +1,383 @@
+= Searchlogic
+
+Searchlogic is orgasmic. Maybe not orgasmic, but you will get aroused. So go grab a towel and let's dive in.
+
+<b>Searchlogic'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! It's searching, ordering, and pagination all in one.</b>
+
+== Helpful links
+
+*	<b>Documentation:</b> http://searchlogic.rubyforge.org
+*	<b>Easy pagination, ordering, and searching tutorial:</b> http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchlogic
+*	<b>Live example of the tutorial above (with source):</b> http://searchlogic_example.binarylogic.com
+* <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/16601-searchlogic
+
+== Install and use
+
+  sudo gem install searchlogic
+
+For rails
+
+  $ cd vendor/plugins
+  $ sudo gem unpack searchlogic
+
+Or as a plugin
+
+  script/plugin install git://github.com/binarylogic/searchlogic.git
+
+Now try out some of the examples below:
+
+<b>For all examples, let's assume the following relationships: User => Orders => Line Items</b>
+
+== Simple Searching Example
+
+  User.all(
+    :conditions => {
+      :first_name_contains => "Ben",          # first_name like '%Ben%'
+      :email_ends_with => "binarylogic.com",  # email like '%binarylogic.com'
+      :created_after => Time.now,             # created_at > Time.now
+      :hour_of_created_at => 5                # HOUR(created_at) > 5 (depends on DB type)
+    },
+    :per_page => 20,                        # limit 20
+    :page => 3,                             # offset 40, which starts us on page 3
+    :order_as => "ASC",
+    :order_by => {:user_group => :name}     # order user_groups.name ASC
+  )
+  
+same as above, but object based
+
+  search = User.new_search
+  search.conditions.first_name_contains = "Ben"
+  search.conditions.email_ends_with = "binarylogic.com"
+  search.conditions.created_after = Time.now
+  search.conditiona.hour_of_created_at = 5
+  search.per_page = 20
+  search.page = 3
+  search.order_as = "ASC"
+  search.order_by = {:user_group => :name}
+  search.all
+
+In both examples, instead of using the "all" method you could use any search method: first, find(:all), find(:first), count, sum, average, etc, just like ActiveRecord.
+
+== The beauty of searchlogic, integration into rails
+
+Using Searchlogic 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. Searchlogic is searching, ordering, and pagination all rolled into one simple plugin. Take all of that pagination and searching cruft out of your models and controllers, and let Searchlogic 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:
+
+  # 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"
+  
+  - 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
+  - else
+    No users were found.
+
+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_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.
+
+<b>See my tutorial on this example: http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchlogic</b>
+
+== Exhaustive Example w/ Object Based Searching (great for form_for or fields_for)
+
+  # Start a new search
+  @search = User.new_search(
+    :conditions => {
+      :first_name_contains => "Ben", 
+      :age_gt => 18,
+      :orders => {:total_lt => 100}
+    },
+    :per_page => 20,
+    :page => 2,
+    :order_by => {:orders => :total},
+    :order_as => "DESC"
+  )
+  
+  # Set local conditions
+  @search.conditions.email_ends_with = "binarylogic.com"
+
+  # 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.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"
+  @search.readonly = true
+  # ... see ActiveRecord documentation
+  
+  # Return results just like ActiveRecord
+  @search.all
+  @search.first
+
+Take the @search object and pass it right into form\_for or fields\_for (see above).
+
+== Calculations
+
+Using the object from above:
+
+  @search.average('id')
+  @search.count # ignores limit and offset
+  @search.maximum('id')
+  @search.minimum('id')
+  @search.sum('id')
+  @search.calculate(:sum, 'id')
+  # ...any of the above calculations, see ActiveRecord documentation on calculations
+
+Or do it from your model:
+
+  User.count(:conditions => {:first_name_contains => "Ben"})
+  User.sum('id', :conditions => {:first_name_contains => "Ben"})
+  # ... all other calcualtions, etc.
+
+== 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:
+
+  User.all(:conditions => {:age_gt => 18}, :per_page => 20)
+
+  User.first(:conditions => {:age_gt => 18}, :per_page => 20)
+
+  User.find(:all, :conditions => {:age_gt => 18}, :per_page => 20)
+
+  User.find(:first, :conditions => {:age_gt => 18}, :per_page => 20)
+
+  search = User.new_search(:conditions => {:age_gt => 18})  # build_search is an alias
+  search.conditions.first_name_contains = "Ben"
+  search.per_page = 20
+  search.all
+  
+== Match ANY or ALL of the conditions
+
+As you saw above, the nice thing about Searchlogic is it's integration with forms. I designed the "any" option so that forms can set this as well, just like a condition.
+
+  search = User.new_search(:conditions => {:age_gt => 18})
+  search.conditions.first_name_contains = "Ben"
+  search.conditions.any = true # can set this to "true" or "1" or "yes"
+  search.all # will join all conditions with "or" instead of "and"
+  # ... all operations above are available
+
+== 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(:conditions => {:total_lte => 500})
+
+== Scope support
+
+Not only can you use searchlogic when searching, but you can use it when using scopes.
+
+  class User < ActiveRecord::Base
+    named_scope :sexy, :conditions => {:first_name => "Ben", email_ends_with => "binarylogic.com"}, :per_page => 20
+  end
+  
+or
+
+  class User < ActiveRecord::Base
+    def self.find_sexy
+      with_scope(:find => {:conditions => {:first_name => "Ben", email_ends_with => "binarylogic.com"}, :per_page => 20}) do
+        all
+      end
+    end
+  end
+
+== Always use protection...against SQL injections
+
+If there is one thing we all know, it's to always use protection against SQL injections. That's why searchlogic protects you by default. The new\_search methods protect mass assignments by default (instantiation and search.options = {}). This means that various checks are done to ensure it is not possible to perform any type of SQL injection during mass assignments. 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 method: new\_search!.
+
+=== Protected from SQL injections
+
+  search = Account.new_search(params[:search])
+
+=== *NOT* protected from SQL injections
+
+  accounts = Account.find(params[:search])
+  accounts = Account.all(params[:search])
+  account = Account.first(params[:search])
+  search = Account.new_search!(params[:search])
+
+I'm sure you already knew this, but it's tempting to do this when you can pass the params hash right into these methods.
+
+Lesson learned: use new\_search when passing in params as *ANY* of the options.
+
+== Available Conditions
+
+The conditions are pretty self explanitory, but if you need more information checkout the docs or the source. The code is very simple and self explanatory.
+
+=== Column conditions
+
+Each column can be used with any of the following conditions
+
+  Name                          Aliases                             Description
+  :begins_with                  :starts_with, :sw, :bw, :start      col LIKE 'value%'
+  :ends_with                    :ew, :ends, :end                    col LIKE '%value'
+  :equals                       :is, ""                             Lets ActiveRecord handle this
+  :greater_than                 :gt, :after                         col > value
+  :greater_than_or_equal_to     :at_least, :least, :gte             col >= value
+  :ilike                        :icontains, :ihas                   PostgreSQL specific, makes LIKE case insensitive
+  :less_than                    :lt, :before                        col < value
+  :less_than_or_equal_to        :at_most, :most, :lte               col <= value
+  :keywords                     :kwords, :kw                        Splits into each word and omits meaningless words, a true keyword search
+  :like                         :contains, :has                     col LIKE '%value%'
+  
+  :not_begin_with               :not_bw, :not_sw, :not_start_with, :not_start, :beginning_is_not, :beginning_not
+  :not_end_with                 :not_ew, :not_end, :end_is_not, :end_not
+  :not_equal                    :does_not_equal, :is_not, :not
+  :not_have_keywords            :not_have_keywords, :not_keywords, :not_have_kw, :not_kw, :not_have_kwwords, :not_kwwords
+  :not_ilike                    :not_icontain, :not_ihave
+  :not_like                     :not_contain, :not_have
+
+=== Class level conditions
+
+Each model comes preloaded with class level conditions as well. The difference is that these are not applied to each column, but instead to the model as a whole. Example: search.conditions.child_of = 2
+
+  Name                          Description
+  :child_of                     Returns all children of value
+  :descendant_of                Returns all descendants (children, grandchildren, grandgrandchildren, etc)
+  :inclusive_descendant_of      Same as above but also includes the root
+  :sibling_of                   Returns all records that have the same parent
+
+== Modifiers
+
+=== What are modifiers?
+
+ActiveRecord does a great job when it comes to keeping your code database agnostic. But I feel like it neglected searching when it came to that goal. What if you want to find all records that were created after 7am? Depending on your database you would have to do something like the following:
+
+  MySQL:        HOUR(created_at)
+  PostgreSQL:   date_part('hour', created_at)
+  SQLite:       strftime('%H', created_at)
+
+All of a sudden your app is not database agnostic. Searchlogic to the rescue! Searchlogic creates what I like to call "modifiers" to handle this nonsense for you. A modifier modifies a column. For example, the hour modifier modifies a datetime column to return the hour.
+
+The last thing to keep in mind is that <b>not all modifiers are available for every database</b>. MySQL and PostgreSQL support all of these, but SQLite does not. SQLite is nice, in the sense that its really is "lite". The only modifiers it supports are the datetime modifiers. If you want support for the other modifiers you have to write the SQLite function yourself and register the modifier in searchlogic.
+
+Here are all of the available modifiers:
+
+=== Available modifiers
+
+  Name              Aliases                                     Description
+  :microsecond      :microseconds, :microsecs, :microsec        Extracts the microseconds
+  :millisecond      :milliseconds, :millisecs, :millisec        Extracts the milliseconds
+  :second           :sec                                        Extracts the seconds
+  :minute           :min                                        Extracts the minute
+  :hour                                                         Extracts the hour
+  :day_of_week      :dow                                        Extracts the day of week (1-7)
+  :day_of_month     :dom                                        Extracts the day of month (1-31)
+  :day_of_year      :doy                                        Extracts the day of year (1-366)
+  :week                                                         Extracts the week (1-53), 53rd week can be a "run-over" week to the next year
+  :month            :mon                                        Extracts the month (1-12)
+  :year                                                         Extracts the year
+  
+  :md5                                                          Converts to a MD5
+  :char_length      :length                                     The length of the string (integer)
+  :lower            :downcase, :lcase                           Converts the string to all lower case characters
+  :ltrin            :lstrip                                     Strips off spaces from the beginning of the string
+  :trim             :strip                                      Strips off spaces from the beginning and end of the string
+  :rtrim            :rstrip                                     Strips off spaces from the end of the string
+  :upper            :upcase, :ucase                             Converts the string to all upper case character
+  
+  :absolute         :abs                                        The absolute value (-1 => 1)
+  :acos                                                         The arc cosine
+  :asin                                                         The arc sine
+  :atan                                                         The arc tangent
+  :ceil             :round_up                                   Rounds up to the nearest int
+  :cos              :cosine                                     The cosine
+  :cot              :cotangent                                  The cotangent
+  :degrees                                                      Converts radians to degrees
+  :exp              :exponential                                Returns the value of e (the base of natural logarithms) raised to the power of X
+  :floor            :round_down                                 Rounds down to the nearest int
+  :hex                                                          Converts the number to a hex
+  :log              :ln                                         The natural logarithm
+  :log10                                                        Returns the base-10 logarithm
+  :log2                                                         Returns the base-2 logarithm
+  :octal            :oct                                        Return an octal representation of a decimal number
+  :radians                                                      Converts to radians
+  :round                                                        Rounds the number
+  :sign                                                         The sign of the number
+  :sin                                                          The sine of the number
+  :square_root      :sqrt, :sq_rt                               The square root of the number
+  :tan              :tangent                                    The tangent of the number
+
+=== How to use modifiers
+
+Here's what the above table means. Let's take the created_at column. The created_at column is a datetime column, laet's apply modifiers that make sense for a datetime column.
+
+  search.conditions.second_of_created_at = 2
+  search.conditions.sec_of_created_at_greater_than = 3
+  search.conditions.year_of_created_at_most = 5
+  search.conditions.year_of_created_at_lt = 2000
+  # ... any of the modifiers that apply to datetime columns
+  
+Here's the cool part. Chaining modifiers:
+
+  search.conditions.ceil_of_cos_of_sec_of_created_at_greater_than = 3
+  
+As long as the modifier chain makes sense the possibilities are endless.
+
+=== Modifiers are not indexed
+
+Depending on your database you can create complex indexes. But chances are you probably didn't or don't plan to. So keep in mind that once you use a modifier it will not be using an index, meaning the query will be slower. One of the ways to get the best of both worlds is to cache virtual attributes in the database. Checkout my tutorial:
+
+http://www.binarylogic.com/2008/10/5/tutorial-caching-virtual-attributes-in-the-database
+
+== Roll your own conditions & modifiers
+
+For more information on this please see Searchlogic::Conditions::Base
+
+== 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 and I had 1 main rule when developing this:
+
+ActiveRecord should never know about Searchlogic
+
+What that rule means is that any options you pass when searching get "sanitized" down into options ActiveRecord can understand. Searchlogic serves as a transparent filter between you and ActiveRecord. 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 stays completely out of the way.
+
+Lastly, Searchlogic is lazy. It only creates objects, methods, and classes when needed. Once it creates them it caches them. For example, all of the nifty conditions are created via meta programming. The first time you execute something like User.new_search all of that method creation gets cached into Searchlogic::Cache::UserSearch. The next time you execute User.new_search it will be over 50 times faster because it uses the cached class.
+
+Between that and the extensive tests, this is a solid and fast plugin.
+
+== Credits
+
+Author: {Ben Johnson}[http://github.com/binarylogic] of {Binary Logic}[http://www.binarylogic.com]
+
+Credit to {Zack Ham}[http://github.com/zackham] 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