searchable_record 0.0.2 → 0.0.3

data/CHANGELOG.rdoc

@@ -0,0 +1,11 @@
+=== 0.0.3 released 2009-01-14
+
+* Small code refactorization, documentation clarifications.
+
+=== 0.0.2 released 2008-08-26
+
+* Changed specs to use RSpec syntax instead of test/spec.
+
+=== 0.0.1 released 2008-03-03
+
+* First release.

data/Manifest

@@ -0,0 +1,11 @@
+CHANGELOG.rdoc
+lib/searchable_record/core.rb
+lib/searchable_record/util.rb
+lib/searchable_record/version.rb
+lib/searchable_record.rb
+Manifest
+Rakefile
+README.rdoc
+spec/searchable_record_spec.rb
+spec/searchable_record_spec_helper.rb
+spec/util_spec.rb

data/README.rdoc

@@ -0,0 +1,164 @@
+= 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
+<tt>ActiveRecord::Base#find</tt>: 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).
+
+First, we need resource items. Let us presume the application allows its
+clients to query <tt>Item</tt> type of resources:
+
+  class Item < ActiveRecord::Base
+    include SearchableRecord
+  end
+
+By including SearchableRecord module to Item, the method
+<tt>find_queried</tt> becomes available. The method can be called, for
+example, in <tt>ItemController</tt> to parse the client's query parameters:
+
+  Item.find_queried(:all, query_params, rules, options)
+
+In the beginning of this example, we stated requirements what the clients
+are allowed to query. These requirements 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
+  }
+
+These rules are fed to <tt>find_queried</tt> as the third argument.
+
+In addition, the application may to require options to be passed to
+<tt>find</tt>:
+
+  options = {
+    :include    => [ :owners ],
+    :conditions => "items.flag = 'f'"
+  }
+
+These can be supplied to <tt>find_queried</tt> as the fourth argument.
+
+The second argument to <tt>find_queried</tt> is the query parameters
+<tt>ItemController</tt> receives. For example, 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 application's resource containing the
+items. The action results to the following parameters:
+
+  query_params = params
+
+  # => query_params = {
+  #      'offset' => '4',
+  #      'limit'  => '5',
+  #      'rsort'  => 'name',
+  #      'until'  => '2008-02-28',
+  #      'name'   => 'foo_bar',
+  #      ...
+  #      # plus Rails-specific parameters, such as 'action' and 'controller'
+  # }
+
+With these query parameters and arguments, <tt>find_queried</tt> calls
+<tt>find</tt> with the following arguments:
+
+  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%" } ])
+
+This particular search results to 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 <tt>find_queried</tt> method in SearchableRecord::ClassMethods for
+details.
+
+== 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 feedback by email to Tuomas Kareinen < tkareine (at) gmail (dot)
+com >.
+
+== Legal notes
+
+This software is licensed under the terms of the "MIT license":
+
+Copyright (c) 2008-2009 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/Rakefile

@@ -1,35 +1,39 @@
-require 'rubygems'
-require 'hoe'
-require 'spec/rake/spectask'
+require "rubygems"
+require "spec/rake/spectask"
+require File.dirname(__FILE__) << "/lib/searchable_record/version"
+require "echoe"
 
-$LOAD_PATH.unshift(File.dirname(__FILE__) + "/lib")
+task :default => :spec
 
-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
+Echoe.new("searchable_record") do |p|
   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.email = "tkareine@gmail.com"
+  p.project = "searchable-rec" # If different than the project name in lowercase.
+  p.version = SearchableRecord::Version.to_s
   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']
+  p.summary =<<-END
+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.
+  END
+  p.runtime_dependencies = %w(activesupport)
+  p.ignore_pattern = "release-script.txt"
+  p.rdoc_pattern = ["*.rdoc", "lib/**/*.rb"]
 end
 
 desc "Run specs."
-Spec::Rake::SpecTask.new('spec') do |t|
-  t.spec_files = FileList['spec/**/*.rb']
+Spec::Rake::SpecTask.new("spec") do |t|
+  t.spec_files = FileList["spec/**/*.rb"]
   t.spec_opts = ["--format", "specdoc"]
   #t.warning = true
 end
 
+desc "Find code smells."
+task :roodi do
+  sh("roodi '**/*.rb'")
+end
+
 desc "Search unfinished parts of source code."
 task :todo do
-  FileList['**/*.rb'].egrep /#.*(TODO|FIXME)/
+  FileList["**/*.rb"].egrep /#.*(TODO|FIXME)/
 end

data/lib/searchable_record/core.rb

@@ -0,0 +1,270 @@
+# See SearchableRecord::ClassMethods#find_queried for usage documentation.
+module SearchableRecord
+  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 for 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
+    # <tt>ActiveRecord::Base#find</tt>. 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 recognized keys are the
+    # following:
+    #
+    # *  <tt>:limit</tt>, allowing limiting the number of matching items
+    #    (the same effect as with <tt>find</tt>). The value for the key is
+    #    irrelevant; use +nil+. The rule enables query parameter "limit"
+    #    that accepts an integer value.
+    # *  <tt>:offset</tt>, allowing skipping matching items (the same effect
+    #    as with <tt>find</tt>). The value for the key is irrelevant; use
+    #    +nil+. The rule enables query parameter "offset" that accepts an
+    #    integer value.
+    # *  <tt>:sort</tt>, which determines the ordering of matching items
+    #    (the same effect as with the <tt>:order</tt> option of
+    #    <tt>find</tt>). The value is a Hash of
+    #    <tt>"<parameter_value>" => "<table>.<column>"</tt> pairs. The rule
+    #    enables query parameter "sort" that accepts keys from the Hash as
+    #    its legal values.
+    # *  <tt>:rsort</tt>, for reverse sort. Uses the rules of
+    #    <tt>:sort</tt>; thus, use +nil+ as the value if you want to enable
+    #    "rsort" query parameter.
+    # *  <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 like
+    #    <tt>:column => "<table>.<column>"</tt> and
+    #    <tt>:cast_as => "<sql_timedate_type>"</tt>. The rule enables query
+    #    parameter "since" that accepts timedate values.
+    # *  <tt>:until</tt>, which sets an upper timedate limit. It is 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,
+    #    while the corresponding values to the keys correspond to database
+    #    table columns. For each pattern, the value is either directly a
+    #    string, or a Hash containing an entry like
+    #    <tt>:column => "<table>.<column>"</tt>. A pattern's Hash may
+    #    contain two optional entries in addition to <tt>:column</tt>:
+    #    <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 given, the converter specified in
+    #       <tt>:pattern_converter</tt> in the default settings is used
+    #       instead.
+    #    -  <tt>:operator</tt> specifies a custom match operator for the
+    #       pattern; if the key is not given, the operator specified in
+    #       <tt>:pattern_operator</tt> in the default settings is used
+    #       instead.
+    #
+    # If both +sort+ and +rsort+ parameters are given in the URL and both
+    # are allowed query parameter 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.txt and the specs 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 as a Hash.
+    # +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 <tt>ActiveRecord::Base#find</tt>.
+    def find_queried(extend, query_params, rules, options = { })
+      # Ensure the proper types of arguments.
+      query_params = query_params.to_hash
+      rules = rules.to_hash
+      options = options.to_hash
+
+      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_conditional_rules(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_conditional_rules(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_and_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_and_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_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 parse_patterns(cond_strs, cond_syms, query_params, rules)
+      if rules[:patterns]
+        rules[:patterns].each do |param, rule|
+          parse_pattern(cond_strs, cond_syms, query_params, param, rule)
+        end
+      end
+    end
+
+    def parse_pattern(cond_strs, cond_syms, query_params, 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
+
+    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 → searchable_record/util.rb}

@@ -6,7 +6,7 @@ module SearchableRecord
       dup_hash = { }
 
       preserved_keys.to_a.each do |key|
-        if !hash[key.to_s].blank?         # try to find first with 'key'; if that fails
+        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]

data/lib/searchable_record/version.rb

@@ -0,0 +1,11 @@
+module SearchableRecord
+  module Version #:nodoc:
+    MAJOR = 0
+    MINOR = 0
+    BUILD = 3
+
+    def self.to_s
+      [ MAJOR, MINOR, BUILD ].join('.')
+    end
+  end
+end