# module ActiveRecord::Scoping::Named::ClassMethods

### Public Instance Methods

all() click to toggle source

Returns an ActiveRecord::Relation scope object.

    posts = Post.all
    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

    fruits = Fruit.all
    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 default_scope.

    # File lib/active_record/scoping/named.rb, line 24
    def all
      if current_scope
        current_scope.clone
      else
        default_scoped
      end
    end

scope(name, body, &block) click to toggle source

Adds a class method for retrieving and querying objects. The method is intended to return an ActiveRecord::Relation object, which is composable with other scopes. If it returns `nil` or `false`, an all scope is returned instead.

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) }
    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')`.

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')
      end
    end

Unlike `Shirt.find(...)`, however, the object returned by `Shirt.red` is not an Array but an ActiveRecord::Relation, which is composable with other scopes; 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 have extensions, just as with has_many declarations:

    class Shirt < ActiveRecord::Base
      scope :red, -> { where(color: 'red') } do
        def dom_id
          'red_shirts'
        end
      end
    end

Scopes can also be used while creating/building a record.

    class Article < ActiveRecord::Base
      scope :published, -> { where(published: true) }
    end

    Article.published.new.published    # => true
    Article.published.create.published # => true

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) }

      def self.latest_article
        order('published_at desc').first
      end

      def self.titles
        pluck(:title)
      end
    end

We are able to call the methods like this:

    Article.published.featured.latest_article
    Article.featured.titles

    # File lib/active_record/scoping/named.rb, line 155
    def scope(name, body, &block)
      unless body.respond_to?(:call)
        raise ArgumentError, "The scope body needs to be callable."
      end

      if dangerous_class_method?(name)
        raise ArgumentError, "You tried to define a scope named \"#{name}\" "                "on the model \"#{self.name}\", but Active Record already defined "                "a class method with the same name."
      end

      valid_scope_name?(name)
      extension = Module.new(&block) if block

      if body.respond_to?(:to_proc)
        singleton_class.send(:define_method, name) do |*args|
          scope = all.scoping { instance_exec(*args, &body) }
          scope = scope.extending(extension) if extension

          scope || all
        end
      else
        singleton_class.send(:define_method, name) do |*args|
          scope = all.scoping { body.call(*args) }
          scope = scope.extending(extension) if extension

          scope || all
        end
      end
    end

### Private Instance Methods

valid_scope_name?(name) click to toggle source

    # File lib/active_record/scoping/named.rb, line 188
    def valid_scope_name?(name)
      if respond_to?(name, true) && logger
        logger.warn "Creating scope :#{name}. "                  "Overwriting existing method #{self.name}.#{name}."
      end
    end