REXML::Text#indent_text broken since v3.2.6

[pboling]

Version 3.2.6 of this gem released a major performance improvement from #94 which was largely the result of freezing strings by default, by adding the magoc comment to many files:

# frozen_string_literal: true

The following method from the REXML::Text class has never worked since that time, because it modifies frozen strings in multiple places.

    def indent_text(string, level=1, style="\t", indentfirstline=true)
      return string if level < 0
      new_string = ''
      string.each_line { |line|
        indent_string = style * level
        new_line = (indent_string + line).sub(/[\s]+$/,'')
        new_string << new_line
      }
      new_string.strip! unless indentfirstline
      return new_string
    end

I did not catch this myself, rather my IDE (RubyMine) noticed it and redlined it for me.

The fact this has never been reported (until now) is likely the result of a few factors:

1. It is an instance method that is unrelated to the instance. There is never a reason to call this method on an instance of Text, and it doesn't use Text. Instead it operates on a string passed in as an argument.
2. The method is never called by any code within the gem.
3. There are no tests for the method.
4. There is a different indent_text method in the Pretty formatter which probably gets used, and is called from internal code.

As a result I propose we do one of the following:

• Deprecate REXML::Text#indent_text, but leave it broken, resulting in throwing an error, as it has since v3.2.6. Remove in v4.
• Deprecate REXML::Text#indent_text, but fix it. Remove in v4.

[pboling]

I wrote a test for the method and ran it in the devcontainer I added in #271 to check Ruby 2.5:

root@850564c203de:/IdeaProjects/rexml# bundle exec rake test
/usr/local/bin/ruby test/run.rb
Loaded suite test
Started
E
====================================================================================================================================
Error: test_indent_text(REXMLTests::TextTester): FrozenError: can't modify frozen String
/IdeaProjects/rexml/lib/rexml/text.rb:280:in `<<'
/IdeaProjects/rexml/lib/rexml/text.rb:280:in `block in indent_text'
/IdeaProjects/rexml/lib/rexml/text.rb:277:in `each_line'
/IdeaProjects/rexml/lib/rexml/text.rb:277:in `indent_text'
/IdeaProjects/rexml/test/test_text.rb:75:in `test_indent_text'
     72: 
     73:     def test_indent_text
     74:       text = Text.new("")
  => 75:       assert_equal("\tline1\tline2\tline3", text.indent_text("line1\r\nline2\r\nline3\r\n"))
     76:     end
     77:   end
     78: end
====================================================================================================================================
Finished in 3.902984876 seconds.
------------------------------------------------------------------------------------------------------------------------------------
713 tests, 2165 assertions, 0 failures, 1 errors, 0 pendings, 0 omissions, 0 notifications
99.8597% passed
------------------------------------------------------------------------------------------------------------------------------------
182.68 tests/s, 554.70 assertions/s
rake aborted!
Command failed with status (1): [/usr/local/bin/ruby test/run.rb]
/IdeaProjects/rexml/Rakefile:9:in `block in <top (required)>'
/usr/local/bundle/gems/rake-13.3.0/exe/rake:27:in `<top (required)>'
/usr/local/bin/bundle:25:in `load'
/usr/local/bin/bundle:25:in `<main>'
Tasks: TOP => test
(See full trace by running task with --trace)
root@850564c203de:/IdeaProjects/rexml# ruby -v
ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]

The error is the same in Ruby 2.7 and 3.4.

[pboling]

Additionally, the method never actually worked, so I very much doubt it was ever used. The way the logic works it results in a single line of text, with tabs separating each former line. It does not indent multi-line text, rather it collapses it to a single line.

[pboling]

Additionally, the method has not been used internally since 2007, when the now deprecated REXML::Text#write method switched to calling the formatters. I think it is entirely vestigial, and probably should have been removed at that time.

[pboling]

Given that:

1. it is clearly unused in the wild
2. it is unused internally since 2007
3. its former caller (#write) deprecated since 2017
4. behavior is unchanged since the original 2004 commit (meaning it never worked as multi-line indent).

I think it is safest to restore the original behavior, and deprecate.