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

💖 MsOffice::Word::Surgeon::Text 💖

okay bestie so this is MsOffice::Word::Surgeon::Text, a lil module from the User Contributed Perl Documentation corner of the world, and she is a 3pm page, iykyk. she's internal, she's lowkey, she's the whole vibe behind storing text. let's get into it 🫶

---

✨ NAME ✨

MsOffice::Word::Surgeon::Text — the internal representation for a node of literal text. she's giving "just a chunk of words" but make it ✨structural✨.

---

🦋 DESCRIPTION 🦋

so basically? this module is used internally by MsOffice::Word::Surgeon for storing a chunk of literal text in a MsWord document. no cap.

she loosely corresponds to a <w:t> node in OOXML — like, vibe-wise, that's her cousin. but she may also contain an anonymous XML fragment which is the part of the document just before the <w:t> node. and why do we care? because that fragment is used for reconstructing the complete document after having changed the contents of some text nodes. iconic behaviour honestly 💅

---

💅 METHODS 💅

🌸 new 🌸

my $text_node = MsOffice::Word::Surgeon::Text(
  xml_before   => $xml_string,
  literal_text => $text_string,
);

constructor for a brand new text object ✨ arguments are, and listen closely because both of them are required bestie:

• xml_before — a string containing arbitrary XML preceding that text node in the complete document. the string may be empty but it must be present. so like… show up even if you have nothing to say 🫶
• literal_text — a string of literal text. that's it, that's the tea.

🎀 as_xml 🎀

my $xml = $text_node->as_xml;

returns the XML representation of that text node. and here's the cute lil detail: the attribute xml:space="preserve" is automatically added if the literal text starts of ends with a space character. (yes, the original says "starts of ends", we're keeping it, no editing the source bestie 😭). so your trailing and leading spaces are protected, periodt.

⭐ merge ⭐

$text_node->merge($next_text_node);

merges the contents of $next_text_node together with the current text node. but — and this is the catch — this is only possible if the next text node has an empty xml_before attribute.

if this condition is not met, an exception is raised. no vibes, no merge, sorry bestie 😭

🔥 replace 🔥

my $xml = $text_node->replace($pattern, $replacement_callback, %args);

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

and the lore? this is the internal implementation for the public method "replace" in MsOffice::Word::Surgeon. so she's the backstage queen, the main character working behind the curtain 👑

🌈 to_uppercase 🌈

puts the literal text within the node into UPPERCASE LETTERS. THAT'S IT. SHE'S LOUD NOW. 📢

---

👑 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. slay, legally 💜

---

and that's the whole page bestie!! 🌸🦋✨ this was written for perl v5.40.1 and dated 2025-10-05, and it's still called MsOffi...n::Text(3pm) because apparently we're all too cool for full filenames. mwah, bye!! 💖🎀🧚