Pod::Tidy(3pm)

📦
version 0.10 · 2 versions
, in fedora 43

💖 Pod::Tidy — a reformatting Pod Processor 💖

okay bestie, so this is Pod::Tidy, a user-contributed Perl module (perl doc, obviously, it's a (3pm) situation) and it is literally the module that makes your Pod look cute instead of chaotic. No cap.

✨ SYNOPSIS ✨

use Pod::Tidy qw( tidy_files tidy_filehandle );

my $processed = Pod::Tidy::tidy_files(
    files       => \@list,
    ignore      => [qr/foo/, qr/bar/],
    recursive   => $recursive,
    verbose     => $verbose,
    inplace     => $inplace,
    nobackup    => $nobackup,
    columns     => $columns,
);

Pod::Tidy::tidy_filehandle($input);

🌸 DESCRIPTION 🌸

This module does all the heavy lifting for the podtidy utility 🫶 — like, it's the muscle behind the whole glow-up. But also, the API is general enough that you can just use it directly if that's your vibe. main character energy honestly.

🎀 USAGE 🎀

Import Parameters 💅

This module accepts no arguments to its import method and exports no symbols. It's giving "I don't do small talk", and honestly? Respect.

Exportable Subroutines 🦋

  • tidy_files( ... ) — accepts a mandatory hash.
my $processed = Pod::Tidy::tidy_files(
    files       => \@list,
    ignore      => [qr/foo/, qr/bar/],
    recursive   => $recursive,
    verbose     => $verbose,
    inplace     => $inplace,
    nobackup    => $nobackup,
    columns     => $columns,
);
  • files — an array ref to a list of files and/or directories.
  • ignore — an array ref to regex objects, used to reject files and/or directories. Each pattern gets tried for a match against, in order: the absolute file path, the relative (canonical) file path, and the basename. For directories, the "basename" is the right-most path component. Like, the "basename" of /foo/bar/baz/ would be baz. ✨

This key is optional.

  • recursive — accepts undef, 0, or 1. Set it to 1 and any directories you handed to the files key get recursively expanded. Defaults to undef.

This key is optional.

  • verbose — accepts undef, 0, or 1. 1 turns on verbose warnings. Defaults to undef.

This key is optional.

  • inplace — accepts undef, 0, or 1. 1 turns on in-place reformatting of files. Updated files get backed up unless the nobackup key is set. The mtime of the file is guarenteed not to change unless formatting changes actually happened. Defaults to undef.

This key is optional.

  • nobackup — accepts undef, 0, or 1. Set it to 1 and files being reformatted in place will not be backed up. Defaults to undef.

This key is optional.

  • columns — accepts any number. Sets the line width of the reformatted pod. Defaults to 76 (Text::Wrap's default).

This key is optional.

Before processing a file, it gets checked for:

  • correct access permissions
  • containing Pod
  • legal Pod syntax

Any file that fails to meet those criteria will not be processed. (vibe check: failed 😭)

Returns a count of processed files, or undef if no files could be processed.

  • tidy_filehandle($input) — accepts an open filehandle. Data from the filehandle is processed as it's read, so this subroutine can be used to filter large amounts of data. Because of this behavior, the input can not be checked in advance to verify a) that it's actually Pod and b) that the Pod document uses only valid Pod syntax. Output is set to STDOUT. Returns nothing.

Internal Subroutines 🙈

These subroutines are not exportable. They're backstage. Don't touch, bestie.

  • backup_file
  • base
  • build_pod_queue
  • process_pod_queue
  • valid_pod_syntax

🔥 DEVELOPER NOTES 🔥

Efficiency concerns 💀

The tidy_files() subroutine does a number of highly inefficient things. Each file is opened and closed at least 3 different times as it's passed through a number of different modules just to see if it meets the processing criteria. This shouldn't be a major performance issue with a modern OS's VM subsystem, but it still leaves much to be desired. ngl, it's a lot.

When doing inplace file reformatting, a complete copy of the original file and the updated file are held in memory for comparison. So you're limited to reformatting Pod documents < ( available_system_memory / 2 ). That's the rule, no cap.

😭 GOTCHAS 😭

Pod files not identified

Due to a bug in the version of contains_pod in Pod::Find bundled with Pod::Parser 1.33, Pod containing files will not be detected if the only =[foo]N directive is on the first line of the file. For example:

=head1 foo

foobarbaz

=cut

Would not be detected unless there was a newline before =head1 foo. See CPAN bug #14871 for a patch to correct Pod::Find. This should be fixed in version 1.34 of Pod::Parser.

Mangled verbatim blocks 💅

Unfortunately, the perldoc utility doesn't follow perlpodspec for what it considers a verbatim block. As far as perldoc is concerned, any line that begins with whitespace is in a verbatim block. While the Pod spec requires that all blocks are separated by a blank line.

Consider this example:

=head1 What Would Brian Boitano Do?

What would Brian Boitano do
If he was here right now?
He'd make a plan and he'd follow through
That's what Brian Boitano'd do
    When Brian Boitano was in the olympics
    Skating for the gold
    He'd do sound cows and a triple relux
    wearin a blindfold

=cut

perldoc incorrectly considers the second paragraph to be indented and would display it as one might be expecting. However, podtidy would turn it into this:

=head1 What Would Brian Boitano Do?

What would Brian Boitano do If he was here right now?  He'd make a plan and
he'd follow through That's what Brian Boitano'd do     When Brian Boitano was
in the olympics     Skating for the gold     He'd do sound cows and a triple
relux     wearin a blindfold

=cut

If a single blank line is added between the two paragraphs as required by perlpodspec, the original document would look like this:

=head1 What Would Brian Boitano Do?

What would Brian Boitano do
If he was here right now?
He'd make a plan and he'd follow through
That's what Brian Boitano'd do

    When Brian Boitano was in the olympics
    Skating for the gold
    He'd do sound cows and a triple relux
    wearin a blindfold

=cut

Then the result from podtidy would be nice and... well... tidy. ✨

=head1 What Would Brian Boitano Do?

What would Brian Boitano do If he was here right now? He'd make a plan and he'd
follow through That's what Brian Boitano'd do

    When Brian Boitano was in the olympics
    Skating for the gold
    He'd do sound cows and a triple relux
    wearin a blindfold

=cut

🌈 CREDITS 🌈

Larry Denneau denneau@ifa.hawaii.edu reported test failures caused by Module::Build stripping the execute bit from scripts/podtidy. 🫶

Grant McLean grant@mclean.net.nz caught a grammatical error in the documentation.

Michael Cartmell Michael.Cartmell@thomson.com provided some grammatical corrections and a patch to fix Pod::Tidy::build_pod_queue() tests on Win32, reporting test failures on Win32 caused by differing newline encodings, and reporting CPANPLUS playing badly with Module::Build's build_requires.

Hanno Hecker <vetinari@ankh-morp.org> provided a patch to allow the column width to specified in both the Pod::Tidy library and podtidy utility.

💜 SUPPORT 💜

Please contact the author directly via e-mail.

👑 AUTHOR 👑

Joshua Hoblitt jhoblitt@cpan.org

Copyright (c) 2005 Joshua Hoblitt. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the licenses can be found in the LICENSE file included with this module, or in perlartistic and perlgpl Pods as supplied with Perl 5.8.1 and later.

🧚 SEE ALSO 🧚

podtidy, Pod::Wrap::Pretty, podwrap, Pod::Wrap, Perl::Tidy

okay that's the whole thing bestie, you ate 💅✨

this was perl v5.42.0, dated 2025-07-25 — user contributed perl documentation, Pod::Tidy(3pm) 🦋 go forth and tidy, periodt 💖

📦 where this page comes from