2008-05-18 06:22:34 +02:00
module ActiveRecord
module NamedScope
2009-02-28 02:23:00 +01:00
# All subclasses of ActiveRecord::Base have one named scope:
2008-10-27 07:47:01 +01:00
# * <tt>scoped</tt> - which allows for the creation of anonymous \scopes, on the fly: <tt>Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)</tt>
2008-05-18 06:22:34 +02:00
#
2008-10-27 07:47:01 +01:00
# These anonymous \scopes tend to be useful when procedurally generating complex queries, where passing
2008-05-18 06:22:34 +02:00
# intermediate values (scopes) around as first-class objects is convenient.
2009-02-28 02:23:00 +01:00
#
# You can define a scope that applies to all finders using ActiveRecord::Base.default_scope.
2008-05-18 06:22:34 +02:00
def self . included ( base )
2010-09-05 22:24:15 +02:00
base . extend ClassMethods
2008-05-18 06:22:34 +02:00
end
module ClassMethods
def scopes
read_inheritable_attribute ( :scopes ) || write_inheritable_attribute ( :scopes , { } )
end
2010-09-05 22:24:15 +02:00
def scoped ( scope , & block )
Scope . new ( self , scope , & block )
end
2008-05-18 06:22:34 +02:00
# Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query,
# such as <tt>:conditions => {:color => :red}, :select => 'shirts.*', :include => :washing_instructions</tt>.
#
# 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
#
2008-10-27 07:47:01 +01:00
# The above calls to <tt>named_scope</tt> define class methods Shirt.red and Shirt.dry_clean_only. Shirt.red,
2008-05-18 06:22:34 +02:00
# in effect, represents the query <tt>Shirt.find(:all, :conditions => {:color => 'red'})</tt>.
#
2008-10-27 07:47:01 +01:00
# Unlike <tt>Shirt.find(...)</tt>, however, the object returned by Shirt.red is not an Array; it resembles the association object
2008-05-18 06:22:34 +02:00
# constructed by a <tt>has_many</tt> declaration. For instance, you can invoke <tt>Shirt.red.find(:first)</tt>, <tt>Shirt.red.count</tt>,
# <tt>Shirt.red.find(:all, :conditions => {:size => 'small'})</tt>. Also, just
2008-10-27 07:47:01 +01:00
# as with the association objects, named \scopes act like an Array, implementing Enumerable; <tt>Shirt.red.each(&block)</tt>,
# <tt>Shirt.red.first</tt>, and <tt>Shirt.red.inject(memo, &block)</tt> all behave as if Shirt.red really was an Array.
2008-05-18 06:22:34 +02:00
#
2008-10-27 07:47:01 +01:00
# 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.
2008-05-18 06:22:34 +02:00
# Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments
# for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>.
#
2009-02-04 21:26:08 +01:00
# All \scopes are available as class methods on the ActiveRecord::Base descendant upon which the \scopes were defined. But they are also available to
2008-05-18 06:22:34 +02:00
# <tt>has_many</tt> associations. If,
#
# class Person < ActiveRecord::Base
# has_many :shirts
# end
#
# then <tt>elton.shirts.red.dry_clean_only</tt> will return all of Elton's red, dry clean
# only shirts.
#
2008-10-27 07:47:01 +01:00
# Named \scopes can also be procedural:
2008-05-18 06:22:34 +02:00
#
# class Shirt < ActiveRecord::Base
# named_scope :colored, lambda { |color|
# { :conditions => { :color => color } }
# }
# end
#
# In this example, <tt>Shirt.colored('puce')</tt> finds all puce shirts.
#
2008-10-27 07:47:01 +01:00
# Named \scopes can also have extensions, just as with <tt>has_many</tt> declarations:
2008-05-18 06:22:34 +02:00
#
# class Shirt < ActiveRecord::Base
# named_scope :red, :conditions => {:color => 'red'} do
# def dom_id
# 'red_shirts'
# end
# end
# end
#
#
2008-10-27 07:47:01 +01:00
# For testing complex named \scopes, you can examine the scoping options using the
2008-05-18 06:22:34 +02:00
# <tt>proxy_options</tt> 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 )
2008-09-07 07:54:05 +02:00
name = name . to_sym
2010-09-05 22:24:15 +02:00
2008-05-18 06:22:34 +02:00
scopes [ name ] = lambda do | parent_scope , * args |
Scope . new ( parent_scope , case options
when Hash
options
when Proc
2010-09-05 22:24:15 +02:00
if self . model_name != parent_scope . model_name
options . bind ( parent_scope ) . call ( * args )
else
options . call ( * args )
end
2008-05-18 06:22:34 +02:00
end , & block )
end
2010-09-05 22:24:15 +02:00
singleton_class . send :define_method , name do | * args |
scopes [ name ] . call ( self , * args )
2008-05-18 06:22:34 +02:00
end
end
end
2009-03-16 15:55:30 +01:00
2008-05-18 06:22:34 +02:00
class Scope
2009-02-28 02:23:00 +01:00
attr_reader :proxy_scope , :proxy_options , :current_scoped_methods_when_defined
2008-10-27 07:47:01 +01:00
NON_DELEGATE_METHODS = %w( nil? send object_id class extend find size count sum average maximum minimum paginate first last empty? any? respond_to? ) . to_set
2008-06-02 08:35:38 +02:00
[ ] . methods . each do | m |
2008-10-27 07:47:01 +01:00
unless m =~ / ^__ / || NON_DELEGATE_METHODS . include? ( m . to_s )
2008-06-02 08:35:38 +02:00
delegate m , :to = > :proxy_found
end
end
2009-08-04 17:16:03 +02:00
delegate :scopes , :with_scope , :scoped_methods , :to = > :proxy_scope
2008-05-18 06:22:34 +02:00
def initialize ( proxy_scope , options , & block )
2009-03-16 15:55:30 +01:00
options || = { }
2008-05-18 06:22:34 +02:00
[ options [ :extend ] ] . flatten . each { | extension | extend extension } if options [ :extend ]
extend Module . new ( & block ) if block_given?
2009-02-28 02:23:00 +01:00
unless Scope === proxy_scope
@current_scoped_methods_when_defined = proxy_scope . send ( :current_scoped_methods )
end
2008-05-18 06:22:34 +02:00
@proxy_scope , @proxy_options = proxy_scope , options . except ( :extend )
end
def reload
load_found ; self
end
2008-06-02 08:35:38 +02:00
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
2008-10-27 07:47:01 +01:00
def size
@found ? @found . length : count
end
2008-06-02 08:35:38 +02:00
def empty?
@found ? @found . empty? : count . zero?
end
2008-09-07 07:54:05 +02:00
def respond_to? ( method , include_private = false )
super || @proxy_scope . respond_to? ( method , include_private )
end
2008-10-27 07:47:01 +01:00
def any?
if block_given?
proxy_found . any? { | * block_args | yield ( * block_args ) }
else
! empty?
end
end
2008-05-18 06:22:34 +02:00
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
2009-03-16 15:55:30 +01:00
with_scope ( { :find = > proxy_options , :create = > proxy_options [ :conditions ] . is_a? ( Hash ) ? proxy_options [ :conditions ] : { } } , :reverse_merge ) do
2008-10-27 07:47:01 +01:00
method = :new if method == :build
2009-08-04 17:16:03 +02:00
if current_scoped_methods_when_defined && ! scoped_methods . include? ( current_scoped_methods_when_defined )
2009-02-28 02:23:00 +01:00
with_scope current_scoped_methods_when_defined do
proxy_scope . send ( method , * args , & block )
end
else
proxy_scope . send ( method , * args , & block )
end
2008-05-18 06:22:34 +02:00
end
end
end
def load_found
@found = find ( :all )
end
end
end
2008-06-02 08:35:38 +02:00
end