Pod::Wrap(3pm)

💖 Pod::Wrap 💖

okay bestie, welcome to Pod::Wrap — a little Perl module (it's a 3pm page, user contributed perl documentation, iykyk) whose whole thing is: Wrap pod paragraphs, leaving verbatim text and code alone. ✨

That's it. That's the name and the job. Slay.

---

✨ SYNOPSIS ✨

here's the vibe, copy-paste ready, no cap:

#!/usr/bin/perl

use strict;
use warnings;

use Pod::Wrap;

my $w = new Pod::Wrap;

unless (@ARGV) {
    $w->parse_from_filehandle() # STDIN
} else {
    $w->parse_from_file($_) for @ARGV;
}

so like, no args? it eats STDIN. args? it chews through each file one by one. iconic behavior honestly.

---

🌸 DESCRIPTION 🌸

So this is a Pod::Parser subclass, based on Pod::Stripper (shoutout to the ancestor 💜). What it does: it parses perl files, wraps the pod text, and leaves everything else untouched — like, not a single non-pod byte gets disturbed, fr fr.

It prints its output to wherever you point it (exactly like you do with Pod::Parser — and with Pod::Stripper too). So you're the one driving, it's just vibing in the passenger seat. 🚗

---

🎀 METHODS 🎀

• new — this is literally just "new" in Pod::Parser. All arguments you pass it are meaningless, same as they are in Pod::Parser. So don't stress about them, bestie, they're giving decoration. 💅
• parse_from_filehandle
• parse_from_file

These are actually "parse_from_filehandle" in Pod::Parser and "parse_from_file" in Pod::Parser. Yeah. Same names, inherited energy.

They will receive input and output as described therein (go read Pod::Parser, it's the whole lore).

They will invoke this parser class, which will filter the pod text, wrapping the appropriate sections using Text::Wrap. 🦋

---

🌈 MOTIVATION 🌈

okay storytime. The author prefers editing with tabs and soft wrapping. Soft wrap gang rise up. 🫶

But most people like getting documentation hard wrapped and with tabs expanded. (Valid! Different strokes!)

The tabs part is easy — that's Text::Tabs. But wrapping only the correct parts of the pod is a little trickier. This module attempts to do this correctly, by wrapping only what isn't:

• a command
• a verbatim example (indented text)
• actual Perl code

like, it's doing a vibe check on every paragraph and only wrapping the ones that deserve it. 👑

PodMaster noted that the author should see what perltidy has to offer. Turns out that:

What perltidy does not parse and format
...
And, of course, it does not modify pod documents.

(read: perltidy doesn't do this job, so not me thinking it would 😭)

This drove the author to release this tiny module. Tiny but mighty. ⭐

---

💀 BEHAVIOR MODIFICATION 💀

The wrapping behavior is defined entirely by Text::Wrap. Not partially. Entirely. That's the whole thing.

No re-exporting is made, in order to minimize bugs. So if you want to import the variables Text::Wrap uses, do something like this:

use Pod::Wrap;
use Text::Wrap qw/$columns $huge/;

do it yourself, deliberately, on purpose. that's the vibe. 🧚

---

🙈 BUGS 🙈

Welcome. 💖

(that's it, that's the section. bugs are welcome. come on in.)

---

⭐ TODO ⭐

You can ask me.

---

👑 CREDITS 👑

Podmaster wrote Pod::Stripper. Even though the functionality of this module is very limited, and is not really derived from Pod::Stripper, the author would have been too lazy to read Pod::Parser's docs without seeing Pod::Stripper's code as an example first. real.

Bottom line: most of the work (the research) that was actually done is not the author's. The implementation wouldn't have happened if they hadn't known for sure it's possible to get perl code, verbatim, out of a pod parser. And they wouldn't have known that if they hadn't seen a working example. Standing on shoulders, fr fr. 🌸

---

💅 COPYRIGHT & LICENSE 💅

You may not wrap pod files in any way without my explicit permission, in writing.

Just kidding.

Copyright 2004 Yuval Kogman. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

the fake-out was highkey iconic, we have to respect it 😭

---

🍓 AUTHOR 🍓

Yuval Kogman <nothingmuch@woobling.org>

---

🦋 SEE ALSO 🦋

Text::Wrap, Pod::Parser, Pod::Stripper, Perl::Tidy

---

okay and finally, the lil' sign-off ✨ — this page is running under perl v5.42.0, dated 2025-07-25, and it's the Pod::Wrap(3pm) page, which we already established at the top because I'm not copy-pasting header lines like a square. anyway bestie, go wrap some pod (respectfully, with permission, per the license, jk jk). periodt. 💖🌈✨