several enhancements to humanize [closes #12288]

* Strips leading underscores.
* Changes some unnecessary gsub!s to sub!s.
* Replaces some anchors ^, $ with \A, \z.
* Documents that human inflection rules are applied.
* Documents that words are downcased except acronyms.
* Adds an example with an acronym.
* Rewords docs.

activesupport/CHANGELOG.md

@@ -1,3 +1,15 @@
+*   `humanize` strips leading underscores, if any.
+
+    Before:
+
+        '_id'.humanize # => ""
+
+    After:
+
+        '_id'.humanize # => "Id"
+
+    *Xavier Noria*
+
 *   Fixed backward compatibility isues introduced in 326e652.
 
     Empty Hash or Array should not present in serialization result.

activesupport/lib/active_support/inflector/methods.rb

@@ -99,26 +99,46 @@ module ActiveSupport
       word
     end
 
-    # Capitalizes the first word, turns underscores into spaces, and strips a
+    # Tweaks an attribute name for display to end users.
-    # trailing '_id' if present.
+    #
-    # Like +titleize+, this is meant for creating pretty output.
+    # Specifically, +humanize+ performs these transformations:
+    #
+    #   * Applies human inflection rules to the argument.
+    #   * Deletes leading underscores, if any.
+    #   * Removes a "_id" suffix if present.
+    #   * Replaces underscores with spaces, if any.
+    #   * Downcases all words except acronyms.
+    #   * Capitalizes the first word.
     #
     # The capitalization of the first word can be turned off by setting the
-    # optional parameter +capitalize+ to false.
+    # +:capitalize+ option to false (default is true).
-    # By default, this parameter is true.
     #
     #   humanize('employee_salary')              # => "Employee salary"
     #   humanize('author_id')                    # => "Author"
     #   humanize('author_id', capitalize: false) # => "author"
+    #   humanize('_id')                          # => "Id"
+    #
+    # If "SSL" was defined to be an acronym:
+    #
+    #   humanize('ssl_error') # => "SSL error"
+    #
     def humanize(lower_case_and_underscored_word, options = {})
       result = lower_case_and_underscored_word.to_s.dup
+
       inflections.humans.each { |(rule, replacement)| break if result.sub!(rule, replacement) }
-      result.gsub!(/_id$/, "")
+
+      result.sub!(/\A_+/, '')
+      result.sub!(/_id\z/, '')
       result.tr!('_', ' ')
-      result.gsub!(/([a-z\d]*)/i) { |match|
+
+      result.gsub!(/([a-z\d]*)/i) do |match|
         "#{inflections.acronyms[match] || match.downcase}"
-      }
+      end
-      result.gsub!(/^\w/) { |match| match.upcase } if options.fetch(:capitalize, true)
+
+      if options.fetch(:capitalize, true)
+        result.sub!(/\A\w/) { |match| match.upcase }
+      end
+
       result
     end
 

activesupport/test/inflector_test_cases.rb

@@ -208,9 +208,11 @@ module InflectorTestCases
   }
 
   UnderscoreToHuman = {
-    "employee_salary" => "Employee salary",
+    'employee_salary' => 'Employee salary',
-    "employee_id"     => "Employee",
+    'employee_id'     => 'Employee',
-    "underground"     => "Underground"
+    'underground'     => 'Underground',
+    '_id'             => 'Id',
+    '_external_id'    => 'External'
   }
 
   UnderscoreToHumanWithoutCapitalize = {

guides/source/active_support_core_extensions.md

@@ -1768,21 +1768,36 @@ NOTE: Defined in `active_support/core_ext/string/inflections.rb`.
 
 #### `humanize`
 
-The method `humanize` gives you a sensible name for display out of an attribute name. To do so it replaces underscores with spaces, removes any "_id" suffix, and capitalizes the first word:
+The method `humanize` tqweaks an attribute name for display to end users.
-
+
-```ruby
+Specifically performs these transformations:
-"name".humanize           # => "Name"
+
-"author_id".humanize      # => "Author"
+  * Applies human inflection rules to the argument.
-"comments_count".humanize # => "Comments count"
+  * Deletes leading underscores, if any.
-```
+  * Removes a "_id" suffix if present.
-
+  * Replaces underscores with spaces, if any.
-The capitalization of the first word can be turned off by setting the optional parameter `capitalize` to false:
+  * Downcases all words except acronyms.
+  * Capitalizes the first word.
+
+The capitalization of the first word can be turned off by setting the
++:capitalize+ option to false (default is true).
 
 ```ruby
+"name".humanize                         # => "Name"
+"author_id".humanize                    # => "Author"
 "author_id".humanize(capitalize: false) # => "author"
+"comments_count".humanize               # => "Comments count"
+"_id".humanize                          # => "Id"
 ```
 
-The helper method `full_messages` uses `humanize` as a fallback to include attribute names:
+If "SSL" was defined to be an acronym:
+
+```ruby
+'ssl_error'.humanize # => "SSL error"
+```
+
+The helper method `full_messages` uses `humanize` as a fallback to include
+attribute names:
 
 ```ruby
 def full_messages