From c6372d604952a8eef16ce73a06814aa143b94779 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 3 Apr 2010 01:49:01 +0100 Subject: Improve scope docs --- activerecord/lib/active_record/named_scope.rb | 44 +++++++++------------------ 1 file changed, 14 insertions(+), 30 deletions(-) diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index 50c57783b2..632322b517 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -8,16 +8,15 @@ module ActiveRecord extend ActiveSupport::Concern module ClassMethods - # Returns a relation if invoked without any arguments. + # Returns an anonymous scope. # # posts = Post.scoped # posts.size # Fires "select count(*) from posts" and returns the count # posts.each {|p| puts p.name } # Fires "select * from posts" and loads post objects # - # Returns an anonymous named scope if any options are supplied. - # - # shirts = Shirt.scoped(:conditions => {:color => 'red'}) - # shirts = shirts.scoped(:include => :washing_instructions) + # fruits = Fruit.scoped + # fruits = fruits.where(:colour => 'red') if options[:red_only] + # fruits = fruits.limit(10) if limited? # # Anonymous \scopes tend to be useful when procedurally generating complex queries, where passing # intermediate values (scopes) around as first-class objects is convenient. @@ -37,21 +36,21 @@ module ActiveRecord 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. + # such as where(:color => :red).select('shirts.*').includes(:washing_instructions). # # class Shirt < ActiveRecord::Base - # scope :red, :conditions => {:color => 'red'} - # scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true] + # scope :red, where(:color => 'red') + # scope :dry_clean_only, joins(:washing_instructions).where('washing_instructions.dry_clean_only = ?', true) # end # # The above calls to scope define class methods Shirt.red and Shirt.dry_clean_only. Shirt.red, - # in effect, represents the query Shirt.find(:all, :conditions => {:color => 'red'}). + # in effect, represents the query Shirt.where(: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, named \scopes act 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 was an Array. + # constructed by a has_many declaration. For instance, you can invoke Shirt.red.first, Shirt.red.count, + # Shirt.red.where(:size => 'small'). Also, just as with the association objects, named \scopes act 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 was 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 @@ -70,9 +69,7 @@ module ActiveRecord # Named \scopes can also be procedural: # # class Shirt < ActiveRecord::Base - # scope :colored, lambda { |color| - # { :conditions => { :color => color } } - # } + # scope :colored, lambda {|color| where(:color => color) } # end # # In this example, Shirt.colored('puce') finds all puce shirts. @@ -80,25 +77,12 @@ module ActiveRecord # Named \scopes can also have extensions, just as with has_many declarations: # # class Shirt < ActiveRecord::Base - # scope :red, :conditions => {:color => 'red'} do + # scope :red, where(: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 - # scope :colored, lambda { |color| - # { :conditions => { :color => color } } - # } - # end - # - # expected_options = { :conditions => { :colored => 'red' } } - # assert_equal expected_options, Shirt.colored('red').proxy_options def scope(name, scope_options = {}, &block) name = name.to_sym -- cgit v1.2.3