Text::Quoted(3pm)

💌 Text::Quoted — it's giving "extract the structure of a quoted mail message" 💌

okay bestie, welcome to Text::Quoted, a lil Perl module that lives in the User Contributed Perl Documentation section of your man pages. it's here to look at a quoted email and figure out who said what at which level of nesting. no cap, it's actually so useful. 🫶

---

✨ SYNOPSIS ✨

use Text::Quoted;
my $structure = extract($text);

# Optionally, customize recognized quote characters:
Text::Quoted::set_quote_characters( qr/[:]/ );

like. that's it. that's the whole vibe check. 💅

---

🌸 DESCRIPTION 🌸

so Text::Quoted looks at the structure of some text that might have multiple different levels of quoting going on, and turns that text into a nested data structure. main character energy fr fr. 👑

the structure is an array reference, and inside it are hash references for each paragraph that belongs to the same author. every level of quoting recursively adds another list reference. so for instance, this:

> foo
> # Bar
> baz

quux

turns into:

[
  [
    { text => 'foo', quoter => '>', raw => '> foo' },
    [
        { text => 'Bar', quoter => '> #', raw => '> # Bar' }
    ],
    { text => 'baz', quoter => '>', raw => '> baz' }
  ],

  { empty => 1 },
  { text => 'quux', quoter => '', raw => 'quux' }
];

see how it nests?? literally a whole family tree of paragraphs. 🌈

this also tells you what's inside those hash references, so listen up: raw is the paragraph of text exactly as it appeared in the original input; text is what it looked like once we stripped off the quotation characters; and quoter is the quotation string itself. three little keys, so much lore. 🔑

---

🎀 FUNCTIONS 🎀

🦋 extract

my $struct = extract($text, \%arg);

takes a single string argument, which is the text you want to extract the quote structure from. returns a nested datastructure exactly like the one described up above. yes queen, recursion. 💖

the second argument is optional: a hashref of options. the only valid argument at present is:

• no_separators — never mark paragraphs as "separators"

not me pointing out that "at present" means that's the only one, don't come for me if more get added later. 🙈

Exported by default. so you can just call extract like it's nothing.

🧚 set_quote_characters

takes a regex (qr//) matching the characters that should indicate a quoted line. by default, a very liberal set is used:

set_quote_characters(qr/[!#%=|:]/);

the character > is always recognized as a quoting character. it's the icon, it's the blueprint, it never leaves. ⭐

if undef is provided instead of a regex, only > will remain as a quote character. everything else gets uninvited from the group chat. 💀

Not exported by default, but exportable. so you gotta ask for it, bestie.

🍓 combine_hunks

my $text = combine_hunks( $arrayref_of_hunks );

takes the output of extract and turns it back into text. it's the reverse uno card of this whole module. 🔥

Not exported by default, but exportable. same deal as above.

---

💜 CREDITS 💜

most of the heavy lifting is done by a modified version of Damian Conway's Text::Autoformat. shoutout to the legend, we stan. 🙌

---

👑 AUTHOR 👑

Best Practical Solutions, LLC <modules@bestpractical.com>

---

📜 LICENSE AND COPYRIGHT 📜

this software is Copyright (c) 2004-2015 by Best Practical Solutions, LLC

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

so yes, you can absolutely remix it. go off. just keep the same terms as Perl itself, periodt. ✨

---

okay that's the whole page bestie!! this was perl v5.36.0, dated 2022-12-12, and it lives in the Text::Quoted(3pm) man page 💖 mwah, go read some emails and untangle those quote levels, you've got this 🎀🦋🌸