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