Pod::Tidy - a reformatting Pod Processor
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, ); Pod::Tidy::tidy_filehandle($input);
This module provides the heavy lifting needed by the podtidy utility although the API should be general enough that it can be used directly.
podtidy
This module accepts no arguments to it's import method and exports no symbols.
import
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, );
files
An array ref to a list of files and/or directories.
ignore
An array ref to regex objects that are used to reject files and/or directories. Each pattern is tried for a match against (in order) the absolute file path, the relative file path (canonical), and the basename. In the case of directories, the "basename" is considered to be the right most path component. For example, the "basename" of /foo/bar/baz/ would be to be baz.
/foo/bar/baz/
baz
This key is optional.
recursive
Accepts undef, 0, or 1. If set to 1 any directories provided to the files key will be recursively expanded. Defaults to undef
undef
0
1
verbose
Accepts undef, 0, or 1. 1 enables verbose warnings. Defaults to undef.
inplace
Accepts undef, 0, or 1. 1 enables in place reformatting of files. Updated files will be backed up unless the nobackup key is set. The mtime of the file is guarenteed not to be changed unless formating changes did occur. Defaults to undef.
nobackup
mtime
Accepts undef, 0, or 1. If set to 1 files being reformatted in place will not be backed up. Defaults to undef.
Before processing a file it is checked for:
correct access permissions
containing Pod
legal Pod syntax
Any file failing to meet those criteria will not be processed.
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 is 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.
STDOUT
These subroutines are not exportable.
backup_file
base
build_pod_queue
process_pod_queue
valid_pod_syntax
The tidy_files() subroutine does a number of highly inefficient things. Each file is opened and closed at least 3 different times as it is passed through a number of different modules to see if it meets the processing criteria. This shouldn't be a major performance issue with an modern OS's VM subsystem but it still leaves much to be desired. When doing inplace file reformatting a complete copy of the original file and the updated file and held in memory for comparison. Thus you are limited to reformatting Pod documents < ( available_system_memory / 2 ).
tidy_files()
< ( available_system_memory / 2 )
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:
=[foo]N
=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
=head1 foo
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.
perldoc
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:
If a single blank line is added between the two paragraphs as required by perlpodspec, the original document would look like this:
Then the result from podtidy would be nice and... well... tidy.
Larry Denneau denneau@ifa.hawaii.edu reported test failures caused by Module::Build stripping the execute bit from scripts/podtidy.
denneau@ifa.hawaii.edu
Grant McLean grant@mclean.net.nz caught a grammatical error in the documentation.
grant@mclean.net.nz
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.
Michael.Cartmell@thomson.com
Pod::Tidy::build_pod_queue()
build_requires
Please contact the author directly via e-mail.
Joshua Hoblitt jhoblitt@cpan.org
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.
podtidy, Pod::Wrap::Pretty, podwrap, Pod::Wrap, Perl::Tidy
To install Pod::Tidy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Tidy
CPAN shell
perl -MCPAN -e shell install Pod::Tidy
For more information on module installation, please visit the detailed CPAN module installation guide.