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

Author: k0kubun

NEWS

@@ -69,6 +69,11 @@ with all sufficient information, see the ChangeLog file or Redmine
 
 === Stdlib updates (outstanding ones only)
 
+* ERB
+
+  * 2nd, 3rd and 4th arguments of ERB.new are deprecated. 2nd argument (safe_level) will be dropped in the future
+    and some of those arguments (trim_mode, eoutvar) are changed to keyword arguments. [Feature #14256]
+
 * Matrix
 
   * New method:

bin/erb

@@ -75,6 +75,7 @@ class ERB
           when '-r'                        # require
             require ARGV.req_arg
           when '-S'                        # security level
+            warn 'warning: -S option of erb command is deprecated. Please do not use this.'
             arg = ARGV.req_arg
             raise "invalid safe_level #{arg.dump}" unless arg =~ /\A[0-1]\z/
             safe_level = arg.to_i
@@ -112,7 +113,6 @@ class ERB
   -v               enable verbose mode
   -d               set $DEBUG to true
   -r library       load a library
-  -S safe_level    set $SAFE (0..1)
   -E ex[:in]       set default external/internal encodings
   -U               set default encoding to UTF-8.
   -T trim_mode     specify trim_mode (0..2, -)
@@ -127,7 +127,12 @@ EOU
       filename = $FILENAME
       exit 2 unless src
       trim = trim_mode_opt(trim_mode, disable_percent)
-      erb = factory.new(src.untaint, safe_level, trim)
+      if safe_level.nil?
+        erb = factory.new(src.untaint, trim_mode: trim)
+      else
+        # [deprecated] This will be removed at Ruby 2.7.
+        erb = factory.new(src.untaint, safe_level, trim_mode: trim)
+      end
       erb.filename = filename
       if output
         if number

enc/make_encmake.rb

@@ -121,7 +121,11 @@ def target_transcoders
 ATRANS, TRANS = target_transcoders
 
 if File.exist?(depend = File.join($srcdir, "depend"))
-  erb = ERB.new(File.read(depend), nil, '%')
+  if RUBY_VERSION >= '2.6'
+    erb = ERB.new(File.read(depend), trim_mode: '%')
+  else
+    erb = ERB.new(File.read(depend), nil, '%')
+  end
   erb.filename = depend
   tmp = erb.result(binding)
   dep = "\n#### depend ####\n\n" << depend_rules(tmp).join
@@ -135,7 +139,11 @@ def target_transcoders
 }
 if MODULE_TYPE == :static
   filename = "encinit.c.erb"
-  erb = ERB.new(File.read(File.join($srcdir, filename)), nil, '%-')
+  if RUBY_VERSION >= '2.6'
+    erb = ERB.new(File.read(File.join($srcdir, filename)), trim_mode: '%-')
+  else
+    erb = ERB.new(File.read(File.join($srcdir, filename)), nil, '%-')
+  end
   erb.filename = "enc/#{filename}"
   tmp = erb.result(binding)
   begin

ext/etc/mkconstants.rb

@@ -66,7 +66,15 @@ def each_name(pat)
   }
 end
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_const_decls")
+erb_new = lambda do |src, safe, trim|
+  if RUBY_VERSION >= '2.6'
+    ERB.new(src, trim_mode: trim)
+  else
+    ERB.new(src, safe, trim)
+  end
+end
+
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_const_decls")
 % each_const {|name, default_value|
 #if !defined(<%=name%>)
 # if defined(HAVE_CONST_<%=name.upcase%>)
@@ -80,7 +88,7 @@ def each_name(pat)
 % }
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_const_defs")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_const_defs")
 % each_const {|name, default_value|
 #if defined(<%=name%>)
 %   if comment = COMMENTS[name]
@@ -91,13 +99,13 @@ def each_name(pat)
 % }
 EOS
 
-header_result = ERB.new(<<'EOS', nil, '%').result(binding)
+header_result = erb_new.call(<<'EOS', nil, '%').result(binding)
 /* autogenerated file */
 
 <%= gen_const_decls %>
 EOS
 
-result = ERB.new(<<'EOS', nil, '%').result(binding)
+result = erb_new.call(<<'EOS', nil, '%').result(binding)
 /* autogenerated file */
 
 #ifdef HAVE_LONG_LONG

ext/socket/mkconstants.rb

@@ -73,7 +73,15 @@ def each_name(pat)
   }
 end
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_const_decls")
+erb_new = lambda do |src, safe, trim|
+  if RUBY_VERSION >= '2.6'
+    ERB.new(src, trim_mode: trim)
+  else
+    ERB.new(src, safe, trim)
+  end
+end
+
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_const_decls")
 % each_const {|guard, name, default_value|
 #if !defined(<%=name%>)
 # if defined(HAVE_CONST_<%=name.upcase%>)
@@ -87,7 +95,7 @@ def each_name(pat)
 % }
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_const_defs_in_guard(name, default_value)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_const_defs_in_guard(name, default_value)")
 #if defined(<%=name%>)
     /* <%= COMMENTS[name] %> */
     rb_define_const(rb_cSocket, <%=c_str name%>, INTEGER2NUM(<%=name%>));
@@ -96,7 +104,7 @@ def each_name(pat)
 #endif
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_const_defs")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_const_defs")
 % each_const {|guard, name, default_value|
 %   if guard
 #if <%=guard%>
@@ -146,7 +154,7 @@ def each_names_with_len(pat, prefix_optional=nil)
   }
 end
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_name_to_int_decl(funcname, pat, prefix_optional, guard=nil)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_name_to_int_decl(funcname, pat, prefix_optional, guard=nil)")
 %if guard
 #ifdef <%=guard%>
 int <%=funcname%>(const char *str, long len, int *valp);
@@ -156,7 +164,7 @@ def each_names_with_len(pat, prefix_optional=nil)
 %end
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_name_to_int_func_in_guard(funcname, pat, prefix_optional, guard=nil)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_name_to_int_func_in_guard(funcname, pat, prefix_optional, guard=nil)")
 int
 <%=funcname%>(const char *str, long len, int *valp)
 {
@@ -177,7 +185,7 @@ def each_names_with_len(pat, prefix_optional=nil)
 }
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_name_to_int_func(funcname, pat, prefix_optional, guard=nil)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_name_to_int_func(funcname, pat, prefix_optional, guard=nil)")
 %if guard
 #ifdef <%=guard%>
 <%=gen_name_to_int_func_in_guard(funcname, pat, prefix_optional, guard)%>
@@ -206,7 +214,7 @@ def reverse_each_name_with_prefix_optional(pat, prefix_pat)
   end
 end
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_int_to_name_hash(hash_var, pat, prefix_pat)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_int_to_name_hash(hash_var, pat, prefix_pat)")
     <%=hash_var%> = st_init_numtable();
 % reverse_each_name_with_prefix_optional(pat, prefix_pat) {|n,s|
 #ifdef <%=n%>
@@ -215,7 +223,7 @@ def reverse_each_name_with_prefix_optional(pat, prefix_pat)
 % }
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_int_to_name_func(func_name, hash_var)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_int_to_name_func(func_name, hash_var)")
 ID
 <%=func_name%>(int val)
 {
@@ -226,7 +234,7 @@ def reverse_each_name_with_prefix_optional(pat, prefix_pat)
 }
 EOS
 
-ERB.new(<<'EOS', nil, '%').def_method(Object, "gen_int_to_name_decl(func_name, hash_var)")
+erb_new.call(<<'EOS', nil, '%').def_method(Object, "gen_int_to_name_decl(func_name, hash_var)")
 ID <%=func_name%>(int val);
 EOS
 
@@ -275,7 +283,7 @@ def def_intern(func_name, pat, prefix_optional=nil)
 def_intern('rsock_intern_scm_optname',  /\ASCM_/, "SCM_")
 def_intern('rsock_intern_local_optname',  /\ALOCAL_/, "LOCAL_")
 
-result = ERB.new(<<'EOS', nil, '%').result(binding)
+result = erb_new.call(<<'EOS', nil, '%').result(binding)
 /* autogenerated file */
 
 <%= INTERN_DEFS.map {|vardef, gen_hash, decl, func| vardef }.join("\n") %>
@@ -318,7 +326,7 @@ def def_intern(func_name, pat, prefix_optional=nil)
 
 EOS
 
-header_result = ERB.new(<<'EOS', nil, '%').result(binding)
+header_result = erb_new.call(<<'EOS', nil, '%').result(binding)
 /* autogenerated file */
 <%= gen_const_decls %>
 <%= NAME_TO_INT_DEFS.map {|decl, func| decl }.join("\n") %>

lib/erb.rb

@@ -115,7 +115,7 @@
 #     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,14 +802,31 @@ 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)
     @src, @encoding, @frozen_string = *compiler.compile(str)
     @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

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
 
   ##

lib/rdoc/generator/darkfish.rb

@@ -778,7 +778,11 @@ def template_for file, page = true, klass = ERB
       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

sample/ripper/ruby2html.rb

@@ -73,7 +73,11 @@ def result(b)
 end
 
 def ruby2html(f, encoding, css, print_line_number)
-  erb = ERB.new(TEMPLATE, nil, '>')
+  if RUBY_VERSION >= '2.6'
+    erb = ERB.new(TEMPLATE, trim_mode: '>')
+  else
+    erb = ERB.new(TEMPLATE, nil, '>')
+  end
   erb.filename = __FILE__
   erb.lineno = TEMPLATE_LINE
   erb.result(binding())

spec/ruby/library/erb/defmethod/def_erb_method_spec.rb

@@ -50,7 +50,11 @@ def initialize(items)
     MY_INPUT4_FOR_ERB = input
     class MyClass4ForErb
       extend ERB::DefMethod
-      erb = ERB.new(MY_INPUT4_FOR_ERB, nil, '<>')
+      if RUBY_VERSION >= '2.6'
+        erb = ERB.new(MY_INPUT4_FOR_ERB, trim_mode: '<>')
+      else
+        erb = ERB.new(MY_INPUT4_FOR_ERB, nil, '<>')
+      end
       def_erb_method('render()', erb)
       def initialize(items)
         @items = items