module ActiveRecord module NamedScope # All subclasses of ActiveRecord::Base have two named_scopes: # * all, which is similar to a find(:all) query, and # * scoped, which allows for the creation of anonymous scopes, on the fly: Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions) # # These anonymous scopes tend to be useful when procedurally generating complex queries, where passing # intermediate values (scopes) around as first-class objects is convenient. def self.included(base) base.class_eval do extend ClassMethods named_scope :scoped, lambda { |scope| scope } end end module ClassMethods def scopes read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {}) end # Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query, # such as :conditions => {:color => :red}, :select => 'shirts.*', :include => :washing_instructions. # # class Shirt < ActiveRecord::Base # named_scope :red, :conditions => {:color => 'red'} # named_scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true] # end # # The above calls to named_scope define class methods Shirt.red and Shirt.dry_clean_only. Shirt.red, # in effect, represents the query Shirt.find(:all, :conditions => {:color => 'red'}). # # Unlike Shirt.find(...), however, the object returned by Shirt.red is not an Array; it resembles the association object # constructed by a has_many declaration. For instance, you can invoke Shirt.red.find(:first), Shirt.red.count, # Shirt.red.find(:all, :conditions => {:size => 'small'}). Also, just # as with the association objects, name scopes acts like an Array, implementing Enumerable; Shirt.red.each(&block), # Shirt.red.first, and Shirt.red.inject(memo, &block) all behave as if Shirt.red really were an Array. # # These named scopes are composable. For instance, Shirt.red.dry_clean_only will produce all shirts that are both red and dry clean only. # Nested finds and calculations also work with these compositions: Shirt.red.dry_clean_only.count returns the number of garments # for which these criteria obtain. Similarly with Shirt.red.dry_clean_only.average(:thread_count). # # All scopes are available as class methods on the ActiveRecord::Base descendent upon which the scopes were defined. But they are also available to # has_many associations. If, # # class Person < ActiveRecord::Base # has_many :shirts # end # # then elton.shirts.red.dry_clean_only will return all of Elton's red, dry clean # only shirts. # # Named scopes can also be procedural. # # class Shirt < ActiveRecord::Base # named_scope :colored, lambda { |color| # { :conditions => { :color => color } } # } # end # # In this example, Shirt.colored('puce') finds all puce shirts. # # Named scopes can also have extensions, just as with has_many declarations: # # class Shirt < ActiveRecord::Base # named_scope :red, :conditions => {:color => 'red'} do # def dom_id # 'red_shirts' # end # end # end # # # For testing complex named scopes, you can examine the scoping options using the # proxy_options method on the proxy itself. # # class Shirt < ActiveRecord::Base # named_scope :colored, lambda { |color| # { :conditions => { :color => color } } # } # end # # expected_options = { :conditions => { :colored => 'red' } } # assert_equal expected_options, Shirt.colored('red').proxy_options def named_scope(name, options = {}, &block) scopes[name] = lambda do |parent_scope, *args| Scope.new(parent_scope, case options when Hash options when Proc options.call(*args) end, &block) end (class << self; self end).instance_eval do define_method name do |*args| scopes[name].call(self, *args) end end end end class Scope attr_reader :proxy_scope, :proxy_options [].methods.each do |m| unless m =~ /(^__|^nil\?|^send|^object_id$|class|extend|find|count|sum|average|maximum|minimum|paginate|first|last|empty?)/ delegate m, :to => :proxy_found end end delegate :scopes, :with_scope, :to => :proxy_scope def initialize(proxy_scope, options, &block) [options[:extend]].flatten.each { |extension| extend extension } if options[:extend] extend Module.new(&block) if block_given? @proxy_scope, @proxy_options = proxy_scope, options.except(:extend) end def reload load_found; self end def first(*args) if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash)) proxy_found.first(*args) else find(:first, *args) end end def last(*args) if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash)) proxy_found.last(*args) else find(:last, *args) end end def empty? @found ? @found.empty? : count.zero? end protected def proxy_found @found || load_found end private def method_missing(method, *args, &block) if scopes.include?(method) scopes[method].call(self, *args) else with_scope :find => proxy_options do proxy_scope.send(method, *args, &block) end end end def load_found @found = find(:all) end end end end