модуль ActiveRecord::Scoping::Named::ClassMethods

Возвращает объект области видимости ActiveRecord::Relation.

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?

Вы можете определить область видимости, которая применяется ко всем нахождениям, используя ActiveRecord::Base.default_scope.

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

Добавляет метод класса для извлечения и запроса объектов. Область видимости представляет собой сужение запроса к базе данных, например, 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

Вышеупомянутые вызовы scope определяют методы класса Shirt.red и Shirt.dry_clean_only. Shirt.red, по сути, представляет запрос Shirt.where(color: 'red').

Вы всегда должны передавать вызываемый объект в области видимости, определенные с помощью scope. Это гарантирует, что область видимости переоценивается каждый раз, когда она вызывается.

Обратите внимание, что это просто «синтаксический сахар» для определения фактического метода класса:

class Shirt < ActiveRecord::Base
  def self.red
    where(color: 'red')
  end
end

В отличие от Shirt.find(...), однако, объект, возвращаемый Shirt.red, не является массивом; он похож на объект ассоциации, созданный объявлением has_many. Например, вы можете вызвать Shirt.red.first, Shirt.red.count, Shirt.red.where(size: 'small'). Также, как и с объектами ассоциации, именованные области видимости ведут себя как массив, реализуя Enumerable; Shirt.red.each(&block), Shirt.red.first, и Shirt.red.inject(memo, &block) все ведут себя так, как будто Shirt.red на самом деле был массивом.

Эти именованные области видимости являются композиционными. Например, Shirt.red.dry_clean_only вернёт все красные рубашки, которые нужно только химчистить. Вложенные поиска и вычисления также работают с этими композициями: Shirt.red.dry_clean_only.count возвращает количество предметов одежды, для которых соблюдаются эти критерии. Аналогично с Shirt.red.dry_clean_only.average(:thread_count).

Все области видимости доступны как методы класса в потомке ActiveRecord::Base, в котором были определены области видимости. Но они также доступны для ассоциаций has_many. Если,

class Person < ActiveRecord::Base
  has_many :shirts
end

то elton.shirts.red.dry_clean_only вернёт все красные рубашки Элтона, которые нужно только химчистить.

Именованные области видимости также могут иметь расширения, как и с объявлениями has_many:

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

Области видимости также могут использоваться при создании/создании записи.

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

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

Методы класса в вашей модели автоматически доступны в областях видимости. Предполагая следующее конфигурацию:

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

Мы можем вызвать методы так:

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

# File activerecord/lib/active_record/scoping/named.rb, line 141
def scope(name, body, &block)
  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

  extension = Module.new(&block) if block

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

    scope || all
  end
end