Merge pull request #181 from ruby-docx/fix-147-cross-run-substitution

Add Paragraph#substitute for placeholders split across runs (#147)

Author: satoryu

README.md

@@ -154,6 +154,15 @@ doc.paragraphs.each do |p|
   end
 end
 
+# Substitute a placeholder even when Word has split it across several runs
+# (e.g. "{{first_name}}" stored as "{{fi", "rst_na", "me}}"). Paragraph#substitute
+# matches across run boundaries, where the per-run TextRun#substitute above cannot.
+# Accepts a String or a Regexp (capture-group backreferences work in the replacement).
+doc.paragraphs.each do |p|
+  p.substitute('{{first_name}}', 'Jane')
+  p.substitute(/\{\{(\w+)\}\}/, 'value of \1')
+end
+
 # Substitute text with access to captures, note block arg is a MatchData, a bit
 # different than String.gsub. https://ruby-doc.org/3.3.7/MatchData.html
 doc.paragraphs.each do |p|

lib/docx/containers/paragraph.rb

@@ -65,6 +65,59 @@ def each_text_run
           text_runs.each { |tr| yield(tr) }
         end
 
+        # Substitute text within the paragraph, even when a match spans multiple
+        # text runs (e.g. a "{{placeholder}}" that Word split across several runs,
+        # such as "{{fi", "rst_na", "me}}"). The per-run TextRun#substitute cannot
+        # match those, but this can, because it joins the runs first.
+        #
+        # The matched region is collapsed into the first run it touches, so that
+        # run's formatting is kept while the other spanned runs are emptied; runs
+        # outside the match are left untouched.
+        #
+        # +pattern+ may be a String or a Regexp; +replacement+ follows String#sub
+        # semantics, so capture-group backreferences (e.g. '\1') work with a Regexp.
+        #
+        #   # given a paragraph reading "Hello {{first_name}}!"
+        #   paragraph.substitute('{{first_name}}', 'Jane')   # => "Hello Jane!"
+        #   paragraph.substitute(/\{\{(\w+)\}\}/, 'value of \1')
+        #
+        # See https://github.com/ruby-docx/docx/issues/147
+        def substitute(pattern, replacement)
+          search_from = 0
+          loop do
+            runs = text_runs
+            break if runs.empty?
+
+            offsets = []
+            cursor = 0
+            runs.each do |run|
+              offsets << cursor
+              cursor += run.text.length
+            end
+            full_text = runs.map(&:text).join
+
+            match = full_text.match(pattern, search_from)
+            break unless match
+            break if match.end(0) == match.begin(0) # ignore empty matches
+
+            match_start = match.begin(0)
+            match_end   = match.end(0) # exclusive
+            first = offsets.rindex { |offset| offset <= match_start }
+            last  = offsets.rindex { |offset| offset < match_end }
+
+            combined = runs[first..last].map(&:text).join
+            local_start = match_start - offsets[first]
+            local_end   = match_end - offsets[first]
+            replaced = combined[local_start...local_end].sub(pattern, replacement)
+            runs[first].text = combined[0...local_start] + replaced + combined[local_end..-1]
+            ((first + 1)..last).each { |index| runs[index].text = '' }
+
+            # advance past the inserted replacement so it is not re-matched
+            search_from = match_start + replaced.length
+          end
+          self
+        end
+
         def aligned_left?
           ['left', nil].include?(alignment)
         end

spec/docx/document_spec.rb

@@ -317,6 +317,39 @@
     end
   end
 
+  # Regression test for #147: a placeholder split across multiple text runs
+  # (as Word often produces) must be replaceable.
+  describe 'substituting a placeholder split across runs' do
+    before do
+      @doc = Docx::Document.open(@fixtures_path + '/split_placeholder.docx')
+      @paragraph = @doc.paragraphs.find { |p| p.text.include?('{{') }
+    end
+
+    it 'has the placeholder split across several runs' do
+      expect(@paragraph.text).to eq('Hello {{first_name}}!')
+      expect(@paragraph.text_runs.map(&:text)).to eq(['Hello ', '{{fi', 'rst_na', 'me}}', '!'])
+    end
+
+    it 'replaces the placeholder via Paragraph#substitute, preserving surrounding text' do
+      @paragraph.substitute('{{first_name}}', 'World')
+      expect(@paragraph.text).to eq('Hello World!')
+    end
+
+    it 'supports regex patterns and capture groups' do
+      @paragraph.substitute(/\{\{(\w+)\}\}/, 'name=\1')
+      expect(@paragraph.text).to eq('Hello name=first_name!')
+    end
+
+    it 'persists the substitution after save' do
+      @paragraph.substitute('{{first_name}}', 'World')
+      new_path = @fixtures_path + '/split_placeholder_saved.docx'
+      @doc.save(new_path)
+      reopened = Docx::Document.open(new_path)
+      expect(reopened.paragraphs.find { |p| p.text.include?('Hello') }.text).to eq('Hello World!')
+      File.delete(new_path) if File.exist?(new_path)
+    end
+  end
+
   describe 'read formatting' do
     before do
       @doc = Docx::Document.open(@fixtures_path + '/formatting.docx')