searchable_record 0.0.2 → 0.0.3

data/README.txt

@@ -1,128 +0,0 @@
-= SearchableRecord
-
-SearchableRecord is a small Ruby on Rails plugin that makes the parsing of
-query parameters from URLs easy for resources, allowing the requester to
-control the items (records) shown in the resource's representation.
-
-The implementation is a helper module (a mixin) for ActiveRecord models. It
-is used by including SearchableRecord module in a model.
-
-The mixin provides a class method, <tt>SearchableRecord#find_queried</tt>,
-to the class that includes it. The method is a front-end to
-ActiveRecord::Base#find: it parses query parameters against the given rules
-and calls <tt>find</tt> accordingly, returning the results of <tt>find</tt>.
-
-== A usage example
-
-The following example, although a bit contrived, allows the client to
-
-*  limit the number of items as the result of the search
-   (<tt>limit</tt> parameter),
-*  set an offset for the items (<tt>offset</tt> parameter, intended to be
-   used together with <tt>limit</tt>),
-*  sort the items either in ascending (<tt>sort</tt> parameter) or
-   descending (<tt>rsort</tt> parameter) order by items' type and name,
-*  to limit the result by matching only items that were update before
-   (<tt>until</tt> parameter) or after (<tt>since</tt> parameter) a certain
-   date, and
-*  to limit the result by matching only items with certain kind of
-   types (<tt>type</tt> parameter) or names (<tt>name</tt> parameter), or
-   both (for a name, a conversion to the client supplied parameter must be
-   applied before matching the name in the database).
-
-   
-These requirements for the query parameters are expressed as the following
-rules:
-   
-    rules = {
-      :limit    => nil,                 # key as a flag; the value for the key is not used
-      :offset   => nil,                 # key as a flag
-      :sort     => { 'name' => 'items.name', 'created' => 'items.created_at' },
-      :rsort    => nil,                 # rsort is allowed according to rules in :sort (key as a flag)
-      :since    => 'items.created_at',  # cast parameter value as the default type
-      :until    => 'items.created_at',  # cast parameter value as the default type
-      :patterns => { :type => 'items.type', # match the pattern with the default operator and converter
-                     :name => { :column    => 'items.name',
-                                :converter => lambda { |val| "%#{val.gsub('_', '.')}%" } } }
-                                        # match the pattern with the default operator
-    }
-
-The client uses the URL
-<tt>http://example-site.org/items?limit=5&offset=4&rsort=name&since=2008-02-28&name=foo_bar</tt>
-to fetch a representation of the resource containing the items. The action
-results to the following parameters:
-    
-    # => query_params = {
-    #      'offset' => '4',
-    #      'limit'  => '5',
-    #      'rsort'  => 'name',
-    #      'until'  => '2008-02-28',
-    #      'name'   => 'foo_bar',
-    #      ...
-    #      # plus Rails-specific parameters, such as 'action' and 'controller'
-    # }
-
-In addition, the application happens to require some options to be passed to
-<tt>find</tt>:
-    
-    options = {
-      :include    => [ :owners ],
-      :conditions => "items.flag = 'f'"
-    }
-
-When <tt>find_queried</tt> is called, with
-    
-    Item.find_queried(:all, query_params, rules, options)
-
-the result is the following call to <tt>find</tt>.
-   
-    Item.find(:all,
-              :include => [ :owners ],
-              :order   => 'items.name desc',
-              :offset  => 4,
-              :limit   => 5,
-              :conditions => [ "(items.flag = 'f') and (items.created_at <= cast(:until as datetime)) and (items.name like :name)",
-                               { :until => '2008-02-28', :name => '%foo.bar%' } ])
-
-The search result for <tt>find</tt> contains at most 5 items that are
-
-*  from offset 4 (that is, items from positions 5 to 9),
-*  sorted in descending order by items' names,
-*  updated since 2008-02-28, and
-*  have <tt>foo.bar</tt> in their name.
-
-See +find_queried+ method in SearchableRecord::ClassMethods for usage
-documentation.
-
-== Installation
-
-In order to install the plugin as a Ruby gem for a Rails application,
-edit the <tt>environment.rb</tt> file of the application to contain the
-following line:
-
-  config.gem "searchable_record"
-
-(This requires Rails version 2.1 or above.)
-
-Then install the gem, either using the Rakefile of the Rails application:
-
-  rake gems:install
-
-...or with the <tt>gem</tt> tool:
-	
-  gem install searchable_record
-
-Use git to get the source code for modifications and hacks:
-
-  git clone git://gitorious.org/searchable-rec/mainline.git
-
-== Contacting
-
-Please send comments, suggestions, bugs, or patches by email to Tuomas
-Kareinen < tkareine (at) gmail (dot) com >.
-
-== Legal note
-
-Copyright (c) 2008 Tuomas Kareinen.
-
-SearchableRecord plugin is licensed under the MIT license.