3 # All subclasses of ActiveRecord::Base have one named scope:
4 # * <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>
6 # These anonymous \scopes tend to be useful when procedurally generating complex queries, where passing
7 # intermediate values (scopes) around as first-class objects is convenient.
9 # You can define a scope that applies to all finders using ActiveRecord::Base.default_scope.
10 def self.included(base
)
13 named_scope
:scoped, lambda
{ |scope
| scope
}
19 read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {})
22 # Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query,
23 # such as <tt>:conditions => {:color => :red}, :select => 'shirts.*', :include => :washing_instructions</tt>.
25 # class Shirt < ActiveRecord::Base
26 # named_scope :red, :conditions => {:color => 'red'}
27 # named_scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true]
30 # The above calls to <tt>named_scope</tt> define class methods Shirt.red and Shirt.dry_clean_only. Shirt.red,
31 # in effect, represents the query <tt>Shirt.find(:all, :conditions => {:color => 'red'})</tt>.
33 # Unlike <tt>Shirt.find(...)</tt>, however, the object returned by Shirt.red is not an Array; it resembles the association object
34 # constructed by a <tt>has_many</tt> declaration. For instance, you can invoke <tt>Shirt.red.find(:first)</tt>, <tt>Shirt.red.count</tt>,
35 # <tt>Shirt.red.find(:all, :conditions => {:size => 'small'})</tt>. Also, just
36 # as with the association objects, named \scopes act like an Array, implementing Enumerable; <tt>Shirt.red.each(&block)</tt>,
37 # <tt>Shirt.red.first</tt>, and <tt>Shirt.red.inject(memo, &block)</tt> all behave as if Shirt.red really was an Array.
39 # 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.
40 # Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments
41 # for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>.
43 # All \scopes are available as class methods on the ActiveRecord::Base descendant upon which the \scopes were defined. But they are also available to
44 # <tt>has_many</tt> associations. If,
46 # class Person < ActiveRecord::Base
50 # then <tt>elton.shirts.red.dry_clean_only</tt> will return all of Elton's red, dry clean
53 # Named \scopes can also be procedural:
55 # class Shirt < ActiveRecord::Base
56 # named_scope :colored, lambda { |color|
57 # { :conditions => { :color => color } }
61 # In this example, <tt>Shirt.colored('puce')</tt> finds all puce shirts.
63 # Named \scopes can also have extensions, just as with <tt>has_many</tt> declarations:
65 # class Shirt < ActiveRecord::Base
66 # named_scope :red, :conditions => {:color => 'red'} do
74 # For testing complex named \scopes, you can examine the scoping options using the
75 # <tt>proxy_options</tt> method on the proxy itself.
77 # class Shirt < ActiveRecord::Base
78 # named_scope :colored, lambda { |color|
79 # { :conditions => { :color => color } }
83 # expected_options = { :conditions => { :colored => 'red' } }
84 # assert_equal expected_options, Shirt.colored('red').proxy_options
85 def named_scope(name
, options
= {}, &block
)
87 scopes
[name
] = lambda
do |parent_scope
, *args
|
88 Scope
.new(parent_scope
, case options
94 with_scope(:find => parent_scope
.proxy_options
) { options
.call(*args
) }
100 (class << self; self end).instance_eval
do
101 define_method name
do |*args
|
102 scopes
[name
].call(self, *args
)
109 attr_reader
:proxy_scope, :proxy_options, :current_scoped_methods_when_defined
110 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
111 [].methods
.each
do |m
|
112 unless m
=~
/^__/ || NON_DELEGATE_METHODS
.include?(m
.to_s
)
113 delegate m
, :to => :proxy_found
117 delegate
:scopes, :with_scope, :to => :proxy_scope
119 def initialize(proxy_scope
, options
, &block
)
121 [options
[:extend]].flatten
.each
{ |extension
| extend extension
} if options
[:extend]
122 extend Module
.new(&block
) if block_given
?
123 unless Scope
=== proxy_scope
124 @current_scoped_methods_when_defined = proxy_scope
.send(:current_scoped_methods)
126 @proxy_scope, @proxy_options = proxy_scope
, options
.except(:extend)
134 if args
.first
.kind_of
?(Integer
) || (@found && !args
.first
.kind_of
?(Hash
))
135 proxy_found
.first(*args
)
142 if args
.first
.kind_of
?(Integer
) || (@found && !args
.first
.kind_of
?(Hash
))
143 proxy_found
.last(*args
)
150 @found ? @found.length
: count
154 @found ? @found.empty
? : count
.zero
?
157 def respond_to
?(method
, include_private
= false)
158 super || @proxy_scope.respond_to
?(method
, include_private
)
163 proxy_found
.any
? { |*block_args
| yield(*block_args
) }
175 def method_missing(method
, *args
, &block
)
176 if scopes
.include?(method
)
177 scopes
[method
].call(self, *args
)
179 with_scope({:find => proxy_options
, :create => proxy_options
[:conditions].is_a
?(Hash
) ? proxy_options
[:conditions] : {}}, :reverse_merge) do
180 method
= :new if method
== :build
181 if current_scoped_methods_when_defined
182 with_scope current_scoped_methods_when_defined
do
183 proxy_scope
.send(method
, *args
, &block
)
186 proxy_scope
.send(method
, *args
, &block
)