MsOffi...n::Run(3pm)

💖 MsOffice::Word::Surgeon::Run — the whole vibe 💖

okay so bestie, welcome to MsOffice::Word::Surgeon::Run, a little corner of the MsOffice::Word::Surgeon universe. it's an internal representation — like, the backstage dressing room — for a "run of text". yes it lives in the Perl docs, yes it's a 3pm page, no you don't have to be scared. 🎀

---

✨ NAME ✨

MsOffice::Word::Surgeon::Run — the internal representation for a "run of text". that's the whole name, that's the whole assignment. 💅

---

🌸 DESCRIPTION 🌸

so here's the tea: this thing is used internally by MsOffice::Word::Surgeon for storing a "run of text" inside a MsWord document. it's giving very much backstage crew energy, not main character energy — you're probably not calling it directly, but it's doing the work. 👑

it loosely corresponds to a <w:r> node in OOXML. loose correspondence, like when you say you'll be ready in five minutes. 🦋

but WAIT, there's more — it may also contain an anonymous XML fragment which is the part of the document just before the <w:r> node. why? because it's used for reconstructing the complete document after having changed the contents of some runs. it remembers the little bits so nothing gets lost. iconic behaviour, honestly. ✨

---

🫶 METHODS 🫶

💜 new

my $run = MsOffice::Word::Surgeon::Run(
  xml_before  => $xml_string,
  props       => $properties_string,
  inner_texts => [MsOffice::Word::Surgeon::Text(...), ...],
);

Constructor for a new run object. the arguments are, in order of the group chat:

• xml_before — a string containing arbitrary XML preceding that run in the complete document. it may be empty but must be present (so don't ghost it, bestie, it has to show up even if it's saying nothing). 🙈
• props — a string containing XML for the properties of this run (think instructions for bold, italic, font, etc.). important: the module does not parse this information — it just compares the string for equality with the next run. literally just a string comparison, no deep analysis, no therapy. 💀
• inner_texts — an array of MsOffice::Word::Surgeon::Text objects, corresponding to the XML <w:t> nodes inside the run. 🍓

🎀 as_xml

my $xml = $run->as_xml;

returns the XML representation of that run. that's it, that's the method. short and slay. 💅

🌈 merge

$run->merge($next_run);

merge the contents of $next_run together with the current run. this is only possible if both runs have the same properties (same string returned by the props method), and if the next run has an empty xml_before attribute.

if the conditions are not met, an exception is raised. no soft launch, no "let's see how it goes" — it just throws. 🚨

⭐ replace

my $xml = $run->replace($pattern, $replacement_callback, %replacement_args);

replaces all occurrences of $pattern within all text nodes by a new string computed by $replacement_callback, and returns a new xml string corresponding to the result of all these replacements. 🔥

this is the internal implementation for the public method replace in MsOffice::Word::Surgeon::PackagePart — so it's the understudy that's actually doing the performance, iykyk. 🎭

🧚 remove_caps_property

searches in the run properties for a <w:caps/> property; if found, it removes it, and replaces all inner texts by their uppercase equivalents. so it's a glow-up that also makes everything SHOUT. 📣✨

---

👑 AUTHOR 👑

Laurent Dami, <dami AT cpan DOT org<gt>

---

💖 COPYRIGHT AND LICENSE 💖

Copyright 2019-2024 by Laurent Dami.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0. 🫶

---

and that's the whole page, bestie. this gem of a doc was served up courtesy of perl v5.40.1, dated 2025-10-05 — so when you cite your sources, say it with your chest. mwah, go forth and merge responsibly. 💋🌈✨