[ruby-core:49988] [ruby-trunk - Feature #6801] String#~ for a here document

["trans (Thomas Sawyer)" <transfire@gmail.com>]

Issue #6801 has been updated by trans (Thomas Sawyer).


=begin
This is really an area in which Ruby is sorely missing some needed String methods. Some of the most commonly used methods in Ruby Facets deal with indention, mainly:

  # Preserves relative tabbing such that the line with the least amount 
  # of white space ends up with `n` number of spaces before non-space and
  # all other lines move relative to it.

  def tab(n)
    str = gsub("\t", "  ")  # option?

    min = []
    str.each_line do |line|
      next if line.strip.empty?
      min << line.index(/\S/)
    end
    min = min.min

    str.indent(n - min)
  end

  # Preserves relative tabbing, such that the first non-empty line ends up with
  # `n` number of spaces before non-space, and all subsequent lines move relative
  # to the first.
  #
  # CREDIT: Gavin Sinclair

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

  # Indent left or right by `n` spaces, or `n` number of `c` string.
  #
  # CREDIT: Gavin Sinclair, Trans, Tyler Rick

  def indent(n, c=' ')
    if n >= 0
      gsub(/^/, c * n)
    else
      gsub(/^#{Regexp.escape(c)}{0,#{-n}}/, "")
    end
  end

  # Equivalent to String#indent, but modifies the receiver in place.

  def indent!(n, c=' ')
    replace(indent(n,c))
  end

  # Remove excessive indentation. Useful for multi-line strings embeded in
  # already indented code.
  #
  #   <<-END.unindent
  #       ohaie
  #         wurld
  #   END
  #
  # Outputs ...
  #
  #   ohaie
  #     wurld
  #
  # Instead of ...
  #
  #       ohaie
  #         wurld
  #
  # CREDIT: Noah Gibbs, mynyml

  def unindent(size=nil)
    if size
      indent(-size)
    else
      char = ' '
      self.scan(/^[\ \t]*\S/) do |m|
        if size.nil? || m.size < size
          size = m.size
          char = m[0...-1]
        end
      end
      size -= 1
      indent(-size, char)
    end
  end

  # Equivalent to String#unindent, but modifies the receiver in place.
  #
  # CREDIT: mynyml

  def unindent!
    self.replace(self.unindent)
  end

While I understand the intention of using (({~})) so as to make it part of HERE document syntax, I don't think it outweighs the advantages of having more flexible methods such as these.

=end
----------------------------------------
Feature #6801: String#~ for a here document
https://bugs.ruby-lang.org/issues/6801#change-33757

Author: merborne (kyo endo)
Status: Assigned
Priority: Normal
Assignee: matz (Yukihiro Matsumoto)
Category: 
Target version: Next Major


=begin
Let me propose a new method (({String#~})) for a here document.

次のような実装の(({String#~}))を提案します。

    class String
      def ~
        margin = scan(/^ +/).map(&:size).min
        gsub(/^ {#{margin}}/, '')
      end
    end

This is for removing leading margins of a here document.

これはヒアドキュメントにおける先頭マージンを除去するためのものです。

    class ATool
      def self.help
        lines = ~<<-EOS
                  Instruction of `#{self}`
    
        `#{self}` is one of a great tool in the world.
           This helps you a lot on your daily work.
          Your life will be changed with `#{self}`!!
               Everyone knows about `#{self}`.
            So, You can ask them to learn `#{self}`
    
                    Just Use `#{self}`
    
                       from Today!
        EOS
        lines
      end
    end
    
    puts ATool.help
    
    # >>           Instruction of `ATool`
    # >> 
    # >> `ATool` is one of a great tool in the world.
    # >>    This helps you a lot on your daily work.
    # >>   Your life will be changed with `ATool`!!
    # >>        Everyone knows about `ATool`.
    # >>     So, You can ask them to learn `ATool`
    # >> 
    # >>             Just Use `ATool`
    # >> 
    # >>                from Today!

you can put a tilde sign just before the "<<" characters to call String#~, just like putting a minus sign after "<<" to indent the terminator. This is achieved with uniqueness of tilde sign method, which takes the receiver object on the right-hand side.

If you define String#unindent for this purpose, you put `.unindent` after EOS. I think its less elegant than a tilde.

"<<"文字の直前にチルダを置くことで、String#~を呼び出すことができます。これはチルダ記号のメソッドが、そのレシーバオブジェクトを右側に取るという特徴によって実現されます。仮にこの目的のためにString#unindentを定義した場合は、EOSの後に`.unindent`を書くことになりますが、これはチルダに比べると美しくありません。

I understand that this is not general method for string but just for here document. However, I think using a tilde as a method is very restricted because it can't take parameters and is difficult to read the meanings or behavior from the sign. From this, there are few tilde methods within built-in classes of ruby inspite of its uniqness(only for Fixnum, Bignum and Regexp).

so, I think using tilde for the above purpose is the one of the few good chances.

Thank you for your consideration.

このメソッドがStringのための汎用的なものでなく、ヒアドキュメント専用であるということに問題がある点は理解しています。しかし、チルダをメソッドとして使える機会は、それが引数を取れないことと、その記号からはその意味や動作を察することは難しいことから、非常に限られていると想像します。故に、そのユニークさにも拘らず、Rubyの組み込みクラスでの使用例は少しです（Fixnum, BignumおよびRegexpでだけ）。

従って、上記目的でチルダを使うことは、数少ない良い機会であると考えます。

以上、ご検討のほどよろしくお願い致します。

This is based on the following my Japanese blog post.

((<URL:http://melborne.github.com/2012/04/27/ruby-heredoc-without-leading-whitespace/>))
=end



-- 
http://bugs.ruby-lang.org/