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.

3 files changed, 46 insertions, 12 deletions

diff --git a/activesupport/CHANGELOG.md b/activesupport/CHANGELOG.md
index 36955e5ca6..8e63273271 100644
--- a/activesupport/CHANGELOG.md
+++ b/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.
diff --git a/activesupport/lib/active_support/inflector/methods.rb b/activesupport/lib/active_support/inflector/methods.rb
index 69f77453e7..51720d0192 100644
--- a/activesupport/lib/active_support/inflector/methods.rb
+++ b/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
-    # trailing '_id' if present.
-    # Like +titleize+, this is meant for creating pretty output.
+    # Tweaks an attribute name for display to end users.
+    #
+    # 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.
-    # By default, this parameter is true.
+    # +:capitalize+ option to false (default 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}"
-      }
-      result.gsub!(/^\w/) { |match| match.upcase } if options.fetch(:capitalize, true)
+      end
+
+      if options.fetch(:capitalize, true)
+        result.sub!(/\A\w/) { |match| match.upcase }
+      end
+
       result
     end
 
diff --git a/activesupport/test/inflector_test_cases.rb b/activesupport/test/inflector_test_cases.rb
index dd03a61176..b556da0046 100644
--- a/activesupport/test/inflector_test_cases.rb
+++ b/activesupport/test/inflector_test_cases.rb
@@ -208,9 +208,11 @@ module InflectorTestCases
   }
 
   UnderscoreToHuman = {
-    "employee_salary" => "Employee salary",
-    "employee_id"     => "Employee",
-    "underground"     => "Underground"
+    'employee_salary' => 'Employee salary',
+    'employee_id'     => 'Employee',
+    'underground'     => 'Underground',
+    '_id'             => 'Id',
+    '_external_id'    => 'External'
   }
 
   UnderscoreToHumanWithoutCapitalize = {