outoftime-record_filter 0.6.0 → 0.8.0

data/README.rdoc

@@ -12,7 +12,7 @@ record_filter has the following top-level features:
 
 == Installation
 
-gem install outoftime-record_filter --source=http://gems.github.com
+  gem install outoftime-record_filter --source=http://gems.github.com
 
 == Usage
 

data/Rakefile

@@ -1,4 +1,4 @@
-ENV['RUBYOPT'] = '-W1'
+# ENV['RUBYOPT'] = '-W1'
 
 require 'rubygems'
 require 'rake'
@@ -22,3 +22,37 @@ rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
 end
 
+# Try to use hanna to create spiffier docs.
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "record_filter #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'ruby-prof/task'
+
+  RubyProf::ProfileTask.new do |t|
+    t.test_files = FileList['test/performance_test.rb']
+    t.output_dir = 'perf'
+    t.printer = :graph_html
+    t.min_percent = 5
+  end
+rescue LoadError
+  puts 'Ruby-prof not available. Profiling tests are disabled.'
+end
+

data/VERSION.yml

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

data/lib/record_filter.rb

@@ -6,10 +6,31 @@ require 'active_record'
   require File.join(File.dirname(__FILE__), 'record_filter', file)
 end
 
+# The base-level namespace for the record_filter code. See RecordFilter::ActiveRecordExtension::ClassMethods
+# for a description of the public API.
 module RecordFilter
-  AssociationNotFoundException = Class.new(StandardError)
-  ColumnNotFoundException = Class.new(StandardError)
-  InvalidFilterException = Class.new(StandardError)
-  InvalidJoinException = Class.new(StandardError)
-  NamedFilterNotFoundException = Class.new(StandardError)
+
+  # An exception that is raised when an implicit join is attempted on an association 
+  # that does not exist.
+  class AssociationNotFoundException < StandardError; end
+  
+  # An exception that is raised when attempting to place restrictions or specify an
+  # explicit join on a column that doesn't exist.
+  class ColumnNotFoundException < StandardError; end
+
+  # An exception that is raised when operations such as limit, order, group_by, or
+  # on are called out of context.
+  class InvalidFilterException < StandardError; end
+
+  # An exception that is raised when attempting to create a named filter with a name that
+  # already exists in the class it is created on or one of its superclasses.
+  class InvalidFilterNameException < StandardError; end
+
+  # An exception that is raised when no columns are privided to specify an explicit join. 
+  class InvalidJoinException < StandardError; end
+
+  # An exception raised in the case where a named filter is called from within a filter
+  # and the named filter does not exist.
+  class NamedFilterNotFoundException < StandardError; end
 end
+

data/lib/record_filter/active_record.rb

@@ -2,33 +2,68 @@ 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.
+  # See RecordFilter::ActiveRecordExtension::ClassMethods for more detail on the
+  # API.
   module ActiveRecordExtension
     module ClassMethods
 
-      # Execute an ad-hoc filter  
+      # Create a filter on the fly to find a set of results that matches the given criteria.
+      # This method, which can be called on any ActiveRecord::Base subclass, accepts a block
+      # that defines the contents of the filter and returns a Filter object that contains a list
+      # of the objects resulting from the query. See the documentation for RecordFilter::DSL
+      # for more information on how to specify the filter.
       #
       # ==== Parameters
-      # block::
+      # block<Proc>::
       #   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.
+      # 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
-      #—
+      #   Blog.filter do
+      #     having(:posts).with(:name, nil)
+      #   end
+      #
       # @public
       def filter(&block)
         Filter.new(self, nil, &block)
       end
 
+      # Create a new named filter, which defines a function on the callee class that provides easy
+      # access to the query defined by the filter. Any number of named filters can be created on a
+      # class, and they can also be chained to create complex queries out of simple building blocks.
+      # In addition, named filters can accept any number of arguments in order to allow customization
+      # of their behavior when used. For more details on how to specify the contents of named filters,
+      # see the documentation for RecordFilter::DSL.
+      #
+      #   Post.named_filter(:without_permalink) do
+      #     with(:permalink, nil)
+      #   end
+      #
+      #   Post.named_filter(:created_after) do |time|
+      #     with(:created_at).gt(time)
+      #   end
+      #
+      #   Post.without_permalink                             # :conditions => ['permalink IS NULL']
+      #   Post.created_after(3.hours.ago)                    # :conditions => ['created_at > ?', 3.hours.ago]
+      #   Post.without_permalink.created_after(3.hours.ago)  # :conditions => ['permalink IS NULL AND created_at > ?', 3.hours.ago]
+      #
+      # ==== Raises
+      # InvalidFilterNameException::
+      #   There is already a named filter with the given name on this class or one of its superclasses.
+      #
+      # ==== Returns
+      # nil
+      #
+      # @public
       def named_filter(name, &block)
-        return if named_filters.include?(name.to_sym)
+        if named_filters.include?(name.to_sym)
+          raise InvalidFilterNameException.new("A named filter with the name #{name} already exists on the class #{self.name}.")
+        end
         local_named_filters << name.to_sym 
-        DSL::DSL::subclass(self).module_eval do
+        DSL::DSLFactory::subclass(self).module_eval do
           define_method(name, &block)
         end
 
@@ -37,8 +72,16 @@ module RecordFilter
             Filter.new(self, name, *args)
           end
         end
+        nil
       end
 
+      # Retreive a list of named filters that apply to a specific class, including ones
+      # that were defined in its superclasses.
+      #
+      # ==== Returns
+      # Array:: A list of the names of the named filters, as symbols. 
+      #
+      # @public
       def named_filters
         result = local_named_filters.dup
         result.concat(superclass.named_filters) if (superclass && superclass.respond_to?(:named_filters))
@@ -46,8 +89,8 @@ module RecordFilter
       end
 
       protected
-
-      def local_named_filters
+      
+      def local_named_filters # :nodoc:
         @local_named_filters ||= []
       end
     end

data/lib/record_filter/conjunctions.rb

@@ -1,5 +1,5 @@
 module RecordFilter
-  module Conjunctions
+  module Conjunctions # :nodoc: all
     class Base
       attr_reader :table_name, :limit, :offset
 

data/lib/record_filter/dsl.rb

@@ -1,6 +1,21 @@
-%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) }
+%w(class_join conjunction conjunction_dsl dsl dsl_factory group_by join join_dsl join_condition limit named_filter order restriction).each { |file| require File.join(File.dirname(__FILE__), 'dsl', file) }
 
 module RecordFilter
+  # The DSL module defines the structure of the criteria API used in calls to
+  # filter and named_filter. The API is defined by its four submodules, which
+  # define context-specific hooks for the API as well as defining a list of
+  # available restrictions. At the top level of a filter definition, all of the
+  # methods in DSL and ConjunctionDSL are available. In inner blocks, the methods
+  # in ConjunctionDSL are available, and within explicit joins defined using 'join'
+  # the methods in JoinDSL are added. The API provides access to:
+  #
+  # * Restrictions, using ConjunctionDSL.with and the methods in Restriction.
+  # * Conjunctions, such as all_of, any_of, etc. in ConjunctionDSL.
+  # * Implicit joins on associations, using ConjunctionDSL.having
+  # * Explicit joins, using ConjunctionDSL.join and JoinDSL.on
+  # * Ordering, using DSL.order
+  # * Grouping, using DSL.group_by
+  # * Limits and offsets, using DSL.limit
   module DSL
   end
 end

data/lib/record_filter/dsl/class_join.rb

@@ -1,6 +1,6 @@
 module RecordFilter
   module DSL
-    class ClassJoin
+    class ClassJoin # :nodoc: all
       attr_reader :join_class, :join_type, :table_alias, :conjunction
 
       def initialize(join_class, join_type, table_alias, conjunction, join_conditions)

data/lib/record_filter/dsl/conjunction.rb

@@ -1,6 +1,6 @@
 module RecordFilter
   module DSL
-    class Conjunction
+    class Conjunction # :nodoc: all
 
       attr_reader :type, :steps
 

data/lib/record_filter/dsl/conjunction_dsl.rb

@@ -1,78 +1,304 @@
 module RecordFilter
   module DSL
+    # The ConjunctionDSL is used for specifying restrictions, conjunctions and joins, with methods that
+    # can be accessed from any point in a filter declaration. The where method is used for creating
+    # restrictions, conjunctions are specified through any_of, all_of, none_of and not_all_of, and joins
+    # are described by having and join.
     class ConjunctionDSL
 
-      attr_reader :conjunction
+      attr_reader :conjunction # :nodoc:
 
-      def initialize(model_class, conjunction)
+      def initialize(model_class, conjunction) # :nodoc:
         @model_class = model_class
         @conjunction = conjunction
       end
 
-      # restriction
+      # Specify a condition on the given column, which will be added to the WHERE clause
+      # of the resulting query. This method returns a Restriction object, which can be called
+      # with any of the specific restriction methods described there in order to create many
+      # types of conditions. If both a column name and a value are passed, this will automatically
+      # create an equality condition, so the following two examples are equal:
+      #   with(:permalink, 'junk')
+      #   with(:permalink).equal_to('junk')
+      # If nil is passed as the second argument, an is_null restriction will automatically be
+      # created, so these two examples are equal as well:
+      #   with(:permalink, nil)
+      #   with(:permalink).is_null
+      # This method can be called at any point in the filter specification, and the appropriate
+      # clauses will be created if it is called within or other conjunctions.
+      #
+      # ==== Parameters
+      # column<Symbol>::
+      #   The name of the column to restrict. The column is assumed to exist in the table that is
+      #   currently in scope. In the outer block of a filter, that would be the table being filtered,
+      #   and within joins it would be the table being joined.
+      # value<value, optional>::
+      #   If specified, the value will be used to automatically create either an equality restriction
+      #   or an IS NULL test, as described above.
+      #
+      # ==== Returns
+      # Restriction::
+      #   A restriction object that can be used to create a specific condition. See the API in
+      #   Restriction for options.
+      #
+      # ==== Alternatives
+      # The value parameter is optional, as described above.
+      #
+      # @public
       def with(column, value=Restriction::DEFAULT_VALUE)
         return @conjunction.add_restriction(column, value)
       end
 
-      # conjunction
+      # Add a where clause that will pass if any of the conditions specified within it
+      # are true.  Any restrictions created inside the given block are OR'ed together
+      # in the final query, and the block can contain any number of joins, restrictions, or
+      # other conjunctions.
+      #   Blog.filter do
+      #     any_of do
+      #       with(:created_at, nil)
+      #       with(:created_at).greater_than(3.days.ago)
+      #     end
+      #   end
+      #
+      #   # :conditions => { ['blogs.created_at IS NULL OR blogs.created_at > ?', 3.days.ago] }
+      #
+      # ==== Parameters
+      # block<Proc>::
+      #   The block can contain any sequence of calls, and the conditions that it contains will be
+      #   OR'ed together to create a where clause.
+      #
+      # ==== Returns
+      # nil
+      #
+      # @public
       def any_of(&block)
         @conjunction.add_conjunction(:any_of, &block)
         nil
       end
 
-      # conjunction
+      # Add a where clause that will pass only if all of the conditions specified within it
+      # are true.  Any restrictions created inside the given block are AND'ed together
+      # in the final query, and the block can contain any number of joins, restrictions, or
+      # other conjunctions.
+      #   Blog.filter do
+      #     all_of do
+      #       with(:created_at, nil)
+      #       with(:created_at).greater_than(3.days.ago)
+      #     end
+      #   end
+      #
+      #   # :conditions => { ['blogs.created_at IS NULL AND blogs.created_at > ?', 3.days.ago] }
+      #
+      # ==== Parameters
+      # block<Proc>::
+      #   The block can contain any sequence of calls, and the conditions that it contains will be
+      #   AND'ed together to create a where clause.
+      #
+      # ==== Returns
+      # nil
+      #
+      # @public
       def all_of(&block)
         @conjunction.add_conjunction(:all_of, &block)
         nil
       end
 
+      # Add a where clause that will pass only if none of the conditions specified within it
+      # are true.  Any restrictions created inside the given block are OR'ed together
+      # in the final query and the result is negated. The block can contain any number of joins, 
+      # restrictions, or other conjunctions.
+      #   Blog.filter do
+      #     none_of do
+      #       with(:created_at, nil)
+      #       with(:created_at).greater_than(3.days.ago)
+      #     end
+      #   end
+      #
+      #   # :conditions => { ['NOT (blogs.created_at IS NULL OR blogs.created_at > ?)', 3.days.ago] }
+      #
+      # ==== Parameters
+      # block<Proc>::
+      #   The block can contain any sequence of calls, and the conditions that it contains will be
+      #   OR'ed together and then negated to create a where clause.
+      #
+      # ==== Returns
+      # nil
+      #
+      # @public
       def none_of(&block)
         @conjunction.add_conjunction(:none_of, &block)
         nil
       end
 
+      # Add a where clause that will pass unless all of the conditions specified within it
+      # are true.  Any restrictions created inside the given block are AND'ed together
+      # in the final query and the result is negated. The block can contain any number of joins, 
+      # restrictions, or other conjunctions.
+      #   Blog.filter do
+      #     none_of do
+      #       with(:created_at, nil)
+      #       with(:created_at).greater_than(3.days.ago)
+      #     end
+      #   end
+      #
+      #   # :conditions => { ['NOT (blogs.created_at IS NULL AND blogs.created_at > ?)', 3.days.ago] }
+      #
+      # ==== Parameters
+      # block<Proc>::
+      #   The block can contain any sequence of calls, and the conditions that it contains will be
+      #   AND'ed together and then negated to create a where clause.
+      #
+      # ==== Returns
+      # nil
+      #
+      # @public
       def not_all_of(&block)
         @conjunction.add_conjunction(:not_all_of, &block)
         nil
       end
 
-      # join
-      def having(join_type_or_association, association=nil, &block)
+      # Create an implicit join using an association as the target. This method allows you to
+      # easily specify a join without specifying the columns to use by taking any needed data
+      # from the specified ActiveRecord association. If given, the block will be evaluated in
+      # the context of the table that has been joined, so any restrictions or other joins will
+      # be performed using its columns and associations. For example, if a Post has_many comments
+      # then the following code will join to the comments table and restrict the comments based
+      # on their created_at field:
+      #   Post.filter do
+      #     having(:comments) do
+      #       with(:created_at).greater_than(3.days.ago)
+      #     end
+      #   end
+      # If one argument is given, it is assumed to be a symbol representing the name of the association
+      # that will be used for the join and a join type of :inner will be used. If two arguments are 
+      # provided, the first one is assumed to be the join type, which can be one of :inner, :left or 
+      # :right and the second one is the association name. An alias will automatically be created
+      # for the joined table named "#{left_table}__#{association_name}", so in the above example, the
+      # alias would be posts__comments.
+      #
+      # ==== Parameters
+      # join_type<Symbol>::
+      #   Specifies the type of join to perform, and can be one of :inner, :left or :right. :left
+      #   and :right will create left and right outer joins, respectively.
+      # association<Symbol>::
+      #   The name of the association to use as a base for the join.
+      #
+      # ==== Returns
+      # ConjunctionDSL::
+      #   A DSL object is returned in order to allow constructs like: having(:comments).with(:offensive, true)
+      #
+      # ==== Alternatives
+      # If only one argument is given, the join type will default to :inner and the first argument will
+      # be used as the association name.
+      #
+      # @public
+      def having(join_type, association=nil, &block)
         if association.nil?
-          association, join_type = join_type_or_association, nil
-        else
-          join_type = join_type_or_association
+          association, join_type = join_type, nil
         end
         @conjunction.add_join(association, join_type, &block)
       end
 
+      # Create an explicit join on the table of the given class. This method allows more complex
+      # joins to be speficied than can be created using having, including jump joins and ones that
+      # include conditions on column values. The method accepts a block that can contain any sequence
+      # of conjunctions, restrictions, or other joins, but it must also contain at least one call to
+      # JoinDSL.on to specify the conditions for the join.
+      #
+      # ==== Parameters
+      # clazz<Class>::
+      #   The class that is being joined to.
+      # join_type<Symbol>::
+      #   Indicates the type of join to use and must be one of :inner, :left or :right, where :left
+      #   or :right will create a LEFT or RIGHT OUTER join respectively.
+      # table_alias<String, optional>::
+      #   If provided, will specify an alias to use in the SQL when referring to the joined table.
+      #   If the argument is not given, the alias will be "#{left_table}__#{clazz.name}"
+      # block<Proc>
+      #   The contents of the join block can contain any sequence of conjunctions, restrictions, or joins.
+      #
+      # ==== Returns
+      # JoinDSL::
+      #   A DSL object that can be used to specify the contents of the join. Returning this value allows
+      #   for constructions like: join(Comment, :inner).on(:id => :post_id)
+      #
+      # @public
       def join(clazz, join_type, table_alias=nil, &block)
         @conjunction.add_class_join(clazz, join_type, table_alias, &block)
       end
 
+      # Access the class that the current filter is being applied to. This is necessary
+      # because the filter is evaluated in the context of the DSL object, so self will
+      # not give access to any methods that need to be called on the filtered class.
+      # It is especially useful in named filters that may be defined in a way that allows
+      # them to apply to multiple classes.
+      #
+      # ==== Returns
+      # Class::
+      #   The class that is currently being filtered.
+      #
+      # @public
       def filter_class
         @model_class
       end
+      
+      # Enable calling of named filters from within other filters by catching unknown calls
+      # and assuming that they are to named filters. This enables the following examples:
+      #   class Post < ActiveRecord::Base
+      #     has_many :comments
+      #     named_filter(:empty) { with(:contents).nil }
+      #   end
+      #
+      #   class Comment < ActiveRecord::Base
+      #     belongs_to :post
+      #     named_filter(:offensive) { |value| with(:offensive, value) }
+      #   end
+      #
+      #   Post.filter do
+      #     with(:created_at).less_than(1.hour.ago)
+      #     empty
+      #   end
+      #
+      #   # Results in:
+      #   # :conditions => { ['posts.created_at < ? AND posts.contents IS NULL', 1.hour.ago] }
+      #   # And even cooler:
+      #
+      #   Post.filter do
+      #     having(:comments).offensive(true)
+      #   end
+      #
+      #   # Results in:
+      #   # :conditions => { ['posts__comments.offensive = ?', true] }
+      #   # :joins => { 'INNER JOIN "comments" AS posts__comments ON "posts".id = posts__comments.post_id' }
+      #
+      # ==== Parameters
+      # args<Array>::
+      #   The arguments to pass to the named filter when called.
+      #
+      # @public
+      def method_missing(method, *args)
+        @conjunction.add_named_filter(method, *args)
+      end
 
-      def limit(offset_or_limit, limit=nil)
+      #
+      # Define these_methods here just so that we can throw exceptions when they are called. They should not
+      # be callable in the scope of a conjunction_dsl.
+      #
+      def limit(offset_or_limit, limit=nil) # :nodoc:
         raise InvalidFilterException.new('Calls to limit can only be made in the outer block of a filter.')
       end
 
-      def order(column, direction=:asc)
+      def order(column, direction=:asc) # :nodoc:
         raise InvalidFilterException.new('Calls to order can only be made in the outer block of a filter.')
       end
 
-      def group_by(column)
+      def group_by(column) # :nodoc:
         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)
+      def on(column, value=Restriction::DEFAULT_VALUE) # :nodoc:
         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