From 5ea3f284a4d07f5572f7ae2a7442cca8761fa8fc Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 14 Sep 2012 22:44:06 -0500 Subject: update AS/inflector docs [ci skip] --- .../lib/active_support/inflector/inflections.rb | 112 ++++++++++++--------- 1 file changed, 64 insertions(+), 48 deletions(-) (limited to 'activesupport/lib/active_support/inflector/inflections.rb') diff --git a/activesupport/lib/active_support/inflector/inflections.rb b/activesupport/lib/active_support/inflector/inflections.rb index 091692e5a4..af506d6f2e 100644 --- a/activesupport/lib/active_support/inflector/inflections.rb +++ b/activesupport/lib/active_support/inflector/inflections.rb @@ -5,9 +5,10 @@ module ActiveSupport module Inflector extend self - # A singleton instance of this class is yielded by Inflector.inflections, which can then be used to specify additional - # inflection rules. If passed an optional locale, rules for other languages can be specified. The default locale is - # :en. Only rules for English are provided. + # A singleton instance of this class is yielded by Inflector.inflections, + # which can then be used to specify additional inflection rules. If passed + # an optional locale, rules for other languages can be specified. The + # default locale is :en. Only rules for English are provided. # # ActiveSupport::Inflector.inflections(:en) do |inflect| # inflect.plural /^(ox)$/i, '\1\2en' @@ -15,12 +16,13 @@ module ActiveSupport # # inflect.irregular 'octopus', 'octopi' # - # inflect.uncountable "equipment" + # inflect.uncountable 'equipment' # end # - # New rules are added at the top. So in the example above, the irregular rule for octopus will now be the first of the - # pluralization and singularization rules that is runs. This guarantees that your rules run before any of the rules that may - # already have been loaded. + # New rules are added at the top. So in the example above, the irregular + # rule for octopus will now be the first of the pluralization and + # singularization rules that is runs. This guarantees that your rules run + # before any of the rules that may already have been loaded. class Inflections def self.instance(locale = :en) @__instance__ ||= Hash.new { |h, k| h[k] = new } @@ -34,36 +36,40 @@ module ActiveSupport end # Private, for the test suite. - def initialize_dup(orig) + def initialize_dup(orig) # :nodoc: %w(plurals singulars uncountables humans acronyms acronym_regex).each do |scope| instance_variable_set("@#{scope}", orig.send(scope).dup) end end - # Specifies a new acronym. An acronym must be specified as it will appear in a camelized string. An underscore - # string that contains the acronym will retain the acronym when passed to `camelize`, `humanize`, or `titleize`. - # A camelized string that contains the acronym will maintain the acronym when titleized or humanized, and will - # convert the acronym into a non-delimited single lowercase word when passed to +underscore+. + # Specifies a new acronym. An acronym must be specified as it will appear + # in a camelized string. An underscore string that contains the acronym + # will retain the acronym when passed to +camelize+, +humanize+, or + # +titleize+. A camelized string that contains the acronym will maintain + # the acronym when titleized or humanized, and will convert the acronym + # into a non-delimited single lowercase word when passed to +underscore+. # # acronym 'HTML' - # titleize 'html' #=> 'HTML' - # camelize 'html' #=> 'HTML' + # titleize 'html' #=> 'HTML' + # camelize 'html' #=> 'HTML' # underscore 'MyHTML' #=> 'my_html' # - # The acronym, however, must occur as a delimited unit and not be part of another word for conversions to recognize it: + # The acronym, however, must occur as a delimited unit and not be part of + # another word for conversions to recognize it: # # acronym 'HTTP' # camelize 'my_http_delimited' #=> 'MyHTTPDelimited' - # camelize 'https' #=> 'Https', not 'HTTPs' - # underscore 'HTTPS' #=> 'http_s', not 'https' + # camelize 'https' #=> 'Https', not 'HTTPs' + # underscore 'HTTPS' #=> 'http_s', not 'https' # # acronym 'HTTPS' - # camelize 'https' #=> 'HTTPS' + # camelize 'https' #=> 'HTTPS' # underscore 'HTTPS' #=> 'https' # - # Note: Acronyms that are passed to `pluralize` will no longer be recognized, since the acronym will not occur as - # a delimited unit in the pluralized result. To work around this, you must specify the pluralized form as an - # acronym as well: + # Note: Acronyms that are passed to +pluralize+ will no longer be + # recognized, since the acronym will not occur as a delimited unit in the + # pluralized result. To work around this, you must specify the pluralized + # form as an acronym as well: # # acronym 'API' # camelize(pluralize('api')) #=> 'Apis' @@ -71,42 +77,49 @@ module ActiveSupport # acronym 'APIs' # camelize(pluralize('api')) #=> 'APIs' # - # `acronym` may be used to specify any word that contains an acronym or otherwise needs to maintain a non-standard - # capitalization. The only restriction is that the word must begin with a capital letter. + # +acronym+ may be used to specify any word that contains an acronym or + # otherwise needs to maintain a non-standard capitalization. The only + # restriction is that the word must begin with a capital letter. # # acronym 'RESTful' - # underscore 'RESTful' #=> 'restful' + # underscore 'RESTful' #=> 'restful' # underscore 'RESTfulController' #=> 'restful_controller' - # titleize 'RESTfulController' #=> 'RESTful Controller' - # camelize 'restful' #=> 'RESTful' - # camelize 'restful_controller' #=> 'RESTfulController' + # titleize 'RESTfulController' #=> 'RESTful Controller' + # camelize 'restful' #=> 'RESTful' + # camelize 'restful_controller' #=> 'RESTfulController' # # acronym 'McDonald' # underscore 'McDonald' #=> 'mcdonald' - # camelize 'mcdonald' #=> 'McDonald' + # camelize 'mcdonald' #=> 'McDonald' def acronym(word) @acronyms[word.downcase] = word @acronym_regex = /#{@acronyms.values.join("|")}/ end - # Specifies a new pluralization rule and its replacement. The rule can either be a string or a regular expression. - # The replacement should always be a string that may include references to the matched data from the rule. + # Specifies a new pluralization rule and its replacement. The rule can + # either be a string or a regular expression. The replacement should + # always be a string that may include references to the matched data from + # the rule. def plural(rule, replacement) @uncountables.delete(rule) if rule.is_a?(String) @uncountables.delete(replacement) @plurals.prepend([rule, replacement]) end - # Specifies a new singularization rule and its replacement. The rule can either be a string or a regular expression. - # The replacement should always be a string that may include references to the matched data from the rule. + # Specifies a new singularization rule and its replacement. The rule can + # either be a string or a regular expression. The replacement should + # always be a string that may include references to the matched data from + # the rule. def singular(rule, replacement) @uncountables.delete(rule) if rule.is_a?(String) @uncountables.delete(replacement) @singulars.prepend([rule, replacement]) end - # Specifies a new irregular that applies to both pluralization and singularization at the same time. This can only be used - # for strings, not regular expressions. You simply pass the irregular in singular and plural form. + # Specifies a new irregular that applies to both pluralization and + # singularization at the same time. This can only be used for strings, not + # regular expressions. You simply pass the irregular in singular and + # plural form. # # irregular 'octopus', 'octopi' # irregular 'person', 'people' @@ -129,26 +142,29 @@ module ActiveSupport # Add uncountable words that shouldn't be attempted inflected. # - # uncountable "money" - # uncountable "money", "information" + # uncountable 'money' + # uncountable 'money', 'information' # uncountable %w( money information rice ) def uncountable(*words) (@uncountables << words).flatten! end - # Specifies a humanized form of a string by a regular expression rule or by a string mapping. - # When using a regular expression based replacement, the normal humanize formatting is called after the replacement. - # When a string is used, the human form should be specified as desired (example: 'The name', not 'the_name') + # Specifies a humanized form of a string by a regular expression rule or + # by a string mapping. When using a regular expression based replacement, + # the normal humanize formatting is called after the replacement. When a + # string is used, the human form should be specified as desired (example: + # 'The name', not 'the_name'). # # human /_cnt$/i, '\1_count' - # human "legacy_col_person_name", "Name" + # human 'legacy_col_person_name', 'Name' def human(rule, replacement) @humans.prepend([rule, replacement]) end - # Clears the loaded inflections within a given scope (default is :all). - # Give the scope as a symbol of the inflection type, the options are: :plurals, - # :singulars, :uncountables, :humans. + # Clears the loaded inflections within a given scope (default is + # :all). Give the scope as a symbol of the inflection type, the + # options are: :plurals, :singulars, :uncountables, + # :humans. # # clear :all # clear :plurals @@ -162,13 +178,13 @@ module ActiveSupport end end - # Yields a singleton instance of Inflector::Inflections so you can specify additional - # inflector rules. If passed an optional locale, rules for other languages can be specified. - # If not specified, defaults to :en. Only rules for English are provided. - # + # Yields a singleton instance of Inflector::Inflections so you can specify + # additional inflector rules. If passed an optional locale, rules for other + # languages can be specified. If not specified, defaults to :en. + # Only rules for English are provided. # # ActiveSupport::Inflector.inflections(:en) do |inflect| - # inflect.uncountable "rails" + # inflect.uncountable 'rails' # end def inflections(locale = :en) if block_given? -- cgit v1.2.3