searchlogic 1.6.6 → 2.1.0

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+*.log
+pkg/*
+coverage/*
+doc/*
+benchmarks/*

data/CHANGELOG.rdoc

@@ -1,3 +1,20 @@
+== 2.0.2
+
+* Added a delete method to the Search class to allow the deleting of conditions off of the object.
+* Add alias_scope feature, lets your create "named scopes" that represent a procedure of named scopes, while at the same time telling Searchlogic it is safe to use in the Search class.
+* Use url_for as the default with form_for since rails does some magic to determine the url to use.
+
+== 2.0.1 released 2009-06-20
+
+* Allow the chaining of conditions off of a search object. Ex: search.username_like("bjohnson").age_gt(20).all
+* Split out left outer join creation into its own method, allowing you to use it in your own named scopes.
+* Make sure the search objects clone properly.
+* named_scope_options should return the proper options for existing named scopes with an arity greater than 0
+
+== 2.0.0
+
+* Everything, completely rewritten.
+
 == 1.6.6
 
 * Fixed time zone issues when searching.

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Ben Johnson of Binary Logic (binarylogic.com)
+Copyright (c) 2009 Ben Johnson of Binary Logic
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,461 +1,210 @@
 = Searchlogic
 
-Searchlogic's goal is to keep your application free of searching clutter. It's is an ActiveRecord extension that allows you to perform simple and complex searches with a hash. Why is this great? Because GET and POST parameters are a hash. This means if you can execute a search with a hash, you can execute a search using GET or POST parameters. This makes searching in your application dead simple and clutter free:
+<b>Searchlogic has been <em>completely</em> rewritten for v2. It is much simpler and has taken an entirely new approach. To give you an idea, v1 had ~2300 lines of code, v2 has ~420 lines of code.</b>
 
-  @search = User.new_search(params[:search])
-  @users = @search.all
-
-Now think about it this way. How are resources / web services used? Through GET and POST. All of a sudden you have a resource that comes preloaded with a *very* flexible searching functionality, all with 2 lines of code.
-
-What about your interface? What is an HTML form's sole purpose? It's to send GET or POST parameters to a URI. Now you can build a form that represents a search. Meaning adding a condition to your search is as easy as adding a field to your form. That's what the @search object above is all about. You can pass that right into your form builder and build a form just like you would for an ActiveRecord object. Now you can use that handy form builder that you like you use and get rid of even more searching clutter in your views.
-
-Searching in your application has never been cleaner, more flexible, or easier.
-
-These are just the basics of Searchlogic, it can do a lot more, including pagination, ordering data, etc. All of these things are just as simple, if not simpler. Keep reading to find out everything it can do.
+Searchlogic provides common named scopes and object based searching for ActiveRecord.
 
 == 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>Complex searching:</b> http://www.binarylogic.com/2008/11/30/searchlogic-1-5-7-complex-searching-no-longer-a-problem
+* <b>Documentation:</b> http://rdoc.info/projects/binarylogic/searchlogic
+* <b>Repository:</b> http://github.com/binarylogic/searchlogic/tree/master
 * <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/16601-searchlogic
+* <b>Google group:</b> http://groups.google.com/group/searchlogic
 
-== Install and use
-
-  sudo gem install searchlogic
-
-For rails, as a gem (recommended)
-  
-  # config/environment.rb
-  config.gem "searchlogic"
+<b>Before contacting me directly, please read:</b>
 
-Or as a plugin (for older versions of rails)
+If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.
 
-  script/plugin install git://github.com/binarylogic/searchlogic.git
+== Install & use
 
-Now try out some of the examples below:
+Install the gem from rubyforge:
 
-<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
+  sudo gem install searchlogic
 
-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.
+Or from github:
 
-== The beauty of Searchlogic, integration into rails
+  sudo gem install binarylogic-searchlogic
 
-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:
+Now just include it in your project and you are ready to go. See below for usage examples.
 
-  # app/controllers/users_controller.rb
-  def index
-    @search = User.new_search(params[:search])
-    @users, @users_count = @search.all, @search.count
-  end
+== Search using conditions on columns
 
-Now your view:
+Instead of explaining what Searchlogic can do, let me show you. Let's start at the top:
 
-  # 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.date_select :created_after
-      - users.fields_for users.object.orders do |orders|
-        = orders.select :total_gt, (1..100)
-    = f.submit "Search"
+  # We have the following model
+  User(id: integer, created_at: datetime, username: string, age: integer)
   
-  - unless @users_count.zero?
-    %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
+  # Searchlogic gives you a bunch of named scopes for free:
+  User.username_equals("bjohnson")
+  User.username_does_not_equal("bjohnson")
+  User.username_begins_with("bjohnson")
+  User.username_like("bjohnson")
+  User.username_ends_with("bjohnson")
+  User.age_greater_than(20)
+  User.age_greater_than_or_equal_to(20)
+  User.age_less_than(20)
+  User.age_less_than_or_equal_to(20)
+  User.username_null
+  User.username_blank
   
-    == 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
+  # You can also order by columns
+  User.ascend_by_username
+  User.descend_by_username
+  User.order("ascend_by_username")
 
-Using the object from above:
+Any named scope Searchlogic creates is dynamic and created via method_missing. Meaning it will only create what you need. Also, keep in mind, these are just named scopes, you can chain them, call methods off of them, etc:
 
-  @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
+  scope = User.username_like("bjohnson").age_greater_than(20).ascend_by_username
+  scope.all
+  scope.first
+  scope.count
+  # etc...
 
-Or do it from your model:
+That's all pretty standard, but here's where Searchlogic starts to get interesting...
 
-  User.count(:conditions => {:first_name_contains => "Ben"})
-  User.sum('id', :conditions => {:first_name_contains => "Ben"})
-  # ... all other calcualtions, etc.
+== Search using conditions on associated columns
 
-== Different ways to search, take your pick
+You also get named scopes for any of your associations:
 
-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
+  # We have the following relationships
+  User.has_many :orders
+  Order.has_many :line_items
+  LineItem
   
-  search = User.new_search(:conditions => {:age_gt => 18}) do |s|
-    s.conditions.first_name_contains = "Ben"
-    s.per_page = 20
-  end
-  search.all
+  # Set conditions on association columns
+  User.orders_total_greater_than(20)
+  User.orders_line_items_price_greater_than(20)
   
-== 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.
+  # Order by association columns
+  User.ascend_by_order_total
+  User.descend_by_orders_line_items_price
 
-  @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
+Again these are just named scopes. You can chain them together, call methods off of them, etc. What's great about these named scopes is that they do NOT use the :include option, making them <em>much</em> faster. Instead they create a INNER JOIN and pass it to the :joins option, which is great for performance. To prove my point here is a quick benchmark from an application I am working on:
 
-What if you want to mix and match?
-
-  @search = User.new_search(:conditions => {:age_gt => 18})
-  @search.conditions.or_first_name_contains = "Ben"
-  @search.conditions.or_last_name_contains = "Johnson"
-  @search.conditions.and_id_gt = 5 # the and_ is optional, calling just id_gt is the same thing
-  @search.all # will join conditions in the orders they were set with their specified join condition
-  # => age > 18 OR first_name like '%Ben%' OR lsat_name like '%Johnson%' AND id > 5
+  Benchmark.bm do |x|
+    x.report { 10.times { Event.tickets_id_gt(10).all(:include => :tickets) } }
+    x.report { 10.times { Event.tickets_id_gt(10).all } }
+  end
+        user     system      total        real
+   10.120000   0.170000  10.290000 ( 12.625521)
+    2.630000   0.050000   2.680000 (  3.313754)
 
-The order the conditions is set is relevant, as the SQL will be built in the same order.
+If you want to use the :include option, just specify it:
 
-== Grouping conditions
+  User.orders_line_items_price_greater_than(20).all(:include => {:orders => :line_items})
 
-In more complex searching situations you might want to group conditions. Just like you use parenthesis in raw SQL. Searchlogic's "group" function is basically a way to implement parenthesis in your conditions. It's simple:
+Obviously, only do this if you want to actually use the included objects.
 
-Group off an object:
+== Make searching and ordering data in your application trivial
 
-  search = User.new_search
-  search.id_gt = 2
-  group1 = search.conditions.group
-  group1.first_name_like = "Ben"
-  group2 = search.conditions.group
-  group2.last_name_like = "Johnson"
-  group21 = group2.group
-  group21.email_ends_with = "binarylogic.com"
-  # => id > 2 AND (first_name like '%Ben%') AND (last_name like '%Johnson%' AND (email like '%binarylogic.com'))
-  
-Group with a block:
+The above is great, but what about tying all of this in with a search form in your application? What would be really nice is if we could use an object that represented a single search. Like this...
 
-  search = User.new_search
-  search.id_gt = 2
-  search.conditions.group do |group|
-    group.first_name_like = "Ben"
-  end
-  search.conditions.or_group do |group|
-    group.last_name_like = "Johnson"
-    group.group do |sub_group|
-      sub_group.email_ends_with = "binarylogic.com"
-    end
-  end
-  # => id > 2 AND (first_name like '%Ben%') OR (last_name like '%Johnson%' AND (email like '%binarylogic.com'))
-
-Group with a hash:
-
-  search = User.new_search(:conditions => [
-    {:id_gt => 2},
-    {:group => {:first_name_like => "Ben"}},
-    {:group => [
-      {:last_name_like => "Johnson"},
-      {:group => {:email_ends_with => "binarylogic.com"}}
-    ]}
-  ])
-  # => id > 2 AND (first_name like '%Ben%') AND (last_name like '%Johnson%' AND (email like '%binarylogic.com'))
-
-I want to end this by saying Searchlogic was never meant to replace SQL, name_scopes, etc. If you need to perform complex searching there is nothing wrong with resorting to a named scope or using the traditional search methods. In fact, search logic plays nice with named_scopes anyways, so you can combine the 2 if needed:
-
-  @search = User.my_awesome_scope.another_cool_scope.new_search
+  search = User.search(:username_like => "bjohnson", :age_less_than => 20)
+  search.all
 
-You decide when a named scope makes the most sense. If you are creating a named scope that is specific to the search form you are building, you should consider adding the conditions right into the form. But if you are creating a named scope that you are using throughout your application, then it probably makes sense for it to be a named scope.
+The above is equivalent to:
 
-== Scoped searching
+  User.username_like("bjohnson").age_less_than(20).all
 
-  @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})
-  @current_user.orders.build_search(:conditions => {:total_lte => 500})
+You can set, read, and chain conditions off of your search too:
 
-== Scope support
+  search.username_like                              => "bjohnson"
+  search.age_gt = 2                                 => 2
+  search.id_gt(10).email_begins_with("bjohnson")    => <#Searchlogic::Search...>
+  search.all                                        => An array of users
+  search.count                                      => integer
+  # .. etc
 
-Not only can you use searchlogic when searching, but you can use it when using scopes.
+So let's start with the controller...
 
-  class User < ActiveRecord::Base
-    named_scope :sexy, :conditions => {:first_name => "Ben", email_ends_with => "binarylogic.com"}, :per_page => 20
-  end
+=== Your controller
 
-or
+The search class just chains named scopes together for you. What's so great about that? It keeps your controllers extremely simple:
 
-  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
+  class UsersController < ApplicationController
+    def index
+      @search = User.search(params[:search])
+      @users = @search.all
     end
   end
 
-== Protection against SQL injections
-
-SQL injections are not fun, so let's make sure they don't happen. 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!.
+It doesn't get any simpler than that.
 
-=== Protected from SQL injections
+=== Your form
 
-  search = Account.new_search(params[:search])
+Adding a search condition is as simple as adding a condition to your form. Remember all of those named scopes above? Just create fields with the same names:
 
-=== *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
+  - form_for @search do |f|
+    = f.text_field :username_like
+    = f.select :age_greater_than, (0..100)
+    = f.text_field :orders_total_greater_than
+    = f.submit
 
-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.
+When a Searchlogic::Search object is passed to form_for it will add a hidden field for the "order" condition, to preserve the order of the data.
 
-=== Column conditions
+=== Additional helpers
 
-Each column can be used with any of the following conditions
+There really isn't a big need for helpers in searchlogic, other than helping you order data. If you want to order your search with a link, just specify the name of the column. Ex:
 
-  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
+  = order @search, :by => :age
+  = order @search, :by => :created_at, :as => "Created date"
 
-=== Class level conditions
+The first one will create a link that alternates between calling "ascend_by_age" and "descend_by_age". If you wanted to order your data by more than just a column, create your own named scopes: "ascend_by_*" and "descend_by_*". The "order" helper is a very straight forward helper, checkout the docs for some of the options.
 
-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
+<b>This helper is just a convenience method. It's extremely simple and there is nothing wrong with creating your own. If it doesn't do what you want, copy the code, modify it, and create your own. You could even fork the project, modify it there, and use your own gem.</b>
 
-  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
+== Use your existing named scopes
 
-The above conditions are for a nested set data structure, *not* a tree. Since we need to traverse through the tree a nested set is required for performance reasons. Traversing through a large tree is very bad for performance, a nested set solves this problem.
+This is one of the big differences between Searchlogic v1 and v2. What about your existing named scopes? Let's say you have this:
 
-== Modifiers
+  User.named_scope :four_year_olds, :conditions => {:age => 4}
 
-=== What are modifiers?
+Again, these are all just named scopes, use it in the same way:
 
-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:
+  User.search(:four_year_olds => true, :username_like => "bjohnson")
 
-  MySQL:        HOUR(created_at)
-  PostgreSQL:   date_part('hour', created_at)
-  SQLite:       strftime('%H', created_at)
+Notice we pass true as the value. If a named scope does not accept any parameters (arity == 0) you can simply pass it true or false. If you pass false, the named scope will be ignored. If your named scope accepts a parameter, the value will be passed right to the named scope regardless of the value.
 
-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.
+Now just throw it in your form:
 
-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.
+  - form_for @search do |f|
+    = f.text_field :username_like
+    = f.check_box :four_year_olds
+    = f.submit
 
-Here are all of the available modifiers:
+What's great about this is that you can do just about anything you want. If Searchlogic doesn't provide a named scope for that crazy edge case that you need, just create your own named scope. The sky is the limit.
 
-=== Available modifiers
+== Use any or all
 
-  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
-  :avg              :average                                    The average
-  :ceil             :round_up                                   Rounds up to the nearest int
-  :cos              :cosine                                     The cosine
-  :cot              :cotangent                                  The cotangent
-  :count                                                        The count
-  :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
-  :sum                                                          The sum 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:
+Every condition you've seen in this readme also has 2 related conditions that you can use. Example:
 
-  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.
+  User.username_like_any("bjohnson", "thunt")   # will return any users that have either of the strings in their username
+  User.username_like_all("bjohnson", "thunt")   # will return any users that have all of the strings in their username
+  User.username_like_any(["bjohnson", "thunt"]) # also accepts an array
 
-=== Modifiers are not indexed
+This is great for checkbox filters, etc. Where you can pass an array right from your form to this condition.
 
-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:
+== Pagination (leverage will_paginate)
 
-http://www.binarylogic.com/2008/10/5/tutorial-caching-virtual-attributes-in-the-database
+Instead of recreating the wheel with pagination, Searchlogic works great with will_paginate. All that Searchlogic is doing is creating named scopes, and will_paginate works great with named scopes:
 
-== Roll your own conditions & modifiers
+  User.username_like("bjohnson").age_less_than(20).paginate(:page => params[:page])
+  User.search(:username_like => "bjohnson", :age_less_than => 20).paginate(:page => params[:page])
 
-For more information on this please see Searchlogic::Conditions::Base
+If you don't like will_paginate, use another solution, or roll your own. Pagination really has nothing to do with searching, and the main goal for Searchlogic v2 was to keep it lean and simple. No reason to recreate the wheel and bloat the library.
 
 == 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.
+Before I use a library in my application I like to glance at the source and try to at least understand the basics of how it works. If you are like me, a nice little explanation from the author is always helpful:
 
-Between that and the extensive tests, this is a solid and fast plugin.
+Searchlogic utilizes method_missing to create all of these named scopes. When it hits method_missing it creates a named scope to ensure it will never hit method missing for that named scope again. Sort of a caching mechanism. It works in the same fashion as ActiveRecord's "find_by_*" methods. This way only the named scopes you need are created and nothing more.
 
-== Credits
+That's about it, the named scope options are pretty bare bones and created just like you would manually.
 
-Author: {Ben Johnson}[http://github.com/binarylogic] of {Binary Logic}[http://www.binarylogic.com]
+== Credit
 
-Credit to {Zack Ham}[http://github.com/zackham] for helping with feature suggestions.
+Thanks a lot to {Tyler Hunt}[http://github.com/tylerhunt] for helping plan, design, and start the project. He was a big help.
 
+== Copyright
 
-Copyright (c) 2008 {Ben Johnson}[http://github.com/binarylogic] of {Binary Logic}[http://www.binarylogic.com], released under the MIT license 
+Copyright (c) 2009 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license