Make Paragraph#substitute work on w:t nodes (approach by @Andy9822 in #187)

[satoryu]

Bug (#187)

Paragraph#substitute joined the paragraph's TextRuns, wrote the merged result into the first run of the match, and emptied the other runs through TextRun#text=. It never checked that those writes happened. TextRun#text= does nothing on a run with more than one w:t (#197). That kind of run is common:

• LibreOffice and macOS textutil write text<w:br/>text or text<w:tab/>text in one run.
• A hyperlink with several runs is read as a single TextRun.

Depending on which write was skipped, the placeholder stayed unfilled, the text after the match was duplicated (Name: JaneNext lineme}}Next line), stray characters were left behind (A Jane Bam), or the rest of the line was lost (See site {{na). Nothing raised.

There was a second problem even when every write succeeded: the text after the match moved into the first run, which put it before any line break in that range, and it lost its own run formatting.

Fix

Do the substitution on the w:t nodes that #text reads (w:r/w:t, w:hyperlink/w:r/w:t, in document order):

• The replacement goes into the w:t holding the first matched character, so that run's formatting is used, as before.
• The rest of the match is cut from the following w:t. Text after the match stays in its own node and keeps its own formatting.
• w:br / w:tab / w:cr inside the match are dropped. Those outside it stay where they are.
• All writes go through Elements::Text#content=, so surrounding spaces get xml:space="preserve" (Preserve leading/trailing spaces written to w:t (reported by @Andy9822 in #187) #198).

I deliberately did not use .//w:t, which would also pick up text from text boxes nested in a run (w:drawing//w:txbxContent), and would let substitute match text that #text doesn't show.

The public behavior otherwise stays the same: String or Regexp patterns, String#sub replacement semantics, every occurrence replaced, no re-matching inside a replacement, and the method returns self. The new constants are private_constant.

Tests

Unit specs in spec/docx/containers/paragraph_spec.rb built from XML fragments:

• each row of substitute leaves placeholders unfilled, or garbles the line, in files saved by LibreOffice #187: break in the same run, split placeholder plus break, tab inside the placeholder, placeholder starting in a hyperlink, trailing space
• breaks and tabs outside the match keep their position (the specs check the order of w:t / w:br / w:tab)
• text after the match keeps its run and formatting

The reproduction script from the issue now prints the expected result for every row, including after save and reopen. The existing #147 specs and the split_placeholder.docx integration spec still pass.

Thanks to @Andy9822 for the detailed report and for suggesting the w:t-level approach.

Closes #187

🤖 Generated with Claude Code