Refactor and document `Inreplace`.

Library/Homebrew/test/inreplace_spec.rb

@@ -280,13 +280,13 @@ describe Utils::Inreplace do
   it "raises error if there are no files given to replace" do
     expect {
       described_class.inreplace [], "d", "f"
-    }.to raise_error(Utils::InreplaceError)
+    }.to raise_error(Utils::Inreplace::Error)
   end
 
   it "raises error if there is nothing to replace" do
     expect {
       described_class.inreplace file.path, "d", "f"
-    }.to raise_error(Utils::InreplaceError)
+    }.to raise_error(Utils::Inreplace::Error)
   end
 
   it "raises error if there is nothing to replace in block form" do
@@ -294,7 +294,7 @@ describe Utils::Inreplace do
       described_class.inreplace(file.path) do |s|
         s.gsub!("d", "f") # rubocop:disable Performance/StringReplacement
       end
-    }.to raise_error(Utils::InreplaceError)
+    }.to raise_error(Utils::Inreplace::Error)
   end
 
   it "raises error if there is no make variables to replace" do
@@ -303,14 +303,14 @@ describe Utils::Inreplace do
         s.change_make_var! "VAR", "value"
         s.remove_make_var! "VAR2"
       end
-    }.to raise_error(Utils::InreplaceError)
+    }.to raise_error(Utils::Inreplace::Error)
   end
 
   describe "#inreplace_pairs" do
     it "raises error if there is no old value" do
       expect {
         described_class.inreplace_pairs(file.path, [[nil, "f"]])
-      }.to raise_error(Utils::InreplaceError)
+      }.to raise_error(Utils::Inreplace::Error)
     end
   end
 end

Library/Homebrew/utils/inreplace.rb

 # frozen_string_literal: true
 
 module Utils
-  class InreplaceError < RuntimeError
-    def initialize(errors)
-      formatted_errors = errors.reduce(+"inreplace failed\n") do |s, (path, errs)|
-        s << "#{path}:\n" << errs.map { |e| "  #{e}\n" }.join
+  # Helper functions for replacing text in files in-place.
+  #
+  # @api private
+  module Inreplace
+    # Error during replacement.
+    class Error < RuntimeError
+      def initialize(errors)
+        formatted_errors = errors.reduce(+"inreplace failed\n") do |s, (path, errs)|
+          s << "#{path}:\n" << errs.map { |e| "  #{e}\n" }.join
+        end
+        super formatted_errors.freeze
       end
-      super formatted_errors.freeze
     end
-  end
 
-  module Inreplace
     module_function
 
     # Sometimes we have to change a bit before we install. Mostly we
@@ -21,6 +25,8 @@ module Utils
     #
     # `inreplace` supports regular expressions:
     # <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
+    #
+    # @api public
     def inreplace(paths, before = nil, after = nil, audit_result = true) # rubocop:disable Style/OptionalBooleanParameter
       errors = {}
 
@@ -42,7 +48,7 @@ module Utils
         Pathname(path).atomic_write(s.inreplace_string)
       end
 
-      raise InreplaceError, errors unless errors.empty?
+      raise Error, errors unless errors.empty?
     end
 
     def inreplace_pairs(path, replacement_pairs, read_only_run: false, silent: false)
@@ -57,7 +63,7 @@ module Utils
 
         contents.gsub!(old, new)
       end
-      raise InreplaceError, path => contents.errors unless contents.errors.empty?
+      raise Error, path => contents.errors unless contents.errors.empty?
 
       Pathname(path).atomic_write(contents.inreplace_string) unless read_only_run
       contents.inreplace_string