1 Comment charger les extensions de base

1.1 Active Support autonome

Afin d'avoir la plus petite empreinte possible par défaut, Active Support charge les dépendances minimales par défaut. Il est divisé en petites parties afin que seules les extensions souhaitées puissent être chargées. Il dispose également de points d'entrée pratiques pour charger des extensions connexes en une seule fois, voire tout.

Ainsi, après un simple require comme :

require "active_support"

seules les extensions requises par le framework Active Support sont chargées.

1.1.1 Sélectionner une définition

Cet exemple montre comment charger Hash#with_indifferent_access. Cette extension permet la conversion d'un Hash en ActiveSupport::HashWithIndifferentAccess qui permet d'accéder aux clés sous forme de chaînes de caractères ou de symboles.

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

Pour chaque méthode définie en tant qu'extension de base, ce guide comporte une note indiquant où cette méthode est définie. Dans le cas de with_indifferent_access, la note indique :

NOTE : Défini dans active_support/core_ext/hash/indifferent_access.rb.

Cela signifie que vous pouvez le requérir comme ceci :

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

Active Support a été soigneusement révisé de manière à ce que la sélection d'un fichier ne charge que les dépendances strictement nécessaires, le cas échéant.

1.1.2 Charger les extensions de base groupées

Le niveau suivant consiste simplement à charger toutes les extensions de Hash. En règle générale, les extensions de SomeClass sont disponibles en une seule fois en chargeant active_support/core_ext/some_class.

Ainsi, pour charger toutes les extensions de Hash (y compris with_indifferent_access) :

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

1.1.3 Charger toutes les extensions de base

Vous pouvez préférer simplement charger toutes les extensions de base, il y a un fichier pour cela :

require "active_support"
require "active_support/core_ext"

1.1.4 Charger tout Active Support

Et enfin, si vous souhaitez avoir tout Active Support disponible, il suffit de lancer :

require "active_support/all"

Cela ne met même pas tout Active Support en mémoire à l'avance, en effet, certaines choses sont configurées via autoload, donc elles ne sont chargées que si elles sont utilisées.

1.2 Active Support dans une application Ruby on Rails

Une application Ruby on Rails charge tout Active Support à moins que config.active_support.bare ne soit vrai. Dans ce cas, l'application ne chargera que ce que le framework lui-même sélectionne pour ses propres besoins, et peut toujours se sélectionner elle-même à n'importe quel niveau de granularité, comme expliqué dans la section précédente.

2 Extensions pour tous les objets

2.1 `blank?` et `present?`

Les valeurs suivantes sont considérées comme vides dans une application Rails :

nil et false,
les chaînes de caractères composées uniquement d'espaces (voir la note ci-dessous),
les tableaux et les hachages vides, et
tout autre objet qui répond à empty? et qui est vide.

INFO : Le prédicat pour les chaînes de caractères utilise la classe de caractères sensible à l'Unicode [:space:], donc par exemple U+2029 (séparateur de paragraphe) est considéré comme un espace. AVERTISSEMENT: Notez que les nombres ne sont pas mentionnés. En particulier, 0 et 0.0 ne sont pas vides.

Par exemple, cette méthode de ActionController::HttpAuthentication::Token::ControllerMethods utilise blank? pour vérifier si un jeton est présent:

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

La méthode present? est équivalente à !blank?. Cet exemple est tiré de ActionDispatch::Http::Cache::Response:

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

Défini dans active_support/core_ext/object/blank.rb.

2.2 `presence`

La méthode presence renvoie son receveur s'il est present?, et nil sinon. Elle est utile pour des idiomes comme celui-ci:

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

Défini dans active_support/core_ext/object/blank.rb.

2.3 `duplicable?`

À partir de Ruby 2.5, la plupart des objets peuvent être dupliqués via dup ou 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 fournit duplicable? pour interroger un objet à ce sujet:

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

AVERTISSEMENT: Toute classe peut interdire la duplication en supprimant dup et clone ou en levant des exceptions à partir d'eux. Ainsi, seul rescue peut dire si un objet arbitraire donné est duplicable. duplicable? dépend de la liste codée en dur ci-dessus, mais il est beaucoup plus rapide que rescue. Utilisez-le uniquement si vous savez que la liste codée en dur est suffisante dans votre cas d'utilisation.

Défini dans active_support/core_ext/object/duplicable.rb.

2.4 `deep_dup`

La méthode deep_dup renvoie une copie en profondeur d'un objet donné. Normalement, lorsque vous dupliquez un objet qui contient d'autres objets, Ruby ne les duplique pas, il crée donc une copie superficielle de l'objet. Si vous avez un tableau avec une chaîne, par exemple, cela ressemblera à ceci:

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

duplicate.push 'another-string'

# l'objet a été dupliqué, donc l'élément a été ajouté uniquement à la copie
array     # => ['string']
duplicate # => ['string', 'another-string']

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

# le premier élément n'a pas été dupliqué, il sera modifié dans les deux tableaux
array     # => ['foo']
duplicate # => ['foo', 'another-string']

Comme vous pouvez le voir, après avoir dupliqué l'instance Array, nous avons obtenu un autre objet, donc nous pouvons le modifier et l'objet original restera inchangé. Cependant, cela n'est pas vrai pour les éléments du tableau. Comme dup ne fait pas de copie en profondeur, la chaîne à l'intérieur du tableau est toujours le même objet.

Si vous avez besoin d'une copie en profondeur d'un objet, vous devez utiliser deep_dup. Voici un exemple:

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

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

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

Si l'objet n'est pas duplicable, deep_dup le renverra simplement:

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

Défini dans active_support/core_ext/object/deep_dup.rb.

2.5 `try`

Lorsque vous souhaitez appeler une méthode sur un objet uniquement s'il n'est pas nil, la manière la plus simple de le faire est d'utiliser des instructions conditionnelles, ce qui ajoute un encombrement inutile. L'alternative est d'utiliser try. try est comme Object#public_send, sauf qu'il renvoie nil s'il est envoyé à nil. Voici un exemple :

# sans try
unless @number.nil?
  @number.next
end

# avec try
@number.try(:next)

Un autre exemple est ce code de ActiveRecord::ConnectionAdapters::AbstractAdapter où @logger pourrait être nil. Vous pouvez voir que le code utilise try et évite une vérification inutile.

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 peut également être appelé sans arguments mais avec un bloc, qui ne sera exécuté que si l'objet n'est pas nul :

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

Notez que try va ignorer les erreurs de méthode inexistante, renvoyant à la place nil. Si vous voulez vous protéger contre les fautes de frappe, utilisez try! à la place :

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

NOTE : Défini dans active_support/core_ext/object/try.rb.

2.6 `class_eval(*args, &block)`

Vous pouvez évaluer du code dans le contexte de la classe singleton de n'importe quel objet en utilisant 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

NOTE : Défini dans active_support/core_ext/kernel/singleton_class.rb.

2.7 `acts_like?(duck)`

La méthode acts_like? permet de vérifier si une classe se comporte comme une autre classe en se basant sur une simple convention : une classe qui fournit la même interface que String définit

def acts_like_string?
end

qui est simplement un marqueur, son corps ou sa valeur de retour sont sans importance. Ensuite, le code client peut interroger la conformité au type de canard de cette manière :

some_klass.acts_like?(:string)

Rails possède des classes qui se comportent comme Date ou Time et qui suivent ce contrat.

NOTE : Défini dans active_support/core_ext/object/acts_like.rb.

2.8 `to_param`

Tous les objets dans Rails répondent à la méthode to_param, qui est censée renvoyer quelque chose qui les représente comme des valeurs dans une chaîne de requête ou comme des fragments d'URL.

Par défaut, to_param appelle simplement to_s :

7.to_param # => "7"

La valeur de retour de to_param ne doit pas être échappée :

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

Plusieurs classes dans Rails redéfinissent cette méthode.

Par exemple, nil, true et false renvoient eux-mêmes. Array#to_param appelle to_param sur les éléments et joint le résultat avec "/":

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

Il est important de noter que le système de routage de Rails appelle to_param sur les modèles pour obtenir une valeur pour le paramètre :id. ActiveRecord::Base#to_param renvoie l'id d'un modèle, mais vous pouvez redéfinir cette méthode dans vos modèles. Par exemple, avec :

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

nous obtenons :

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

ATTENTION. Les contrôleurs doivent être conscients de toute redéfinition de to_param car lorsque cette requête arrive, "357-john-smith" est la valeur de params[:id].

NOTE : Défini dans active_support/core_ext/object/to_param.rb.

2.9 `to_query`

La méthode to_query construit une chaîne de requête qui associe une clé donnée à la valeur renvoyée par to_param. Par exemple, avec la définition to_param suivante :

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

nous obtenons :

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

Cette méthode échappe tout ce qui est nécessaire, à la fois pour la clé et pour la valeur :

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

ainsi sa sortie est prête à être utilisée dans une chaîne de requête. Les tableaux renvoient le résultat de l'application de to_query à chaque élément avec key[] comme clé, et joignent le résultat avec "&":

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

Les hachages répondent également à to_query mais avec une signature différente. Si aucun argument n'est passé, un appel génère une série triée d'assignations clé/valeur en appelant to_query(key) sur ses valeurs. Ensuite, il joint le résultat avec "&":

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

La méthode Hash#to_query accepte un espace de noms facultatif pour les clés:

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

NOTE : Défini dans active_support/core_ext/object/to_query.rb.

2.10 `with_options`

La méthode with_options permet de regrouper des options communes dans une série d'appels de méthode.

Étant donné un hachage d'options par défaut, with_options renvoie un objet proxy à un bloc. Dans le bloc, les méthodes appelées sur le proxy sont transmises au receveur avec leurs options fusionnées. Par exemple, vous pouvez vous débarrasser de la duplication dans :

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

de cette manière :

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

Cette expression peut également transmettre un regroupement au lecteur. Par exemple, supposons que vous souhaitiez envoyer une newsletter dont la langue dépend de l'utilisateur. Vous pouvez regrouper les éléments dépendant de la langue quelque part dans le mailer de cette manière :

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

CONSEIL : Comme with_options transmet les appels à son receveur, ils peuvent être imbriqués. Chaque niveau d'imbrication fusionnera les valeurs par défaut héritées en plus des siennes propres.

NOTE : Défini dans active_support/core_ext/object/with_options.rb.

2.11 Support JSON

Active Support fournit une meilleure implémentation de to_json que la gemme json ne le fait normalement pour les objets Ruby. Cela est dû au fait que certaines classes, comme Hash et Process::Status, nécessitent un traitement spécial pour fournir une représentation JSON appropriée.

NOTE : Défini dans active_support/core_ext/object/json.rb.

2.12 Variables d'instance

Active Support fournit plusieurs méthodes pour faciliter l'accès aux variables d'instance.

2.12.1 `instance_values`

La méthode instance_values renvoie un hachage qui fait correspondre les noms de variables d'instance sans "@" à leurs valeurs correspondantes. Les clés sont des chaînes de caractères :

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

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

NOTE : Défini dans active_support/core_ext/object/instance_variables.rb.

2.12.2 `instance_variable_names`

La méthode instance_variable_names renvoie un tableau. Chaque nom inclut le signe "@".

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

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

NOTE : Défini dans active_support/core_ext/object/instance_variables.rb.

2.13 Suppression des avertissements et des exceptions

Les méthodes silence_warnings et enable_warnings modifient la valeur de $VERBOSE en conséquence pendant la durée de leur bloc, puis la réinitialisent :

silence_warnings { Object.const_set "RAILS_DEFAULT_LOGGER", logger }

Il est également possible de supprimer les exceptions avec suppress. Cette méthode reçoit un nombre arbitraire de classes d'exceptions. Si une exception est levée pendant l'exécution du bloc et qu'elle est kind_of? l'un des arguments, suppress la capture et la renvoie silencieusement. Sinon, l'exception n'est pas capturée : ```ruby

Si l'utilisateur est verrouillé, l'incrément est perdu, pas de problème majeur.

suppress(ActiveRecord::StaleObjectError) do current_user.increment! :visits end ```

NOTE : Défini dans active_support/core_ext/kernel/reporting.rb.

2.14 `in?`

Le prédicat in? teste si un objet est inclus dans un autre objet. Une exception ArgumentError sera levée si l'argument passé ne répond pas à include?.

Exemples de in? :

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

NOTE : Défini dans active_support/core_ext/object/inclusion.rb.

3 Extensions à `Module`

3.1 Attributs

3.1.1 `alias_attribute`

Les attributs du modèle ont un lecteur, un écrivain et un prédicat. Vous pouvez créer un alias pour un attribut du modèle en utilisant alias_attribute, qui définit automatiquement les trois méthodes correspondantes pour vous. Comme pour les autres méthodes d'aliasing, le nouveau nom est le premier argument et l'ancien nom est le deuxième (un moyen mnémotechnique est de les mettre dans le même ordre que si vous faisiez une affectation) :

class User < ApplicationRecord
  # Vous pouvez vous référer à la colonne email en tant que "login".
  # Cela peut être utile pour le code d'authentification.
  alias_attribute :login, :email
end

NOTE : Défini dans active_support/core_ext/module/aliasing.rb.

3.1.2 Attributs internes

Lorsque vous définissez un attribut dans une classe destinée à être sous-classée, les collisions de noms sont un risque. Cela est particulièrement important pour les bibliothèques.

Active Support définit les macros attr_internal_reader, attr_internal_writer et attr_internal_accessor. Elles fonctionnent comme leurs homologues Ruby attr_*, à la différence qu'elles nomment la variable d'instance sous-jacente de manière à réduire les risques de collision.

La macro attr_internal est un synonyme de attr_internal_accessor :

# bibliothèque
class ThirdPartyLibrary::Crawler
  attr_internal :log_level
end

# code client
class MyCrawler < ThirdPartyLibrary::Crawler
  attr_accessor :log_level
end

Dans l'exemple précédent, il se peut que :log_level n'appartienne pas à l'interface publique de la bibliothèque et qu'il ne soit utilisé que pour le développement. Le code client, ignorant le risque de conflit, sous-classe et définit son propre :log_level. Grâce à attr_internal, il n'y a pas de collision.

Par défaut, la variable d'instance interne est nommée avec un tiret bas en préfixe, @_log_level dans l'exemple ci-dessus. Cela peut être configuré via Module.attr_internal_naming_format, vous pouvez passer n'importe quelle chaîne de format sprintf avec un @ en préfixe et un %s quelque part, où le nom sera placé. La valeur par défaut est "@_%s".

Rails utilise des attributs internes à quelques endroits, par exemple pour les vues :

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

NOTE : Défini dans active_support/core_ext/module/attr_internal.rb.

3.1.3 Attributs de module

Les macros mattr_reader, mattr_writer et mattr_accessor sont identiques aux macros cattr_* définies pour les classes. En fait, les macros cattr_* ne sont que des alias des macros mattr_*. Voir Attributs de classe.

Par exemple, l'API pour le journal de Active Storage est générée avec mattr_accessor :

module ActiveStorage
  mattr_accessor :logger
end

NOTE : Défini dans active_support/core_ext/module/attribute_accessors.rb.

3.2 Parents

3.2.1 `module_parent`

La méthode module_parent sur un module nommé imbriqué renvoie le module qui contient sa constante correspondante :

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

Si le module est anonyme ou appartient au niveau supérieur, module_parent renvoie Object. AVERTISSEMENT: Notez que dans ce cas, module_parent_name renvoie nil.

Défini dans active_support/core_ext/module/introspection.rb.

3.2.2 `module_parent_name`

La méthode module_parent_name sur un module nommé imbriqué renvoie le nom entièrement qualifié du module qui contient sa constante correspondante:

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"

Pour les modules de niveau supérieur ou anonymes, module_parent_name renvoie nil.

AVERTISSEMENT: Notez que dans ce cas, module_parent renvoie Object.

Défini dans active_support/core_ext/module/introspection.rb.

3.2.3 `module_parents`

La méthode module_parents appelle module_parent sur le receveur et remonte jusqu'à ce que Object soit atteint. La chaîne est renvoyée dans un tableau, du bas vers le haut:

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]

Défini dans active_support/core_ext/module/introspection.rb.

3.3 Anonyme

Un module peut avoir ou non un nom:

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

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

Module.new.name # => nil

Vous pouvez vérifier si un module a un nom avec le prédicat anonymous?:

module M
end
M.anonymous? # => false

Module.new.anonymous? # => true

Notez que le fait d'être inaccessible n'implique pas d'être anonyme:

module M
end

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

m.anonymous? # => false

bien qu'un module anonyme soit inaccessible par définition.

Défini dans active_support/core_ext/module/anonymous.rb.

3.4 Délégation de méthode

3.4.1 `delegate`

La macro delegate offre un moyen facile de déléguer des méthodes.

Imaginons que les utilisateurs dans une application aient des informations de connexion dans le modèle User mais un nom et d'autres données dans un modèle séparé Profile:

class User < ApplicationRecord
  has_one :profile
end

Avec cette configuration, vous obtenez le nom d'un utilisateur via son profil, user.profile.name, mais il pourrait être pratique de pouvoir toujours accéder à cet attribut directement:

class User < ApplicationRecord
  has_one :profile

  def name
    profile.name
  end
end

C'est ce que fait delegate pour vous:

class User < ApplicationRecord
  has_one :profile

  delegate :name, to: :profile
end

C'est plus court et l'intention est plus évidente.

La méthode doit être publique dans la cible.

La macro delegate accepte plusieurs méthodes:

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

Lorsqu'elle est interpolée dans une chaîne, l'option :to doit devenir une expression qui s'évalue à l'objet auquel la méthode est déléguée. Typiquement une chaîne de caractères ou un symbole. Une telle expression est évaluée dans le contexte du receveur:

# délègue à la constante Rails
delegate :logger, to: :Rails

# délègue à la classe du receveur
delegate :table_name, to: :class

AVERTISSEMENT: Si l'option :prefix est true, cela est moins générique, voir ci-dessous.

Par défaut, si la délégation génère une NoMethodError et que la cible est nil, l'exception est propagée. Vous pouvez demander que nil soit renvoyé à la place avec l'option :allow_nil:

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

Avec :allow_nil, l'appel user.name renvoie nil si l'utilisateur n'a pas de profil.

L'option :prefix ajoute un préfixe au nom de la méthode générée. Cela peut être pratique, par exemple, pour obtenir un meilleur nom: ruby delegate :street, to: :address, prefix: true

L'exemple précédent génère address_street plutôt que street.

AVERTISSEMENT: Dans ce cas, le nom de la méthode générée est composé des noms de l'objet cible et de la méthode cible, l'option :to doit donc être un nom de méthode.

Un préfixe personnalisé peut également être configuré:

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

Dans l'exemple précédent, la macro génère avatar_size plutôt que size.

L'option :private modifie la portée des méthodes:

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

Les méthodes déléguées sont publiques par défaut. Passez private: true pour changer cela.

Défini dans active_support/core_ext/module/delegation.rb

3.4.2 `delegate_missing_to`

Imaginez que vous souhaitez déléguer tout ce qui manque à l'objet User à l'objet Profile. La macro delegate_missing_to vous permet de mettre en œuvre cela facilement:

class User < ApplicationRecord
  has_one :profile

  delegate_missing_to :profile
end

La cible peut être n'importe quoi de callable dans l'objet, par exemple des variables d'instance, des méthodes, des constantes, etc. Seules les méthodes publiques de la cible sont déléguées.

Défini dans active_support/core_ext/module/delegation.rb.

3.5 Redéfinition des méthodes

Il existe des cas où vous devez définir une méthode avec define_method, mais vous ne savez pas si une méthode portant ce nom existe déjà. Si c'est le cas, un avertissement est émis s'ils sont activés. Ce n'est pas grave, mais ce n'est pas propre non plus.

La méthode redefine_method évite un tel avertissement potentiel, en supprimant la méthode existante si nécessaire.

Vous pouvez également utiliser silence_redefinition_of_method si vous avez besoin de définir la méthode de remplacement vous-même (parce que vous utilisez delegate, par exemple).

Défini dans active_support/core_ext/module/redefine_method.rb.

4 Extensions à `Class`

4.1 Attributs de classe

4.1.1 `class_attribute`

La méthode class_attribute déclare un ou plusieurs attributs de classe héritables qui peuvent être remplacés à n'importe quel niveau de la hiérarchie.

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

Par exemple, ActionMailer::Base définit:

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

Ils peuvent également être accédés et remplacés au niveau de l'instance.

A.x = 1

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

a1.x # => 1, provient de A
a2.x # => 2, remplacé dans a2

La génération de la méthode d'instance writer peut être empêchée en définissant l'option :instance_writer sur false.

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

Un modèle peut trouver cette option utile comme moyen d'empêcher l'attribution en masse de définir l'attribut.

La génération de la méthode d'instance reader peut être empêchée en définissant l'option :instance_reader sur false.

class A
  class_attribute :x, instance_reader: false
end

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

Pour plus de commodité, class_attribute définit également un prédicat d'instance qui est la double négation de ce que renvoie le lecteur d'instance. Dans les exemples ci-dessus, il serait appelé x?. Lorsque :instance_reader est false, le prédicat d'instance renvoie une NoMethodError tout comme la méthode de lecture.

Si vous ne souhaitez pas utiliser le prédicat d'instance, passez instance_predicate: false et il ne sera pas défini.

NOTE : Défini dans active_support/core_ext/class/attribute.rb.

4.1.2 `cattr_reader`, `cattr_writer` et `cattr_accessor`

Les macros cattr_reader, cattr_writer et cattr_accessor sont analogues à leurs homologues attr_* mais pour les classes. Elles initialisent une variable de classe à nil sauf si elle existe déjà, et génèrent les méthodes de classe correspondantes pour y accéder :

class MysqlAdapter < AbstractAdapter
  # Génère les méthodes de classe pour accéder à @@emulate_booleans.
  cattr_accessor :emulate_booleans
end

De plus, vous pouvez passer un bloc à cattr_* pour configurer l'attribut avec une valeur par défaut :

class MysqlAdapter < AbstractAdapter
  # Génère les méthodes de classe pour accéder à @@emulate_booleans avec une valeur par défaut de true.
  cattr_accessor :emulate_booleans, default: true
end

Des méthodes d'instance sont également créées pour plus de commodité, ce sont simplement des proxies vers l'attribut de classe. Ainsi, les instances peuvent modifier l'attribut de classe, mais ne peuvent pas le remplacer comme c'est le cas avec class_attribute (voir ci-dessus). Par exemple, étant donné

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

nous pouvons accéder à field_error_proc dans les vues.

La génération de la méthode de lecture de l'instance peut être empêchée en définissant :instance_reader sur false et la génération de la méthode d'écriture de l'instance peut être empêchée en définissant :instance_writer sur false. La génération des deux méthodes peut être empêchée en définissant :instance_accessor sur false. Dans tous les cas, la valeur doit être exactement false et non une fausse valeur quelconque.

module A
  class B
    # Aucune méthode de lecture de l'instance first_name n'est générée.
    cattr_accessor :first_name, instance_reader: false
    # Aucune méthode d'écriture de l'instance last_name= n'est générée.
    cattr_accessor :last_name, instance_writer: false
    # Aucune méthode de lecture de l'instance surname ou de l'écriture surname= n'est générée.
    cattr_accessor :surname, instance_accessor: false
  end
end

Un modèle peut trouver utile de définir :instance_accessor sur false comme moyen d'empêcher l'assignation en masse de définir l'attribut.

NOTE : Défini dans active_support/core_ext/module/attribute_accessors.rb.

4.2 Sous-classes et descendants

4.2.1 `subclasses`

La méthode subclasses renvoie les sous-classes du receveur :

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]

L'ordre dans lequel ces classes sont renvoyées n'est pas spécifié.

NOTE : Défini dans active_support/core_ext/class/subclasses.rb.

4.2.2 `descendants`

La méthode descendants renvoie toutes les classes qui sont < que son receveur :

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]

L'ordre dans lequel ces classes sont renvoyées n'est pas spécifié.

NOTE : Défini dans active_support/core_ext/class/subclasses.rb.

5 Extensions à `String`

5.1 Sécurité de la sortie

5.1.1 Motivation

Insérer des données dans des modèles HTML nécessite une attention particulière. Par exemple, vous ne pouvez pas simplement interpoler @review.title tel quel dans une page HTML. Pour une chose, si le titre de la revue est "Flanagan & Matz rules!", la sortie ne sera pas bien formée car un esperluette doit être échappée en "&". De plus, selon l'application, cela peut constituer une grande faille de sécurité car les utilisateurs peuvent injecter du code HTML malveillant en définissant un titre de revue spécialement conçu. Consultez la section sur les attaques de type cross-site scripting dans le guide de sécurité pour plus d'informations sur les risques.

5.1.2 Chaînes de caractères sécurisées

Active Support a le concept de chaînes de caractères (html) sécurisées. Une chaîne de caractères sécurisée est marquée comme pouvant être insérée dans du HTML telle quelle. Elle est considérée comme fiable, que ce soit échappée ou non.

Par défaut, les chaînes de caractères sont considérées comme non sécurisées :

"".html_safe? # => false

Vous pouvez obtenir une chaîne de caractères sécurisée à partir d'une chaîne donnée avec la méthode html_safe :

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

Il est important de comprendre que html_safe ne réalise aucune échappement, c'est simplement une assertion :

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

Il est de votre responsabilité de vous assurer que l'appel à html_safe sur une chaîne particulière est correct.

Si vous ajoutez une chaîne à une chaîne sécurisée, que ce soit en place avec concat/<<, ou avec +, le résultat est une chaîne sécurisée. Les arguments non sécurisés sont échappés :

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

Les arguments sécurisés sont directement ajoutés :

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

Ces méthodes ne doivent pas être utilisées dans les vues ordinaires. Les valeurs non sécurisées sont automatiquement échappées :

<%= @review.title %> <%# correct, échappé si nécessaire %>

Pour insérer quelque chose tel quel, utilisez l'aide raw plutôt que d'appeler html_safe :

<%= raw @cms.current_template %> <%# insère @cms.current_template tel quel %>

ou, de manière équivalente, utilisez <%== :

<%== @cms.current_template %> <%# insère @cms.current_template tel quel %>

L'aide raw appelle html_safe pour vous :

def raw(stringish)
  stringish.to_s.html_safe
end

NOTE : Défini dans active_support/core_ext/string/output_safety.rb.

5.1.3 Transformation

En règle générale, à l'exception peut-être de la concaténation comme expliqué ci-dessus, toute méthode qui peut modifier une chaîne de caractères vous donne une chaîne non sécurisée. Il s'agit de downcase, gsub, strip, chomp, underscore, etc.

Dans le cas des transformations en place comme gsub!, le récepteur lui-même devient non sécurisé.

INFO : Le bit de sécurité est toujours perdu, que la transformation ait effectivement changé quelque chose ou non.

5.1.4 Conversion et coercition

Appeler to_s sur une chaîne de caractères sécurisée renvoie une chaîne de caractères sécurisée, mais la coercition avec to_str renvoie une chaîne de caractères non sécurisée.

5.1.5 Copie

Appeler dup ou clone sur des chaînes de caractères sécurisées donne des chaînes de caractères sécurisées.

5.2 `remove`

La méthode remove supprime toutes les occurrences du motif :

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

Il existe également la version destructive String#remove!.

NOTE : Défini dans active_support/core_ext/string/filters.rb.

5.3 `squish`

La méthode squish supprime les espaces vides en début et en fin de chaîne, et remplace les séries d'espaces vides par un seul espace :

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

Il existe également la version destructive String#squish!.

Notez qu'elle gère à la fois les espaces vides ASCII et Unicode.

NOTE : Défini dans active_support/core_ext/string/filters.rb.

5.4 `truncate`

La méthode truncate renvoie une copie de la chaîne de caractères tronquée après une longueur donnée :

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

L'ellipse peut être personnalisée avec l'option :omission :

"Oh dear! Oh dear! I shall be late!".truncate(20, omission: '&hellip;')
# => "Oh dear! Oh &hellip;"

Notez en particulier que la troncature prend en compte la longueur de la chaîne d'omission.

Passez un :separator pour tronquer la chaîne à une rupture naturelle : ```ruby "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..."


L'option `:separator` peut être une expression régulière :

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

Dans les exemples ci-dessus, "dear" est coupé en premier, mais :separator l'empêche ensuite.

NOTE : Défini dans active_support/core_ext/string/filters.rb.

5.5 `truncate_bytes`

La méthode truncate_bytes renvoie une copie de son objet tronqué à un maximum de bytesize octets :

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

L'omission peut être personnalisée avec l'option :omission :

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

NOTE : Défini dans active_support/core_ext/string/filters.rb.

5.6 `truncate_words`

La méthode truncate_words renvoie une copie de son objet tronqué après un certain nombre de mots :

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

L'omission peut être personnalisée avec l'option :omission :

"Oh dear! Oh dear! I shall be late!".truncate_words(4, omission: '&hellip;')
# => "Oh dear! Oh dear!&hellip;"

Passez un :separator pour tronquer la chaîne à une rupture naturelle :

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

L'option :separator peut être une expression régulière :

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

NOTE : Défini dans active_support/core_ext/string/filters.rb.

5.7 `inquiry`

La méthode inquiry convertit une chaîne de caractères en un objet StringInquirer, rendant les comparaisons d'égalité plus jolies.

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

NOTE : Défini dans active_support/core_ext/string/inquiry.rb.

5.8 `starts_with?` et `ends_with?`

Active Support définit des alias à la troisième personne de String#start_with? et String#end_with? :

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

NOTE : Défini dans active_support/core_ext/string/starts_ends_with.rb.

5.9 `strip_heredoc`

La méthode strip_heredoc supprime l'indentation dans les heredocs.

Par exemple, dans

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

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

l'utilisateur verra le message d'utilisation aligné contre la marge gauche.

Techniquement, elle recherche la ligne avec le moins d'indentation dans toute la chaîne, et supprime cette quantité d'espaces en début de ligne.

NOTE : Défini dans active_support/core_ext/string/strip.rb.

5.10 `indent`

La méthode indent indente les lignes de l'objet :

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

Le deuxième argument, indent_string, spécifie quelle chaîne d'indentation utiliser. Par défaut, c'est nil, ce qui indique à la méthode de deviner en regardant la première ligne indentée, et de revenir à un espace s'il n'y en a pas.

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

Bien que indent_string soit généralement un espace ou une tabulation, il peut être n'importe quelle chaîne de caractères.

Le troisième argument, indent_empty_lines, est un indicateur qui indique si les lignes vides doivent être indentées. Par défaut, c'est false.

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

La méthode indent! effectue l'indentation sur place.

NOTE : Défini dans active_support/core_ext/string/indent.rb.

5.11 Accès

5.11.1 `at(position)`

La méthode at renvoie le caractère de la chaîne de caractères à la position position :

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

NOTE : Défini dans active_support/core_ext/string/access.rb.

5.11.2 `from(position)`

La méthode from renvoie la sous-chaîne de caractères de la chaîne de caractères à partir de la position position :

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

NOTE : Défini dans active_support/core_ext/string/access.rb.

5.11.3 `to(position)`

La méthode to renvoie la sous-chaîne de caractères de la chaîne de caractères jusqu'à la position position :

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

NOTE : Défini dans active_support/core_ext/string/access.rb.

5.11.4 `first(limit = 1)`

La méthode first renvoie une sous-chaîne de caractères contenant les limit premiers caractères de la chaîne de caractères.

L'appel str.first(n) est équivalent à str.to(n-1) si n > 0, et renvoie une chaîne vide pour n == 0.

NOTE : Défini dans active_support/core_ext/string/access.rb.

5.11.5 `last(limit = 1)`

La méthode last renvoie une sous-chaîne de caractères contenant les limit derniers caractères de la chaîne de caractères.

L'appel str.last(n) est équivalent à str.from(-n) si n > 0, et renvoie une chaîne vide pour n == 0.

NOTE : Défini dans active_support/core_ext/string/access.rb.

5.12 Inflections

5.12.1 `pluralize`

La méthode pluralize renvoie le pluriel de son objet :

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

Comme le montre l'exemple précédent, Active Support connaît certains pluriels irréguliers et des noms non dénombrables. Les règles intégrées peuvent être étendues dans config/initializers/inflections.rb. Ce fichier est généré par défaut par la commande rails new et contient des instructions en commentaires.

pluralize peut également prendre un paramètre optionnel count. Si count == 1, la forme singulière sera renvoyée. Pour toute autre valeur de count, la forme plurielle sera renvoyée :

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

Active Record utilise cette méthode pour calculer le nom de table par défaut correspondant à un modèle :

# 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

NOTE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.2 `singularize`

La méthode singularize est l'inverse de pluralize :

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

Les associations calculent le nom de la classe associée par défaut en utilisant cette méthode :

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

NOTE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.3 `camelize`

La méthode camelize renvoie son objet en camel case :

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

En règle générale, vous pouvez considérer cette méthode comme celle qui transforme les chemins en noms de classes ou de modules Ruby, où les barres obliques séparent les espaces de noms :

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

Par exemple, Action Pack utilise cette méthode pour charger la classe qui fournit un certain magasin de session :

# 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 accepte un argument optionnel, qui peut être :upper (par défaut) ou :lower. Avec ce dernier, la première lettre devient en minuscule : ruby "visual_effect".camelize(:lower) # => "visualEffect"

Cela peut être pratique pour calculer des noms de méthodes dans une langue qui suit cette convention, par exemple JavaScript.

En règle générale, vous pouvez considérer camelize comme l'inverse de underscore, bien qu'il existe des cas où cela ne s'applique pas: "SSLError".underscore.camelize renvoie "SslError". Pour prendre en charge des cas comme celui-ci, Active Support vous permet de spécifier des acronymes dans config/initializers/inflections.rb:

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

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

camelize est un alias de camelcase.

Défini dans active_support/core_ext/string/inflections.rb.

5.12.4 `underscore`

La méthode underscore fait l'inverse, du camel case aux chemins:

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

Convertit également "::" en "/":

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

et comprend les chaînes qui commencent par une minuscule:

"visualEffect".underscore # => "visual_effect"

underscore n'accepte aucun argument.

Rails utilise underscore pour obtenir un nom en minuscules pour les classes de contrôleur:

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

Par exemple, cette valeur est celle que vous obtenez dans params[:controller].

En règle générale, vous pouvez considérer underscore comme l'inverse de camelize, bien qu'il existe des cas où cela ne s'applique pas. Par exemple, "SSLError".underscore.camelize renvoie "SslError".

Défini dans active_support/core_ext/string/inflections.rb.

5.12.5 `titleize`

La méthode titleize met en majuscule les mots dans la chaîne:

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

titleize est un alias de titlecase.

Défini dans active_support/core_ext/string/inflections.rb.

5.12.6 `dasherize`

La méthode dasherize remplace les underscores dans la chaîne par des tirets:

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

Le sérialiseur XML des modèles utilise cette méthode pour transformer les noms de nœuds en tirets:

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

Défini dans active_support/core_ext/string/inflections.rb.

5.12.7 `demodulize`

Étant donné une chaîne avec un nom de constante qualifié, demodulize renvoie le nom de la constante lui-même, c'est-à-dire la partie la plus à droite:

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

Active Record utilise par exemple cette méthode pour calculer le nom d'une colonne de cache de compteur:

# 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

Défini dans active_support/core_ext/string/inflections.rb.

5.12.8 `deconstantize`

Étant donné une chaîne avec une expression de référence de constante qualifiée, deconstantize supprime le segment le plus à droite, laissant généralement le nom du conteneur de la constante:

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

Défini dans active_support/core_ext/string/inflections.rb.

5.12.9 `parameterize`

La méthode parameterize normalise la chaîne de manière à pouvoir être utilisée dans les URL conviviales.

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

Pour conserver la casse de la chaîne, définissez l'argument preserve_case sur true. Par défaut, preserve_case est défini sur false.

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

Pour utiliser un séparateur personnalisé, remplacez l'argument separator.

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

REMARQUE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.10 `tableize`

La méthode tableize est underscore suivie de pluralize.

"Personne".tableize      # => "people"
"Facture".tableize     # => "invoices"
"LigneFacture".tableize # => "invoice_lines"

En règle générale, tableize renvoie le nom de la table correspondant à un modèle donné pour les cas simples. L'implémentation réelle dans Active Record n'est pas simplement tableize, car elle démodule également le nom de la classe et vérifie quelques options qui peuvent affecter la chaîne renvoyée.

REMARQUE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.11 `classify`

La méthode classify est l'inverse de tableize. Elle vous donne le nom de classe correspondant à un nom de table :

"people".classify        # => "Personne"
"invoices".classify      # => "Facture"
"invoice_lines".classify # => "LigneFacture"

La méthode comprend les noms de table qualifiés :

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

Notez que classify renvoie un nom de classe sous forme de chaîne. Vous pouvez obtenir l'objet de classe réel en invoquant constantize dessus, expliqué ensuite.

REMARQUE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.12 `constantize`

La méthode constantize résout l'expression de référence constante dans son receveur :

"Integer".constantize # => Integer

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

Si la chaîne ne correspond à aucune constante connue, ou si son contenu n'est même pas un nom de constante valide, constantize génère une NameError.

La résolution du nom de constante par constantize commence toujours au niveau supérieur de Object, même s'il n'y a pas de "::" au début.

X = :in_Object
module M
  X = :in_M

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

Ainsi, en général, cela n'est pas équivalent à ce que Ruby ferait au même endroit, si une vraie constante était évaluée.

Les cas de test des mailers obtiennent le mailer testé à partir du nom de la classe de test en utilisant constantize :

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

REMARQUE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.13 `humanize`

La méthode humanize ajuste un nom d'attribut pour l'affichage aux utilisateurs finaux.

Plus précisément, elle effectue ces transformations :

Applique les règles d'inflection humaine à l'argument.
Supprime les tirets bas initiaux, le cas échéant.
Supprime le suffixe "_id" s'il est présent.
Remplace les tirets bas par des espaces, le cas échéant.
Met en minuscule tous les mots sauf les acronymes.
Met en majuscule le premier mot.

La majuscule du premier mot peut être désactivée en définissant l'option :capitalize sur false (par défaut, true).

"name".humanize                         # => "Nom"
"author_id".humanize                    # => "Auteur"
"author_id".humanize(capitalize: false) # => "auteur"
"comments_count".humanize               # => "Nombre de commentaires"
"_id".humanize                          # => "Id"

Si "SSL" est défini comme un acronyme :

'ssl_error'.humanize # => "Erreur SSL"

La méthode d'aide full_messages utilise humanize comme solution de secours pour inclure les noms d'attributs :

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

REMARQUE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.14 `foreign_key`

La méthode foreign_key donne le nom de la colonne de clé étrangère à partir d'un nom de classe. Pour ce faire, elle démodule, ajoute des tirets bas et ajoute "_id" :

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

Passez un argument faux si vous ne voulez pas de tiret bas dans "_id":

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

Les associations utilisent cette méthode pour déduire les clés étrangères, par exemple has_one et has_many font cela:

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

NOTE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.15 `upcase_first`

La méthode upcase_first met en majuscule la première lettre du récepteur :

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

NOTE : Défini dans active_support/core_ext/string/inflections.rb.

5.12.16 `downcase_first`

La méthode downcase_first convertit la première lettre du récepteur en minuscule :

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

NOTE : Défini dans active_support/core_ext/string/inflections.rb.

5.13 Conversions

5.13.1 `to_date`, `to_time`, `to_datetime`

Les méthodes to_date, to_time et to_datetime sont essentiellement des enveloppes pratiques autour de 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 reçoit un argument facultatif :utc ou :local, pour indiquer dans quel fuseau horaire vous voulez l'heure :

"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

La valeur par défaut est :local.

Veuillez vous référer à la documentation de Date._parse pour plus de détails.

INFO : Les trois renvoient nil pour les récepteurs vides.

NOTE : Défini dans active_support/core_ext/string/conversions.rb.

6 Extensions à `Symbol`

6.1 `starts_with?` et `ends_with?`

Active Support définit des alias à la troisième personne de Symbol#start_with? et Symbol#end_with? :

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

NOTE : Défini dans active_support/core_ext/symbol/starts_ends_with.rb.

7 Extensions à `Numeric`

7.1 Bytes

Tous les nombres répondent à ces méthodes :

Elles renvoient la quantité correspondante d'octets, en utilisant un facteur de conversion de 1024 :

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

Les formes singulières sont des alias, vous pouvez donc dire :

1.megabyte # => 1048576

NOTE : Défini dans active_support/core_ext/numeric/bytes.rb.

7.2 Time

Les méthodes suivantes :

permettent les déclarations et les calculs de temps, comme 45.minutes + 2.hours + 4.weeks. Leurs valeurs de retour peuvent également être ajoutées ou soustraites des objets Time.

Ces méthodes peuvent être combinées avec from_now, ago, etc, pour des calculs de date précis. Par exemple :

# équivalent à Time.current.advance(days: 1)
1.day.from_now

# équivalent à Time.current.advance(weeks: 2)
2.weeks.from_now

# équivalent à Time.current.advance(days: 4, weeks: 5)
(4.days + 5.weeks).from_now

ATTENTION. Pour d'autres durées, veuillez vous référer aux extensions de temps à Integer.

NOTE : Défini dans active_support/core_ext/numeric/time.rb.

7.3 Formatage

Permet le formatage des nombres de différentes manières.

Produire une représentation sous forme de chaîne d'un nombre en tant que numéro de téléphone :

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

Produire une représentation sous forme de chaîne d'un nombre en tant que devise :

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

Produire une représentation sous forme de chaîne d'un nombre en pourcentage:

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

Produire une représentation sous forme de chaîne d'un nombre en forme délimitée:

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

Produire une représentation sous forme de chaîne d'un nombre arrondi à une précision:

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

Produire une représentation sous forme de chaîne d'un nombre en tant que nombre de bytes lisible par un humain:

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

Produire une représentation sous forme de chaîne d'un nombre en mots lisibles par un humain:

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

Défini dans active_support/core_ext/numeric/conversions.rb.

8 Extensions à `Integer`

8.1 `multiple_of?`

La méthode multiple_of? teste si un entier est un multiple de l'argument:

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

Défini dans active_support/core_ext/integer/multiple.rb.

8.2 `ordinal`

La méthode ordinal renvoie la chaîne de suffixe ordinal correspondant à l'entier:

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

Défini dans active_support/core_ext/integer/inflections.rb.

8.3 `ordinalize`

La méthode ordinalize renvoie la chaîne ordinale correspondant à l'entier. En comparaison, notez que la méthode ordinal renvoie seulement la chaîne de suffixe.

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

Défini dans active_support/core_ext/integer/inflections.rb.

8.4 Time

Les méthodes suivantes:

permettent les déclarations et les calculs de temps, comme 4.months + 5.years. Leurs valeurs de retour peuvent également être ajoutées ou soustraites des objets Time.

Ces méthodes peuvent être combinées avec from_now, ago, etc, pour des calculs de dates précis. Par exemple:

# équivalent à Time.current.advance(months: 1)
1.month.from_now

# équivalent à Time.current.advance(years: 2)
2.years.from_now

# équivalent à Time.current.advance(months: 4, years: 5)
(4.months + 5.years).from_now

ATTENTION. Pour d'autres durées, veuillez vous référer aux extensions de temps à Numeric.

Défini dans active_support/core_ext/integer/time.rb.

9 Extensions à `BigDecimal`

9.1 `to_s`

La méthode to_s fournit un spécificateur par défaut de "F". Cela signifie qu'un simple appel à to_s donnera une représentation en virgule flottante au lieu de la notation scientifique:

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

La notation scientifique est toujours prise en charge:

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

10 Extensions à `Enumerable`

10.1 `sum`

La méthode sum ajoute les éléments d'un énumérable: ruby [1, 2, 3].sum # => 6 (1..100).sum # => 5050

L'addition suppose seulement que les éléments répondent à +:

[[1, 2], [2, 3], [3, 4]].sum    # => [1, 2, 2, 3, 3, 4]
%w(foo bar baz).sum             # => "foobarbaz"
{ a: 1, b: 2, c: 3 }.sum          # => [:a, 1, :b, 2, :c, 3]

La somme d'une collection vide est zéro par défaut, mais cela peut être personnalisé:

[].sum    # => 0
[].sum(1) # => 1

Si un bloc est donné, sum devient un itérateur qui renvoie les éléments de la collection et additionne les valeurs renvoyées:

(1..5).sum { |n| n * 2 } # => 30
[2, 4, 6, 8, 10].sum    # => 30

La somme d'un récepteur vide peut également être personnalisée sous cette forme:

[].sum(1) { |n| n**3 } # => 1