RCR 188: Remove whitespace before here doc contents

Here docs are a useful tool, but they are often avoided because they break indentation. To avoid this, extended heredocs should be added that strip whitespace at parse-time; there are many options for doing this, and all of them have their pros and their cons.

When using here docs, there is no good way to indent the here doc the same way as the code surrounding it. For example, the code:

  def foo
    return <<-END
      This is a test.
    END
  end

results in a function foo() that returns " This is a test.\n". This is probably not what the author intended the result to be. There are solutions that use regular expressions at run-time to build a here-doc without leading whitespace. For example [ruby-talk:61677],

  def foo
    return %Q{
      This is a test.
    }.gsub!(/^\s*/, '')
  end

which strips all leading whitespace (and therefore probably undesirable). Another option [ruby-talk:61446]:

  def tabto(n)
    if self =~ /^( *)\S/
      tab(n - $1.length)
    else
      self
    end
  end

  def foo
    return %Q{
      This is a test.
    }.tabto(0)
  end

which is good but IMO is not intuitive when reading code that uses it.

As long as we are missing extended here docs, users will continue to produce ad-hoc solutions like the above. we need a solution that occurs at parse time and is intuitive and easy to use.

Nobu Nakada proposed in [ruby-dev:19261] the following solution:

  p <<-|EOS
    |  foo
    |    bar
  EOS
  # => "  foo\n    bar\n".

The parser should understand the <<-| syntax to indicate an extended here doc in which the | character is used to indicate the start of the line.

This solution is easy to read and to understand, and the parsing of the here doc occurs at parse time, as it should.

The patch has already been posted in [ruby-dev:19261].