implements String#strip_heredoc

activesupport/CHANGELOG

@@ -1,5 +1,7 @@
 *Rails 3.0.0 (August 29, 2010)*
 
+* Implemented String#strip_heredoc. [fxn]
+
 * Pluggable cache stores: setting config.cache_store = "custom_store" will require 'active_support/cache/custom_store' and look for the CustomStore constant.  #5486 [Mike Perham]
 
 * Removed Object#returning, Object#tap should be used instead. [Santiago Pastorino]

activesupport/lib/active_support/core_ext/string.rb

@@ -9,4 +9,5 @@
 require 'active_support/core_ext/string/interpolation'
 require 'active_support/core_ext/string/output_safety'
 require 'active_support/core_ext/string/exclude'
-require 'active_support/core_ext/string/encoding'
+require 'active_support/core_ext/string/encoding'
+require 'active_support/core_ext/string/strip'

activesupport/lib/active_support/core_ext/string/strip.rb

@@ -0,0 +1,24 @@
+class String
+  # Strips indentation in heredocs.
+  #
+  # For example in
+  #
+  #   if options[:usage]
+  #     puts <<-USAGE.strip_heredoc
+  #       This command does such and such.
+  #
+  #       Supported options are:
+  #         -h         This message
+  #         ...
+  #     USAGE
+  #   end
+  #
+  # the user would see the usage message aligned against the left margin.
+  #
+  # Technically, it looks for the least indented line in the whole string, and removes
+  # that amount of leading whitespace.
+  def strip_heredoc
+    indent = chomp.scan(/^\s*/).min.size
+    gsub(/^\s{#{indent}}/, '')
+  end
+end

activesupport/test/core_ext/string_ext_test.rb

@@ -6,10 +6,33 @@
 require 'active_support/core_ext/string'
 require 'active_support/time'
 require 'active_support/core_ext/kernel/reporting'
+require 'active_support/core_ext/string/strip'
 
 class StringInflectionsTest < Test::Unit::TestCase
   include InflectorTestCases
 
+  def test_strip_heredoc_on_an_empty_string
+    assert_equal '', ''.strip_heredoc
+  end
+
+  def test_strip_heredoc_on_a_string_with_no_lines
+    assert_equal 'x', 'x'.strip_heredoc
+    assert_equal 'x', '    x'.strip_heredoc
+  end
+
+  def test_strip_heredoc_on_a_heredoc_with_no_margin
+    assert_equal "foo\nbar", "foo\nbar".strip_heredoc
+    assert_equal "foo\n  bar", "foo\n  bar".strip_heredoc
+  end
+
+  def test_strip_heredoc_on_a_regular_indented_heredoc
+    assert_equal "foo\n  bar\nbaz\n", <<-EOS.strip_heredoc
+      foo
+        bar
+      baz
+    EOS
+  end
+
   def test_pluralize
     SingularToPlural.each do |singular, plural|
       assert_equal(plural, singular.pluralize)

railties/guides/source/active_support_core_extensions.textile

@@ -1296,6 +1296,31 @@ Active Support defines 3rd person aliases of +String#start_with?+ and +String#en
 
 NOTE: Defined in +active_support/core_ext/string/starts_ends_with.rb+.
 
+h4. +strip_heredoc+
+
+The method +strip_heredoc+ strips indentation in heredocs.
+
+For example in
+
+<ruby>
+if options[:usage]
+  puts <<-USAGE.strip_heredoc
+    This command does such and such.
+
+    Supported options are:
+      -h         This message
+      ...
+  USAGE
+end
+</ruby>
+
+the user would see the usage message aligned against the left margin.
+
+Technically, it looks for the least indented line in the whole string, and removes
+that amount of leading whitespace.
+
+NOTE: Defined in +active_support/core_ext/string/strip.rb+.
+
 h4. Access
 
 h5. +at(position)+