Расширения ядра Active Support

Active Support - это компонент Ruby on Rails, отвечающий за предоставление расширений и утилит для языка Ruby.

Он предлагает более ценные функции на уровне языка, нацеленные как на разработку приложений на Rails, так и на разработку самого Ruby on Rails.

После прочтения этого руководства, вы узнаете:

• Что такое расширения ядра.
• Как загрузить все расширения.
• Как подобрать только те расширения, которые вам нужны.
• Какие расширения предоставляет Active Support.

Как загрузить расширения ядра

Автономный Active Support

Для обеспечения минимального влияния, Active Support по умолчанию загружает минимальные зависимости. Он разбит на маленькие части, поэтому можно загружать лишь желаемые зависимости. Он также имеет некоторые точки входа, которые по соглашению загружают все относящиеся расширения за раз, или даже все.

Таким образом, после обычного require:

require "active_support"

будут загружены только расширения, требуемые для фреймворка Active Support.

Подбор определений

Этот пример показывает, как загрузить Hash#with_indifferent_access. Это расширение включает преобразование Hash в ActiveSupport::HashWithIndifferentAccess, который позволяет доступ с как строковыми, так и символьными ключами.

{ a: 1 }.with_indifferent_access["a"] # => 1

Для каждого отдельного метода, определенного как расширение ядра, в этом руководстве имеется заметка, сообщающая, где такой метод определяется. В случае с with_indifferent_access заметка гласит:

Это означает, что это можно затребовать следующим образом:

require "active_support"
require "active_support/core_ext/hash/indifferent_access"

Active Support был тщательно пересмотрен и теперь подхватывает только те файлы для загрузки, которые содержат строго необходимые зависимости, если такие имеются.

Загрузка сгруппированных расширений ядра

Следующий уровень - это просто загрузка всех расширений к Hash. Как правило, расширения к SomeClass доступны за раз при загрузке active_support/core_ext/some_class.

Таким образом, чтобы загрузить все расширения Hash (в том числе with_indifferent_access):

require "active_support"
require "active_support/core_ext/hash"

Загрузка всех расширений ядра

Возможно, вы предпочтете загрузить все расширения ядра, вот файл для этого необходимо:

require "active_support"
require "active_support/core_ext"

Загрузка всего Active Support

И наконец, если необходимо получить доступ ко всему Active Support, просто выполните:

require "active_support/all"

В действительности это даже не поместит весь Active Support в память, так как некоторые вещи настроены через autoload, поэтому они загружаются только когда используются.

Active Support в приложении на Ruby on Rails

Приложение на Ruby on Rails загружает весь Active Support, кроме случая когда config.active_support.bare равен true. В этом случае приложение загрузит только сам фреймворк и подберет файлы для собственных нужд, и позволит подобрать вам файлы самостоятельно на любом уровне, как описано в предыдущем разделе.

Расширения ко всем объектам

blank? и present?

Следующие значения рассматриваются как пустые в Rails приложении:

• nil и false,
• строки, состоящие только из пробелов (смотрите примечание ниже),
• пустые массивы и хэши,
• и любые другие объекты, откликающиеся на empty? и являющиеся пустыми.

Например, этот метод из ActionController::HttpAuthentication::Token::ControllerMethods использует blank? для проверки, существует ли токен:

def authenticate(controller, &login_procedure)
  token, options = token_and_options(controller.request)
  unless token.blank?
    login_procedure.call(token, options)
  end
end

Метод present? является эквивалентом !blank?. Этот пример взят из ActionDispatch::Http::Cache::Response:

def set_conditional_cache_control!
  unless self["Cache-Control"].present?
    # ...
  end
end

presence

Метод presence возвращает его получателя, если present?, и nil в противном случае. Он полезен для подобных идиом:

host = config[:host].presence || "localhost"

duplicable?

В Ruby 2.5 большинство объектов могут дублироваться с помощью dup или clone:

"foo".dup           # => "foo"
"".dup              # => ""
Rational(1).dup     # => (1/1)
Complex(0).dup      # => (0+0i)
1.method(:+).dup    # => TypeError (allocator undefined for Method)

Active Support предоставляет duplicable? для запроса к объекту об этой возможности:

"foo".duplicable?        # => true
"".duplicable?           # => true
Rational(1).duplicable?  # => true
Complex(1).duplicable?   # => true
1.method(:+).duplicable? # => false

WARNING. Любой класс может запретить дублирование, убрав dup и clone, или вызвав исключение в них. Таким образом, только rescue может сказать, является ли данный произвольный объект дублируемым. duplicable? зависит от жестко заданного вышеуказанного перечня, но он намного быстрее, чем rescue. Используйте его только в том случае, если знаете, что жесткий перечень достаточен в конкретном случае.

deep_dup

Метод deep_dup возвращает "глубокую" копию данного объекта. Обычно при вызове dup на объекте, содержащем другие объекты, Ruby не вызывает dup для них, поэтому он создает "мелкую" копию объекта. Если, к примеру, имеется массив со строкой, это будет выглядеть так:

array     = ["string"]
duplicate = array.dup

duplicate.push "another-string"

# объект был дублирован, поэтому элемент был добавлен только в дубликат
array     # => ["string"]
duplicate # => ["string", "another-string"]

duplicate.first.gsub!("string", "foo")

# первый элемент не был дублирован, он будет изменен в обоих массивах
array     # => ["foo"]
duplicate # => ["foo, "another-string"]

Как видите, после дублирования экземпляра Array, мы получили еще один объект, следовательно мы можем его модифицировать, и исходный объект останется нетронутым. Однако, это не истинно для элементов массива. Поскольку dup не делает "глубокую" копию, строка внутри массива остается тем же самым объектом.

Если нужна "глубокая" копия объекта, следует использовать deep_dup. Вот пример:

array     = ["string"]
duplicate = array.deep_dup

duplicate.first.gsub!("string", "foo")

array     # => ["string"]
duplicate # => ["foo"]

Если объект нельзя дублировать, deep_dup просто возвратит его:

number = 1
duplicate = number.deep_dup
number.object_id == duplicate.object_id   # => true

try

Когда необходимо вызвать метод на объекте, но только в том случае, если он не nil, то простейшим способом достичь этого является условное выражение, добавляющее ненужный код. Альтернативой является использование try. try похож на Object#public_send за исключением того, что он возвращает nil, если вызван на nil.

Вот пример:

# без try
unless @number.nil?
  @number.next
end

# используя try
@number.try(:next)

Другим примером является этот код из ActiveRecord::ConnectionAdapters::AbstractAdapter, где @logger может быть nil. Код использует try и позволяет избегать ненужной проверки.

def log_info(sql, name, ms)
  if @logger.try(:debug?)
    name = "%s (%.1fms)" % [name || "SQL", ms]
    @logger.debug(format_log_entry(name, sql.squeeze(" ")))
  end
end

try также может быть вызван не с аргументами, а с блоком, который будет выполнен, если объект не nil:

@person.try { |p| "#{p.first_name} #{p.last_name}" }

Отметьте, что try поглотит ошибки об отсутствующем методе, возвратив вместо них nil. Если необходимо защититься от таких ошибок, используйте вместо него try!:

@number.try(:nest)  # => nil
@number.try!(:nest) # NoMethodError: undefined method `nest' for 1:Integer

class_eval(*args, &block)

Можно вычислить код в контексте синглтон-класса любого объекта, используя class_eval:

class Proc
  def bind(object)
    block, time = self, Time.current
    object.class_eval do
      method_name = "__bind_#{time.to_i}_#{time.usec}"
      define_method(method_name, &block)
      method = instance_method(method_name)
      remove_method(method_name)
      method
    end.bind(object)
  end
end

acts_like?(duck)

Метод acts_like? предоставляет возможность проверить, работает ли некий класс как некоторый другой класс, основываясь на простом соглашении: класс предоставляющий тот же интерфейс, как у String определяет

def acts_like_string?
end

являющийся всего лишь маркером, его содержимое или возвращаемое значение ничего не значит. Затем, код клиента может запросить "безопасную утиную типизацию" следующим образом:

some_klass.acts_like?(:string)

В Rails имеются классы, действующие как Date или Time и следующие этому соглашению.

to_param

Все объекты в Rails отвечают на метод to_param, который предназначен для возврата чего-то, что представляет их в строке запроса или как фрагменты URL.

По умолчанию to_param просто вызывает to_s:

7.to_param # => "7"

Возвращаемое значение to_param не должно быть экранировано:

"Tom & Jerry".to_param # => "Tom & Jerry"

Некоторые классы в Rails переопределяют этот метод.

Например, nil, true и false возвращают сами себя. Array#to_param вызывает to_param на элементах и соединяет результат с помощью "/":

[0, true, String].to_param # => "0/true/String"

В частности, система роутинга Rails вызывает to_param на моделях, чтобы получить значение для местозаполнителя :id. ActiveRecord::Base#to_param возвращает id модели, но можно переопределить этот метод в своих моделях. Например, задав

class User
  def to_param
    "#{id}-#{name.parameterize}"
  end
end

мы получим:

user_path(@user) # => "/users/357-john-smith"

WARNING. Контроллерам нужно быть в курсе любых переопределений to_param, поскольку в подобном запросе "357-john-smith" будет значением params[:id].

to_query

Метод to_query создает строку запроса, который связывает заданный key с возвращаемым значением to_param. Например, для следующего определения to_param:

class User
  def to_param
    "#{id}-#{name.parameterize}"
  end
end

мы получим:

current_user.to_query("user") # => "user=357-john-smith"

Этот метод экранирует все, что требуется: и ключ, и значение:

account.to_query("company[name]")
# => "company%5Bname%5D=Johnson+%26+Johnson"

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

Массивы возвращают результат применения to_query к каждому элементу с key[] в качестве ключа, и соединяет результат с помощью "&":

[3.4, -45.6].to_query("sample")
# => "sample%5B%5D=3.4&sample%5B%5D=-45.6"

Хэши также отвечают на to_query, но c другой сигнатурой. Если аргумент не передается, вызов генерирует отсортированную серию присваиваний ключ/значение, вызвав to_query(key) на этих значениях. Затем он соединяет результат с помощью "&":

{ c: 3, b: 2, a: 1 }.to_query # => "a=1&b=2&c=3"

Метод Hash#to_query принимает опциональное пространство имен для ключей:

{ id: 89, name: "John Smith" }.to_query("user")
# => "user%5Bid%5D=89&user%5Bname%5D=John+Smith"

with_options

Метод with_options предоставляет способ для выделения общих опций в серии вызовов метода.

Задав дефолтный хэш опций, with_options предоставляет прокси-объект в блок. Внутри блока методы, вызванные на прокси, отправляются получателю с объединением своих опций. Например, чтобы избавиться от дублирования:

class Account < ApplicationRecord
  has_many :customers, dependent: :destroy
  has_many :products,  dependent: :destroy
  has_many :invoices,  dependent: :destroy
  has_many :expenses,  dependent: :destroy
end

заменяем на:

class Account < ApplicationRecord
  with_options dependent: :destroy do |assoc|
    assoc.has_many :customers
    assoc.has_many :products
    assoc.has_many :invoices
    assoc.has_many :expenses
  end
end

Эта идиома может передавать группировку в ридер (reader). Например скажем, что нужно послать newsletter, язык которого зависит от пользователя. Где-нибудь в рассыльщике можно сгруппировать кусочки, зависимые от локали, следующим образом:

I18n.with_options locale: user.locale, scope: "newsletter" do |i18n|
  subject i18n.t :subject
  body    i18n.t :body, user_name: user.name
end

Поддержка JSON

Active Support обеспечивает лучшую реализацию to_json, чем гем json, обычно предоставленный для объектов Ruby. Это так, потому что некоторые классы, такие как Hash и Process::Status, нуждаются в специальной обработке для обеспечения подходящего JSON.

Переменные экземпляра

Active Support предоставляет несколько методов для облегчения доступа к переменным экземпляра.

instance_values

Метод instance_values возвращает хэш, который связывает имена переменных экземпляра без "@" с их соответствующими значениями. Ключи являются строками:

class C
  def initialize(x, y)
    @x, @y = x, y
  end
end

C.new(0, 1).instance_values # => {"x" => 0, "y" => 1}

instance_variable_names

Метод instance_variable_names возвращает массив. Каждое имя включает знак "@".

class C
  def initialize(x, y)
    @x, @y = x, y
  end
end

C.new(0, 1).instance_variable_names # => ["@x", "@y"]

Отключение предупреждений и исключения

Методы silence_warnings и enable_warnings изменяют значение $VERBOSE в течение исполнения блока, и сбрасывают в исходное значение после его окончания:

silence_warnings { Object.const_set "RAILS_DEFAULT_LOGGER", logger }

Отключение исключений также возможно с помощью suppress. Этот метод получает определенное количество классов исключений. Если вызывается исключение во время выполнения блока, и kind_of? соответствует любому аргументу, suppress ловит его и возвращает отключенным. В противном случае исключение не захватывается:

# Если пользователь под блокировкой, инкремент теряется, ничего страшного.
suppress(ActiveRecord::StaleObjectError) do
  current_user.increment! :visits
end

in?

Предикат in? проверяет, включен ли объект в другой объект. Если переданный элемент не отвечает на include?, будет вызвано исключение ArgumentError.

Примеры применения in?:

1.in?([1, 2])       # => true
"lo".in?("hello")   # => true
25.in?(30..50)      # => false
1.in?(1)            # => ArgumentError

Расширения для Module

Атрибуты

alias_attribute

В атрибутах модели есть ридер (reader), райтер (writer) и предикат. Можно создать псевдоним к атрибуту модели, в котором будут определены сразу три соответствующих метода, используя alias_attribute. Как и в других создающих псевдоним методах, новое имя - это первый аргумент, а старое имя - второй (мнемоническое правило такое: они идут в том же порядке, как если бы делалось присваивание):

class User < ApplicationRecord
  # Теперь можно обращаться к столбцу email как "login".
  # Это имеет больше смысла для кода аутентификации.
  alias_attribute :login, :email
end

Внутренние атрибуты

При определении атрибута в классе, который предназначен для подкласса, есть риск коллизии подклассовых имен. Это особенно важно для библиотек.

Active Support определяет макросы attr_internal_reader, attr_internal_writer и attr_internal_accessor. Они ведут себя подобно встроенным в Ruby коллегам attr_*, за исключением того, что они именуют лежащую в основе переменную экземпляра способом, наиболее снижающим коллизии.

Макрос attr_internal - это синоним для attr_internal_accessor:

# библиотека
class ThirdPartyLibrary::Crawler
  attr_internal :log_level
end

# код клиента
class MyCrawler < ThirdPartyLibrary::Crawler
  attr_accessor :log_level
end

В предыдущем примере мог быть случай, при котором :log_level не принадлежит публичному интерфейсу библиотеки и используется только для разработки. Код клиента, не подозревающий о потенциальном конфликте, создает подкласс и определяет внутри него свой :log_level. Благодаря attr_internal здесь не будет коллизий.

По умолчанию внутренняя переменная экземпляра именуется с предшествующим подчеркиванием, @_log_level в примере выше. Это настраивается через Module.attr_internal_naming_format, куда можно передать любую строку в формате sprintf с предшествующими @ и %s в любом месте, которая означает место, куда вставляется имя. По умолчанию "@_%s".

Rails использует внутренние атрибуты в некоторых местах, например для вью:

module ActionView
  class Base
    attr_internal :captures
    attr_internal :request, :layout
    attr_internal :controller, :template
  end
end

Атрибуты модуля

Макросы mattr_reader, mattr_writer и mattr_accessor - это те же самые макросы cattr_*, определенным для класса. Фактически, макросы cattr_* — это всего лишь псевдонимы для макросов mattr_*. Смотрите Атрибуты класса.

Например, API логирования Active Storage генерируется с помощью mattr_accessor:

module ActiveStorage
  mattr_accessor :logger
end

Родители

module_parent

Метод module_parent на вложенном именованном модуле возвращает модуль, содержащий его соответствующую константу:

module X
  module Y
    module Z
    end
  end
end
M = X::Y::Z

X::Y::Z.module_parent # => X::Y
M.module_parent       # => X::Y

Если модуль анонимный или относится к верхнему уровню, module_parent возвращает Object.

module_parent_name

Метод module_parent_name на вложенном именованном модуле возвращает полностью определенное имя модуля, содержащего его соответствующую константу:

module X
  module Y
    module Z
    end
  end
end
M = X::Y::Z

X::Y::Z.module_parent_name # => "X::Y"
M.module_parent_name       # => "X::Y"

Для верхнеуровневых и анонимных модулей module_parent_name возвращает nil.

parents

Метод module_parents вызывает module_parent на получателе и вверх по иерархии, пока не будет достигнут Object. Цепочка возвращается в массиве, от низшего к высшему:

module X
  module Y
    module Z
    end
  end
end
M = X::Y::Z

X::Y::Z.module_parents # => [X::Y, X, Object]
M.module_parents       # => [X::Y, X, Object]

Anonymous

У модуля может быть или не быть имени:

module M
end
M.name # => "M"

N = Module.new
N.name # => "N"

Module.new.name # => nil

Можно проверить, имеет ли модуль имя с помощью предиката anonymous?:

module M
end
M.anonymous? # => false

Module.new.anonymous? # => true

Отметьте, что быть недостижимым не означает быть анонимным:

module M
end

m = Object.send(:remove_const, :M)

m.anonymous? # => false

хотя анонимный модуль недостижим по определению.

Делегирование метода

delegate

Макрос delegate предлагает простой способ передать методы.

Давайте представим, что у пользователей в неком приложении имеется информация о логинах в модели User, но имена и другие данные в отдельной модели Profile:

class User < ApplicationRecord
  has_one :profile
end

С такой конфигурацией можно получить имя пользователя через его профиль, user.profile.name, но было бы удобнее обеспечить доступ к такому атрибуту напрямую:

class User < ApplicationRecord
  has_one :profile

  def name
    profile.name
  end
end

Это как раз то, что делает delegate:

class User < ApplicationRecord
  has_one :profile

  delegate :name, to: :profile
end

Это короче, и намерения более очевидные.

Целевой метод должен быть публичным.

Макрос delegate принимает несколько методов:

delegate :name, :age, :address, :twitter, to: :profile

При интерполяции в строку опция :to должна стать выражением, вычисляемым объектом, метод которого делегируется. Обычно строка или символ. Такое выражение вычисляется в контексте получателя:

# делегирует константе Rails
delegate :logger, to: :Rails

# делегирует классу получателя
delegate :table_name, to: :class

По умолчанию, если делегирование вызывает NoMethodError и цель является nil, выводится исключение. Можно попросить с помощью опции :allow_nil, чтобы вместо этого возвращался nil:

delegate :name, to: :profile, allow_nil: true

С :allow_nil вызов user.name возвратит nil, если у пользователя нет профиля.

Опция :prefix добавляет префикс к имени генерируемого метода. Это может быть удобно, например, для получения более благозвучного имени:

delegate :street, to: :address, prefix: true

Предыдущий пример сгенерирует address_street, а не street.

Также может быть настроен произвольный префикс:

delegate :size, to: :attachment, prefix: :avatar

В предыдущем примере макрос генерирует avatar_size, а не size.

Опция :private изменяет область видимости методов:

delegate :date_of_birth, to: :profile, private: true

Делегированные методы являются публичными по умолчанию. Передайте private: true, чтобы изменить это.

delegate_missing_to

Представьте, что нужно делегировать все, отсутствующее в объекте User в Profile. Макрос delegate_missing_to позволяет реализовать это быстро:

class User < ApplicationRecord
  has_one :profile

  delegate_missing_to :profile
end

Целью может быть все что угодно, вызываемое внутри объекта, например, переменные экземпляра, методы, константы и т.д. Делегируются только публичные методы цели.

Переопределение методов

Бывают ситуации, когда нужно определить метод с помощью define_method, но вы не знаете, существует ли уже метод с таким именем. Если так, то выдается предупреждение, если оно включено. Такое поведение хоть и не ошибочно, но не элегантно.

Метод redefine_method предотвращает такое потенциальное предупреждение, предварительно убирая существующий метод, если нужно.

Также можно использовать silence_redefinition_of_method, если необходимо определить заменяющий метод отдельно (потому что используется delegate, например).

Расширения для Class

Атрибуты класса

class_attribute

Метод class_attribute объявляет один или более наследуемых атрибутов класса, которые могут быть переопределены на низшем уровне иерархии:

class A
  class_attribute :x
end

class B < A; end

class C < B; end

A.x = :a
B.x # => :a
C.x # => :a

B.x = :b
A.x # => :a
C.x # => :b

C.x = :c
A.x # => :a
B.x # => :b

Например, ActionMailer::Base определяет:

class_attribute :default_params
self.default_params = {
  mime_version: "1.0",
  charset: "UTF-8",
  content_type: "text/plain",
  parts_order: [ "text/plain", "text/enriched", "text/html" ]
}.freeze

К ним также есть доступ, и они могут быть переопределены на уровне экземпляра:

A.x = 1

a1 = A.new
a2 = A.new
a2.x = 2

a1.x # => 1, приходит из A
a2.x # => 2, переопределено в a2

Генерация райтер-метода экземпляра может быть отключена установлением опции :instance_writer в false.

module ActiveRecord
  class Base
    class_attribute :table_name_prefix, instance_writer: false, default: "my"
  end
end

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

Генерация ридер-метода экземпляра может быть отключена установлением опции :instance_reader в false.

class A
  class_attribute :x, instance_reader: false
end

A.new.x = 1
A.new.x # NoMethodError

Для удобства class_attribute определяет также предикат экземпляра, являющийся двойным отрицанием того, что возвращает ридер экземпляра. В вышеописанном примере оно может вызываться x?.

Когда instance_reader равен false, предикат экземпляра возвратит NoMethodError, как и ридер-метод.

Если не нужен предикат, передайте instance_predicate: false, и он не будет определен.

cattr_reader, cattr_writer и cattr_accessor

Макросы cattr_reader, cattr_writer и cattr_accessor являются аналогами их коллег attr_*, но для классов. Они инициализируют переменную класса как nil, если она еще не существует, и генерируют соответствующие методы класса для доступа к ней:

class MysqlAdapter < AbstractAdapter
  # Генерирует методы класса для доступа к @@emulate_booleans.
  cattr_accessor :emulate_booleans
end

Также можно передать блок в cattr_* для настройки атрибута со значением по умолчанию:

class MysqlAdapter < AbstractAdapter
  # Генерирует методы класса для доступа к @@emulate_booleans со значением по умолчанию true.
  cattr_accessor :emulate_booleans, default: true
end

Методы экземпляра также создаются для удобства, они всего лишь прокси к атрибуту класса. Таким образом, экземпляры могут менять атрибут класса, но не могут переопределять его, как это происходит в случае с class_attribute (смотрите выше). К примеру, задав

module ActionView
  class Base
    cattr_accessor :field_error_proc, default: Proc.new {
      # ...
    }
  end
end

мы получим доступ к field_error_proc во вью.

Генерация ридер-метода экземпляра предотвращается установкой :instance_reader в false и генерация райтер-метода экземпляра предотвращается установкой :instance_writer в false. Генерация обоих методов предотвращается установкой :instance_accessor в false. Во всех случаях, должно быть не любое ложное значение, а именно false:

module A
  class B
    # first_name ридер экземпляра не генерируется.
    cattr_accessor :first_name, instance_reader: false
    # last_name= райтер экземпляра не генерируется.
    cattr_accessor :last_name, instance_writer: false
    # surname ридер экземпляра или surname= райтер экземпляра не генерируется.
    cattr_accessor :surname, instance_accessor: false
  end
end

В модели может быть полезным установить :instance_accessor в false как способ предотвращения массового назначения для установки атрибута.

Подклассы и потомки

subclasses

Метод subclasses возвращает подклассы получателя:

class C; end
C.subclasses # => []

class B < C; end
C.subclasses # => [B]

class A < B; end
C.subclasses # => [B]

class D < C; end
C.subclasses # => [B, D]

Порядок, в котором эти классы возвращаются, не определен.

descendants

Метод descendants возвращает все классы, которые являются < к его получателю:

class C; end
C.descendants # => []

class B < C; end
C.descendants # => [B]

class A < B; end
C.descendants # => [B, A]

class D < C; end
C.descendants # => [B, A, D]

Порядок, в котором эти классы возвращаются, не определен.

Расширения для String

Безопасность вывода

Мотивация

Вставка данных в шаблоны HTML требует дополнительной осторожности. Например, нельзя просто интерполировать @review.title на страницу HTML. С одной стороны, если заголовок рецензии "Flanagan & Matz rules!", то результат не будет правильно отображен, поскольку амперсанд должен быть экранирован как "&". К тому же, в зависимости от приложения, это может быть большой дырой в безопасности, так как пользователи могут внедрить вредоносный HTML, устанавливающий вручную изготовленный заголовок рецензии. Смотрите подробную информацию о рисках в разделе о межсайтовом скриптинге в руководстве Безопасность приложений на Rails.

Безопасные строки

В Active Support есть концепция (html) безопасных строк. Безопасная строка - это та, которая помечена как подлежащая вставке в HTML как есть. Ей можно доверять, независимо от того, была она экранирована или нет.

Строки рассматриваются как небезопасные по умолчанию:

"".html_safe? # => false

Можно получить безопасную строку из заданной с помощью метода html_safe:

s = "".html_safe
s.html_safe? # => true

Важно понять, что html_safe не выполняет какого бы то ни было экранирования, это всего лишь утверждение:

s = "<script>...</script>".html_safe
s.html_safe? # => true
s            # => "<script>...</script>"

Вы ответственны за обеспечение вызова html_safe на подходящей строке.

При присоединении к безопасной строке или с помощью concat/<<, или с помощью +, результат будет безопасной строкой. Небезопасные аргументы экранируются:

"".html_safe + "<" # => "&lt;"

Безопасные аргументы непосредственно присоединяются:

"".html_safe + "<".html_safe # => "<"

Эти методы не должны использоваться в обычных вью. Небезопасные значения автоматически экранируются:

<%= @review.title %> <%# прекрасно, экранируется, если нужно %>

Чтобы вставить что-либо дословно, используйте хелпер raw вместо вызова html_safe:

<%= raw @cms.current_template %> <%# вставляет @cms.current_template как есть %>

или используйте эквивалентную запись <%==:

<%== @cms.current_template %> <%# вставляет @cms.current_template как есть %>

Хелпер raw вызывает за вас хелпер html_safe:

def raw(stringish)
  stringish.to_s.html_safe
end

Преобразование

Как правило, за исключением, разве что, конкатенации, как объяснялось выше, любой метод, который может изменить строку, дает небезопасную строку. Это downcase, gsub, strip, chomp, underscore и т.д.

В случае встроенного преобразования, такого как gsub!, получатель сам становится небезопасным.

Конверсия и принуждение

Вызов to_s на безопасной строке возвратит безопасную строку, но принуждение с помощью to_str возвратит небезопасную строку.

Копирование

Вызов dup или clone на безопасной строке создаст безопасные строки.

remove

Метод remove уберет все совпадения с шаблоном:

"Hello World".remove(/Hello /) # => "World"

Также имеется деструктивная версия String#remove!.

squish

Метод squish отсекает начальные и конечные пробелы, а также заменяет внутренние пробелы на один пробел:

" \n  foo\n\r \t bar \n".squish # => "foo bar"

Также имеется разрушительная версия String#squish!.

Отметьте, что он обрабатывает и ASCII, и Unicode пробелы.

truncate

Метод truncate возвращает копию получателя, сокращенную после заданного length:

"Oh dear! Oh dear! I shall be late!".truncate(20)
# => "Oh dear! Oh dear!..."

Многоточие может быть настроено с помощью опции :omission:

"Oh dear! Oh dear! I shall be late!".truncate(20, omission: "…")
# => "Oh dear! Oh …"

Отметьте, что сокращение учитывает длину строки omission.

Передайте :separator для сокращения строки по естественным разрывам:

"Oh dear! Oh dear! I shall be late!".truncate(18)
# => "Oh dear! Oh dea..."
"Oh dear! Oh dear! I shall be late!".truncate(18, separator: " ")
# => "Oh dear! Oh..."

Опция :separator может быть регулярным выражением:

"Oh dear! Oh dear! I shall be late!".truncate(18, separator: /\s/)
# => "Oh dear! Oh..."

В вышеуказанных примерах "dear" обрезается сначала, а затем :separator предотвращает это.

truncate_bytes

Метод truncate_bytes возвращает копию получателя, обрезанную к максимуму bytesize байт:

"👍👍👍👍".truncate_bytes(15)
# => "👍👍👍…"

Многоточие может быть настроено с помощью опции :omission:

"👍👍👍👍".truncate_bytes(15, omission: "🖖")
# => "👍👍🖖"

truncate_words

Метод truncate_words возвращает копию получателя, сокращенную после заданного количества слов:

"Oh dear! Oh dear! I shall be late!".truncate_words(4)
# => "Oh dear! Oh dear!..."

Многоточие может быть настроено с помощью опции :omission:

"Oh dear! Oh dear! I shall be late!".truncate_words(4, omission: "…")
# => "Oh dear! Oh dear!…"

Передайте :separator для сокращения строки по естественным разрывам:

"Oh dear! Oh dear! I shall be late!".truncate_words(3, separator: "!")
# => "Oh dear! Oh dear! I shall be late..."

Опция :separator может быть регулярным выражением:

"Oh dear! Oh dear! I shall be late!".truncate_words(4, separator: /\s/)
# => "Oh dear! Oh dear!..."

inquiry

Метод inquiry конвертирует строку в объект StringInquirer, делая проверки равенства более красивыми.

"production".inquiry.production? # => true
"active".inquiry.inactive?       # => false

starts_with? и ends_with?

Active Support определяет псевдонимы String#start_with? и String#end_with? (в связи с особенностями английской морфологии, преобразует глаголы в форму 3-го лица):

"foo".starts_with?("f") # => true
"foo".ends_with?("o")   # => true

strip_heredoc

Метод strip_heredoc обрезает отступы в heredocs.

Для примера в

if options[:usage]
  puts <<-USAGE.strip_heredoc
    This command does such and such.

    Supported options are:
      -h         This message
      ...
  USAGE
end

пользователь увидит используемое сообщение, выровненное по левому краю.

Технически это выглядит как выделение красной строки в отдельную строку и удаление всех идущих впереди пробелов.

indent

Метод indent устанавливает отступы строчкам получателя:

<<EOS.indent(2)
def some_method
  some_code
end
EOS
# =>
  def some_method
    some_code
  end

Второй аргумент, indent_string, определяет, какой отступ строки использовать. По умолчанию nil, что сообщает методу самому догадаться на основе первой строчки с отступом, а если такой нет, то использовать пробел.

"  foo".indent(2)        # => "    foo"
"foo\n\t\tbar".indent(2) # => "\t\tfoo\n\t\t\t\tbar"
"foo".indent(2, "\t")    # => "\t\tfoo"

Хотя indent_string это обычно один пробел или табуляция, он может быть любой строкой.

Третий аргумент, indent_empty_lines, это флажок, указывающий, должен ли быть отступ для пустых строчек. По умолчанию false.

"foo\n\nbar".indent(2)            # => "  foo\n\n  bar"
"foo\n\nbar".indent(2, nil, true) # => "  foo\n  \n  bar"

Метод indent! добавляет отступ строке.

Доступ

at(position)

Метод at возвращает символ строки на позиции position:

"hello".at(0)  # => "h"
"hello".at(4)  # => "o"
"hello".at(-1) # => "o"
"hello".at(10) # => nil

from(position)

Метод from возвращает подстроку строки, начинающуюся с позиции position:

"hello".from(0)  # => "hello"
"hello".from(2)  # => "llo"
"hello".from(-2) # => "lo"
"hello".from(10) # => nil

to(position)

Метод to возвращает подстроку строки с начала до позиции position:

"hello".to(0)  # => "h"
"hello".to(2)  # => "hel"
"hello".to(-2) # => "hell"
"hello".to(10) # => "hello"

first(limit = 1)

Метод first возвращает подстроку, содержащую первые limit символов строки.

Вызов str.first(n) эквивалентен str.to(n-1), если n > 0, и возвращает пустую строку для n == 0.

last(limit = 1)

Метод last возвращает подстроку, содержащую последние limit символов строки.

Вызов str.last(n) эквивалентен str.from(-n), если n > 0, и возвращает пустую строку для n == 0.

Изменения слов

pluralize

Метод pluralize возвращает множественное число получателя:

"table".pluralize     # => "tables"
"ruby".pluralize      # => "rubies"
"equipment".pluralize # => "equipment"

Как показывает предыдущий пример, Active Support знает некоторые неправильные множественные числа и неисчисляемые существительные. Встроенные правила могут быть расширены в config/initializers/inflections.rb. Этот файл генерируется по умолчанию, командой rails new, и имеет инструкции в комментариях.

pluralize также может принимать опциональный параметр count. Если count == 1, будет возвращена единственная форма. Для остальных значений count будет возвращена множественная форма:

"dude".pluralize(0) # => "dudes"
"dude".pluralize(1) # => "dude"
"dude".pluralize(2) # => "dudes"

Active Record использует этот метод для вычисления дефолтного имени таблицы, соответствующей модели:

# active_record/model_schema.rb
def undecorated_table_name(model_name)
  table_name = model_name.to_s.demodulize.underscore
  pluralize_table_names ? table_name.pluralize : table_name
end

singularize

Метод singularize это противоположность pluralize:

"tables".singularize    # => "table"
"rubies".singularize    # => "ruby"
"equipment".singularize # => "equipment"

Связи вычисляют имя соответствующего связанного дефолтного класса, используя этот метод:

# active_record/reflection.rb
def derive_class_name
  class_name = name.to_s.camelize
  class_name = class_name.singularize if collection?
  class_name
end

camelize

Метод camelize возвращает получателя в стиле CamelCase:

"product".camelize    # => "Product"
"admin_user".camelize # => "AdminUser"

Как правило, об этом методе думают, как о преобразующем пути в классы Ruby или имена модулей, где слэши разделяют пространства имен:

"backoffice/session".camelize # => "Backoffice::Session"

Например, Action Pack использует этот метод для загрузки класса, предоставляющего определенное хранилище сессии:

# action_controller/metal/session_management.rb
def session_store=(store)
  @@session_store = store.is_a?(Symbol) ?
    ActionDispatch::Session.const_get(store.to_s.camelize) :
    store
end

camelize принимает опциональный аргумент, он может быть :upper (по умолчанию) или :lower. В последнем случае первая буква становится строчной:

"visual_effect".camelize(:lower) # => "visualEffect"

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

ActiveSupport::Inflector.inflections do |inflect|
  inflect.acronym 'SSL'
end

"SSLError".underscore.camelize # => "SSLError"

camelize имеет псевдоним camelcase.

underscore

Метод underscore делает наоборот, от CamelCase к путям:

"Product".underscore   # => "product"
"AdminUser".underscore # => "admin_user"

Также преобразует "::" обратно в "/":

"Backoffice::Session".underscore # => "backoffice/session"

и понимает строки, начинающиеся с прописной буквы:

"visualEffect".underscore # => "visual_effect"

хотя underscore не принимает никакие аргументы.

Rails использует underscore чтобы получить имя классов контроллера в нижнем регистре:

# actionpack/lib/abstract_controller/base.rb
def controller_path
  @controller_path ||= name.delete_suffix("Controller").underscore
end

Например, это значение можно получить в params[:controller].

titleize

Метод titleize озаглавит слова в получателе:

"alice in wonderland".titleize # => "Alice In Wonderland"
"fermat's enigma".titleize     # => "Fermat's Enigma"

titleize имеет псевдоним titlecase.

dasherize

Метод dasherize заменяет подчеркивания в получателе дефисами:

"name".dasherize         # => "name"
"contact_data".dasherize # => "contact-data"

Сериализатор XML моделей использует этот метод для форматирования имен узлов:

# active_model/serializers/xml.rb
def reformat_name(name)
  name = name.camelize if camelize?
  dasherize? ? name.dasherize : name
end

demodulize

Для заданной строки с ограниченным именем константы, demodulize возвращает само имя константы, то есть правой части этого:

"Product".demodulize                        # => "Product"
"Backoffice::UsersController".demodulize    # => "UsersController"
"Admin::Hotel::ReservationUtils".demodulize # => "ReservationUtils"
"::Inflections".demodulize                  # => "Inflections"
"".demodulize                               # => ""

Active Record, к примеру, использует этот метод для вычисления имени столбца кэширования счетчика:

# active_record/reflection.rb
def counter_cache_column
  if options[:counter_cache] == true
    "#{active_record.name.demodulize.underscore.pluralize}_count"
  elsif options[:counter_cache]
    options[:counter_cache]
  end
end

deconstantize

У заданной строки с ограниченным выражением ссылки на константу deconstantize убирает самый правый сегмент, в основном оставляя имя контейнера константы:

"Product".deconstantize                        # => ""
"Backoffice::UsersController".deconstantize    # => "Backoffice"
"Admin::Hotel::ReservationUtils".deconstantize # => "Admin::Hotel"

parameterize

Метод parameterize нормализует получателя способом, который может использоваться в красивых URL.

"John Smith".parameterize # => "john-smith"
"Kurt Gödel".parameterize # => "kurt-godel"

Чтобы сохранить регистр строки, установите аргумент preserve_case в true. По умолчанию preserve_case установлен в false.

"John Smith".parameterize(preserve_case: true) # => "John-Smith"
"Kurt Gödel".parameterize(preserve_case: true) # => "Kurt-Godel"

Чтобы использовать произвольный разделитель, переопределите аргумент separator.

"John Smith".parameterize(separator: "_") # => "john_smith"
"Kurt Gödel".parameterize(separator: "_") # => "kurt_godel"

tableize

Метод tableize - это underscore вместе с pluralize.

"Person".tableize      # => "people"
"Invoice".tableize     # => "invoices"
"InvoiceLine".tableize # => "invoice_lines"

Как правило, tableize возвращает имя таблицы, соответствующей заданной модели для простых случаев. На самом деле фактическая реализация в Active Record не является прямым tableize, так как он также демодулизирует имя класса и проверяет несколько опций, которые могут повлиять на возвращаемую строку.

classify

Метод classify является противоположностью tableize. Он выдает имя класса, соответствующего имени таблицы:

"people".classify        # => "Person"
"invoices".classify      # => "Invoice"
"invoice_lines".classify # => "InvoiceLine"

Метод понимает ограниченные имена таблиц:

"highrise_production.companies".classify # => "Company"

Отметьте, что classify возвращает имя класса как строку. Можете получить фактический объект класса, вызвав constantize на ней, как объяснено далее.

constantize

Метод constantize решает выражение, ссылающееся на константу, в его получателе:

"Integer".constantize # => Integer

module M
  X = 1
end
"M::X".constantize # => 1

Если строка вычисляет неизвестную константу, или ее содержимое даже не является валидным именем константы, constantize вызывает NameError.

Анализ имени константы с помощью constantize начинается всегда с верхнего уровня Object, даже если нет предшествующих "::".

X = :in_Object
module M
  X = :in_M

  X                 # => :in_M
  "::X".constantize # => :in_Object
  "X".constantize   # => :in_Object (!)
end

Таким образом, в общем случае это не эквивалентно тому, что Ruby сделал бы в том же месте, когда вычислял настоящую константу.

Тестовые случаи рассыльщика получают тестируемый рассыльщик из имени класса теста, используя constantize:

# action_mailer/test_case.rb
def determine_default_mailer(name)
  name.delete_suffix("Test").constantize
rescue NameError => e
  raise NonInferrableMailerError.new(name)
end

humanize

Метод humanize настраивает имя атрибута для отображения конечным пользователям.

В частности, он выполняет эти преобразования:

• Применяет правила словоизменения к аргументу.
• Удаляет любые предшествующие знаки подчеркивания.
• Убирает суффикс "_id".
• Заменяет знаки подчеркивания пробелами.
• Переводит в нижний регистр все слова, кроме акронимов.
• Озаглавливает первое слово.

Озаглавливание первого слова может быть выключено с помощью установки опции :capitalize в false (по умолчанию true).

"name".humanize                         # => "Name"
"author_id".humanize                    # => "Author"
"author_id".humanize(capitalize: false) # => "author"
"comments_count".humanize               # => "Comments count"
"_id".humanize                          # => "Id"

Если "SSL" был определен как акроним:

"ssl_error".humanize # => "SSL error"

Метод хелпера full_messages использует humanize как резервный способ для включения имен атрибутов:

def full_messages
  map { |attribute, message| full_message(attribute, message) }
end

def full_message
  # ...
  attr_name = attribute.to_s.tr(".", "_").humanize
  attr_name = @base.class.human_attribute_name(attribute, default: attr_name)
  # ...
end

foreign_key

Метод foreign_key дает имя столбца внешнего ключа из имени класса. Чтобы это сделать он демодулизирует, подчеркивает и добавляет "_id":

"User".foreign_key           # => "user_id"
"InvoiceLine".foreign_key    # => "invoice_line_id"
"Admin::Session".foreign_key # => "session_id"

Передайте аргумент false, если не хотите подчеркивание в "_id":

"User".foreign_key(false) # => "userid"

Связи используют этот метод для вывода внешних ключей, например has_one и has_many делают так:

# active_record/associations.rb
foreign_key = options[:foreign_key] || reflection.active_record.name.foreign_key

upcase_first

Метод upcase_first озаглавливает первую букву получателя:

"employee salary".upcase_first # => "Employee salary"
"".upcase_first                # => ""

downcase_first

Метод downcase_first конвертирует первую букву получателя в нижний регистр:

"If I had read Alice in Wonderland".downcase_first # => "if I had read Alice in Wonderland"
"".downcase_first                                  # => ""

Конвертирование

to_date, to_time, to_datetime

Методы to_date, to_time и to_datetime - в основном удобные обертки для Date._parse:

"2010-07-27".to_date              # => Tue, 27 Jul 2010
"2010-07-27 23:37:00".to_time     # => 2010-07-27 23:37:00 +0200
"2010-07-27 23:37:00".to_datetime # => Tue, 27 Jul 2010 23:37:00 +0000

to_time получает опциональный аргумент :utc или :local, для указания, время какой временной зоны необходимо:

"2010-07-27 23:42:00".to_time(:utc)   # => 2010-07-27 23:42:00 UTC
"2010-07-27 23:42:00".to_time(:local) # => 2010-07-27 23:42:00 +0200

По умолчанию :local.

Пожалуйста, обратитесь к документации по Date._parse для получения дополнительной информации.

Расширения для Symbol

starts_with? и ends_with?

Active Support определяет сторонние псевдонимы для Symbol#start_with? и Symbol#end_with?:

:foo.starts_with?("f") # => true
:foo.ends_with?("o")   # => true

Расширения для Numeric

Байты

Все числа отвечают на эти методы:

• bytes
• kilobytes
• megabytes
• gigabytes
• terabytes
• petabytes
• exabytes
• zettabytes

Они возвращают соответствующее количество байтов, используя конвертирующий множитель 1024:

2.kilobytes   # => 2048
3.megabytes   # => 3145728
3.5.gigabytes # => 3758096384.0
-4.exabytes   # => -4611686018427387904

Форма в единственном числе является псевдонимом, поэтому можно написать так:

1.megabyte # => 1048576

Время

Следующие методы:

• seconds
• minutes
• hours
• days
• weeks
• fortnights

включают вычисление и объявление времени, наподобие 45.minutes + 2.hours + 4.weeks. Их возвращаемое значение также может быть добавлено или вычтено из объектов Time.

Эти методы могут быть объединены с from_now, ago и так далее для уточнения вычисления даты. Например:

# эквивалент для Time.current.advance(days: 1)
1.day.from_now

# эквивалент для Time.current.advance(weeks: 2)
2.weeks.from_now

# эквивалент для Time.current.advance(days: 4, weeks: 5)
(4.days + 5.weeks).from_now

WARNING. Для других длительностей, обратитесь, пожалуйста, к временному расширению для Integer.

Форматирование

Включает форматирование чисел различными способами.

Преобразует число в строковое представление телефонного номера:

5551234.to_fs(:phone)
# => 555-1234
1235551234.to_fs(:phone)
# => 123-555-1234
1235551234.to_fs(:phone, area_code: true)
# => (123) 555-1234
1235551234.to_fs(:phone, delimiter: " ")
# => 123 555 1234
1235551234.to_fs(:phone, area_code: true, extension: 555)
# => (123) 555-1234 x 555
1235551234.to_fs(:phone, country_code: 1)
# => +1-123-555-1234

Преобразует число в строковое представление валюты:

1234567890.50.to_fs(:currency)                 # => $1,234,567,890.50
1234567890.506.to_fs(:currency)                # => $1,234,567,890.51
1234567890.506.to_fs(:currency, precision: 3)  # => $1,234,567,890.506

Преобразует число в строковое представление процентов:

100.to_fs(:percentage)
# => 100.000%
100.to_fs(:percentage, precision: 0)
# => 100%
1000.to_fs(:percentage, delimiter: ".", separator: ",")
# => 1.000,000%
302.24398923423.to_fs(:percentage, precision: 5)
# => 302.24399%

Преобразует число в строковое представление числа с разделенными разрядами:

12345678.to_fs(:delimited)                     # => 12,345,678
12345678.05.to_fs(:delimited)                  # => 12,345,678.05
12345678.to_fs(:delimited, delimiter: ".")     # => 12.345.678
12345678.to_fs(:delimited, delimiter: ",")     # => 12,345,678
12345678.05.to_fs(:delimited, separator: " ")  # => 12,345,678 05

Преобразует число в строковое представление числа, округленного с определенной точностью:

111.2345.to_fs(:rounded)                     # => 111.235
111.2345.to_fs(:rounded, precision: 2)       # => 111.23
13.to_fs(:rounded, precision: 5)             # => 13.00000
389.32314.to_fs(:rounded, precision: 0)      # => 389
111.2345.to_fs(:rounded, significant: true)  # => 111

Преобразует число в строковое представление с удобочитаемым количеством байт:

123.to_fs(:human_size)                  # => 123 Bytes
1234.to_fs(:human_size)                 # => 1.21 KB
12345.to_fs(:human_size)                # => 12.1 KB
1234567.to_fs(:human_size)              # => 1.18 MB
1234567890.to_fs(:human_size)           # => 1.15 GB
1234567890123.to_fs(:human_size)        # => 1.12 TB
1234567890123456.to_fs(:human_size)     # => 1.1 PB
1234567890123456789.to_fs(:human_size)  # => 1.07 EB

Преобразует число в строковое представление с удобочитаемым числом слов:

123.to_fs(:human)               # => "123"
1234.to_fs(:human)              # => "1.23 Thousand"
12345.to_fs(:human)             # => "12.3 Thousand"
1234567.to_fs(:human)           # => "1.23 Million"
1234567890.to_fs(:human)        # => "1.23 Billion"
1234567890123.to_fs(:human)     # => "1.23 Trillion"
1234567890123456.to_fs(:human)  # => "1.23 Quadrillion"

Расширения для Integer

multiple_of?

Метод multiple_of? проверяет, является ли целое число множителем аргумента:

2.multiple_of?(1) # => true
1.multiple_of?(2) # => false

ordinal

Метод ordinal возвращает суффикс порядковой строки, соответствующей полученному целому числу:

1.ordinal    # => "st"
2.ordinal    # => "nd"
53.ordinal   # => "rd"
2009.ordinal # => "th"
-21.ordinal  # => "st"
-134.ordinal # => "th"

ordinalize

Метод ordinalize возвращает порядковую строку, соответствующую полученному целому числу. Для сравнения отметьте, что метод ordinal возвращает только строковый суффикс.

1.ordinalize    # => "1st"
2.ordinalize    # => "2nd"
53.ordinalize   # => "53rd"
2009.ordinalize # => "2009th"
-21.ordinalize  # => "-21st"
-134.ordinalize # => "-134th"

Время

Следующие методы:

• months
• years

включают объявление и вычисление времени, подобно 4.months + 5.years. Их возвращаемое значение также может быть добавлено или вычтено из объектов Time.

Эти методы могут быть объединены с from_now, ago и так далее для уточнения вычисления даты. Например:

# эквивалент для Time.current.advance(months: 1)
1.month.from_now

# эквивалент для Time.current.advance(years: 2)
2.years.from_now

# эквивалент для Time.current.advance(months: 4, years: 5)
(4.months + 5.years).from_now

WARNING. Для других длительностей, обратитесь, пожалуйста, к временному расширению для Numeric.

Расширения для BigDecimal

to_s

Метод to_s предоставляет спецификатор по умолчанию для "F". Это означает, что простой вызов to_s приведет к представлению с плавающей запятой вместо инженерной нотации:

BigDecimal(5.00, 6).to_s       # => "5.0"

Инженерная нотация все еще поддерживается:

BigDecimal(5.00, 6).to_s("e")  # => "0.5E1"

Расширения для Enumerable

index_by

Метод [index_by][Enumerable#index_by] генерирует хэш с элементами перечисления, индексированными по некоторому ключу.

Он перебирает коллекцию и передает каждый элемент в блок. Значение, возвращенное блоком, будет ключом для элемента:

invoices.index_by(&:number)
# => {"2009-032" => <Invoice ...>, "2009-008" => <Invoice ...>, ...}

WARNING. Ключи, как правило, должны быть уникальными. Если блок возвратит одно и то же значение для нескольких элементов, для этого ключа не будет построена коллекция. А значение получит последний элемент.

[index_by][Enumerable#index_by]

index_with

Метод index_with генерирует хэш с элементами перечисления в качестве ключей. Значение является либо переданным по умолчанию, либо возвращенным в блоке.

post = Post.new(title: "hey there", body: "what's up?")

%i( title body ).index_with { |attr_name| post.public_send(attr_name) }
# => { title: "hey there", body: "what's up?" }

WEEKDAYS.index_with([Interval.all_day])
# => { monday: [ 0, 1440 ], … }

many?

Метод many? это сокращение для collection.size > 1:

<% if pages.many? %>
  <%= pagination_links %>
<% end %>

Если задан опциональный блок, many? учитывает только те элементы, которые возвращают true:

@see_more = videos.many? { |video| video.category == params[:category] }

exclude?

Предикат exclude? проверяет, является ли заданный объект не принадлежащим коллекции. Это противоположность встроенного include?:

to_visit << node if visited.exclude?(node)

including

Метод including возвращает новое перечисление, включающее переданные элементы:

[ 1, 2, 3 ].including(4, 5)                    # => [ 1, 2, 3, 4, 5 ]
["David", "Rafael"].including %w[ Aaron Todd ] # => ["David", "Rafael", "Aaron", "Todd"]

excluding

Метод excluding возвращает копию перечисления без указанных элементов:

["David", "Rafael", "Aaron", "Todd"].excluding("Aaron", "Todd") # => ["David", "Rafael"]

У excluding есть псевдоним without.

pluck

Метод pluck возвращает массив на основе заданного ключа:

[{ name: "David" }, { name: "Rafael" }, { name: "Aaron" }].pluck(:name) # => ["David", "Rafael", "Aaron"]
[{ id: 1, name: "David" }, { id: 2, name: "Rafael" }].pluck(:id, :name) # => [[1, "David"], [2, "Rafael"]]

pick

Методpick извлекает заданный ключ из первого элемента:

[{ name: "David" }, { name: "Rafael" }, { name: "Aaron" }].pick(:name) # => "David"
[{ id: 1, name: "David" }, { id: 2, name: "Rafael" }].pick(:id, :name) # => [1, "David"]

Расширения для Array

Доступ

Active Support расширяет API массивов для облегчения нескольких способов доступа к ним. Например, to возвращает подмассив элементов от первого до переданного индекса:

%w(a b c d).to(2) # => ["a", "b", "c"]
[].to(7)          # => []

По аналогии, from возвращает хвост массива, количество элементов которого равно переданному индексу. Если индекс больше длины массива, возвращается пустой массив.

%w(a b c d).from(2)  # => ["c", "d"]
%w(a b c d).from(10) # => []
[].from(0)           # => []

Метод including возвращает новый массив, включающий переданные элементы:

[ 1, 2, 3 ].including(4, 5)          # => [ 1, 2, 3, 4, 5 ]
[ [ 0, 1 ] ].including([ [ 1, 0 ] ]) # => [ [ 0, 1 ], [ 1, 0 ] ]

Метод excluding возвращает копию Array с исключенными указанными элементами. Это оптимизация Enumerable#excluding, использующая Array#- вместо Array#reject по причинам производительности.

["David", "Rafael", "Aaron", "Todd"].excluding("Aaron", "Todd") # => ["David", "Rafael"]
[ [ 0, 1 ], [ 1, 0 ] ].excluding([ [ 1, 0 ] ])                  # => [ [ 0, 1 ] ]

Методы second, third, fourth и fifth возвращают соответствующие элементы, так же как second_to_last и third_to_last (first и last являются встроенными). Благодаря социальной мудрости и всеобщей позитивной конструктивности, forty_two также доступен.

%w(a b c d).third # => "c"
%w(a b c d).fifth # => nil

Извлечение

Метод extract! убирает и возвращает элементы, для которых блок возвращает истинное значение. Если блок не задан, вместо этого возвратиться Enumerator.

numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
odd_numbers = numbers.extract! { |number| number.odd? } # => [1, 3, 5, 7, 9]
numbers # => [0, 2, 4, 6, 8]

Извлечение опций

Когда последний аргумент в вызове метода является хэшем, за исключением, пожалуй, аргумента &block, Ruby позволяет опустить скобки:

User.exists?(email: params[:email])

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

Если метод ожидает различное количество аргументов и использует * в своем объявлении, однако хэш опций завершает их и является последним элементом массива аргументов, тогда тип теряет свою роль.

В этих случаях можно задать хэшу опций отличительную трактовку с помощью extract_options!. Метод проверяет тип последнего элемента массива. Если это хэш, он вырезает его и возвращает, в противном случае возвращает пустой хэш.

Давайте рассмотрим пример определения макроса контроллера caches_action:

def caches_action(*actions)
  return unless cache_configured?
  options = actions.extract_options!
  # ...
end

Этот метод получает произвольное число имен экшнов и опциональный хэш опций как последний аргумент. Вызвав extract_options!, получаем хэш опций и убираем его из actions простым и явным способом.

Преобразование

to_sentence

Метод to_sentence превращает массив в строку, содержащую предложение, в котором перечисляются элементы массива:

%w().to_sentence                # => ""
%w(Earth).to_sentence           # => "Earth"
%w(Earth Wind).to_sentence      # => "Earth and Wind"
%w(Earth Wind Fire).to_sentence # => "Earth, Wind, and Fire"

Этот метод принимает три опции:

• :two_words_connector: Что используется для массивов с длиной 2. По умолчанию " and ".
• :words_connector: Что используется для соединения элементов массивов с 3 и более элементами, кроме последних двух. По умолчанию ", ".
• :last_word_connector: Что используется для соединения последних элементов массива из 3 и более элементов. По умолчанию ", and ".

По умолчанию эти опции могут быть локализованы, их ключи следующие:

to_fs

Метод to_fs по умолчанию работает как to_s.

Однако, если массив содержит элементы, откликающиеся на id, как аргумент можно передать символ :db. Это обычно используется с коллекциями объектов Active Record. Возвращаемые строки следующие:

[].to_fs(:db)            # => "null"
[user].to_fs(:db)        # => "8456"
invoice.lines.to_fs(:db) # => "23,567,556,12"

Целые числа в примере выше предполагается, что приходят от соответствующих вызовов id.

to_xml

Метод to_xml возвращает строку, содержащую представление XML его получателя:

Contributor.limit(2).order(:rank).to_xml
# =>
# <?xml version="1.0" encoding="UTF-8"?>
# <contributors type="array">
#   <contributor>
#     <id type="integer">4356</id>
#     <name>Jeremy Kemper</name>
#     <rank type="integer">1</rank>
#     <url-id>jeremy-kemper</url-id>
#   </contributor>
#   <contributor>
#     <id type="integer">4404</id>
#     <name>David Heinemeier Hansson</name>
#     <rank type="integer">2</rank>
#     <url-id>david-heinemeier-hansson</url-id>
#   </contributor>
# </contributors>

Чтобы это сделать, он посылает to_xml к каждому элементу за раз и собирает результаты в корневом узле. Все элементы должны откликаться на to_xml, иначе будет вызвано исключение.

По умолчанию имя корневого элемента - это подчеркнутое и dasherize имя класса первого элемента во множественном числе, при условии что остальные элементы принадлежат этому типу (проверяется с помощью is_a?) и они не являются хэшами. В примере выше это "contributors".

Если есть какой-либо элемент, не принадлежащий типу первого, корневой узел становится "objects":

[Contributor.first, Commit.first].to_xml
# =>
# <?xml version="1.0" encoding="UTF-8"?>
# <objects type="array">
#   <object>
#     <id type="integer">4583</id>
#     <name>Aaron Batalion</name>
#     <rank type="integer">53</rank>
#     <url-id>aaron-batalion</url-id>
#   </object>
#   <object>
#     <author>Joshua Peek</author>
#     <authored-timestamp type="datetime">2009-09-02T16:44:36Z</authored-timestamp>
#     <branch>origin/master</branch>
#     <committed-timestamp type="datetime">2009-09-02T16:44:36Z</committed-timestamp>
#     <committer>Joshua Peek</committer>
#     <git-show nil="true"></git-show>
#     <id type="integer">190316</id>
#     <imported-from-svn type="boolean">false</imported-from-svn>
#     <message>Kill AMo observing wrap_with_notifications since ARes was only using it</message>
#     <sha1>723a47bfb3708f968821bc969a9a3fc873a3ed58</sha1>
#   </object>
# </objects>

Если получатель является массивом хэшей, корневой элемент по умолчанию также "objects":

[{ a: 1, b: 2 }, { c: 3 }].to_xml
# =>
# <?xml version="1.0" encoding="UTF-8"?>
# <objects type="array">
#   <object>
#     <b type="integer">2</b>
#     <a type="integer">1</a>
#   </object>
#   <object>
#     <c type="integer">3</c>
#   </object>
# </objects>

WARNING. Если коллекция пустая, корневой элемент по умолчанию "nil-classes". Пример для понимания, корневой элемент вышеописанного списка вкладчиков будет не "contributors", если коллекция пустая, а "nil-classes". Можно использовать опцию :root для обеспечения согласованного корневого элемента.

Имя дочерних узлов по умолчанию является именем корневого узла в единственном числе. В вышеприведенных примерах мы видели "contributor" и "object". Опция :children позволяет установить эти имена узлов.

По умолчанию билдер XML является свежим экземпляром Builder::XmlMarkup. Можно сконфигурировать свой собственный билдер через опцию :builder. Метод также принимает опции, такие как :dasherize и ему подобные, они перенаправляются в билдер:

Contributor.limit(2).order(:rank).to_xml(skip_types: true)
# =>
# <?xml version="1.0" encoding="UTF-8"?>
# <contributors>
#   <contributor>
#     <id>4356</id>
#     <name>Jeremy Kemper</name>
#     <rank>1</rank>
#     <url-id>jeremy-kemper</url-id>
#   </contributor>
#   <contributor>
#     <id>4404</id>
#     <name>David Heinemeier Hansson</name>
#     <rank>2</rank>
#     <url-id>david-heinemeier-hansson</url-id>
#   </contributor>
# </contributors>

Оборачивание

Метод Array.wrap оборачивает свои аргументы в массив, кроме случая когда это уже массив (или массивоподобные).

А именно:

• Если аргумент nil, возвращается пустой массив.
• В противном случае, если аргумент откликается на to_ary, он вызывается, и, если значение to_ary не nil, оно возвращается.
• В противном случае, возвращается массив с аргументом в качестве его первого элемента.

Array.wrap(nil)       # => []
Array.wrap([1, 2, 3]) # => [1, 2, 3]
Array.wrap(0)         # => [0]