From 6dec7535fd26b8abea0211313ef2936d28ed1637 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 21 Sep 2012 23:25:52 -0500 Subject: update AR::Scoping documentation [ci skip] --- activerecord/lib/active_record/scoping/default.rb | 55 ++++++----- activerecord/lib/active_record/scoping/named.rb | 113 +++++++++------------- 2 files changed, 77 insertions(+), 91 deletions(-) diff --git a/activerecord/lib/active_record/scoping/default.rb b/activerecord/lib/active_record/scoping/default.rb index a2a85d4b96..6835d0e01b 100644 --- a/activerecord/lib/active_record/scoping/default.rb +++ b/activerecord/lib/active_record/scoping/default.rb @@ -5,17 +5,17 @@ module ActiveRecord extend ActiveSupport::Concern included do - # Stores the default scope for the class + # Stores the default scope for the class. class_attribute :default_scopes, instance_writer: false self.default_scopes = [] end module ClassMethods - # Returns a scope for the model without the default_scope. + # Returns a scope for the model without the +default_scope+. # # class Post < ActiveRecord::Base # def self.default_scope - # where :published => true + # where published: true # end # end # @@ -23,16 +23,16 @@ module ActiveRecord # Post.unscoped.all # Fires "SELECT * FROM posts" # # This method also accepts a block. All queries inside the block will - # not use the default_scope: + # not use the +default_scope+: # # Post.unscoped { # Post.limit(10) # Fires "SELECT * FROM posts LIMIT 10" # } # # It is recommended that you use the block form of unscoped because - # chaining unscoped with scope does not work. Assuming that - # published is a scope, the following two statements - # are equal: the default_scope is applied on both. + # chaining unscoped with +scope+ does not work. Assuming that + # +published+ is a +scope+, the following two statements + # are equal: the +default_scope+ is applied on both. # # Post.unscoped.published # Post.published @@ -50,35 +50,37 @@ module ActiveRecord # the model. # # class Article < ActiveRecord::Base - # default_scope { where(:published => true) } + # default_scope { where(published: true) } # end # # Article.all # => SELECT * FROM articles WHERE published = true # - # The default_scope is also applied while creating/building a record. It is not - # applied while updating a record. + # The +default_scope+ is also applied while creating/building a record. + # It is not applied while updating a record. # # Article.new.published # => true # Article.create.published # => true # - # (You can also pass any object which responds to call to the default_scope - # macro, and it will be called when building the default scope.) + # (You can also pass any object which responds to +call+ to the + # +default_scope+ macro, and it will be called when building the + # default scope.) # - # If you use multiple default_scope declarations in your model then they will - # be merged together: + # If you use multiple +default_scope+ declarations in your model then + # they will be merged together: # # class Article < ActiveRecord::Base - # default_scope { where(:published => true) } - # default_scope { where(:rating => 'G') } + # default_scope { where(published: true) } + # default_scope { where(rating: 'G') } # end # # Article.all # => SELECT * FROM articles WHERE published = true AND rating = 'G' # - # This is also the case with inheritance and module includes where the parent or module - # defines a default_scope and the child or including class defines a second one. + # This is also the case with inheritance and module includes where the + # parent or module defines a +default_scope+ and the child or including + # class defines a second one. # - # If you need to do more complex things with a default scope, you can alternatively - # define it as a class method: + # If you need to do more complex things with a default scope, you can + # alternatively define it as a class method: # # class Article < ActiveRecord::Base # def self.default_scope @@ -100,7 +102,7 @@ module ActiveRecord self.default_scopes = default_scopes + [scope] end - def build_default_scope #:nodoc: + def build_default_scope # :nodoc: if !Base.is_a?(method(:default_scope).owner) # The user has defined their own default scope method, so call that evaluate_default_scope { default_scope } @@ -117,17 +119,18 @@ module ActiveRecord end end - def ignore_default_scope? #:nodoc: + def ignore_default_scope? # :nodoc: Thread.current["#{self}_ignore_default_scope"] end - def ignore_default_scope=(ignore) #:nodoc: + def ignore_default_scope=(ignore) # :nodoc: Thread.current["#{self}_ignore_default_scope"] = ignore end - # The ignore_default_scope flag is used to prevent an infinite recursion situation where - # a default scope references a scope which has a default scope which references a scope... - def evaluate_default_scope + # The ignore_default_scope flag is used to prevent an infinite recursion + # situation where a default scope references a scope which has a default + # scope which references a scope... + def evaluate_default_scope # :nodoc: return if ignore_default_scope? begin diff --git a/activerecord/lib/active_record/scoping/named.rb b/activerecord/lib/active_record/scoping/named.rb index 75f31229b5..fb5f5b5be0 100644 --- a/activerecord/lib/active_record/scoping/named.rb +++ b/activerecord/lib/active_record/scoping/named.rb @@ -3,7 +3,7 @@ require 'active_support/core_ext/hash/except' require 'active_support/core_ext/kernel/singleton_class' module ActiveRecord - # = Active Record Named \Scopes + # = Active Record \Named \Scopes module Scoping module Named extend ActiveSupport::Concern @@ -16,11 +16,11 @@ module ActiveRecord # posts.each {|p| puts p.name } # Fires "select * from posts" and loads post objects # # fruits = Fruit.all - # fruits = fruits.where(:color => 'red') if options[:red_only] + # fruits = fruits.where(color: 'red') if options[:red_only] # fruits = fruits.limit(10) if limited? # - # You can define a \scope that applies to all finders using - # ActiveRecord::Base.default_scope. + # You can define a scope that applies to all finders using + # ActiveRecord::Base.default_scope. def all if current_scope current_scope.clone @@ -31,7 +31,6 @@ module ActiveRecord end end - ## # Collects attributes from scopes that should be applied when creating # an AR instance for the particular class this is called on. def scope_attributes # :nodoc: @@ -44,86 +43,70 @@ module ActiveRecord end end - ## # Are there default attributes associated with this scope? def scope_attributes? # :nodoc: current_scope || default_scopes.any? end - # Adds a class method for retrieving and querying objects. A \scope represents a narrowing of a database query, - # such as where(:color => :red).select('shirts.*').includes(:washing_instructions). + # Adds a class method for retrieving and querying objects. A \scope + # represents a narrowing of a database query, such as + # where(color: :red).select('shirts.*').includes(:washing_instructions). # # class Shirt < ActiveRecord::Base - # scope :red, where(:color => 'red') - # scope :dry_clean_only, joins(:washing_instructions).where('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.where(:color => 'red'). + # The above calls to +scope+ define class methods Shirt.red and + # Shirt.dry_clean_only. Shirt.red, in effect, + # represents the query Shirt.where(color: 'red'). # - # Note that this is simply 'syntactic sugar' for defining an actual class method: + # You should always pass a callable object to the scopes defined + # with +scope+. This ensures that the scope is re-evaluated each + # time it is called. + # + # Note that this is simply 'syntactic sugar' for defining an actual + # class method: # # class Shirt < ActiveRecord::Base # def self.red - # where(:color => 'red') + # where(color: 'red') # end # end # - # 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.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 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 descendant upon which - # the \scopes were defined. But they are also available to has_many associations. If, + # 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.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 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 + # descendant 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 - # scope :colored, lambda { |color| where(:color => color) } - # end - # - # In this example, Shirt.colored('puce') finds all puce shirts. - # - # On Ruby 1.9 you can use the 'stabby lambda' syntax: - # - # scope :colored, ->(color) { where(:color => color) } - # - # Note that scopes defined with \scope will be evaluated when they are defined, rather than - # when they are used. For example, the following would be incorrect: - # - # class Post < ActiveRecord::Base - # scope :recent, where('published_at >= ?', Time.current - 1.week) - # end - # - # The example above would be 'frozen' to the Time.current value when the Post - # class was defined, and so the resultant SQL query would always be the same. The correct - # way to do this would be via a lambda, which will re-evaluate the scope each time - # it is called: - # - # class Post < ActiveRecord::Base - # scope :recent, lambda { where('published_at >= ?', Time.current - 1.week) } - # end + # then elton.shirts.red.dry_clean_only will return all of + # Elton's red, dry clean only shirts. # - # Named \scopes can also have extensions, just as with has_many declarations: + # \Named scopes can also have extensions, just as with +has_many+ + # declarations: # # class Shirt < ActiveRecord::Base - # scope :red, where(:color => 'red') do + # scope :red, -> { where(color: 'red') } do # def dom_id # 'red_shirts' # end @@ -133,18 +116,18 @@ module ActiveRecord # Scopes can also be used while creating/building a record. # # class Article < ActiveRecord::Base - # scope :published, where(:published => true) + # scope :published, -> { where(published: true) } # end # # Article.published.new.published # => true # Article.published.create.published # => true # - # Class methods on your model are automatically available + # \Class methods on your model are automatically available # on scopes. Assuming the following setup: # # class Article < ActiveRecord::Base - # scope :published, where(:published => true) - # scope :featured, where(:featured => true) + # scope :published, -> { where(published: true) } + # scope :featured, -> { where(featured: true) } # # def self.latest_article # order('published_at desc').first -- cgit v1.2.3