outoftime-record_filter 0.2.0 → 0.6.0

data/README.rdoc

@@ -0,0 +1,205 @@
+= record_filter
+
+record_filter is a DSL for specifying criteria for ActiveRecord queries in pure Ruby.
+It has support for filters created on the fly and for named filters that are associated with object types.
+record_filter has the following top-level features:
+
+* Pure ruby API eliminates the need for hard-coded SQL in most cases.
+* Works seamlessly with existing ActiveRecord APIs, including named scopes.
+* Supports creation of ad-hoc filters as well as named filters that can be associated with object types.
+* Allows chaining of filters with each other and with named scopes to create complex queries.
+* Takes advantage of the associations in your ActiveRecord objects for a clean implicit join API.
+
+== Installation
+
+gem install outoftime-record_filter --source=http://gems.github.com
+
+== Usage
+
+=== Ad-hoc filters
+
+  Post.filter do
+    with(:permalink, 'blog-post')
+    having(:blog).with(:name, 'Blog')
+  end
+
+This could be expressed in ActiveRecord as:
+
+  Post.find(:all, :joins => :blog, :conditions => ['posts.permalink = ? AND blogs.name = ?', 'blog-post', 'Blog')
+
+and it returns the same result, a list of Post objects that are returned from the query.
+
+=== Named filters
+
+  class Post < ActiveRecord::Base
+    named_filter(:with_title) do |title|
+      with(:title, title)
+    end
+  end
+
+  Post.with_title('posted')
+
+This is the same as the following code using named scopes, and returns the same result:
+
+  class Post < ActiveRecord::Base
+    named_scope :with_title, lambda { |title| { :conditions => ['title = ?', title] }}
+  end
+  
+  Post.with_title('scoped')
+
+=== Restrictions
+
+Restrictions are specified through the API using the 'with' function. The first argument to 'with' should be the
+name of the field that the restriction applies to. All restriction types can be negated by chaining the 'with'
+method with a call to 'not', as seen in some examples below.
+
+==== Equality
+
+If a second argument is supplied, it is assumed that you are 
+expressing an equality condition and that argument is used as the value.
+
+  with(:title, 'abc') # :conditions => ['title = ?', 'abc']
+
+Which can be negated with:
+
+  with(:title, 'abc').not # :conditions => ['title <> ?', 'abc']
+
+For the more verbose among us, this can also be specified as:
+
+  with(:title).equal_to('abc') # :conditions => ['title = ?', 'abc']
+
+Other types of restrictions are specified by omitting the second argument to 'with' and chaining it with one of the
+restriction methods.
+
+==== Comparison operators
+
+  with(:price).greater_than(10) # :conditions => ['price > ?', 10]
+
+  with(:created_at).less_than(2.days.ago) # :conditions => ['created_at < ?', 2.days.ago]
+
+These methods can also have _or_equal_to tagged onto the end, to obvious affect, and all of the comparison operators are aliased to
+their standard single-character variants:
+
+  gt, gte, lt and lte
+
+==== IS NULL
+
+  with(:price, nil) # :conditions => ['price IS NULL']
+
+This short form can also be made explicit by using the is_null, null, or nil functions on with:
+
+  with(:price).is_null # :conditions => ['price IS NULL']
+
+It can be negated either by chaining with the 'not' function or by using is_not_null:
+
+  with(:price).is_not_null # :conditions => ['price IS NOT NULL']
+  with(:price).is_null.not # "
+
+==== IN
+
+  with(:id).in([1, 2, 3]) # :conditions => ['id IN (?)', [1, 2, 3]]
+
+==== BETWEEN
+
+  with(:id).between(1, 5) # :conditions => ['id BETWEEN ? AND ?', 1, 5]
+
+The argument to between can also be either a tuple or a range
+
+  with(:created_at).between([Time.now, 3.days.ago]) # :conditions => ['created_at BETWEEN ? AND ?', Time.now, 3.days.ago]
+
+  with(:price).between(1..5) # :conditions => ['price BETWEEN ? AND ?', 1, 5]
+
+==== LIKE
+
+  with(:title).like('%help%') # :conditions => ['title LIKE ?', '%help%']
+
+
+=== Implicit Joins
+
+Implicit joins are specified using the 'having' function, which takes as its argument the name of an association to join on.
+
+  having(:comments) # :joins => :comments
+
+This function can be chained with calls to 'with' in order to specify conditions on the joined table:
+
+  having(:comments).with(:created_at).gt(2.days.ago) # :joins => :comments, :conditions => ['comments.created_at > ?', 2.days.ago]
+
+It can also take a block that can have any number of conditions or other clauses (including other joins) in it:
+
+  having(:comments) do
+    with(:created_at).gt(2.days.ago)
+    having(:author).with(:name, 'Bubba')
+  end
+
+The 'having' function can also take :inner, :left or :right as its second argument in order to specify that a particular join type
+should be used.
+
+=== Explicit joins
+
+In cases where there is no ActiveRecord association that can be used to specify an implicit join, explicit joins are also
+supported, using the 'join' function. Its arguments are the class to be joined against, the join type (:inner, left or :right) and
+an optional alias for the join table. A block should also be supplied in order to specify the columns to use for the join using the
+'on' method.
+
+  Post.filter do
+    join(Comment, :inner, :posts__comments_alias) do
+      on(:id => :commentable_id)
+      on(:commentable_type, 'Post')
+    end
+  end
+
+=== Conjunctions
+
+The following conjunction types are supported:
+
+* any_of
+* all_of
+* none_of
+* not_all_of
+
+Each takes a block that can contain conditions or joins and will apply the expected boolean logic to the combination.
+
+  any_of
+    with(:price, 2)
+    with(:price).gt(100)
+  end
+
+  # :conditions => ['price = ? OR price > ?', 2, 100]
+
+=== Limits and ordering
+
+  limit(20)
+
+  order(:id, :desc)
+
+Multiple order clauses can be specified, and they will be applied in the order in which they are specified.
+When joins are used, order can also take a hash as the first argument that leads to the column to order on through the joins:
+
+  having(:comments).with(:offensive, true)
+  order(:comments => :id, :desc)
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Mat Brown
+
+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/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :patch: 0
 :major: 0
-:minor: 2
+:minor: 6

data/lib/record_filter/active_record.rb

@@ -1,14 +1,33 @@
 module RecordFilter
+  # The ActiveRecordExtension module is mixed in to ActiveRecord::Base to form the
+  # top-level API for interacting with record_filter. It adds public methods for
+  # executing ad-hoc filters as well as for creating and querying named filters.
   module ActiveRecordExtension
     module ClassMethods
 
+      # Execute an ad-hoc filter  
+      #
+      # ==== Parameters
+      # block::
+      #   A block that specifies the contents of the filter.
+      #
+      # ==== Returns
+      # Filter:: The Filter object resulting from the query, which can be
+      #   treated as an array of the results.
+      #
+      # ==== Example
+      # Blog.filter do
+      #   having(:posts).with(:name, nil)
+      # end
+      #—
+      # @public
       def filter(&block)
         Filter.new(self, nil, &block)
       end
 
       def named_filter(name, &block)
         return if named_filters.include?(name.to_sym)
-        named_filters << name.to_sym 
+        local_named_filters << name.to_sym 
         DSL::DSL::subclass(self).module_eval do
           define_method(name, &block)
         end
@@ -21,10 +40,19 @@ module RecordFilter
       end
 
       def named_filters
-        read_inheritable_attribute(:named_filters) || write_inheritable_attribute(:named_filters, [])
+        result = local_named_filters.dup
+        result.concat(superclass.named_filters) if (superclass && superclass.respond_to?(:named_filters))
+        result
+      end
+
+      protected
+
+      def local_named_filters
+        @local_named_filters ||= []
       end
     end
   end
 end
 
 ActiveRecord::Base.send(:extend, RecordFilter::ActiveRecordExtension::ClassMethods)
+

data/lib/record_filter/conjunctions.rb

@@ -30,6 +30,8 @@ module RecordFilter
             result.add_order(step.column, step.direction)
           when DSL::GroupBy
             result.add_group_by(step.column)
+          when DSL::NamedFilter
+            result.add_named_filter(step.name, step.args)
           end
         end
         result
@@ -81,6 +83,14 @@ module RecordFilter
         @limit, @offset = limit, offset
       end
 
+      def add_named_filter(name, args)
+        unless @table.model_class.named_filters.include?(name.to_sym)
+          raise NamedFilterNotFoundException.new("The named filter #{name} was not found in #{@table.model_class}")
+        end
+        query = Query.new(@table.model_class, name, *args)
+        self << self.class.create_from(query.dsl_conjunction, @table)
+      end
+
       def <<(restriction)
         @restrictions << restriction
       end

data/lib/record_filter/dsl/conjunction.rb

@@ -44,6 +44,10 @@ module RecordFilter
       def add_group_by(column)
         @steps << GroupBy.new(column)
       end
+
+      def add_named_filter(method, *args)
+        @steps << NamedFilter.new(method, *args)
+      end
     end
   end
 end

data/lib/record_filter/dsl/conjunction_dsl.rb

@@ -53,6 +53,26 @@ module RecordFilter
       def filter_class
         @model_class
       end
+
+      def limit(offset_or_limit, limit=nil)
+        raise InvalidFilterException.new('Calls to limit can only be made in the outer block of a filter.')
+      end
+
+      def order(column, direction=:asc)
+        raise InvalidFilterException.new('Calls to order can only be made in the outer block of a filter.')
+      end
+
+      def group_by(column)
+        raise InvalidFilterException.new('Calls to group_by can only be made in the outer block of a filter.')
+      end
+
+      def on(column, value=Restriction::DEFAULT_VALUE)
+        raise InvalidFilterException.new('Calls to on can only be made in the block of a call to join.')
+      end
+
+      def method_missing(method, *args)
+        @conjunction.add_named_filter(method, *args)
+      end
     end
   end
 end

data/lib/record_filter/dsl/dsl.rb

@@ -12,7 +12,7 @@ module RecordFilter
         end
 
         def subclass(clazz)
-          SUBCLASSES[clazz.name.to_sym]
+          SUBCLASSES[clazz.object_id]
         end
       end
 

data/lib/record_filter/dsl/named_filter.rb

@@ -0,0 +1,12 @@
+module RecordFilter
+  module DSL
+    class NamedFilter
+
+      attr_reader :name, :args
+
+      def initialize(name, *args)
+        @name, @args = name, args
+      end
+    end
+  end
+end

data/lib/record_filter/dsl/restriction.rb

@@ -35,6 +35,11 @@ module RecordFilter
         end
       end
 
+      def is_not_null
+        @operator = :is_null
+        @negated = true
+      end
+
       alias_method :gt, :greater_than
       alias_method :gte, :greater_than_or_equal_to
       alias_method :lt, :less_than

data/lib/record_filter/dsl.rb

@@ -1,4 +1,4 @@
-%w(class_join conjunction conjunction_dsl dsl group_by join join_dsl join_condition limit order restriction).each { |file| require File.join(File.dirname(__FILE__), 'dsl', file) }
+%w(class_join conjunction conjunction_dsl dsl group_by join join_dsl join_condition limit named_filter order restriction).each { |file| require File.join(File.dirname(__FILE__), 'dsl', file) }
 
 module RecordFilter
   module DSL

data/lib/record_filter/filter.rb

@@ -12,29 +12,18 @@ module RecordFilter
       @current_scoped_methods = clazz.send(:current_scoped_methods)
       @clazz = clazz
 
-      @dsl = dsl_for_named_filter(@clazz, named_filter)
-      @dsl.instance_eval(&block) if block
-      @dsl.send(named_filter, *args) if named_filter && @dsl.respond_to?(named_filter)
-      @query = Query.new(@clazz, @dsl.conjunction)
+      @query = Query.new(@clazz, named_filter, *args, &block)
     end
 
     def first(*args)
-      if args.first.kind_of?(Integer)
-        loaded_data.first(*args)
-      else
-        do_with_scope do
-          @clazz.find(:first, *args)
-        end
+      do_with_scope do
+        @clazz.find(:first, *args)
       end
     end
 
     def last(*args)
-      if args.first.kind_of?(Integer)
-        loaded_data.last(*args)
-      else
-        do_with_scope do
-          @clazz.find(:last, *args)
-        end
+      do_with_scope do
+        @clazz.find(:last, *args)
       end
     end
 
@@ -90,16 +79,6 @@ module RecordFilter
       end
     end
 
-    def dsl_for_named_filter(clazz, named_filter)
-      return DSL::DSL.create(clazz) if named_filter.blank?
-      while (clazz)
-        dsl = DSL::DSL::SUBCLASSES.has_key?(clazz.name.to_sym) ? DSL::DSL::SUBCLASSES[clazz.name.to_sym] : nil
-        return DSL::DSL.create(clazz) if dsl && dsl.instance_methods(false).include?(named_filter.to_s)
-        clazz = clazz.superclass
-      end
-      nil
-    end
-
     def loaded_data
       @loaded_data ||= do_with_scope do
         @clazz.find(:all)

data/lib/record_filter/query.rb

@@ -1,31 +1,53 @@
 module RecordFilter
   class Query
 
-    def initialize(clazz, dsl_conjunction)
+    attr_reader :dsl_conjunction
+    attr_reader :conjunction
+
+    def initialize(clazz, named_filter, *args, &block)
+      dsl = dsl_for_named_filter(clazz, named_filter)
+      dsl.instance_eval(&block) if block
+      dsl.send(named_filter, *args) if named_filter && dsl.respond_to?(named_filter)
+
       @table = RecordFilter::Table.new(clazz)
-      @conjunction = RecordFilter::Conjunctions::Base.create_from(dsl_conjunction, @table)
+      @dsl_conjunction = dsl.conjunction
+      @conjunction = RecordFilter::Conjunctions::Base.create_from(@dsl_conjunction, @table)
     end
 
     def to_find_params(count_query=false)
-      params = {}
-      conditions = @conjunction.to_conditions
-      params = { :conditions => conditions } if conditions
-      joins = @table.all_joins
-      params[:joins] = joins.map { |join| join.to_sql } * ' ' unless joins.empty?
-      if (joins.any? { |j| j.requires_distinct_select? })
-        if count_query
-          params[:select] = "DISTINCT #{@table.model_class.quoted_table_name}.#{@table.model_class.primary_key}"
-        else
-          params[:select] = "DISTINCT #{@table.model_class.quoted_table_name}.*"
+      @params_cache ||= {}
+      @params_cache[count_query] ||= begin
+        params = {}
+        conditions = @conjunction.to_conditions
+        params = { :conditions => conditions } if conditions
+        joins = @table.all_joins
+        params[:joins] = joins.map { |join| join.to_sql } * ' ' unless joins.empty?
+        if (joins.any? { |j| j.requires_distinct_select? })
+          if count_query
+            params[:select] = "DISTINCT #{@table.model_class.quoted_table_name}.#{@table.model_class.primary_key}"
+          else
+            params[:select] = "DISTINCT #{@table.model_class.quoted_table_name}.*"
+          end
         end
+        orders = @table.orders
+        params[:order] = orders.map { |order| order.to_sql } * ', ' unless orders.empty?
+        group_bys = @table.group_bys
+        params[:group] = group_bys.map { |group_by| group_by.to_sql } * ', ' unless group_bys.empty?
+        params[:limit] = @conjunction.limit if @conjunction.limit
+        params[:offset] = @conjunction.offset if @conjunction.offset
+        params
+      end
+    end
+
+    protected
+
+    def dsl_for_named_filter(clazz, named_filter)
+      return DSL::DSL.create(clazz) if named_filter.blank?
+      while (clazz)
+        dsl = DSL::DSL.subclass(clazz)
+        return DSL::DSL.create(clazz) if dsl && dsl.instance_methods(false).include?(named_filter.to_s)
+        clazz = clazz.superclass
       end
-      orders = @table.orders
-      params[:order] = orders.map { |order| order.to_sql } * ', ' unless orders.empty?
-      group_bys = @table.group_bys
-      params[:group] = group_bys.map { |group_by| group_by.to_sql } * ', ' unless group_bys.empty?
-      params[:limit] = @conjunction.limit if @conjunction.limit
-      params[:offset] = @conjunction.offset if @conjunction.offset
-      params
     end
   end
 end