searchable_record 0.0.2

data/History.txt

@@ -0,0 +1,7 @@
+=== 0.0.2 / 2008-08-26
+
+* Changed specs to use RSpec syntax instead of test/spec.
+
+=== 0.0.1 / 2008-03-03
+
+* First release.

data/MIT-LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Tuomas Kareinen
+
+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.txt

@@ -0,0 +1,10 @@
+History.txt
+Manifest.txt
+MIT-LICENSE.txt
+Rakefile
+README.txt
+lib/searchable_record.rb
+lib/util.rb
+spec/searchable_record_spec_helper.rb
+spec/searchable_record_spec.rb
+spec/util_spec.rb

data/README.txt

@@ -0,0 +1,128 @@
+= 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.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'hoe'
+require 'spec/rake/spectask'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/lib")
+
+require 'searchable_record'
+
+Hoe.new('searchable_record', SearchableRecord::Meta::VERSION.to_s) do |p|
+  p.name = "searchable_record"
+  p.rubyforge_name = 'searchable-rec' # If different than lowercase project name
+  p.author = "Tuomas Kareinen"
+  p.email = 'tkareine@gmail.com'
+  p.summary = "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."
+  p.description = p.paragraphs_of('README.txt', 1..3).join("\n\n")
+  p.url = "http://searchable-rec.rubyforge.org"
+  # p.clean_globs = ['test/actual'] # Remove this directory on "rake clean"
+  p.remote_rdoc_dir = '' # Release to root
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.extra_deps = ['activesupport']
+end
+
+desc "Run specs."
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ["--format", "specdoc"]
+  #t.warning = true
+end
+
+desc "Search unfinished parts of source code."
+task :todo do
+  FileList['**/*.rb'].egrep /#.*(TODO|FIXME)/
+end

data/lib/searchable_record.rb

@@ -0,0 +1,267 @@
+unless defined? ActiveSupport
+  require 'rubygems'
+  gem 'activesupport'
+  require 'active_support'
+end
+require 'util'
+
+# See SearchableRecord::ClassMethods#find_queried for usage documentation.
+module SearchableRecord
+  module Meta #:nodoc:
+    module VERSION #:nodoc:
+      MAJOR = 0
+      MINOR = 0
+      BUILD = 2
+
+      def self.to_s
+        [ MAJOR, MINOR, BUILD ].join('.')
+      end
+    end
+  end
+
+  def self.included(base_class)   #:nodoc:
+    base_class.class_eval do
+      extend ClassMethods
+
+      @@searchable_record_settings = {
+        :cast_since_as     => 'datetime',
+        :cast_until_as     => 'datetime',
+        :pattern_operator  => 'like',
+        :pattern_converter => lambda { |val| "%#{val}%" }
+      }
+
+      cattr_accessor :searchable_record_settings
+    end
+  end
+
+  private
+
+  module ClassMethods
+    # === Description
+    #
+    # Parses the query parameters the client has given in the URL of the HTTP
+    # request. With the query parameters, the client may set a limit, an
+    # offset, or an ordering to the items in the search result. In addition,
+    # the client may limit the output by allowing only certain records that
+    # match to specific patterns.
+    #
+    # What the client user is allowed to query is defined by specific rules
+    # passed to the method as a Hash argument. Query parameters that are not
+    # explicitly stated in the rules are silently discarded.
+    #
+    # Essentially, the method is a frontend for
+    # ActiveRecord::Base#find. The method
+    #
+    # 1.  parses the query parameters the client has given in the URL for the
+    #     HTTP request (+query_params+) against the rules (+rules+), and
+    # 2.  calls <tt>find</tt> with the parsed options.
+    #
+    # ==== Parsing rules
+    #
+    # The parsing rules must be given as a Hash; the keys in the hash indicate
+    # the parameters that are allowed. The recognized keys are the following:
+    #
+    # *  <tt>:limit</tt>, which uses nil as the value (the same effect as with
+    #    <tt>find</tt>).
+    # *  <tt>:offset</tt>, which uses nil as the value (the same effect as with
+    #    <tt>find</tt>).
+    # *  <tt>:sort</tt>, which determines the ordering. The value is a Hash of
+    #    <tt>'parameter value' => 'internal table column'</tt> pairs (the same
+    #    effect as with the <tt>:order</tt> option of
+    #    <tt>find</tt>);
+    # *  <tt>:rsort</tt>, for reverse sort. Uses the rules of +:sort+; thus,
+    #    use <tt>nil</tt> as the value.
+    # *  <tt>:since</tt>, which sets a lower timedate limit. The value is
+    #    either a string naming the database table column that has timestamps
+    #    (using the type from default settings' <tt>:cast_since_as</tt> entry)
+    #    or a Hash that contains entries <tt>:column => 'table.column'</tt> and
+    #    <tt>:cast_as => '<sql_timedate_type>'</tt>.
+    # *  <tt>:until</tt>, which sets an upper timedate limit. Used like
+    #    <tt>:since</tt>.
+    # *  <tt>:patterns</tt>, where the value is a Hash containing patterns. The
+    #    keys in the Hash correspond to additional query parameters and the
+    #    corresponding values to database table columns. For each pattern,
+    #    the value is either directly a string, or a Hash containing the
+    #    entry <tt>:column => 'table.column'</tt>. In addition, the Hash may
+    #    contain optional entries
+    #    <tt>:converter => lambda { |val| <conversion_operation_for_val> }</tt>
+    #    and <tt>:operator => '<sql_pattern_operator>'</tt>.
+    #    <tt>:converter</tt> expects a block that modifies the input value; if
+    #    the key is not used, the converter specified in
+    #    <tt>:pattern_converter</tt> in the default settings is used.
+    #    <tt>:pattern_operator</tt> specifies a custom match operator for the
+    #    pattern; if the key is not used, the operator specified in
+    #    <tt>:pattern_operator</tt> in default settings is used.
+    #
+    # If both +sort+ and +rsort+ parameters are given in the URL and both are
+    # allowed by the rules, +sort+ is favored over +rsort+. Unlike with +sort+
+    # and +rsort+ rules (+rsort+ uses the rules of +sort+), the rules for
+    # +since+ and +until+ are independent from each other.
+    #
+    # For usage examples, see the example in README and the unit tests that
+    # come with the plugin.
+    #
+    # ==== Default settings for rules
+    #
+    # The default settings for the rules are accessible and modifiable by
+    # calling the method +searchable_record_settings+. The settings are
+    # stored as a Hash; the following keys are recognized:
+    #
+    # *  <tt>:cast_since_as</tt>,
+    # *  <tt>:cast_until_as</tt>,
+    # *  <tt>:pattern_operator</tt>, and
+    # *  <tt>:pattern_converter</tt>.
+    #
+    # See the parsing rules above how the default settings are used.
+    #
+    # === Arguments
+    #
+    # +extend+::  The same as the first argument to <tt>find</tt> (such as <tt>:all</tt>).
+    # +query_params+::  The (unsafe) query parameters from the URL.
+    # +rules+::  The parsing rules as a Hash.
+    # +options+:: Additional options for <tt>find</tt>, such as <tt>:include => [ :an_association ]</tt>.
+    #
+    # === Return
+    #
+    # The same as with ActiveRecord::Base#find.
+    def find_queried(extend, query_params, rules, options = { })
+      query_params = preserve_allowed_query_params(query_params, rules)
+
+      unless query_params.empty?
+        parse_offset(options, query_params)
+        parse_limit(options, query_params)
+        parse_order(options, query_params, rules)
+        parse_conditions(options, query_params, rules)
+      end
+
+      logger.debug("find_queried: query_params=<<#{query_params.inspect}>>, resulted options=<<#{options.inspect}>>")
+
+      self.find(extend, options)
+    end
+
+    private
+
+    def preserve_allowed_query_params(query_params, rules)
+      allowed_keys = rules.keys
+
+      # Add pattern matching parameters to the list of allowed keys.
+      allowed_keys.delete(:patterns)
+      if rules[:patterns]
+        allowed_keys += rules[:patterns].keys
+      end
+
+      # Do not affect the passed query parameters.
+      Util.pruned_dup(query_params, allowed_keys)
+    end
+
+    def parse_offset(options, query_params)
+      if query_params[:offset]
+        value = Util.parse_positive_int(query_params[:offset])
+        options[:offset] = value unless value.nil?
+      end
+    end
+
+    def parse_limit(options, query_params)
+      if query_params[:limit]
+        value = Util.parse_positive_int(query_params[:limit])
+        options[:limit] = value unless value.nil?
+      end
+    end
+
+    def parse_order(options, query_params, rules)
+      # Sort is favored over rsort.
+
+      if query_params[:rsort]
+        raise ArgumentError, "No sort rule specified." if rules[:sort].nil?
+
+        sort_by = rules[:sort][query_params[:rsort]]
+        options[:order] = sort_by + ' desc' unless sort_by.nil?
+      end
+
+      if query_params[:sort]
+        sort_by = rules[:sort][query_params[:sort]]
+        options[:order] = sort_by unless sort_by.nil?
+      end
+    end
+
+    def parse_conditions(options, query_params, rules)
+      cond_strs = [ ]
+      cond_syms = { }
+
+      # The hash query_params is not empty, therefore, it contains at least
+      # some of the allowed query parameters (as Symbols) below. Those
+      # parameters that are not identified are ignored silently.
+
+      parse_since_until(cond_strs, cond_syms, query_params, rules)
+      parse_patterns(cond_strs, cond_syms, query_params, rules)
+
+      construct_conditions(options, cond_strs, cond_syms) unless cond_strs.empty?
+    end
+
+    def parse_since_until(cond_strs, cond_syms, query_params, rules)
+      if query_params[:since]
+        parse_datetime(cond_strs, cond_syms, query_params, rules, :since)
+      end
+
+      if query_params[:until]
+        parse_datetime(cond_strs, cond_syms, query_params, rules, :until)
+      end
+    end
+
+    def parse_patterns(cond_strs, cond_syms, query_params, rules)
+      if rules[:patterns]
+        rules[:patterns].each do |param, rule|
+          if query_params[param]
+            match_op = searchable_record_settings[:pattern_operator]
+            conversion_blk = searchable_record_settings[:pattern_converter]
+
+            if rule.respond_to?(:to_hash)
+              column = rule[:column]
+
+              # Use custom pattern match operator.
+              match_op = rule[:operator] unless rule[:operator].nil?
+
+              # Use custom converter.
+              conversion_blk = rule[:converter] unless rule[:converter].nil?
+            else
+              column = rule
+            end
+
+            cond_strs << "(#{column} #{match_op} :#{param})"
+            cond_syms[param] = conversion_blk.call(query_params[param])
+          end
+        end
+      end
+    end
+
+    def parse_datetime(cond_strs, cond_syms, query_params, rules, type)
+      rule = rules[type]
+      cast_type = searchable_record_settings["cast_#{type}_as".to_sym]
+
+      if rule.respond_to?(:to_hash)
+        column = rule[:column]
+
+        # Use custom cast type.
+        cast_type = rule[:cast_as] unless rule[:cast_as].nil?
+      else
+        column = rule
+      end
+
+      case type
+      when :since then op = '>='
+      when :until then op = '<='
+      else raise ArgumentError, "Could not determine comparison operator for datetime."
+      end
+
+      cond_strs << "(#{column} #{op} cast(:#{type} as #{cast_type}))"
+      cond_syms[type] = query_params[type]
+    end
+
+    def construct_conditions(options, cond_strs, cond_syms)
+      conditions = [ cond_strs.join(' and '), cond_syms ]
+      preconditions = options[:conditions]
+      conditions[0].insert(0, "(#{preconditions}) and ") unless preconditions.nil?
+      options[:conditions] = conditions
+    end
+  end
+end

data/lib/util.rb

@@ -0,0 +1,28 @@
+module SearchableRecord
+  module Util   #:nodoc:
+    def self.pruned_dup(hash, preserved_keys)
+      hash = hash.to_hash
+
+      dup_hash = { }
+
+      preserved_keys.to_a.each do |key|
+        if !hash[key.to_s].blank?         # try to find first with 'key'; if that fails
+          dup_hash[key] = hash[key.to_s]
+        elsif !hash[key].blank?           # ...then with :key
+          dup_hash[key] = hash[key]
+        end
+      end
+
+      return dup_hash
+    end
+
+    def self.parse_positive_int(str)
+      integer = str.to_i
+      if integer > 0    # nil.to_i == 0
+        return integer
+      else
+        return nil
+      end
+    end
+  end
+end

data/spec/searchable_record_spec.rb

@@ -0,0 +1,301 @@
+require File.join(File.dirname(__FILE__) + '/searchable_record_spec_helper')
+require 'logger'
+require 'searchable_record'
+
+class Record; include SearchableRecord; end
+
+describe SearchableRecord, "for finding queried records" do
+  before(:each) do
+    Record.stubs(:logger).returns(stub(:debug))
+    #Record.stubs(:logger).returns(Logger.new(STDOUT))
+  end
+
+  it "should be able to modify default settings" do
+    new_settings = {
+      :cast_since_as     => 'time',
+      :cast_until_as     => 'date',
+      :pattern_operator  => 'regexp',
+      :pattern_converter => lambda { |val| val }
+    }
+
+    org_settings = Record.searchable_record_settings.dup
+
+    Record.searchable_record_settings = new_settings
+    Record.searchable_record_settings.should == new_settings
+
+    Record.searchable_record_settings = org_settings
+    Record.searchable_record_settings.should == org_settings
+  end
+
+  it "should execute find with no parameters, discarding unrecognized parameters" do
+    Record.expects(:find).times(2).with(:all, { })
+
+    Record.find_queried(:all, { }, { })
+    Record.find_queried(:all, { :foo => 'bar' }, { })
+  end
+
+  it "should execute find with a positive offset parameter" do
+    Record.expects(:find).times(1).with(:all, { :offset => 1 })
+
+    Record.find_queried(:all, { :offset => '1' }, { :offset => nil })
+
+    Record.expects(:find).times(2).with(:all, { :offset => 4 })
+
+    Record.find_queried(:all, { :offset => '4' }, { :offset => nil })
+    Record.find_queried(:all, { :offset => '4', :limit => '3' }, { :offset => nil })
+  end
+
+  it "should discard other than positive offset parameters" do
+    Record.expects(:find).times(4).with(:all, { })
+
+    Record.find_queried(:all, { },                  { :offset => nil })
+    Record.find_queried(:all, { :offset => 'aii' }, { :offset => nil })
+    Record.find_queried(:all, { :offset => '0' },   { :offset => nil })
+    Record.find_queried(:all, { :offset => '-1' },  { :offset => nil })
+  end
+
+  it "should execute find with a positive limit parameter" do
+    Record.expects(:find).times(1).with(:all, { :limit => 1 })
+
+    Record.find_queried(:all, { :limit => '1' }, { :limit => nil })
+
+    Record.expects(:find).times(2).with(:all, { :limit => 4 })
+
+    Record.find_queried(:all, { :limit => '4' }, { :limit => nil })
+    Record.find_queried(:all, { :limit => '4', :offset => '3' }, { :limit => nil })
+  end
+
+  it "should discard other than positive limit parameters" do
+    Record.expects(:find).times(4).with(:all, { })
+
+    Record.find_queried(:all, { },                 { :limit => nil })
+    Record.find_queried(:all, { :limit => 'aii' }, { :limit => nil })
+    Record.find_queried(:all, { :limit => '0' },   { :limit => nil })
+    Record.find_queried(:all, { :limit => '-1' },  { :limit => nil })
+  end
+
+  it "should execute find with sort parameter" do
+    Record.expects(:find).times(1).with(:all, { :order => 'users.first_name' })
+
+    Record.find_queried(:all, { :sort => 'first_name' },
+                              { :sort => { 'first_name' => 'users.first_name' } })
+  end
+
+  it "should execute find with reverse sort parameter" do
+    Record.expects(:find).times(1).with(:all, { :order  => 'users.first_name desc' })
+
+    Record.find_queried(:all, { :rsort => 'first_name' },
+                              { :sort  => { 'first_name' => 'users.first_name' },
+                                :rsort => nil })
+  end
+
+  it "should raise an exception if rsort is specified without sort rule" do
+    lambda { Record.find_queried(:all, { :rsort => 'first_name' },
+             { :rsort  => { 'first_name' => 'users.first_name' } }) }.should raise_error(ArgumentError)
+  end
+
+  it "should execute find with sort parameter, favoring 'sort' over 'rsort'" do
+    Record.expects(:find).times(1).with(:all, { :order  => 'users.first_name' })
+
+    Record.find_queried(:all, { :sort => 'first_name', :rsort => 'last_name' },
+                              { :sort  => { 'first_name' => 'users.first_name',
+                                            'last_name'  => 'users.last_name' },
+                                :rsort => nil })
+  end
+
+  it "should discard other than specified sort parameters" do
+    Record.expects(:find).times(1).with(:all, {  })
+
+    Record.find_queried(:all, { :sort => 'first' },
+                              { :sort => { 'first_name' => 'users.first_name' } })
+
+    Record.expects(:find).times(1).with(:all, { :order => 'users.last_name desc' })
+
+    Record.find_queried(:all, { :sort  => 'last', :rsort => 'last_name' },
+                              { :sort  => { 'first_name' => 'users.first_name',
+                                            'last_name'  => 'users.last_name' },
+                                :rsort => nil })
+  end
+
+  it "should execute find with since parameter, with default settings" do
+    Record.expects(:find).times(2).with(:all, { :conditions => [ '(users.created_at >= cast(:since as datetime))',
+                                                                 { :since => '2008-02-26' } ] })
+
+    Record.find_queried(:all, { :since => '2008-02-26' },
+                              { :since => 'users.created_at' })
+    Record.find_queried(:all, { :since => '2008-02-26' },
+                              { :since => { :column => 'users.created_at' } })
+  end
+
+  it "should execute find with since parameter, with custom settings" do
+    Record.expects(:find).times(3).with(:all, { :conditions => [ '(users.time >= cast(:since as time))',
+                                                                 { :since => '11:04' } ] })
+
+    Record.find_queried(:all, { :since => '11:04' },
+                              { :since => { :column  => 'users.time',
+                                            :cast_as => 'time' } })
+
+    org_settings = Record.searchable_record_settings.dup
+    Record.searchable_record_settings[:cast_since_as] = 'time'
+
+    Record.find_queried(:all, { :since => '11:04' },
+                              { :since => 'users.time'})
+
+    Record.find_queried(:all, { :since => '11:04' },
+                              { :since => { :column  => 'users.time' } })
+
+    Record.searchable_record_settings = org_settings
+  end
+
+  it "should execute find with until parameter, with default settings" do
+    Record.expects(:find).times(2).with(:all, { :conditions => [ '(users.created_at <= cast(:until as datetime))',
+                                                                 { :until => '2008-04-28' } ] })
+
+    Record.find_queried(:all, { :until => '2008-04-28' },
+                              { :until => 'users.created_at' })
+    Record.find_queried(:all, { :until => '2008-04-28' },
+                              { :until => { :column => 'users.created_at' } })
+  end
+
+  it "should execute find with until parameter, with custom settings" do
+    Record.expects(:find).times(3).with(:all, { :conditions => [ '(users.time <= cast(:until as time))',
+                                                                 { :until => '13:06' } ] })
+
+    Record.find_queried(:all, { :until => '13:06' },
+                              { :until => { :column  => 'users.time',
+                                            :cast_as => 'time' } })
+
+    org_settings = Record.searchable_record_settings.dup
+    Record.searchable_record_settings[:cast_until_as] = 'time'
+
+    Record.find_queried(:all, { :until => '13:06' },
+                              { :until => 'users.time'})
+
+    Record.find_queried(:all, { :until => '13:06' },
+                              { :until => { :column  => 'users.time' } })
+
+    Record.searchable_record_settings = org_settings
+  end
+
+  it "should execute find with pattern matching parameters" do
+    Record.expects(:find).times(1).with(:all, :conditions => [ "(users.first_name like :name)",
+                                                               { :name => '%john%' } ])
+
+    Record.find_queried(:all, { :name     => 'john' },
+                              { :patterns => { :name => 'users.first_name'} })
+  end
+
+  it "should execute find with a pattern matching parameter, with default settings" do
+    Record.expects(:find).times(1).with(:all, :conditions => [ "(sites.status like :status)",
+                                                               { :status => '%active%' } ])
+
+    Record.find_queried(:all, { :status   => 'active' },
+                              { :patterns => { :status => 'sites.status' } })
+  end
+
+  it "should execute find with a pattern matching parameter, with custom settings" do
+    Record.expects(:find).times(1).with(:all, :conditions => [ "(sites.domain like :domain)",
+                                                               { :domain => '%www.example.fi%' } ])
+
+    Record.find_queried(:all, { :domain   => 'www_example_fi' },
+                              { :patterns => { :domain => { :column    => 'sites.domain',
+                                                            :converter => lambda { |val| "%#{val.gsub('_', '.')}%" } } } })
+
+    Record.expects(:find).times(2).with(:all, :conditions => [ "(sites.domain regexp :domain)",
+                                                               { :domain => 'www.example.fi' } ])
+
+    Record.find_queried(:all, { :domain   => 'www_example_fi' },
+                              { :patterns => { :domain => { :column    => 'sites.domain',
+                                                            :converter => lambda { |val| val.gsub('_', '.') },
+                                                            :operator  => 'regexp' } } })
+
+    org_settings = Record.searchable_record_settings.dup
+    Record.searchable_record_settings[:pattern_operator]  = 'regexp'
+    Record.searchable_record_settings[:pattern_converter] = lambda { |val| val.gsub('_', '.') }
+
+    Record.find_queried(:all, { :domain   => 'www_example_fi' },
+                              { :patterns => { :domain => 'sites.domain' } })
+
+    Record.searchable_record_settings = org_settings
+  end
+
+  it "should execute find with multiple pattern matching parameters" do
+    results = [
+     { :conditions => [ "(sites.domain like :domain) and (sites.status like :status)",
+                      { :domain => '%www.another.example.fi%',
+                        :status => '%active%' } ]},
+     { :conditions => [ "(sites.status like :status) and (sites.domain like :domain)",
+                      { :domain => '%www.another.example.fi%',
+                        :status => '%active%' } ]}
+    ]
+
+    Record.expects(:find).times(1).with(:all, any_of(equals(results[0]), equals(results[1])))
+
+    Record.find_queried(:all, { :domain   => 'www_another_example_fi',
+                                :status   => 'active' },
+                              { :patterns => { :domain => { :column    => 'sites.domain',
+                                                            :converter => lambda { |val| "%#{val.gsub('_', '.')}%" } },
+                                               :status => 'sites.status' } })
+  end
+
+  it "should preserve additional options" do
+    Record.expects(:find).times(1).with(:all, :include => [ :affiliates ],
+                                        :conditions => [ "(sites.flags = 'fo') and (sites.domain like :domain)",
+                                                         { :domain => '%www.still-works.com%' } ])
+
+    Record.find_queried(:all, { :domain     => 'www_still-works_com' },
+                              { :patterns   => { :domain => { :column    => 'sites.domain',
+                                                              :converter => lambda { |val| "%#{val.gsub('_', '.')}%" } } } },
+                              { :conditions => "sites.flags = 'fo'",
+                                :include    => [ :affiliates ] })
+
+    Record.expects(:find).times(1).with(:all, :include => [ :affiliates ],
+                                        :conditions => [ "(sites.flags = 'fo') and (users.time <= cast(:until as time))",
+                                                         { :until => '13:06' } ])
+
+    Record.find_queried(:all, { :until      => '13:06' },
+                              { :until      => { :column  => 'users.time',
+                                                 :cast_as => 'time' } },
+                              { :conditions => "sites.flags = 'fo'",
+                                :include    => [ :affiliates ] })
+  end
+
+  it "should work with all rules combined" do
+    Item = Record
+
+    Item.expects(:find).times(1).with(: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%' } ])
+
+    query_params = {
+      :offset => '4',
+      :limit  => '5',
+      :rsort  => 'name',
+      :until  => '2008-02-28',
+      :name   => 'foo_bar'
+    }
+
+    rules = {
+      :limit    => nil,
+      :offset   => nil,
+      :sort     => { 'name' => 'items.name', 'created' => 'items.created_at' },
+      :rsort    => nil,
+      :since    => 'items.created_at',
+      :until    => 'items.created_at',
+      :patterns => { :type => 'items.type',
+                     :name => { :column    => 'items.name',
+                                :converter => lambda { |val| "%#{val.gsub('_', '.')}%" } } }
+    }
+
+    options = {
+      :include    => [ :owners ],
+      :conditions => "items.flag = 'f'"
+    }
+
+    Item.find_queried(:all, query_params, rules, options)
+  end
+end

data/spec/searchable_record_spec_helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'mocha'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end

data/spec/util_spec.rb

@@ -0,0 +1,32 @@
+require File.join(File.dirname(__FILE__) + '/searchable_record_spec_helper')
+require 'active_support/core_ext/blank'
+require 'util'
+
+include SearchableRecord
+
+describe Util do
+  it "should parse positive integers" do
+    Util.parse_positive_int('1').should == 1
+    Util.parse_positive_int('1sdfgsdf').should == 1
+    Util.parse_positive_int(nil).should be_nil
+    Util.parse_positive_int('0').should be_nil
+    Util.parse_positive_int('-1').should be_nil
+    Util.parse_positive_int('sdfgdfg').should be_nil
+  end
+
+  it "should prune and duplicate hashes" do
+    str = "don't remove me"
+
+    Util.pruned_dup({ :excess => 'foobar', :preserve => str },  [ :preserve ]).should == { :preserve => str }
+    Util.pruned_dup({ :excess => 'foobar', 'preserve' => str }, [ :preserve ]).should == { :preserve => str }
+
+    # A contrived example of calling #to_a for the second argument.
+    Util.pruned_dup({:e => 'foobar', [ :p, str ] => str }, { :p => str }).should == { [:p, str ] => str }
+
+    Util.pruned_dup({ :excess => 'foobar' }, [ :preserve ]).should == { }
+    Util.pruned_dup({ }, [ ]).should == { }
+    Util.pruned_dup({ }, [ :preserve ]).should == { }
+
+    lambda { Util.pruned_dup(nil, [ :foo ]) }.should raise_error(NoMethodError)
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: searchable_record
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Tuomas Kareinen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-27 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.7.0
+    version: 
+description: "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>."
+email: tkareine@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- MIT-LICENSE.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- MIT-LICENSE.txt
+- Rakefile
+- README.txt
+- lib/searchable_record.rb
+- lib/util.rb
+- spec/searchable_record_spec_helper.rb
+- spec/searchable_record_spec.rb
+- spec/util_spec.rb
+has_rdoc: true
+homepage: http://searchable-rec.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: searchable-rec
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: 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.
+test_files: []
+