From f5cc986714ce8db9b63c6a786ed83b3c3b9bcdbb Mon Sep 17 00:00:00 2001
From: Sutou Kouhei <kou@clear-code.com>
Date: Tue, 25 Aug 2026 10:54:22 +0900
Subject: [PATCH] Deprecate unused `REXML::Text.read_with_substitution`

We don't want to maintain unused code.

Use `REXML::Text.unnormalize` instead.
---
 lib/rexml/text.rb | 26 +++++++-------------------
 test/test_text.rb | 16 ++++++++++++++++
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/lib/rexml/text.rb b/lib/rexml/text.rb
index 2319cef8..afa185ba 100644
--- a/lib/rexml/text.rb
+++ b/lib/rexml/text.rb
@@ -334,28 +334,16 @@ def clear_cache
     end
 
     # Reads text, substituting entities
+    #
+    # Deprecated since 3.4.5. Use Text.unnormalize instead.
     def Text::read_with_substitution( input, illegal=nil )
-      copy = input.clone
-
-      if copy =~ illegal
+      Kernel.warn("#{name}.read_with_substitution is deprecated. " +
+                  "Use #{name}.unnormalize instead.", uplevel: 1)
+      copy = input.to_s
+      if illegal and copy =~ illegal
         raise ParseException.new( "malformed text: Illegal character #$& in \"#{copy}\"" )
-      end if illegal
-
-      copy.gsub!( /\r\n?/, "\n" )
-      if copy.include? ?&
-        copy.gsub!( SETUTITSBUS[0], SLAICEPS[0] )
-        copy.gsub!( SETUTITSBUS[1], SLAICEPS[1] )
-        copy.gsub!( SETUTITSBUS[2], SLAICEPS[2] )
-        copy.gsub!( SETUTITSBUS[3], SLAICEPS[3] )
-        copy.gsub!( SETUTITSBUS[4], SLAICEPS[4] )
-        copy.gsub!( /&#0*((?:\d+)|(?:x[a-f0-9]+));/ ) {
-          m=$1
-          #m='0' if m==''
-          m = "0#{m}" if m[0] == ?x
-          [Integer(m)].pack('U*')
-        }
       end
-      copy
+      unnormalize(copy)
     end
 
     EREFERENCE = /&(?!#{Entity::NAME};)/
diff --git a/test/test_text.rb b/test/test_text.rb
index c1f5765e..6dd2a488 100644
--- a/test/test_text.rb
+++ b/test/test_text.rb
@@ -77,5 +77,21 @@ def test_indent_text
         assert_equal("\tline1\tline2\tline3", text.indent_text("line1\r\nline2\r\nline3\r\n"))
       end
     end
+
+    def test_read_with_substitution
+      suppress_warning do
+        assert_equal("a <b> & \"c\" 'd' A B",
+                     Text.read_with_substitution(
+                       "a &lt;b&gt; &amp; &quot;c&quot; &apos;d&apos; &#65; &#x42;"))
+      end
+    end
+
+    def test_read_with_substitution_illegal
+      suppress_warning do
+        assert_raise(REXML::ParseException) do
+          Text.read_with_substitution("bad <", /</)
+        end
+      end
+    end
   end
 end