erb.rb: deprecate safe_level of ERB.new

Also, as it's in the middle of the list of 4 arguments, 3rd and 4th arguments
(trim_mode, eoutvar) are changed to keyword arguments.
Old ways to specify arguments are deprecated and warned now.

bin/erb: deprecate -S option.

We'll remove all of deprecated ones at Ruby 2.7+.

enc/make_encmake.rb: stopped using deprecated interface
ext/etc/mkconstants.rb: ditto
ext/socket/mkconstants.rb: ditto
sample/ripper/ruby2html.rb: ditto
spec/ruby/library/erb/defmethod/def_erb_method_spec.rb: ditto
spec/ruby/library/erb/new_spec.rb: ditto
test/erb/test_erb.rb: ditto
test/erb/test_erb_command.rb: ditto
tool/generic_erb.rb: ditto
tool/ruby_vm/helpers/dumper.rb: ditto
tool/transcode-tblgen.rb: ditto
lib/rdoc/erbio.rb: ditto
lib/rdoc/generator/darkfish.rb: ditto

[Feature #14256]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@62529 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 32 insertions, 7 deletions

diff --git a/lib/erb.rb b/lib/erb.rb
index 215a3f516f..c50d3eac48 100644
--- a/lib/erb.rb
+++ b/lib/erb.rb
@@ -115,7 +115,7 @@ require "cgi/util"
 #     James Edward Gray II
 #   }.gsub(/^  /, '')
 #
-#   message = ERB.new(template, 0, "%<>")
+#   message = ERB.new(template, trim_mode: "%<>")
 #
 #   # Set up template data.
 #   to = "Community Spokesman <spokesman@ruby_community.org>"
@@ -263,7 +263,7 @@ class ERB
 
   # Returns revision information for the erb.rb module.
   def self.version
-    "erb.rb [2.1.0 #{ERB::Revision.split[1]}]"
+    "erb.rb [2.2.0 #{ERB::Revision.split[1]}]"
   end
 end
 
@@ -777,11 +777,11 @@ class ERB
   #    def build
   #      b = binding
   #      # create and run templates, filling member data variables
-  #      ERB.new(<<-'END_PRODUCT'.gsub(/^\s+/, ""), 0, "", "@product").result b
+  #      ERB.new(<<-'END_PRODUCT'.gsub(/^\s+/, ""), trim_mode: "", eoutvar: "@product").result b
   #        <%= PRODUCT[:name] %>
   #        <%= PRODUCT[:desc] %>
   #      END_PRODUCT
-  #      ERB.new(<<-'END_PRICE'.gsub(/^\s+/, ""), 0, "", "@price").result b
+  #      ERB.new(<<-'END_PRICE'.gsub(/^\s+/, ""), trim_mode: "", eoutvar: "@price").result b
   #        <%= PRODUCT[:name] %> -- <%= PRODUCT[:cost] %>
   #        <%= PRODUCT[:desc] %>
   #      END_PRICE
@@ -802,7 +802,22 @@ class ERB
   #  Chicken Fried Steak -- 9.95
   #  A well messages pattie, breaded and fried.
   #
-  def initialize(str, safe_level=nil, trim_mode=nil, eoutvar='_erbout')
+  def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eoutvar=NOT_GIVEN, trim_mode: nil, eoutvar: '_erbout')
+    # Complex initializer for $SAFE deprecation at Feature #14256, which should be removed at Ruby 2.7.
+    if safe_level != NOT_GIVEN
+      warn 'warning: Passing safe_level with the 2nd argument of ERB.new is deprecated. Do not use it, and specify other arguments as keyword arguments.'
+    else
+      safe_level = nil
+    end
+    if legacy_trim_mode != NOT_GIVEN
+      warn 'warning: Passing trim_mode with the 3rd argument of ERB.new is deprecated. Use keyword argument like ERB.new(str, trim_mode: ...) instead.'
+      trim_mode = legacy_trim_mode
+    end
+    if legacy_eoutvar != NOT_GIVEN
+      warn 'warning: Passing eoutvar with the 4th argument of ERB.new is deprecated. Use keyword argument like ERB.new(str, eoutvar: ...) instead.'
+      eoutvar = legacy_eoutvar
+    end
+
     @safe_level = safe_level
     compiler = make_compiler(trim_mode)
     set_eoutvar(compiler, eoutvar)
@@ -810,6 +825,8 @@ class ERB
     @filename = nil
     @lineno = 0
   end
+  NOT_GIVEN = Object.new
+  private_constant :NOT_GIVEN
 
   ##
   # Creates a new compiler for ERB.  See ERB::Compiler.new for details
diff --git a/lib/rdoc/erbio.rb b/lib/rdoc/erbio.rb
index 42ce895fb3..2ebce9519f 100644
--- a/lib/rdoc/erbio.rb
+++ b/lib/rdoc/erbio.rb
@@ -21,7 +21,11 @@ class RDoc::ERBIO < ERB
   # Defaults +eoutvar+ to 'io', otherwise is identical to ERB's initialize
 
   def initialize str, safe_level = nil, trim_mode = nil, eoutvar = 'io'
-    super
+    if RUBY_VERSION >= '2.6'
+      super(str, trim_mode: trim_mode, eoutvar: eoutvar)
+    else
+      super
+    end
   end
 
   ##
diff --git a/lib/rdoc/generator/darkfish.rb b/lib/rdoc/generator/darkfish.rb
index bf4eb1f530..a07f74e716 100644
--- a/lib/rdoc/generator/darkfish.rb
+++ b/lib/rdoc/generator/darkfish.rb
@@ -778,7 +778,11 @@ class RDoc::Generator::Darkfish
       erbout = "_erbout_#{file_var}"
     end
 
-    template = klass.new template, nil, '<>', erbout
+    if RUBY_VERSION >= '2.6'
+      template = klass.new template, trim_mode: '<>', eoutvar: erbout
+    else
+      template = klass.new template, nil, '<>', erbout
+    end
     @template_cache[file] = template
     template
   end